1# Crosvm on ChromeOS 2 3A copy of crosvm is included in the ChromeOS source tree at [chromiumos/platform/crosvm], which is 4referred to as **downstream** crosvm. 5 6All crosvm development is happening **upstream** at [crosvm/crosvm]. Changes from upstream crosvm 7are regularly merged with ChromeOS's downstream crosvm. 8 9## The merge process. 10 11A crosvm bot will regularly generate automated commits that merge upstream crosvm into downstream. 12These commits can be found in 13[gerrit](https://chromium-review.googlesource.com/q/hashtag:crosvm-merge). 14 15The crosvm team is submitting these merges through the ChromeOS CQ regularly, which happens 16**roughly once per week**, but time can vary depending on CQ health. 17 18Googlers can find more information on the merge process at 19[go/crosvm/playbook](http://go/crosvm/playbook) 20 21## Building crosvm for ChromeOS 22 23crosvm on ChromeOS is usually built with Portage, so it follows the same general workflow as any 24`cros_workon` package. The full package name is `chromeos-base/crosvm`. 25 26The developer guide section on 27[Make your Changes](https://chromium.googlesource.com/chromiumos/docs/+/main/developer_guide.md#make-your-changes) 28applies to crosvm as well. You can build crosvm with `cros_workon_make`: 29 30```bash 31cros_workon --board=${BOARD} start crosvm 32cros_workon_make --board=${BOARD} crosvm 33``` 34 35Deploy it via `cros deploy`: 36 37```bash 38cros_workon_make --board=${BOARD} --install crosvm 39cros deploy ${IP} crosvm 40``` 41 42Iterative test runs can be done as well: 43 44```bash 45cros_workon_make --board=${BOARD} --test crosvm 46``` 47 48Warning: `cros_workon_make` patches the local Cargo.toml file. Please do not submit these changes. 49 50### Rebuilding all crosvm dependencies 51 52Crosvm has a lot of rust dependencies that are installed into a registry inside cros_sdk. After a 53`repo sync` these can be out of date, causing compilation issues. To make sure all dependencies are 54up to date, run: 55 56```bash 57emerge-${BOARD} --update --deep -j$(nproc) crosvm 58``` 59 60## Building crosvm for Linux 61 62`emerge` and `cros_workon_make` workflows can be quite slow to work with, hence a lot of developers 63prefer to use standard cargo workflows used upstream. 64 65Just make sure to initialize git submodules (`git submodules update --init`), which is not done by 66repo. After that, you can use the workflows as outlined in [Building Crosvm](../building_crosvm.md) 67**outside** of cros_sdk. 68 69Note: You can **not** build or test ChromeOS specific features this way. 70 71## Submitting Changes 72 73All changes to crosvm are made upstream, using the same process outlined in 74[Contributing](../contributing/index.md). It is recommended to use the 75[Building crosvm for Linux](#building-crosvm-for-linux) setup above to run upstream presubmit checks 76/ formatting tools / etc when submitting changes. 77 78Code submitted upstream is tested on linux, but not on ChromeOS devices. Changes will only be tested 79on the ChromeOS CQ when they go through [the merge process](#the-merge-process). 80 81## Has my change landed in ChromeOS (Googlers only)? 82 83You can use the [crosland](http://crosland/cl) tool to check in which ChromeOS version your changes 84have been merged into the [chromiumos/platform/crosvm] repository. 85 86The merge will also contain all `BUG=` references that will notify your bugs about when the change 87is submitted. 88 89For more details on the process, please see [go/crosvm-playbook](http://go/crosvm-playbook) (Google 90only). 91 92## Cq-Depend 93 94**We cannot support Cq-Depend** to sychronize changes with other ChromeOS repositories. Please try 95to make changes in a backwards compatible way to allow them to be submitted independently. 96 97If it cannot be avoided at all, please follow this process: 98 991. Upload your change to upstream crosvm and get it reviewed. Do not submit it yet. 1001. Upload the change to [chromiumos/platform/crosvm] as well. 1011. Use Cq-Depend on the ChromeOS changes and submit it via the CQ. 1021. After the changes landed in ChromeOS, land them upstream as well. 103 104## Cherry-picking 105 106If you need your changes faster than the usual merge frequency, please follow this process: 107 1081. Upload and submit your change to upstream crosvm. 1091. Upload the change to [chromiumos/platform/crosvm] as well. 1101. Submit as usual through the CQ. 111 112**Never** submit code just to ChromeOS, as it will cause upstream to diverge and result in merge 113conflicts down the road. 114 115[chromiumos/platform/crosvm]: https://chromium.googlesource.com/chromiumos/platform/crosvm 116[crosvm/crosvm]: https://chromium.googlesource.com/crosvm/crosvm 117