From: Alyssa Ross <hi@alyssa.is>
To: Cole Helbling <cole.e.helbling@outlook.com>
Cc: devel@spectrum-os.org
Subject: Re: [PATCH doc] Document spectrum-vm
Date: Wed, 10 Jun 2020 13:34:01 +0000 [thread overview]
Message-ID: <877dwfjb92.fsf@alyssa.is> (raw)
In-Reply-To: <CH2PR14MB35797DF8D54942E4B75E7CDAB3850@CH2PR14MB3579.namprd14.prod.outlook.com>
[-- 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 --]
prev parent reply other threads:[~2020-06-10 13:34 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-06-08 20:44 Cole Helbling
2020-06-10 13:34 ` Alyssa Ross [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=877dwfjb92.fsf@alyssa.is \
--to=hi@alyssa.is \
--cc=cole.e.helbling@outlook.com \
--cc=devel@spectrum-os.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).