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 [go/crosvm-uprev-playbook]. 19 20## Building crosvm for ChromeOS 21 22crosvm on ChromeOS is usually built with Portage, so it follows the same general workflow as any 23`cros_workon` package. The full package name is `chromeos-base/crosvm`. 24 25The developer guide section on 26[Make your Changes](https://www.chromium.org/chromium-os/developer-library/guides/development/developer-guide/#make-your-changes) 27applies to crosvm as well. You can specify the development version to be built with cros_workon, and 28build with cros build-packages. Consecutive builds without changes to dependency can be done with 29emerge. 30 31```bash 32(chroot)$ cros_workon --board=${BOARD} start chromeos-base/crosvm 33(chroot or host)$ cros build-packages --board=${BOARD} chromeos-base/crosvm 34(chroot)$ emerge-${BOARD} chromeos-base/crosvm -j 10 35``` 36 37Deploy it via `cros deploy`: 38 39```bash 40(chroot)$ cros deploy ${IP} crosvm 41``` 42 43Iterative test runs can be done as well: 44 45```bash 46(chroot)$ FEATURES=test emerge-${BOARD} chromeos-base/crosvm -j 10 47``` 48 49Warning: Using `cros_workon_make` is possible but patches the local Cargo.toml file and some 50configuration files. Please do not submit these changes. Also something makes it rebuild a lot of 51the files. 52 53### Rebuilding all crosvm dependencies 54 55Crosvm has a lot of rust dependencies that are installed into a registry inside cros_sdk. After a 56`repo sync` these can be out of date, causing compilation issues. To make sure all dependencies are 57up to date, run: 58 59```bash 60(chroot or host)$ cros build-packages --board=${BOARD} chromeos-base/crosvm 61``` 62 63## Building crosvm for Linux 64 65`emerge` and `cros_workon_make` workflows can be quite slow to work with, hence a lot of developers 66prefer to use standard cargo workflows used upstream. 67 68Just make sure to initialize git submodules (`git submodules update --init`), which is not done by 69repo. After that, you can use the workflows as outlined in 70[Building Crosvm](../building_crosvm/linux.md) **outside** of cros_sdk. 71 72Note: You can **not** build or test ChromeOS specific features this way. 73 74## Submitting Changes 75 76All changes to crosvm are made upstream, using the same process outlined in 77[Contributing](../contributing/index.md). It is recommended to use the 78[Building crosvm for Linux](#building-crosvm-for-linux) setup above to run upstream presubmit checks 79/ formatting tools / etc when submitting changes. 80 81Code submitted upstream is tested on linux, but not on ChromeOS devices. Changes will only be tested 82on the ChromeOS CQ when they go through [the merge process](#the-merge-process). 83 84## Has my change landed in ChromeOS (Googlers only)? 85 86You can use the [crosland](http://crosland/cl) tool to check in which ChromeOS version your changes 87have been merged into the [chromiumos/platform/crosvm] repository. 88 89The merge will also contain all `BUG=` references that will notify your bugs about when the change 90is submitted. 91 92For more details on the process, please see [go/crosvm-uprev-playbook] (Googlers only). 93 94## Cq-Depend 95 96**We cannot support Cq-Depend** to sychronize changes with other ChromeOS repositories. Please try 97to make changes in a backwards compatible way to allow them to be submitted independently. 98 99If it cannot be avoided at all, please follow this process: 100 1011. Upload your change to upstream crosvm and get it reviewed. Do not submit it yet. 1021. Upload the change to [chromiumos/platform/crosvm] as well. 1031. Use Cq-Depend on the ChromeOS changes and submit it via the CQ. 1041. After the changes landed in ChromeOS, land them upstream as well. 105 106## Cherry-picking 107 108### Cherry-picking without the usual merge process 109 110If you need your changes faster than the usual merge frequency, please follow this process: 111 1121. Upload and submit your change to upstream crosvm. 1131. Upload the change to [chromiumos/platform/crosvm] as well. 1141. Submit as usual through the CQ. 115 116**Never** submit code just to ChromeOS, as it will cause upstream to diverge and result in merge 117conflicts down the road. 118 119### Cherry-picking to release branch 120 121Your change need to be merged into [chromiumos/platform/crosvm] to cherry-pick it to a release 122branch. You should follow 123[ChromiumOS Merge Workflow](https://www.chromium.org/chromium-os/developer-library/guides/development/work-on-branch/) 124to cherry-pick your changes. Since changes are merged from [crosvm/crosvm] to 125[chromiumos/platform/crosvm] through [the merge process](#the-merge-process), you can't use gerrit 126to cherry-pick your changes but need to use git command locally. 127 128``` 129$ cd chromiumos/src/platform/crosvm 130$ git branch -a | grep remotes/cros/release-R120 131 remotes/cros/release-R120-15662.B 132$ git checkout -b my-cherry-pick cros/release-R120-15662.B 133$ git cherry-pick -x $COMMIT 134$ git push cros HEAD:refs/for/release-R120-15662.B 135``` 136 137`$COMMIT` is the commit hash of the original change you want to cherry-pick not the merge commit. 138Note that you push to special gerrit `refs/for/`, not pushing directly to the release branch. 139 140Also note that release branch cherry picks don't get CQ tested at all - they are submitted directly 141once you CQ+2 - so it is very important to test locally first. 142 143## Running a Tryjob 144 145For googlers, see go/cdg-site 146 147[chromiumos/platform/crosvm]: https://chromium.googlesource.com/chromiumos/platform/crosvm 148[crosvm/crosvm]: https://chromium.googlesource.com/crosvm/crosvm 149[go/crosvm-uprev-playbook]: http://go/crosvm-uprev-playbook 150