X-Git-Url: https://git.siccegge.de//index.cgi?a=blobdiff_plain;f=README;h=b454865d498da1ea174e8df60c3b22af447dfba4;hb=c476243eafde1e0eda3158f31398b622c8043a9a;hp=711d7373258cb1021fd03af758aa16d291cf8d32;hpb=237ee3171dfda1641f2008f36226b058ddc4b6d3;p=forks%2Fvmdebootstrap.git

diff --git a/README b/README
index 711d737..b454865 100644
--- a/README
+++ b/README
@@ -2,12 +2,49 @@ README for vmdebootstrap
 ========================
 
 `debootstrap` installs a basic Debian system into a directory, for use with
-`chroot`(8). `vmdeboostrap` is a wrapper around it to install Debian into 
+`chroot`(8). `vmdebootstrap` is a wrapper around it to install Debian into
 a disk image, which can be used with a virtual machine (such as KVM).
 
 See the manual page and `vmdebootstrap --help` for details on how to
 use the program. The manual page has an example.
 
+Limitations
+-----------
+
+`vmdebootstrap` is aimed principally at creating virtual machines, not
+installers or prebuilt installation images. It is possible to create
+prebuilt installation images for some devices but this depends on the
+specific device. (A 'prebuilt installation image' is a single image file
+which can be written to physical media in a single operation and which
+allows the device to boot directly into a fully installed system - in a
+similar way to how a virtual machine would behave.)
+
+* `vmdebootstrap` assumes that all operations take place on a local image
+   file, not a physical block device / removable media.
+* `vmdebootstrap` is intended to be used with tools like `qemu` on the
+   command line to launch a new virtual machine. Not all devices have
+   virtualisation support in hardware.
+
+This has implications for `u-boot` support in some cases. If the device
+can support reading the bootloader from a known partition, like the
+Beaglebone-black, then `vmdebootstrap` can provide space for the bootloader
+and the image will work as a prebuilt installation image. If the device
+expects that the bootloader exists at a specific offset and therefore
+requires that the bootloader is written as an image not as a binary which
+can be copied into an existing partition, `vmdebootstrap` is unable to
+include that bootloader image into the virtual machine image.
+
+It is possible to wrap `vmdebootstrap` in such a way as to prepare a
+*physical block device* with a bootloader image and then deploy the
+bootstrap on top. However, this does require physical media to be
+inserted and removed each time the wrapper is executed. Once you have
+working media, an image can be created using ``dd`` to read back from
+the media to an image file, allowing other media to be written with a
+single image file. To do this, use the `--tarball` option to `vmdebootstrap`
+instead of the `--image`` option. Then setup the physical media and
+bootloader image as required for the device, redefine the partitions to
+make space for the rootfs, create a filesystem on the physical media and
+unpack the `vmdebootstrap` tarball onto that filesystem.
 
 What you need
 -------------
@@ -21,7 +58,27 @@ In order to use vmdebootstrap, you'll need a few things:
 * mbr
 * kpartx
 * python-cliapp (see http://liw.fi/cliapp/)
+* python-distro-info
+
+The vmextract helper
+--------------------
+
+Once the image is built, various files can be generated or modified
+during the install operations and some of these files can be useful
+when testing the image. One example is the initrd built by the process
+of installing a Debian kernel. Rather than having to mount the image
+and copy the files manually, the vmextract helper can do it for you,
+without needing root privileges.
+
+$ /usr/share/vmdebootstrap/vmextract.py --verbose \
+  --image bbb/bbb-debian-armmp.img --boot \
+  --path /boot/initrd.img-3.14-2-armmp \
+  --path /lib/arm-linux-gnueabihf/libresolv.so.2
 
+This uses python-guestfs (a Recommended package for vmdebootstrap) to
+prepare a read-only version of the image - in this case with the /boot
+partition also mounted - and copies files out into the current working
+directory.
 
 Legalese
 --------