This workflow allows you to quickly build/deploy Chrome to a Chrome OS VM or device without needing a Chrome OS source checkout or chroot. It‘s useful for trying out your changes on Chrome OS while you’re doing Chrome development. If you have an OS checkout and want your local Chrome changes to be included when building a full OS image, see the OS development guide.
At its core is the chrome-sdk
shell which sets up the shell environment and fetches the necessary SDK components (Chrome OS toolchain, sysroot, VM, etc.).
Label | Paths, files, and commands |
---|---|
(shell) | outside the chroot and SDK shell on your workstation |
(sdk) | inside the chrome-sdk SDK shell on your workstation |
(chroot) | inside the cros_sdk chroot on your workstation |
(device) | in your VM or Chrome OS device |
Check out a copy of the Chrome source code and depot_tools. Be certain to update .gclient to include target_os = ["chromeos"]
.
In order to sign in to Chrome OS you must have Google API keys:
out_$BOARD/Release/args.gn file
, see below.src-internal
in your .gclient
file the official API keys will be set up automatically.Use depot_tools/gsutil.py and run gsutil.py config
to set the authentication token. (Googlers: Use your @google.com account.) Otherwise steps below may run slowly and fail with “Login Required” from gsutil.
When prompted for a project ID, enter 134157665460
(this is the Chrome OS project ID).
The easiest way to develop on Chrome OS is to use a VM.
If you need to test hardware-specific features such as graphics acceleration, bluetooth, mouse or input events, etc, you may also use a physical device (Googlers: Chromestop has the hardware). See Set up the Chrome OS device for details.
Building Chrome for Chrome OS requires a toolchain customized for each Chromebook model (or “board”). For the Chrome OS VM, and non-Googlers, use amd64-generic
. For a physical device, look up the Chrome OS board name by navigating to the URL about:version
on the device. For example: Platform 10176.47.0 (Official Build) beta-channel samus
has board samus
.
To enter the Simple Chrome environment, run these from within your Chrome checkout:
(shell) cd /path/to/chrome/src (shell) export BOARD=amd64-generic (shell) cros chrome-sdk --board=$BOARD --log-level=info [--download-vm]
The command prompt will change to look like (sdk $BOARD $VERSION)
.
Entering the Simple Chrome environment does the following:
--nogoma
).--download-vm
will download a Chrome OS VM and a QEMU binary.Non-Googlers: Only generic boards have publicly available SDK downloads, so you will need to use a generic board (e.g. amd64-generic) or your own Chrome OS build (see Using a custom Chrome OS build). For more info and updates star crbug.com/360342.
--nogn-gen
Do not run ‘gn gen’ automatically.--gn-extra-args='extra_arg=foo other_extra_arg=bar'
For setting extra gn args, e.g. ‘dcheck_always_on = true’.--internal
Sets up Simple Chrome to build and deploy the official Chrome instead of Chromium.--log-level=info
Sets the log level to ‘info’ or ‘debug’ (default is ‘warn’).Important: When you sync/update your Chrome source, the Chrome OS SDK version (src/chromeos/CHROMEOS_LKGM) may change. When the SDK version changes you may need to exit and re-enter the Simple Chrome environment to successfully build and deploy Chrome.
Note: See also Using a custom Chrome OS build.
To build Chrome, run:
(sdk) autoninja -C out_${SDK_BOARD}/Release chrome chrome_sandbox nacl_helper
Note: Targets other than chrome, chrome_sandbox, nacl_helper or (optionally) chromiumos_preflight are not supported in Simple Chrome and will likely fail. browser_tests should be run outside the Simple Chrome environment. Some unit_tests may be built in the Simple Chrome environment and run in the Chrome OS VM. For details, see Running a Chrome Google Test binary in the VM.
Note: Simple Chrome uses Goma. To watch the build progress, find the Goma port (
$ echo $SDK_GOMA_PORT
) and open http://localhost:<port_number> in a browser.
Note: The default extensions will be installed by the test image you use below.
You need the following:
Before you can deploy your build of Chrome to the device, it needs to have a “test” OS image loaded on it. A test image has tools like rsync that are not part of the end-user image.
Chrome should be deployed to a recent Chrome OS test image, ideally the version shown in your SDK prompt (or (sdk) echo $SDK_VERSION
).
Googlers: Images for all boards are available on go/goldeneye:
Non-Googlers: The build infrastructure is currently in flux. See crbug.com/360342 for more details. You may need to build your own Chrome OS image.
After you download the compressed tarball containing the test image (it should have “test” somewhere in the file name), extract the image by running:
(sdk) tar xvf ~/Downloads/<image-you-downloaded>
Copy the image to your USB stick using cros flash
:
(sdk) cros flash usb:// chromiumos_test_image.bin
Tip: If you have a Chrome OS checkout, the following can be used to update a device that already has a test image installed. Star crbug.com/403086 for updates on a proposal to support this without a Chrome OS checkout.
.../chromeos/src $ cros flash $IP_ADDR chromiumos_test_image.bin
You can skip this section if you're using a VM.
Note: Switching to dev mode wipes all data from the device (for security reasons).
Most recent devices can use the generic instructions. To summarize:
From this point on you'll always see the white screen when you turn on the device. Press Ctrl-D to boot.
Older devices may have device-specific instructions.
Googlers: If the device asks you to “enterprise enroll”, click the X in the top-right of the dialog to skip it. Trying to use your google.com credentials will result in an error.
By default Chromebooks will not boot off a USB stick for security reasons. You need to enable it.
root
(no password yet, there will be one later)enable_dev_usb_boot
Note: Do not log into this test image with a username and password you care about. The root password is public (“test0000”), so anyone with SSH access could compromise the device. Create a test Gmail account and use that.
chronos
, password test0000
./usr/sbin/chromeos-install
poweroff
You can now unplug the USB stick.
Use your USB-to-Ethernet adapter to connect the device to a network.
Googlers: You can use a corp Ethernet jack, which will place you on a special restricted network.
i
symbol in the lower-right cornerYou can also run ifconfig
from the terminal (Ctrl-Alt-F2).
To deploy the build to a device/VM, you will need direct SSH access to it from your computer. The scripts below handle everything else.
The deploy_chrome
script uses rsync to incrementally deploy Chrome to the device/VM.
Specify the build output directory to deploy from using --build-dir
. For the VM:
(sdk) deploy_chrome --build-dir=out_${SDK_BOARD}/Release \ --to=localhost --port=9222
For a physical device, which must be ssh-able as user ‘root’, you must specify the IP address using --to
:
(sdk) deploy_chrome --build-dir=out_${SDK_BOARD}/Release --to=$IP_ADDR
Note: The first time you run this you will be prompted to remove rootfs verification from the device. This is required to overwrite /opt/google/chrome and will reboot the device. You can skip the prompt with
--force
.
It is also possible to deploy Chrome to the user partition of the device and set up a temporary mount from /opt/google/chrome
using the option --mount
. This is useful when deploying a binary that will not otherwise fit on the device, e.g.:
--nostrip
to provide symbols for backtraces.(sdk) deploy_chrome --build-dir=out_$SDK_BOARD/Release --to=$IP_ADDR --mount \ [--nostrip]
Note: This also prompts to remove rootfs verification so that /etc/chrome_dev.conf can be modified (see Command-line flags and environment variables). You can skip that by adding
--noremove-rootfs-verification
.
findmnt /opt/google/chrome
. The output should be:TARGET SOURCE FSTYPE OPTIONS /opt/google/chrome /dev/sda1[/deploy_rootfs/opt/google/chrome] ext4 rw,nodev,noatime,resgid=20119,commit=600,data=ordered
mkdir /home/chrome
rm -R /opt/google/chrome
ln -s /home/chrome /opt/google/chrome
deploy_chrome --build-dir=out_${SDK_BOARD}/Release --to=$IP_ADDR --nostrip
deploy_chrome
lives under $CHROME_DIR/src/third_party/chromite/bin
. You can run deploy_chrome
outside of a chrome-sdk
shell.In order to keep Chrome and Chrome OS in sync, the Chrome OS test image should be updated weekly. See Create a bootable USB stick for a tip on updating an existing test device if you have a Chrome OS checkout.
Chrome-related logs are written to several locations on the device:
/var/log/ui/ui.LATEST
contains messages written to stderr by Chrome before its log file has been initialized./var/log/chrome/chrome
contains messages logged by Chrome before a user has logged in./home/chronos/user/log/chrome
contains messages logged by Chrome after a user has logged in./var/log/messages
contains messages logged by session_manager
(which is responsible for starting Chrome), in addition to kernel messages when a Chrome process crashes.If you want to tweak the command line of Chrome or its environment, you have to do this on the device itself.
Edit the /etc/chrome_dev.conf
(device) file. Instructions on using it are in the file itself.
This step is only necessary if you run cros chrome-sdk
with --nogn-gen
.
To create a GN build directory, run the following inside the chrome-sdk shell:
(sdk) gn gen out_$SDK_BOARD/Release --args="$GN_ARGS"
This will generate out_$SDK_BOARD/Release/args.gn
.
--args
, otherwise your build will not work on the device.gn gen
once within the same cros chrome-sdk
session.$GN_ARGS
might change and you need to gn gen
again.You can edit the args with:
(sdk) gn args out_$SDK_BOARD/Release
You can replace Release
with Debug
(or something else) for different configurations. See Debug builds.
GN build configuration discusses various GN build configurations. For more info on GN, run gn help
on the command line or read the quick start guide.
For cros chrome-sdk GN configurations, Release is the default. A debug build of Chrome will include useful tools like DCHECK and debug logs like DVLOG. For a Debug configuration, specify --args="$GN_ARGS is_debug=true is_component_build=false"
.
Alternately, you can just turn on DCHECKs for a release build. You can do this with --args="$GN_ARGS dcheck_always_on=true"
.
To deploy a debug build you need to add --nostrip
to deploy_chrome
because otherwise it will strip symbols even from a debug build. This requires Deploying Chrome to the user partition.
Note: If you just want crash backtraces in the logs you can deploy a release build with
--nostrip
. You don't need a debug build (but you still need to deploy to a user partition).Note: You may hit
DCHECKs
during startup time, or when you login, which eventually may reboot the device. You can check log files in/var/log/chrome
or/home/chronos/user/log
.You can create
/run/disable_chrome_restart
to prevent a restart loop and investigate.You can temporarily disable these
DCHECKs
to proceed, but please file a bug for suchDCHECK
because it's most likely a bug.
Core dumps are disabled by default. See additional debugging tips for how to enable core files.
On the target machine, open up a port for the gdb server to listen on, and attach the gdb server to the top-level Chrome process.
(device) sudo /sbin/iptables -A INPUT -p tcp --dport 1234 -j ACCEPT (device) sudo gdbserver \ --attach :1234 $(pgrep chrome -P $(pgrep session_manager))
On your host machine (inside the chrome-sdk shell), run gdb and start the Python interpreter:
(sdk) cd %CHROME_DIR%/src (sdk) gdb out_${SDK_BOARD}/Release/chrome Reading symbols from /usr/local/google2/chromium2/src/out_amd64-generic/Release/chrome... (gdb) pi >>>
Note: These instructions are for targeting an x86_64 device. For now, to target an ARM device, you need to run the cross-compiled gdb from within a chroot.
Then from within the Python interpreter, run these commands:
import os sysroot = os.environ['SYSROOT'] board = os.environ['SDK_BOARD'] gdb.execute('set sysroot %s' % sysroot) gdb.execute('set solib-absolute-prefix %s' % sysroot) gdb.execute('set debug-file-directory %s/usr/lib/debug' % sysroot) # "Debug" for a debug build gdb.execute('set solib-search-path out_%s/Release/lib' % board) gdb.execute('target remote $IP_ADDR:1234')
If you wish, after you connect, you can Ctrl-D out of the Python shell.
Extra debugging instructions are located at debugging tips.
When you invoke cros chrome-sdk
, the script fetches the version of the SDK that corresponds to your Chrome checkout. To update the SDK, sync your Chrome checkout and re-run cros chrome-sdk
.
IMPORTANT NOTES:
You can specify a version of Chrome OS to build against. This is handy for tracking down when a particular bug was introduced.
(shell) cros chrome-sdk --board=$BOARD --version=11005.0.0
Once you are finished testing the old version of the chrome-sdk, you can always start a new shell with the latest version again. Here's an example:
(shell) cros chrome-sdk --board=$BOARD --clear-sdk-cache
(sdk) exit (shell) git checkout master && git pull # (or if you prefer, git rebase-update) (shell) gclient sync (shell) cros chrome-sdk --board=$BOARD --log-level=info
Tip: If you update Chrome inside the chrome-sdk, you may then be using an SDK that is out of date with the current Chrome. See Updating the version of the Chrome OS SDK section above.
deploy_chrome
determines which files to copy in chrome_util.py
in the chromite repo which is pulled into chrome/src/third_party/chromite
via DEPS.
When updating the list:
_COPY_PATHS_CHROME
).If you are making changes to Chrome OS and have a Chrome OS build inside a chroot that you want to build against, run cros chrome-sdk
with the --chroot
option:
(shell) cros chrome-sdk --board=$BOARD --chroot=/path/to/chromiumos/chroot
cros flash
with xbuddy
will automatically download an image and write it to USB for you. It's very convenient, but for now it requires a full Chrome OS checkout and must be run inside the Chrome OS chroot. (issue 437877)
(chroot) cros flash usb:// xbuddy://remote/$BOARD/<version>/test
Replace $BOARD
and <version>
with the right values. Both can be seen in your SDK prompt (e.g. (sdk lumpy R27-3789.0.0)
is the lumpy board using version R27-3789.0.0).
See the Cros Flash page for more details.
By default, cros chrome-sdk prepends something like ‘(sdk link R52-8315.0.0)
’ to the prompt (with the version of the prebuilt system being used).
If you prefer to colorize the prompt, you can set PS1
in ~/.chromite/chrome_sdk.bashrc
, e.g. to prepend a yellow ‘(sdk link 8315.0.0)
’ to the prompt:
PS1='\[\033[01;33m\](sdk ${SDK_BOARD} ${SDK_VERSION})\[\033[00m\] \w \[\033[01;36m\]$(__git_ps1 "(%s)")\[\033[00m\] \$ '
NOTE: Currently the release version (e.g. 52) is not available as an environment variable.
The legacy GYP
build system is no longer supported.