From dd7cc0f0fe81a12f97c8bc0ea079b9ea37c56ef6 Mon Sep 17 00:00:00 2001
From: Alyssa Ross <hi@alyssa.is>
Date: Fri, 8 May 2020 18:07:44 +0000
Subject: Add "Hacking on crosvm" section

---
 developer-manual.adoc | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

(limited to 'developer-manual.adoc')

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]
-- 
cgit 1.4.1