Re: [PATCH doc] Document spectrum-vm

Alyssa Ross
2020-06-10T13:34:27Z

[-- Attachment #1: Type: text/plain, Size: 3934 bytes --]

> spectrum-vm is a handy way to start a crosvm instance for testing crosvm
> itself, the kernel, or the rootfs. This commit adds some fledgling
> documentation on its functionality and usage.
> ---
> I feel like this is mostly a rough draft, so give me all your
> suggestions/criticisms/what have you.
>
> I put this section above the "Hacking on crosvm" section so that it will
> be introduced before it is used in an example.

You're amazing! Thanks so much for sending this!

> developer-manual.adoc | 43 +++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 43 insertions(+)
>
> diff --git a/developer-manual.adoc b/developer-manual.adoc
> index b7eb2cb..739dc83 100644
> --- a/developer-manual.adoc
> +++ b/developer-manual.adoc
> @@ -106,6 +106,49 @@ the https://spectrum-os.org/doc/crosvm/crosvm/[crosvm documentation]
> for the version currently used by Spectrum is hosted on the Spectrum
> website.
>
> +==== spectrum-vm
> +
> +`spectrum-vm` is a shell script that allows for testing various Spectrum
> +VM components, including crosvm, the kernel, and the rootfs. The

Shall we say "root file system" here, for clarity? We can say "rootfs"
further down to introduce the term, but this might be somebody's first
exposure to it so we should spell it out in full at least once.

> +simplest way to use this tool is by running `nix-shell -I
> +nixpkgs=/path/to/nixpkgs-spectrum -p spectrumPackages.spectrum-vm --run
> +spectrum-vm` in a terminal, which will start up an instance of crosvm
> +from Nixpkgs running Wayfire in a new window.
> +
> +****
> +Be advised that Wayfire's default keymap is set to Dvorak
> +https://spectrum-os.org/git/nixpkgs/tree/pkgs/os-specific/linux/spectrum/rootfs/default.nix[inside
> +of the rootfs] -- to change this to your preferred keymap, just set the
> +`xkb_layout` option (or remove it altogether for a default of QWERTY).
> +****
> +
> +Once you are ready to end your crosvm session, switch back to where you
> +ran `spectrum-vm` and type `reboot` (not `poweroff`). This window is not
> +limited to just stopping the VM, however; it is a functional serial
> +console and you can even run commands like `env` and `cat
> +/etc/passwd`.

It's especially useful for running commands as root, which you can't do
from the graphical interface at the moment. Might be useful to mention
that.

> +
> +As mentioned above, `spectrum-vm` also supports options that allow you
> +to specify custom components or run arbitrary commands before exiting:
> +
> +----
> +nix-shell -I nixpkgs=/path/to/nixpkgs-spectrum -p spectrumPackages.spectrum-vm
> +
> +nix-shell$ spectrum-vm --help
> +Usage: spectrum-vm [OPTION]... [-- CROSVM_OPTIONS]
> +
> + -c COMMAND shell command to run inside VM
> + -C, --crosvm PATH path to custom crosvm executable
> + -k, --kernel PATH path to custom kernel image
> + -f, --rootfs PATH path to custom root file system image
> + -- CROSVM_OPTIONS extra arguments to pass to crosvm

My experience with Nixpkgs documentation makes me think that this is
very likely going to go out of date if spectrum-vm accumulates another
option. I think maybe it would be better to just refer people to
spectrum-vm --help, without showing the output.

> +
> +nix-shell$ spectrum-vm -c 'echo $PATH' # print out the VM's PATH to the serial terminal and exit
> +nix-shell$ spectrum-vm -C target/debug/crosvm -- --disable-sandbox # use the specified crosvm and disable sandboxing
> +nix-shell$ spectrum-vm -k result/bzImage # use the specified kernel image
> +nix-shell$ spectrum-vm -f squashfs # use the specified squashfs as the root filesystem image

These examples are a great idea! Maybe they should go under an
"Examples" heading?

> +----
> +
> ==== Hacking on crosvm
>
> There are a few ways to get a crosvm development environment. You can
> --
> 2.26.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]