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