|author||Matt Stark <firstname.lastname@example.org>||Wed Jun 07 16:37:03 2023 +1000|
|committer||Chromeos LUCI <email@example.com>||Mon Jun 19 23:58:38 2023 +0000|
Rename cros_pkg's example to examples/packaging. BUG=None TEST=tools/run_tests.sh Change-Id: If68b3ae79b5830c6554ef92ad43f4a05d868acb0 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/bazel/+/4624236 Reviewed-by: Ryo Hashimoto <firstname.lastname@example.org> Tested-by: Matt Stark <email@example.com> Commit-Queue: Matt Stark <firstname.lastname@example.org>
This repository provides the implementation to build ChromeOS with Bazel.
Building ChromeOS with Bazel is currently possible only on a special branch for Bazel development. Use the following
repo command to check out the branch with a few additional repositories.
$ mkdir ~/chromiumos $ cd ~/chromiumos $ repo init -u https://chrome-internal.googlesource.com/chromeos/manifest-internal -b stabilize-15429.B -g default,bazel $ repo sync -c -j 4 $ cd src
After checking out, you have to run the following command to create a few necessary symlinks. This is needed only on the first time.
Unless otherwise specified, examples in this doc assume that your current directory is
You need to use a certain version of Bazel for the build to succeed. The current supported Bazel version is denoted in
~/chromiumos/src/.bazelversion. The easiest way to use Bazel of the correct version is to use Bazelisk, which automatically downloads a Bazel binary according to
To install Bazelisk, make sure you have Go toolchain installed, and run the following command:
$ GOBIN=$HOME/go/bin go install github.com/bazelbuild/bazelisk@latest
This command installs bazelisk at
~/go/bin/bazelisk. You‘ll also need to get Bazelisk onto your
PATH, to be executed before any Bazel that’s already on your
PATH, and we‘d like to invoke Bazelisk whenever we run
bazel. Create a symlink to bazelisk in a directory that’ll be on your
PATH before any other bazels, and name the link
$ ln -s ~/go/bin/bazelisk ~/bin/bazel
Now you're ready to start building. To build a single Portage package, e.g. sys-apps/attr:
$ BOARD=amd64-generic bazel build @portage//sys-apps/attr
To build all packages included in the ChromeOS base image:
$ BOARD=amd64-generic bazel build @portage//virtual/target-os:package_set
We have the following targets to build images:
//bazel/images:chromiumos_minimal_image: Minimal image that contains
//bazel/images:chromiumos_base_image: Base image.
//bazel/images:chromiumos_dev_image: Dev image.
//bazel/images:chromiumos_test_image: Test image.
As of June 2023, we primarily test our builds for amd64-generic and arm64-generic. Please file bugs if images don't build for these two boards. Other boards may or may not work (yet).
Building a ChromeOS image takes several hours. Most packages build in a few minutes, but there are several known heavy packages, such as
chromeos-base/chromeos-chrome that takes 2-3 hours. You can inject prebuilt binary packages to bypass building those packages. See Injecting prebuilt binary packages for more details.
After building an image, you can use
cros_vm command available in CrOS SDK to run a VM locally. Make sure to copy an image out from
bazel-bin as it's not writable by default.
$ cp bazel-bin/bazel/images/chromiumos_base_image.bin /tmp/ $ chmod +w /tmp/chromiumos_base_image.bin $ chromite/bin/cros_vm --start --board=amd64-generic --image-path /tmp/chromiumos_base_image.bin
You can use VNC viewer to view the VM.
$ vncviewer localhost:5900
You can also use
cros_vm command to stop the VM.
$ chromite/bin/cros_vm --stop
cmd... misc commands for development
private/... contains programs used by Bazel rules
alchemist... generates a Bazel repository on
cmd/commands internally used in the build
action_wrapper/... the generic wrapper of Bazel actions, handling logs and signals
build_image/... builds ChromeOS images
build_package/... builds a Portage binary package; used by
build_sdk/... builds SDK squashfs; used by
extract_interface/... builds an interface library
fakefs/... simulates chown(2) in unprivileged user namespaces
install_deps/... installs binary packages into an ephemeral SDK
run_in_container/... runs a program within an unprivileged Linux container; used by other programs such as
sdk_from_archive/... creates a base ephemeral SDK from an archive
sdk_update/... updates an ephemeral SDK with patches and packages
common/... common Rust/Go libraries
prebuilts/... defines prebuilt binaries
images/... defines ChromeOS image targets
sdk/... defines the base SDK
tools/... misc small tools for development
workspace_root/... contains various files to be symlinked to the workspace root, including
If a package is failing to build, it‘s sometimes useful to view the package’s work directory. To do this run:
bazel build --sandbox_debug //your/ebuild
In the build output you will see a
cd into the
This directory will contain a directory called
build_package.*. It contains all the artifacts that were generated while building the package.
Build logs can be found in:
The package work dir can be found in:
Sometimes you want to enter an ephemeral CrOS chroot where a package build is failing to inspect the environment interactively.
To enter an ephemeral CrOS chroot, run the following command:
$ BOARD=arm64-generic bazel run @portage//sys-apps/attr:debug -- --login=after
This command will give you an interactive shell after building a package. You can also specify other values to
--login to choose the timing to enter an interactive console:
--login=before: before building the package
--login=after: after building the package
--login=after-fail: after failing to build the package
In the case your work is blocked by some package build failures, you can workaround them by injecting prebuilt binary packages via command line flags.
ebuild target under
@portage//internal/packages/..., an associated string flag target is defined. You can set a
gs:// URL of a prebuilt binary package to inject it.
For example, to inject a prebuilt binary packages for
chromeos-chrome, you can set this option:
We have several named config groupings in prebuilts.bazelrc that define typical options to inject prebuilts. You can specify
--config to use them.
--config=prebuilts/amd64-generic: Injects prebuilt binary packages needed to build amd64-generic images.
In case you need to extract the contents of a binary package so you can easily inspect it, you can use the
xpak split CLI.
bazel run //bazel/ebuild/cmd/xpak:xpak -- split --extract libffi-3.1-r8.tbz2 libusb-0-r2.tbz2
If you'd like to run the tests every time you commit, add the following. You can skip it with
git commit --no-verify.
cd ~/chromiumos/src/bazel ln -s tools/run_tests.sh .git/hooks/pre-commit