* [PATCH doc] Document spectrum-vm
@ 2020-06-08 20:44 Cole Helbling
2020-06-10 13:34 ` Alyssa Ross
0 siblings, 1 reply; 2+ messages in thread
From: Cole Helbling @ 2020-06-08 20:44 UTC (permalink / raw)
To: devel; +Cc: Cole Helbling
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.
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
+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`.
+
+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
+
+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
+----
+
==== Hacking on crosvm
There are a few ways to get a crosvm development environment. You can
--
2.26.2
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [PATCH doc] Document spectrum-vm
2020-06-08 20:44 [PATCH doc] Document spectrum-vm Cole Helbling
@ 2020-06-10 13:34 ` Alyssa Ross
0 siblings, 0 replies; 2+ messages in thread
From: Alyssa Ross @ 2020-06-10 13:34 UTC (permalink / raw)
To: Cole Helbling; +Cc: devel
[-- 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 --]
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-06-10 13:34 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-08 20:44 [PATCH doc] Document spectrum-vm Cole Helbling
2020-06-10 13:34 ` Alyssa Ross
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).