added

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
index 0000000..ce3c7ec
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,64 @@
+= bespoke-installer.git
+
+This is a small project for building the Devuan installer software as
+a kernel and initrd.gz pair for arm64.
+
+The building process is fitted into a single bash script together with
+a special boot-up `initrd-init` file and two "package lists" files:
+
+* `installer-packages.list` enumerates the packages to install into
+  the initrd filesystem so as to become installer software execution
+  core.
+
+* `pool-packages-installer.list` enumerates the packages for an
+  accompanying release pool, which are specifically selected in
+  addition all "required", "important" and "standard" packages. (The
+  latter uses the Priority attribute of the packages themselves).
+
+Both package lists are expanded by recursively including dependent and
+recommended packages starting from the package lists.
+
+== Running build-installer.sh
+
+The script `./build-installer.sh` is run by a non-root user on the
+command line. It prepares three `build` subdirectories:
+
+1. `build/sources` contains the Packages file for the sources, which
+   are the `main`, `non-free-firmware` and `main/debian-installer`
+   components of the Devuan `daedalus` repository.
+
+2. `build/media` is a media filesystem with a repository pool of
+   slightly bespoke structure. It includes
+   * `build/media/.disk` with description files appropriate for a
+      debian-installer media;
+   * `build/media/dists` with a "standard" repository structure of
+     meta files describing the media as repository; and
+   * `build/media/pool` with a bespoke layout containing the packages.
++
+   The directory tree at `build/media` gets packed up as
+   `build/initrd/pool.squashfs` to be included in the initrd for use
+   during the installation.
+
+3. `build/initrd` is the installers core execution filesystem, which
+   gets populated by unpacking and configuring the udeb packages
+   enumerated in `installer-packages.list`. This is augmented with the
+   media squashfs and the `build/initrd/init` script copied from
+   `initrd-init` at top level; this script runs the installer.
++
+   The directory tree at `build/initrd` gets packed up at end into
+   `initrd.gz`at project top level. Further, the linux kernel at
+   `build/initrd/boot/vmlinuz` is also copied up to project to level.
+
+At end, the project toplevel as got the files `vmlinuz` and
+`initrd.gz` to be used by the target arm64 system, as well as the
+`build` directory which may be deleted. `initrd.gz` is quite large
+since it includes the package pool `/pool.squasfs`. The target system
+must have enough RAM to accomodate the unpacking of `initrd.gz` as
+well as free RAM for the installation process. I would suggest it needs
+2Gib RAM.
+
+== Running vm.sh
+
+The script `vm.sh` runs a qemu VM for testing the built `vmlinuz` and
+`initrd.gz` with console interface only using the `virt` platform with
+a cortex-a53 CPU and 4Gib RAM.