1# Building Crosvm on Linux 2 3This page describes how to build and develop crosvm on linux. If you are targeting ChromeOS, please 4see [Integration](../integration/index.md) 5 6## Checking out 7 8Obtain the source code via git clone. 9 10```sh 11git clone https://chromium.googlesource.com/crosvm/crosvm 12``` 13 14## Setting up the development environment 15 16Crosvm uses submodules to manage external dependencies. Initialize them via: 17 18```sh 19git submodule update --init 20``` 21 22It is recommended to enable automatic recursive operations to keep the submodules in sync with the 23main repository (but do not push them, as that can conflict with `repo`): 24 25```sh 26git config submodule.recurse true 27git config push.recurseSubmodules no 28``` 29 30Crosvm development best works on Debian derivatives. We provide a script to install the necessary 31packages on Debian, Ubuntu or gLinux: 32 33```sh 34./tools/install-deps 35``` 36 37For other systems, please see below for instructions on 38[Using the development container](#using-the-development-container). 39 40### Using the development container 41 42We provide a Debian container with the required packages installed. With 43[Podman](https://podman.io/getting-started/installation) or 44[Docker](https://docs.docker.com/get-docker/) installed, it can be started with: 45 46```sh 47./tools/dev_container 48``` 49 50The container image is big and may take a while to download when first used. **Once started, you can 51follow all instructions in this document within the container shell.** 52 53Instead of using the interactive shell, commands to execute can be provided directly: 54 55```sh 56./tools/dev_container cargo build 57``` 58 59Note: The container and build artifacts are preserved between calls to `./tools/dev_container`. If 60you wish to start fresh, use the `--clean` flag. 61 62## Building a binary 63 64If you simply want to try crosvm, run `cargo build`. Then the executable is generated at 65`./target/debug/crosvm`. In case you are using development container, the executable will be inside 66the dev container at `/scratch/cargo_target/debug/crosvm`. 67 68Now you can move to [Example Usage](../running_crosvm/example_usage.md). 69 70If you want to enable [additional features](../running_crosvm/features.md), use the `--features` 71flag. (e.g. `cargo build --features=gdb`) 72 73## Development 74 75### Running all tests 76 77Crosvm's integration tests have special requirements for execution (see 78[Testing](../testing/index.md)), so we use a special test runner. By default it will only execute 79unit tests: 80 81```sh 82./tools/run_tests 83``` 84 85To execute integration tests as well, you need to specify a device-under-test (DUT). The most 86reliable option is to use the built-in VM for testing: 87 88```sh 89./tools/run_tests --dut=vm 90``` 91 92However, you can also use your local host directly. Your mileage may vary depending on your host 93kernel version and permissions. 94 95```sh 96./tools/run_tests --dut=host 97``` 98 99Since we have some architecture-dependent code, we also have the option of running unit tests for 100aarch64, armhf, riscv64, and windows (mingw64). These will use an emulator to execute (QEMU or 101wine): 102 103```sh 104./tools/run_tests --platform=aarch64 105./tools/run_tests --platform=armhf 106./tools/run_tests --platform=riscv64 107./tools/run_tests --platform=mingw64 108``` 109 110When working on a machine that does not support cross-compilation (e.g. gLinux), you can use the dev 111container to build and run the tests. 112 113```sh 114./tools/dev_container ./tools/run_tests --platform=aarch64 115``` 116 117### Presubmit checks 118 119To verify changes before submitting, use the `presubmit` script. To ensure the toolchains for all 120platforms are available, it is recommended to run it inside the dev container. 121 122```sh 123./tools/dev_container ./tools/presubmit 124``` 125 126This will run clippy, formatters and runs all tests for all platforms. The same checks will also be 127run by our CI system before changes are merged into `main`. 128 129See `tools/presumit -h` for details on various options for selecting which checks should be run to 130trade off speed and accuracy. 131 132## Cross-compilation 133 134Crosvm is built and tested on x86, aarch64, armhf, and riscv64. Your system needs some setup work to 135be able to cross-compile for other architectures, hence it is recommended to use the 136[development container](#using-the-development-container), which will have everything configured. 137 138Note: Cross-compilation is **not supported on gLinux**. Please use the development container. 139 140### Enable foreign architectures 141 142Your host needs to be set up to allow installation of foreign architecture packages. 143 144On Debian this is as easy as: 145 146```sh 147sudo dpkg --add-architecture arm64 148sudo dpkg --add-architecture armhf 149sudo dpkg --add-architecture riscv64 150sudo apt update 151``` 152 153On ubuntu this is a little harder and needs some 154[manual modifications](https://askubuntu.com/questions/430705/how-to-use-apt-get-to-download-multi-arch-library) 155of APT sources. 156 157With that enabled, the following scripts will install the needed packages: 158 159```sh 160./tools/install-aarch64-deps 161./tools/install-armhf-deps 162./tools/install-riscv64-deps 163``` 164 165### Configuring wine and mingw64 166 167Crosvm is also compiled and tested on windows. Some limited testing can be done with mingw64 and 168wine on linux machines. Use the provided setup script to install the needed dependencies. 169 170```sh 171./tools/install-mingw64-deps 172``` 173 174### Configure cargo for cross-compilation 175 176Cargo requries additional configuration to support cross-compilation. You can copy the provided 177example config to your cargo configuration: 178 179```sh 180cat .cargo/config.debian.toml >> ${CARGO_HOME:-~/.cargo}/config.toml 181``` 182 183**Note** 184 185In case of cross-compilation, crosvm executable would be at `./target/debug/<target>/crosvm`. If 186cross-compiling inside development container, the executable would be inside dev container at 187`/scratch/cargo_target/<target>/debug/crosvm`. 188 189e.g For aarch64, `target` will be `aarch64-unknown-linux-gnu` and you can build using 190 191```sh 192cargo build --target aarch64-unknown-linux-gnu 193``` 194 195## Known issues 196 197- Devices can't be jailed if `/var/empty` doesn't exist. `sudo mkdir -p /var/empty` to work around 198 this for now. 199- You need read/write permissions for `/dev/kvm` to run tests or other crosvm instances. Usually 200 it's owned by the `kvm` group, so `sudo usermod -a -G kvm $USER` and then log out and back in 201 again to fix this. 202- Some other features (networking) require `CAP_NET_ADMIN` so those usually need to be run as root. 203