From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.3 (2019-12-06) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=-1.5 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS autolearn=unavailable autolearn_force=no version=3.4.3 Received: by atuin.qyliss.net (Postfix, from userid 496) id 44A6C52F2; Wed, 10 Jun 2020 13:34:27 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 2BE5853E7; Wed, 10 Jun 2020 13:34:21 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id D490752D2; Wed, 10 Jun 2020 13:34:18 +0000 (UTC) Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com [66.111.4.27]) by atuin.qyliss.net (Postfix) with ESMTPS id DFD6E52C6 for ; Wed, 10 Jun 2020 13:34:13 +0000 (UTC) Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id 6B15B5C00BE; Wed, 10 Jun 2020 09:34:11 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Wed, 10 Jun 2020 09:34:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=alyssa.is; h= from:to:cc:subject:in-reply-to:references:date:message-id :mime-version:content-type; s=fm3; bh=lW7h1qjbPivo4HCvBgjPNBZDOO h01dqGk3oSV6uFmuo=; b=uxrB8ZtnnQnR3GKrSCSjeTLsgKGw8ftJ8nQYBtRNre dV+JS4r/3Vc3zuXzF9uKJUepauOHoNBB6B0NXwiKHNCPyvVlQMW2Ikt+9jluL7nM 8nHGb1knzA5J+zeGHgXqEQWqacdrWNyCfodiC6TBez7gJjwLwMSThLWKse3PBYyi C/ceRlOrLVYmEEhQrmnn8PPLPyE+/6kxWD/Rx3h6SHyjKVDk8sN0/k4Ddg69UTv1 KbwmBNMYR6CC1ftOqbC3YORJ6Iosnldl53940u1LKaHBySv2c81VDaPkomCLZUrn B1EVLJNg1YWDxCt+AAORkjr6nc1Mk3PCzcGY9Mb9xU4A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=lW7h1q jbPivo4HCvBgjPNBZDOOh01dqGk3oSV6uFmuo=; b=eR57/B0LYxtozIdtvqc7lD Qvbxqlwm5J0uQyTolYVwuV6Xd8InXCPGN/3T4Z49WdVoLJ3e6p6bKdm/WoxjTbtJ sgAbeBQrB3vzDXQ08/iehMw23c42uEu9O623BBzXq9ER3QGlqnRCSR/8Fa9+tPTn OUQTk5kpbYXQVK5bxlq59rdcHWTTRm/TPyRjizAi2vRL+l0mQ71c7i7OADYvV7yB r6ObNZLWPDTDUS3bh7qhW1NYg3yYHCHDcWPXtO+SQsLd8f65KFRg7I6LgwV8TX/A kgG8Ye7wExv1D79NnADaxk8eQodY4jXpPcOgyMCrhKpvNeJoz6WIrLhdrKSFfuAA == X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduhedrudehiedgieelucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufgjfhffkfggtgesghdtreertddttdenucfhrhhomheptehlhihsshgr ucftohhsshcuoehhihesrghlhihsshgrrdhisheqnecuggftrfgrthhtvghrnhepudffie euledtheevheefieetveevfffhvddutefhiedvgfehiedtfeefleevgfdunecuffhomhgr ihhnpehsphgvtghtrhhumhdqohhsrdhorhhgnecukfhppeelfedrvddvkedruddvtddrvd egleenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehh ihesrghlhihsshgrrdhish X-ME-Proxy: Received: from x220.qyliss.net (p5de478f9.dip0.t-ipconnect.de [93.228.120.249]) by mail.messagingengine.com (Postfix) with ESMTPA id AECFD3060F09; Wed, 10 Jun 2020 09:34:10 -0400 (EDT) Received: by x220.qyliss.net (Postfix, from userid 1000) id 3E545272; Wed, 10 Jun 2020 13:34:09 +0000 (UTC) From: Alyssa Ross To: Cole Helbling Subject: Re: [PATCH doc] Document spectrum-vm In-Reply-To: References: Date: Wed, 10 Jun 2020 13:34:01 +0000 Message-ID: <877dwfjb92.fsf@alyssa.is> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Message-ID-Hash: R2IEHHSHPL4GQ4DXMCX3WUO475RE4LZR X-Message-ID-Hash: R2IEHHSHPL4GQ4DXMCX3WUO475RE4LZR X-MailFrom: hi@alyssa.is X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header CC: devel@spectrum-os.org X-Mailman-Version: 3.3.1 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable > 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/[crosv= m documentation] > for the version currently used by Spectrum is hosted on the Spectrum > website. >=20=20 > +=3D=3D=3D=3D 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=3D/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=3D/path/to/nixpkgs-spectrum -p spectrumPackages.spe= ctrum-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 r= oot filesystem image These examples are a great idea! Maybe they should go under an "Examples" heading? > +---- > + > =3D=3D=3D=3D Hacking on crosvm >=20=20 > There are a few ways to get a crosvm development environment. You can > --=20 > 2.26.2 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEH9wgcxqlHM/ARR3h+dvtSFmyccAFAl7g4UkACgkQ+dvtSFmy ccBSkQ/+ISrRuJUZiXjqOWSj0sFLGln6+6vgmlLw898BA212qkZ5feSHXnoMY4lZ DXkdkqOsQ15YmhK+84YAs9tk1VFX5niwplXTP+mnUoMCEfYTGGzY/yfgUjaAS4DK sa5FA9fLN0Fl8XWPYeTzLYOi/vhkdJI6aDnSmbLd/gdoJs6BLKJlNzObZLhxiXVP n+ULdJ1NZir4iFZwQwIm9BOs7vmCM5K1Ix139A5kSydWDAKx4UCqktS7l/oaLgUp c7ThIfyTmNvQyL5ltzErdztuO1Q9my+mvZ5X8Olrm0EbIACpm8ALo1YaAffNFzqp rNN1PzlCYS7VWc0F6pXbP6/YLg4Z6O2B1vuZ10SVlzlgeRN6XqSX2nMR4MeEI0id G238T3EntVm96hrJJBho03L1i6/azFRRiRFrJdv6hm9s+JLh0LWctClv+gKIMYrq kJfcU6QyrdUFfutGAYzuPcWTl5AUDMpvZNHy/LC8v2q45BsDMt6F09DqtYPtbHcz 73saA29LWV65S2XjVbJQx0CvIypZjly7USxUuZqvMwIzD6WZ9lKuFE2Z6sXm8dQO 0wbmCWHFBPz5Cqw55plTZDI7mNaEdUK9NKYj+LePXquWJfnino8jmOvsHRiFLwVy IGTPTHYfTQuu3zv9Nps36pe5jBcSVrOuV2XNV7uotaP2Uu0u/j8= =QBZg -----END PGP SIGNATURE----- --=-=-=--