commit dd7cc0f0fe81a12f97c8bc0ea079b9ea37c56ef6 (patch)
parent d272aa8 Spellcheck
tree 1a1c14c2aed30b79d7523fba9954a8b75e331359
author Alyssa Ross <hi@alyssa.is> 2020-05-08 18:07:44 +0000
committer Alyssa Ross <hi@alyssa.is> 2020-05-08 18:07:44 +0000
Add "Hacking on crosvm" section
---
developer-manual.adoc | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 75 insertions(+)
diff --git a/developer-manual.adoc b/developer-manual.adoc
index 02be9fe..67a171a 100644
--- a/developer-manual.adoc
+++ b/developer-manual.adoc
@@ -106,6 +106,81 @@ the https://spectrum-os.org/doc/crosvm/crosvm/[crosvm documentation]
for the version currently used by Spectrum is hosted on the Spectrum
website.
+==== Hacking on crosvm
+
+There are a few ways to get a crosvm development environment. You can
+set up a full Chromium OS development chroot, or use the provided
+Docker scripts. But an approach with less indirection (and therefore
+probably easier to debug when things to wrong) is to just get
+everything set up on your system.
+
+Like other Chromium OS components, crosvm is easiest to build when its
+positioned where it expects to be relative to other Chromium OS
+components.
+
+So, you should check out the https://spectrum-os.org/git/crosvm[crosvm
+repository] into a hierarchy that looks something like this:
+
+----
+chromiumos/
+├── aosp/
+│ └── external/
+│ └── minijail/ (git clone https://android.googlesource.com/platform/external/minijail)
+├── platform/
+│ └── crosvm/
+└── third_party/
+ └── adhd/ (git clone https://chromium.googlesource.com/chromiumos/third_party/minijail)
+----
+
+The exact other components required by crosvm depend on what build
+options you're using and will also likely change over time. So the
+best thing to do is probably to start with platform/crosvm, and just
+try building. If you're missing a required component, you'll get an
+error message. You should be able to find the required repository
+from the list on https://chromium.googlesource.com/.
+
+****
+Google have a tool, called "repo", for managing all these checkouts,
+and keeping them all in sync. It's a bit heavy for just the couple of
+repos required by crosvm, though.
+****
+
+For a straightforward crosvm build with the default build options, the
+following packages from https://spectrum-os.org/git/nixpkgs[Spectrum's
+Nixpkgs] are required:
+
+- cargo
+- pkg-config
+- libcap
+- minijail
+- dtc
+
+****
+You may wonder why we use Minijail from Nixpkgs when crosvm also
+requires Minijail at ../../aosp/external/minijail. This is because
+Minijail won't build out of the box on NixOS, because of hardcoded
+paths like /bin/echo in its Makefile. Fortunately, when used as a
+Rust library, Minijail will first check if there's a Minijail already
+available in the environment, and if so, it'll use that rather than
+building itself.
+
+So when crosvm loads Minijail at ../../aosp/external/minijail, the
+build.rs there will essentially redirect crosvm to the Minijail from
+Nixpkgs.
+
+This isn't great, but it's the easiest way to get things going. You
+could also, if you wanted to, apply the same modifications the
+Minijail Nixpkgs derivation does to fix these hardcoded paths, and
+then not use the Nixpkgs minijail. You would definitely want to do
+things this if you were going to be hacking on Minijail.
+****
+
+You can then build crosvm with cargo build. Due to hardcoded paths to
+seccomp policy files, this crosvm will probably not work with
+sandboxing enabled, so you'll have to use --disable-sandbox. If you
+need to test sandboxing, your best bet is to try to modify the crosvm
+Nix derivation to use your modified sources.
+
=== Sommelier
https://chromium.googlesource.com/chromiumos/platform2/+/master/vm_tools/sommelier[Sommelier]
glossary
--------
Commit objects reference one tree, and zero or more parents.
Single parent commits can typically generate a patch in
unified diff format via `git format-patch'.
Multiple parents means the commit is a merge.
Root commits have no ancestor. Note that it is
possible to have multiple root commits when merging independent histories.
Every commit references one top-level tree object.
git clone https://inbox.spectrum-os.org/doc