[PATCH 1/1] doc: Show how to boot result of 'vm-image'.

[Leo Famulari <leo@famulari.name>]

* doc/guix.texi (Invoking guix system): Explain how to boot the QEMU
images created by vm-image.
---
 doc/guix.texi | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index e583e8c..51165b4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -9058,9 +9058,6 @@ Return a virtual machine or disk image of the operating system declared
 in @var{file} that stands alone.  Use the @option{--image-size} option
 to specify the size of the image.
 
-When using @code{vm-image}, the returned image is in qcow2 format, which
-the QEMU emulator can efficiently use.
-
 When using @code{disk-image}, a raw disk image is produced; it can be
 copied as is to a USB stick, for instance.  Assuming @code{/dev/sdc} is
 the device corresponding to a USB stick, one can copy the image on it
@@ -9070,6 +9067,44 @@ using the following command:
 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
 @end example
 
+When using @code{vm-image}, the returned image is in qcow2 format, which
+the QEMU emulator can efficiently use.
+
+To run the image in QEMU, copy it out of the store and give yourself
+permission to write to the copy. When invoking QEMU, you must choose a
+system emulator that is suitable for your hardware platform.  Here is a
+minimal QEMU invocation that will boot GuixSD on x86_64 hardware:
+
+@example
+$ qemu-system-x86_64 \
+-net user \
+-net nic,model=virtio \
+-enable-kvm \
+-m 256 \
+/tmp/qemu-image
+@end example
+
+And the annotated version:
+
+@example
+# Hardware platform to emulate. This should match the host.
+$ qemu-system-x86_64 \
+# Unpriviliged user mode networking. Guest can access host but not vice
+# versa. If you don't choose a network stack, the boot will fail.
+-net user \
+# You must create a network interface of a given model. If you don't
+# create a NIC, the boot will fail. You can get a list of available NIC
+# models by running `qemu-system-x86_64 -net nic,model=help`.
+-net nic,model=virtio \
+# If your system is x86 with hardware virtualization extensions,
+# enabling the kernel virtual machine will make things run faster.
+-enable-kvm \
+# RAM available to the guest OS. Defaults to 128 megabytes, which is not
+# enough for the Guix daemon.
+-m 256 \
+/tmp/qemu-image
+@end example
+
 @item container
 Return a script to run the operating system declared in @var{file}
 within a container.  Containers are a set of lightweight isolation
-- 
2.6.4