blob: 89c9024f9336a27ce9f609e03a1ec30e229eeb0c [file] [log] [blame] [view]
# Getting Started
[TOC]
## Checking out the repository
For building ChromeOS with Bazel, use the following `repo` command to check out
with a few additional repositories.
```sh
$ mkdir ~/chromiumos
$ cd ~/chromiumos
# If you have access to the internal manifests:
$ repo init -u https://chrome-internal.googlesource.com/chromeos/manifest-internal -g default,bazel -b snapshot
# Otherwise:
$ repo init -u https://chromium.googlesource.com/chromiumos/manifest -g default,bazel -b snapshot
$ repo sync -c -j 16
$ cd src
```
- `-g default,bazel` is important to check out some additional repositories
needed to build with Bazel.
- We use the `snapshot` branch rather than `main` because Bazel's caching logic
requires all inputs to match exactly, so you're better off working from the
`snapshot` branch that was already built by the Snapshot/CQ builders rather
than working from `main` and picking up whatever commit happened to be at ToT
at the time you ran `repo sync`. You'll be at most 40 minutes behind ToT, and
you'll have the best chance of getting cache hits to speed your builds.
- It's safe to run the `repo init` command atop an existing checkout.
Unless otherwise specified, examples in this doc assume that your current
directory is `~/chromiumos/src`.
## One-time setup
First, enter the CrOS SDK chroot with `cros_sdk` command, which will create a
new one if you haven't already. Then run the following command to create the
`amd64-host` sysroot.
```sh
(cr) $ /mnt/host/source/chromite/shell/create_sdk_board_root --board amd64-host --profile sdk/bootstrap
```
This will create `/build/amd64-host`. This sysroot contains the Portage
configuration that is used when building host tool packages. i.e., [CBUILD].
You can then proceed to create the target board's sysroot:
```sh
(cr) $ setup_board --board amd64-generic --public
```
If you're attempting to build a public image while using an internal manifest,
the `--public` flag allows you to do that, which is useful when attempting to
recreate a CQ/Snapshot failure for build targets that use public manifests on
the CI bots, such as amd64-generic. Omit the flag if you do want to build
internal packages.
[CBUILD]: https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Introduction#Toolchain_tuples
## Building ChromeOS packages with `cros build-packages`
Now that you have configured your chroot, you can invoke a build with the
standard `cros build-packages` command, except that you need to pass the extra
option `--bazel` to build with Bazel.
To build a single Portage package, e.g. `sys-apps/attr`:
```sh
$ cros build-packages --board=amd64-generic --bazel sys-apps/attr
```
To build all packages included in the ChromeOS test image:
```sh
$ cros build-packages --board=amd64-generic --bazel
```
Upon successful completion, packages are installed to the sysroot inside the
CrOS SDK chroot, so you can use other commands expecting built packages to be in
the sysroot, e.g. `cros build-image` and `cros deploy`.
## Building ChromeOS packages directly with Bazel
You can alternatively run Bazel directly to build certain targets.
*** promo
Currently you need to use `/mnt/host/source/chromite/bin/bazel` instead of
`/usr/bin/bazel` that is found first on the standard `$PATH`.
***
The syntax for specifying a Portage package is:
```
@portage//<host|target>/<category>/<package>
```
`host` means the build host ([CBUILD]), and `target` means the cross-compiled
target ([CHOST]) specified by the `BOARD` environment variable.
Now you're ready to start building. To build a single Portage package, e.g.
`sys-apps/attr`:
```sh
$ BOARD=amd64-generic /mnt/host/source/chromite/bin/bazel build @portage//target/sys-apps/attr
```
To build all packages included in the ChromeOS base image:
```sh
$ BOARD=amd64-generic /mnt/host/source/chromite/bin/bazel build @portage//target/virtual/target-os:package_set
```
A `package_set` is a special target that also includes the target's [PDEPEND]s.
To build a package for the host, use the `host` prefix:
```sh
$ BOARD=amd64-generic /mnt/host/source/chromite/bin/bazel build @portage//host/app-shells/bash
```
To build all packages included in the ChromeOS test image:
```sh
$ BOARD=amd64-generic /mnt/host/source/chromite/bin/bazel build @portage//target/virtual/target-os:package_set @portage//target/virtual/target-os-dev:package_set @portage//target/virtual/target-os-test:package_set
```
*** note
When you build packages directly with `bazel build`, packages are not installed
to the sysroot, which means that you can't use built packages with existing
tools like `cros deploy`. Use `cros build-packages --bazel` instead if you want
to install packages to the sysroot after they're built by Bazel.
***
[CBUILD]: https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Introduction#Toolchain_tuples
[CHOST]: https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Introduction#Toolchain_tuples
[PDEPEND]: https://devmanual.gentoo.org/general-concepts/dependencies/#post-dependencies
## Building ChromeOS images
You can simply run `cros build-image` to build ChromeOS images if you use
`cros build-packages --bazel` to build ChromeOS packages included in ChromeOS
images.
## Tips
### Bazel remote caching with RBE
You can speed up the build by enabling remote Bazel caching with RBE.
To do this, follow [this instruction](https://www.chromium.org/chromium-os/developer-library/guides/development/developer-guide/#authenticate-for-remote-bazel-caching-with-rbe-if-applicable)
to authenticate.
After authentication, make sure that you restart the Bazel instance by running
`bazel shutdown`.
### Using reclient for faster build
Building `chromeos-base/chromeos-chrome` takes 2-3 hours, but you can use reclient
to make it as fast as less than 1 hour.
To use reclient, please run `gcloud auth application-default login` for
authentication. If you're going to run `bazel build` inside the chroot, please
make sure that you run this outside the chroot after exiting the chroot in all
existing windows.
After authentication, you can just run `bazel build` with `USE_REMOTEEXEC=true`
to enable reclient.
```
$ USE_REMOTEEXEC=true BOARD=amd64-generic bazel build @portage//chromeos-base/chromeos-chrome
```
You can also run `build_packages` with `--run_remoteexec` to run it with reclient.
```
$ build_packages --bazel --board=amd64-generic --run_remoteexec
```
### Enabling @portage tab completion
By default you can't tab complete the `@portage//` repository. This is because
bazel doesn't provide support for tab completing external repositories. By
setting `export ENABLE_PORTAGE_TAB_COMPLETION=1` in your `.bashrc`/`.profile`,
`bazel` will create a `@portage` symlink in the workspace root (i.e.,
`~/chromiumos/src`). This allows the bazel tab completion to work, but comes
with one caveat. You can no longer run `bazel build //...` because it will
generate analysis errors. This is why this flag is not enabled by default.
The `@portage` symlink has another added benefit, you can easily browse the
generated `BUILD.bazel` files.