Signed-off-by: Fam Zheng <famz@redhat.com>
---
 tests/vm/README | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 tests/vm/README

diff --git a/tests/vm/README b/tests/vm/README
new file mode 100644
index 0000000000..a18b285507
--- /dev/null
+++ b/tests/vm/README
@@ -0,0 +1,63 @@
+=== VM test suite to run build in guests ===
+
+== Intro ==
+
+This test suite contains scripts that bootstrap various guest images that has
+necessary packages to build QEMU. The basic usage is documented in Makefile
+help which is displayed with "make vm-test".
+
+== Quick start ==
+
+Run "make vm-test" to list available make targets.
+
+== Manual invocation ==
+
+Each guest script is an executable script with the same uage. For example to
+work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:
+
+    $ cd $QEMU_SRC/tests/vm
+
+    # To bootstrap the image
+    $ ./netbsd --build-image --image /var/tmp/netbsd.img
+    <...>
+
+    # To run an arbitrary command in guest (the output will not be echoed unless
+    # --debug is added)
+    $ ./netbsd --debug --image /tmp/netbsd.img uname -a
+
+    # To build QEMU in guest
+    $ ./netbsd --debug --image /tmp/netbsd.img --build-qemu $QEMU_SRC
+
+    # To get to an interactive shell
+    $ ./netbsd --interactive --image /tmp/netbsd.img sh
+
+== Adding new guests ==
+
+Please look at existing guest scripts for how to add new guests.
+
+Most importantly, create a subclass of BaseVM and implement build_image()
+method and define BUILD_SCRIPT, then finally call basevm.main() from the
+scripts main().
+
+  - Usually in build_image(), a template image is downloaded from a predefined
+    URL. BaseVM._download_with_cache() takes care of cache the checksum, so
+    consider using it.
+
+  - Once the image is downloaded, users, SSH server and QEMU build deps should
+    be set up:
+
+    * Root password set to BaseVM.ROOT_PASS
+    * User BaseVM.GUEST_USER is create, and password set to BaseVM.GUEST_PASS
+    * SSH service is enabled and started on boot, BaseVM.SSH_PUB_KEY is added
+      to authorized_keys of both root and the normal user
+    * DHCP client service is enabled and started on boot, so that it can
+      automatically configure the virtio-net-pci NIC and communicate with QEMU
+      user net (10.0.2.2)
+    * Necessary packages are installed to untar the source tarball and build
+      QEMU
+
+  - Write a proper BUILD_SCRIPT template, which should be a shell script that
+    untars a raw virtio-blk block device, which is the tarball data blob of the
+    QEMU source tree, then configure/build it. Running "make check" is also
+    recommended.
+
-- 
2.13.5

On Tue, Aug 22, 2017 at 12:41:55PM +0800, Fam Zheng wrote:
> Signed-off-by: Fam Zheng <famz@redhat.com>
> ---
>  tests/vm/README | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 63 insertions(+)
>  create mode 100644 tests/vm/README
> 
> diff --git a/tests/vm/README b/tests/vm/README
> new file mode 100644
> index 0000000000..a18b285507
> --- /dev/null
> +++ b/tests/vm/README
> @@ -0,0 +1,63 @@
> +=== VM test suite to run build in guests ===
> +
> +== Intro ==
> +
> +This test suite contains scripts that bootstrap various guest images that has

s/that has/that have/ (because "images" is plural)

> +necessary packages to build QEMU. The basic usage is documented in Makefile
> +help which is displayed with "make vm-test".
> +
> +== Quick start ==
> +
> +Run "make vm-test" to list available make targets.
> +
> +== Manual invocation ==
> +
> +Each guest script is an executable script with the same uage. For example to

s/uage/usage/

I would say "command-line options" instead though.

> +work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:
> +
> +    $ cd $QEMU_SRC/tests/vm
> +
> +    # To bootstrap the image
> +    $ ./netbsd --build-image --image /var/tmp/netbsd.img
> +    <...>
> +
> +    # To run an arbitrary command in guest (the output will not be echoed unless
> +    # --debug is added)
> +    $ ./netbsd --debug --image /tmp/netbsd.img uname -a
> +
> +    # To build QEMU in guest
> +    $ ./netbsd --debug --image /tmp/netbsd.img --build-qemu $QEMU_SRC
> +
> +    # To get to an interactive shell
> +    $ ./netbsd --interactive --image /tmp/netbsd.img sh
> +
> +== Adding new guests ==
> +
> +Please look at existing guest scripts for how to add new guests.
> +
> +Most importantly, create a subclass of BaseVM and implement build_image()
> +method and define BUILD_SCRIPT, then finally call basevm.main() from the
> +scripts main().

s/scripts/script's/ (possessive form)

> +
> +  - Usually in build_image(), a template image is downloaded from a predefined
> +    URL. BaseVM._download_with_cache() takes care of cache the checksum, so

s/cache/caching/ (verb)

> +    consider using it.
> +
> +  - Once the image is downloaded, users, SSH server and QEMU build deps should
> +    be set up:
> +
> +    * Root password set to BaseVM.ROOT_PASS
> +    * User BaseVM.GUEST_USER is create, and password set to BaseVM.GUEST_PASS

s/create/created/ (participle)

> +    * SSH service is enabled and started on boot, BaseVM.SSH_PUB_KEY is added
> +      to authorized_keys of both root and the normal user
> +    * DHCP client service is enabled and started on boot, so that it can
> +      automatically configure the virtio-net-pci NIC and communicate with QEMU
> +      user net (10.0.2.2)
> +    * Necessary packages are installed to untar the source tarball and build
> +      QEMU
> +
> +  - Write a proper BUILD_SCRIPT template, which should be a shell script that
> +    untars a raw virtio-blk block device, which is the tarball data blob of the
> +    QEMU source tree, then configure/build it. Running "make check" is also
> +    recommended.
> +
> -- 
> 2.13.5
> 

Thanks for the grammar corrections! All make sense.

On Tue, 08/22 14:38, Stefan Hajnoczi wrote:
> On Tue, Aug 22, 2017 at 12:41:55PM +0800, Fam Zheng wrote:
> > Signed-off-by: Fam Zheng <famz@redhat.com>
> > ---
> >  tests/vm/README | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 63 insertions(+)
> >  create mode 100644 tests/vm/README
> > 
> > diff --git a/tests/vm/README b/tests/vm/README
> > new file mode 100644
> > index 0000000000..a18b285507
> > --- /dev/null
> > +++ b/tests/vm/README
> > @@ -0,0 +1,63 @@
> > +=== VM test suite to run build in guests ===
> > +
> > +== Intro ==
> > +
> > +This test suite contains scripts that bootstrap various guest images that has
> 
> s/that has/that have/ (because "images" is plural)

Yes.

> 
> > +necessary packages to build QEMU. The basic usage is documented in Makefile
> > +help which is displayed with "make vm-test".
> > +
> > +== Quick start ==
> > +
> > +Run "make vm-test" to list available make targets.
> > +
> > +== Manual invocation ==
> > +
> > +Each guest script is an executable script with the same uage. For example to
> 
> s/uage/usage/
> 
> I would say "command-line options" instead though.

"Command-line options" sounds better.

> 
> > +work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:
> > +
> > +    $ cd $QEMU_SRC/tests/vm
> > +
> > +    # To bootstrap the image
> > +    $ ./netbsd --build-image --image /var/tmp/netbsd.img
> > +    <...>
> > +
> > +    # To run an arbitrary command in guest (the output will not be echoed unless
> > +    # --debug is added)
> > +    $ ./netbsd --debug --image /tmp/netbsd.img uname -a
> > +
> > +    # To build QEMU in guest
> > +    $ ./netbsd --debug --image /tmp/netbsd.img --build-qemu $QEMU_SRC
> > +
> > +    # To get to an interactive shell
> > +    $ ./netbsd --interactive --image /tmp/netbsd.img sh
> > +
> > +== Adding new guests ==
> > +
> > +Please look at existing guest scripts for how to add new guests.
> > +
> > +Most importantly, create a subclass of BaseVM and implement build_image()
> > +method and define BUILD_SCRIPT, then finally call basevm.main() from the
> > +scripts main().
> 
> s/scripts/script's/ (possessive form)

Little finger is feeling lazy. :)

> 
> > +
> > +  - Usually in build_image(), a template image is downloaded from a predefined
> > +    URL. BaseVM._download_with_cache() takes care of cache the checksum, so
> 
> s/cache/caching/ (verb)

I intended to say "caching and the checksum".

> 
> > +    consider using it.
> > +
> > +  - Once the image is downloaded, users, SSH server and QEMU build deps should
> > +    be set up:
> > +
> > +    * Root password set to BaseVM.ROOT_PASS
> > +    * User BaseVM.GUEST_USER is create, and password set to BaseVM.GUEST_PASS
> 
> s/create/created/ (participle)

Yes.

> 
> > +    * SSH service is enabled and started on boot, BaseVM.SSH_PUB_KEY is added
> > +      to authorized_keys of both root and the normal user
> > +    * DHCP client service is enabled and started on boot, so that it can
> > +      automatically configure the virtio-net-pci NIC and communicate with QEMU
> > +      user net (10.0.2.2)
> > +    * Necessary packages are installed to untar the source tarball and build
> > +      QEMU
> > +
> > +  - Write a proper BUILD_SCRIPT template, which should be a shell script that
> > +    untars a raw virtio-blk block device, which is the tarball data blob of the
> > +    QEMU source tree, then configure/build it. Running "make check" is also
> > +    recommended.
> > +
> > -- 
> > 2.13.5
> > 

Fam