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

diff --git a/README b/README
index 711d737..2b58ccf 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,59 @@ In order to use vmdebootstrap, you'll need a few things:
 * mbr
 * kpartx
 * python-cliapp (see http://liw.fi/cliapp/)
+* python-distro-info
+
+Running vmdebootstrap from git
+------------------------------
+
+$ sudo PYTHONPATH=. ./bin/vmdebootstrap
+
+This has changed slightly with version 1.0 with the need for
+PYTHONPATH to reference the module approach for support handlers.
+
+pylint
+------
+
+vmdebootstrap uses pylint and contains comments to disable certain
+pylint checks in certain areas. pylint compatibility will make it
+easier to accept patches, just follow the existing pattern
+of pylint usage. pylint is far from perfect but can be helpful.
+
+Testing UEFI support
+--------------------
+
+There is EFI firmware available to use with QEMU when testing images
+built using the UEFI support, but this software is in Debian non-free
+due to patent concerns. If you choose to use it to test UEFI builds,
+a secondary change is also needed to symlink the provided OVMF.fd to
+the file required by QEMU: bios-256k.bin and then tell QEMU about the
+location of this file with the -L option:
+
+$ qemu-system-x86_64 -L /usr/share/ovmf/ -machine accel=kvm \
+  -m 4096 -smp 2 -drive file=amd64.img,format=raw
+
+Note the use of -drive file=<img>,format=raw which is needed for newer
+versions of QEMU.
+
+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
 --------