IntroductionThis guide describes how to work on Chromium OS. If you want to help develop Chromium OS and you're looking for detailed information about how to get started, you're in the right place. You can also use the quick-start guide instead, which gives just the basic steps that work for most people.
Target audience
The target audience of this guide is anyone who wants to obtain, build, or contribute to Chromium OS. That includes new developers who are interested in the project
and who simply want to browse through the Chromium OS code, as well as developers who have been
working on Chromium OS for a long time.
Organization & contentThis guide describes the common tasks required to develop Chromium OS. The guide is organized linearly, so that developers who are new to Chromium OS can follow the tasks in sequence. The tasks are grouped into the following sections:
Typography conventions
Modifying this document
Only people with @chromium.org accounts can edit this document. Everyone else should post to the Chromium OS dev group.
If you're a Chromium OS developer, YOU SHOULD UPDATE THIS DOCUMENT and fix things as appropriate. There's a "Sign In" text button at the very bottom of this page. Sign in (with your @chromium.org account, of course) and you'll get an "Edit" button at the top of the page. Bias towards action:
Please try to abide by the following guidelines when you modify this document:
Additional information
This document provides an overview of the tasks required to develop Chromium OS. After you've learned the basics, check out the links in the additional information section at the end of this document for tips and tricks, FAQs, and important details (e.g., the Chromium OS directory structure, using the dev server, etc.).
Finally, if you build a Chromium OS image, please read this important note about attribution requirements. PrerequisitesYou must have Linux to develop Chromium OS. Any recent or up-to-date distribution should work. However, we can't support everyone and their dog's Linux distro, so the only official supported environment is listed below. If you encounter issues with other setups, patches are generally welcomed, but please do not expect us to figure out your distro.
Most developers working on Chromium OS are using Precise (the LTS version of Ubuntu). It is possible that things will work if you're running a different Linux distribution, but you will probably find life easier if you're on this one. Please note that Ubuntu 9.10 (Karmic) is known not to work.
i686 32-bit systems might be supported down the road.
You need root access to run the chroot command and to modify the mount table. NOTE: Do not run any of the commands listed in this document as root – the commands themselves will run sudo to get root access when needed.
While it may be technically possible to build with less, linking the browser uses 4GB, and swapping to disk will make the build prohibitively slow.
You will have a much nicer time if you also have:
The build system is optimized to make good use of all processors, and an 8 core machine will build nearly 8x faster than a single core machine. If you are building the full Chromium OS including Chrome (the browser), your machine should have at least 4GB of RAM, and 8GB is better. If you only have 4GB of RAM make sure you have at least 4GB of swap. There have been reports of even getting by with 2GB of RAM on a Linux box not running a GUI.
This will help for the initial download (minimum of about 2GB) and any further updates.
You must also install the following packages to develop Chromium OS (installation instructions are provided below):
Install git, subversion, and curlInstall the git and subversion revision control systems, and the curl download helper. On Ubuntu, the magic incantation to do this is: sudo aptitude install git-core gitk git-gui subversion curlThis command also installs git's graphical front end ( git gui) and revision history browser (gitk).TODO: On Ubuntu 10.04, the git-core version of default apt-get repository is out-dated. You need to upgrade git-core manually to run 'repo sync' successfully (error message ' error: Exited sync due to gc errors'). You may also want to install 'xz-utils'. Install depot_toolsTo get started, follow the instructions at install depot_tools. This step is required so that you can use the repo command to get/sync the source code. Tweak your sudoers configurationYou must tweak your sudoers configuration to turn off the tty_tickets option. This is required for using cros_sdk. Configure gitSetup git now. If you don't do this, you may run into errors/issues later. Replace you@example.com and Your Name with your information:git config --global user.email "you@example.com"git config --global user.name "Your Name"Preparations to submit changesIMPORTANT NOTE: If you are new to Chromium OS, you can skip this step (go to "decide where your source will live"). This is only for people who wish to make changes to the tree. Remember: anyone can post changes to Gerrit for review. Create your ssh keyYou access Gerrit through an ssh-keygen -t rsa -f ~/.ssh/chromiumSetup your Gerrit AccountFollow the instructions here to setup your Gerrit code review account. Remember a @chromium.org account is not required to submit code for review. Automate usage of your key with keychainYou should protect your chromium ssh key with a password, but of course you don't want to type that password all the time. This is where the keychain command can help you. On Ubuntu, install keychain with this command (assumes apt is configured with universe): sudo aptitude install keychain To use the keychain command, add this to the end of your eval `keychain --eval ~/.ssh/chromium`Run the above SIDE NOTES:
Double-check that you are running a 64-bit architectureRun the following command: uname -mYou should see the result: If you see something else (for example, Sources need to be world-readable to properly function inside the chroot (described later). For that reason, the last digit of your umask should not be higher than 2, eg. '002' or '022'. Many distros have this by default, Ubuntu, for instance, does not. It is essential to put the following line into your ~/.bashrc file before you checkout or sync your sources. umask 022You can verify that this works by creating any file and checking if its permissions are correct. $ touch ~/foo$ ls -la ~/foo-rw-r--r-- 1 user group 0 2012-08-30 23:09 /home/user/fooGet the SourceDecide where your source will liveChromium OS developers commonly put their source code in
${HOME}/chromiumos. If you feel strongly, put your own source elsewhere, but note that all commands in this document assume that your source code is in ${HOME}/chromiumos.Create the directory for your source code with this command:
mkdir -p ${HOME}/chromiumosIMPORTANT NOTE: If your home directory is on NFS (as is true for engineers at Google), you must place your code somewhere else. Not only is it a bad idea to build directly from NFS for performance reasons, but builds won't actually work (builds use sudo, and root doesn't have access to your NFS mount, unless your NFS server has the no_root_squash option). Wherever you place your source, you can still add a symbolic link to it from your home directory (this is suggested), like so:
mkdir -p /usr/local/path/to/source/chromiumosln -s /usr/local/path/to/source/chromiumos ${HOME}/chromiumosDecide if you want the minilayoutBefore you get the source code, you must decide whether you want to the "minilayout" or the "full layout". If you are trying things out first time, a full layout is recommended.
You should probably pick the full layout if:
You should probably pick the minilayout if:
Remember: Even if you choose the minilayout, you can still hand pick packages whose source code you want later by using cros_workon.
Get the source codeChromium OS uses repo to sync down source code.
repo is effectively a wrapper for the git version control system that helps deal with a large number of git repositories. You already installed repo when you installed depot_tools above. Run "gclient" without any args if you want to update your existing version of depot_tools. Add the host keys to your known hosts file:
Both of the options below run SSH in a noninteractive shell, which makes accepting their host keys tricky; you won't be able to type "yes" to tell SSH that the key is OK. You can do this step by manually SSHing to the hosts first:
ssh -p 29418 gerrit.chromium.orgYou won't be able to log in to either host, but you'll have an opportunity to add the host keys.
Alternately, you can paste this into your .ssh/known_hosts:
[gerrit.chromium.org]:29418 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCfRn+J+e9mU0c4bxFD8v2rhhd3O9WPk435xEtG9FD8a8fOnIubJcpObvQJhfSgYkxVUQOKk97V8b2eGjf72AGBhDQVJMiaLQc8ZGomeNlK/7cWjkJFDoIKQHilHQidz/pgZc/Pu+7Tl2emVGd6425QRK1h47CYtT9IUPt3Jtdv4w==Optionally add Google API keys:
Secondly, decide whether you need to use features of Chromium that access Google APIs from the image you are building (translate web pages, geolocation, etc). If the answer is yes, you will need to
have keys (see http://www.chromium.org/developers/how-tos/api-keys)
either in your include.gypi, or in a file in your home directory called ".googleapikeys". If either of these file are present for step 1 of building (below) they will be included automatically. If you don't have these keys, these features of chromium will be quietly disabled.Once your keys are settled, choose one of the options below.
Option #1: If you want a copy of the minilayout, enter the following commands:
cd ${HOME}/chromiumos repo init -u https://git.chromium.org/git/chromiumos/manifest.git -g minilayout --repo-url https://git.chromium.org/git/external/repo.gitrepo syncOption #2: If you want a copy of the full layout, enter the following commands:
cd ${HOME}/chromiumosrepo init -u https://git.chromium.org/git/chromiumos/manifest.git --repo-url https://git.chromium.org/git/external/repo.gitrepo syncGooglers: See goto/chromeos-building for internal notes. SIDE NOTES:
When you use
repo init you will be asked to confirm your name, email address, and whether you want color in your terminal. This command runs quickly. The repo sync command takes a lot longer. Building Chromium OSCreate a chrootTo make sure everyone uses the same exact environment and tools to build Chromium OS, all building is done inside a chroot. This chroot is its own little world: it contains its own compiler, its own tools (its own copy of bash, its own copy of sudo), etc. Now that you've synced down the source code, you need to create this chroot. Assuming you're already in
${HOME}/chromiumos (or wherever your source lives), the command to download and install the chroot is:./chromite/bin/cros_sdk
This will download and setup a prebuilt chroot from Chromium OS mirrors (under 400M). If you prefer to rather build it from source, or have trouble accessing the servers, use cros_sdk --bootstrap. Note that this will also enter the chroot. If you prefer to build only, use --download.
The command with --bootstrap takes about half an hour to run on a four core machine. It compiles quite a bit of software, which it installs into your chroot, and downloads some additional items (around 300MB). While it is building you will see a regular update of the number of packages left to build. Once the command finishes, the chroot will take up total disk space of a little over 3GB.
The chroot lives by default at
${HOME}/chromiumos/chroot. Inside that directory you will find system directories like /usr/bin and /etc. These are local to the chroot and are separate from the system directories on your machine. For example, the chroot has its own version of the ls utility. It will be very similar, but it is actually a different binary than the normal one you use on your machine.SIDE NOTES:
Most of the commands that Chromium OS developers use on a day-to-day basis (including the commands to build a Chromium OS image) expect to be run from within the chroot. You can enter the chroot by calling:
./chromite/bin/cros_sdkThis is the same command used to create the chroot, but if the chroot already exists, it will just enter. NOTE: if you want to run a single command in the chroot (rather than entering the chroot), prefix that command with cros_sdk -- .
This command will probably prompt you for your password for the
sudo command (entering the chroot requires root privileges). Once the command finishes, that terminal is in the chroot and you'll be in the ~/trunk/src/scripts directory, where most build commands live. In the chroot you can only see a subset of the filesystem on your machine. However, through some trickery (bind mounts), you will have access to the whole src directory from within the chroot – this is so that you can build the software within the chroot.Note in particular that the
src/scripts directory is the same src/scripts directory as you were in before you entered the chroot, even though it looks like a different location. That's because when you enter the chroot, the ~/trunk directory in the chroot is mounted such that it points to the main Chromium OS directory ${HOME}/chromiumos. That means that changes that you make to the source code outside of the chroot immediately take effect inside the chroot.Calling this will also install a chroot, if you don't have one yet, for example by not following the above.
While in the chroot you will see a special "(cros-chroot)" prompt to remind you that you are there:
(cros-chroot) johnnyrotten@flyingkite ~/trunk/src/scripts $ You generally cannot run programs on your filesystem from within the chroot. For example, if you are using eclipse as an IDE, or gedit to edit a text file, you will need to run those programs outside the chroot. As a consolation, you can use vim. If you are desperate for emacs, try typing
sudo emerge emacs. Of course this command will build emacs from source so allow 5-10mins.IMPORTANT NOTES:
SIDE NOTES:
Select a boardBuilding Chromium OS produces a disk image (usually just called an "image") that can be copied directly onto the boot disk of a computer intended to run Chromium OS. Depending on the specifics of that computer, you may want different files in the disk image. For example, if your computer has an ARM processor, you'll want to make sure that all executables in the image are compiled for the ARM instruction set. Similarly, if your computer has special hardware, you'll want to include a matching set of device drivers.Different classes of computers are referred to by Chromium OS as different target "boards" The following are some example boards:
You need to choose a board for your first build. Don't worry too much about this choice – you can always build for another board later. If you want a list of known boards, you can look in
~/trunk/src/overlays.Each command in the build processes takes a
--board parameter. To facilitate this, it can be helpful to keep the name of the board in a shell variable. This is not strictly necessary, but if you do this, you can simply copy and paste the commands below into your terminal program. Enter the following inside your chroot (note: change x86-generic to whatever board you want to build for):export BOARD=x86-genericThis setting only holds while you stay in the chroot. If you leave and come back, you need to do specify this setting again.
Initialize the build for a boardTo start building for a given board, issue the following command inside your chroot (you should be in the
~/trunk/src/scripts directory):./setup_board --board=${BOARD}This command sets up the board target with a default sysroot of
/build/${BOARD}. The command downloads a small amount of stuff and takes a few minutes to complete.SIDE NOTES:
Set the chronos user passwordOn a Chromium OS computer, you can get command line access (and root access through the
sudo command) by logging in with the shared user account "chronos". You should set a password for the chronos user by entering the command below from inside the ~/trunk/src/scripts directory:./set_shared_user_password.shYou will be prompted for a password, which will be stored in encrypted form in /etc/shared_user_passwd.txt.
SIDE NOTES:
Build the packages for your boardTo build all the packages for your board, run the following command from inside the ~/trunk/src/scripts directory:
./build_packages --board=${BOARD}This step is the rough equivalent of
make all in a standard Makefile system. This command handles incremental builds; you should run it whenever you change something and need to rebuild it (or after you run repo sync). Normally, the build_packages command builds the stable version of a package (i.e. from committed git sources), unless you are working on a package (with
cros_workon). If you are working on a package, build_packages will build using your local sources. See below for information about cros_workon.SIDE NOTES:
Build a disk image for your boardOnce the
build_packages step is finished, you can build a Chromium OS-base developer image by running the command below from inside the ~/trunk/src/scripts directory:./build_image --board=${BOARD} --noenable_rootfs_verification devThe args for build_image specify what type of build you want (dev in the example above). Developers should normally build developer (dev) images. A developer image provides a Chromium OS-based image with additional developer packages. The --noenable_rootfs_verification turns off verified boot allowing you to freely modify the root file system. The system is less secure using this flag, however, for rapid development you may want to set this flag. If you would like a more secure, locked-down version of Chromium OS, then simply remove the --noenable_rootfs_verification flag. Finally if you want just the pristine Chromium OS-based image (closest to Chrome OS but not quite the same), pass in base rather than dev. Use build_image --help for more information.
The image produced by build_image will be located in
~/trunk/src/build/images/${BOARD}/versionNum/ (where versionNum will actually be a version number). The most recent image produced for a given board will be symlinked to ~/trunk/src/build/images/${BOARD}/latest.IMPORTANT NOTE: It's up to you to delete old builds that you don't need. Every time you run
build_image, the command creates files that take up over 4GB of space(!).Look at your disk image (optional)The preferred way to mount the image you just built to look at it's contents is: ./mount_gpt_image.sh --board=${BOARD} -f $(./get_latest_image.sh --board=${BOARD}) Again, don't forget to unmount the root filesystem when you're done: ./mount_gpt_image.sh --board=${BOARD} -u Optionally, you can unpack the partition as separate files and mount them directly: cd ~/trunk/src/build/images/${BOARD}/latest./unpack_partitions.sh chromiumos_image.binmkdir -p rootfssudo mount -o loop,ro part_3 rootfsIf you built with "--noenable_rootfs_verification" you can omit the "ro" option to mount to mount it read write.
If you built an x86 Chromium OS image, you can probably even try chrooting into the image:
sudo chroot ~/trunk/src/build/images/${BOARD}/latest/rootfsThis is a little hacky (the Chromium OS rootfs isn't really designed to be a chroot for your host machine), but it seems to work pretty well. Don't forget to
exit this chroot when you're done.sudo umount ~/trunk/src/build/images/${BOARD}/latest/rootfs
Installing Chromium OS on your DeviceGetting your image running on a computer without verified bootIf you are trying to run your image on a normal computer, laptop, or netbook (one that didn't come installed with Google Chrome OS), follow the instructions in this section. Said another way:
Put your image on a USB diskThe easiest way to get your image running on your target computer is to put the image on a USB flash disk (sometimes called a USB key), and boot the target computer from the flash disk. The first step is to insert a USB flash disk (4GB or bigger) into your build computer. This disk will be completely erased, so make sure it doesn't have anything important on it. Wait ~10 seconds for the USB disk to register, then type the following command in the ~/trunk/src/scripts directory:
./image_to_usb.sh --board=${BOARD}Since you didn't pass a --to parameter, the image_to_usb.sh command lists all the USB disks that it finds. If your USB disk is not listed, wait a few seconds and try the command again. Note that your USB disk may show up as something like
/dev/sdc. Once the command finds your USB disk, run the command again with the --to parameter (you should replace ${MY_USB_KEY_LOCATION} with the location for your disk, like /dev/sdc):./image_to_usb.sh --board=${BOARD} --to=${MY_USB_KEY_LOCATION}When the image_to_usb.sh command finishes, you can simply unplug your USB key and it's ready to boot from.
IMPORTANT NOTE: To emphasize again, image_to_usb.sh completely replaces the contents of your USB disk. Make sure there is nothing important on your USB disk before you run this command.
SIDE NOTES:
Boot from your USB diskYou should be able to configure your target computer's BIOS to boot from your USB key. After you've done that, simply plug in your newly minted USB key and reboot your target computer – it should now boot from the Chromium OS image on your USB key. Your Chromium OS image may not have all the drivers to run all of the peripherals on your computer, but it should at least boot.
For specific information about what works on various different machines, see the Developer Hardware page.
A quick primer on verified bootYou must understand a bit about verified boot before you can go any further. Unless you crack open the hardware on your notebook (which probably voids any warranty you might have), having a computer with verified boot means:
If you're quick, then you've probably figured out that one way to boot your image on your device is:
Let's go through that one step at a time.
Get your Chrome OS Notebook into Developer ModeThis is different for each computer, but it usually involves flipping a switch that's under the battery (and sometimes also under a sticker). You'll want to reference the documentation for your Chrome OS Notebook.
SIDE NOTE: Switching into Developer Mode does a lot of stuff (erasing your stateful partition, disabling some of the checks that make sure you're running official code, etc). See the documentation for your Chrome OS Notebook for details.
Get an officially-signed Recovery Kernel for your Chrome OS NotebookThe recovery key is different for every version of Chrome OS Notebook, which means you'll need to get a different Recovery Kernel for the type of Chrome OS Notebook you have. You might be able to find a link to download a Recovery Kernel in the documentation for your Chrome OS Notebook. If not, you might be able to extract an officially-signed Recovery Kernel from an officially-signed Recovery Image (Recovery Images are sometimes easier to find).
As an example, you can get an officially-signed Recovery Kernel for the Cr-48 Chromebook (AKA Mario) by running the steps below from inside the chroot:
curl https://dl.google.com/dl/edgedl/chromeos/recovery/mario_recovery_kernel.zip > ~/trunk/mario_recovery_kernel.zipunzip -d ~/trunk ~/trunk/mario_recovery_kernel.zipRECOVERY_KERNEL=~/trunk/mario_recovery_kernel.binThe instructions below assume that you've set the
RECOVERY_KERNEL variable as above.Now that you have a built image and an officially-signed Recovery Kernel, you can build your own recovery image using
mod_image_for_recovery.sh. This image will have the officially-signed Recovery Kernel (so you can boot from USB) and will install a self-signed SSD image (so you can boot only with developer mode). Here's the magic set of steps (assuming that you've got a path to the recovery kernel in ${RECOVERY_KERNEL} and that the recovery kernel is a match for the ${BOARD} you built):./mod_image_for_recovery.sh \ --board=${BOARD} \ --nominimize_image \ --kernel_image ${RECOVERY_KERNEL} \ --image ~/trunk/src/build/images/${BOARD}/latest/chromiumos_image.binSIDE NOTE: If you're interested in creating a test image (used for allowing Chromium OS to talk to autotest), you can run build_image test to create a test image that can be combined with the recovery image:
./build_image --board=${BOARD} test
./mod_image_for_recovery.sh \
--board=${BOARD} \ --nominimize_image \ --kernel_image ${RECOVERY_KERNEL} \ --image ~/trunk/src/build/images/${BOARD}/latest/chromiumos_test_image.binCopy the recovery image to a USB key
The first step is to insert a USB flash disk (4 GB or bigger) into your build computer. This disk will be completely erased, so make sure it doesn't have anything important on it. Wait ~10 seconds for the USB disk to register, then type the following command in the ~/trunk/src/scripts directory:
./image_to_usb.sh --board=${BOARD}Since you didn't pass a --to parameter, the image_to_usb.sh command
lists all the USB disks that it finds. If your USB disk is not listed,
wait a few seconds and try the command again. Note that your USB disk
may show up as something like
/dev/sdc. Once the command finds your USB disk, run the command again with the --to parameter (you should replace ${MY_USB_KEY_LOCATION} with the location for your disk, like /dev/sdc):./image_to_usb.sh --board=${BOARD} --image_name=recovery_image.bin --to=${MY_USB_KEY_LOCATION}When the image_to_usb.sh command finishes, you can simply unplug your USB key and it's ready to boot from.
IMPORTANT NOTE: To emphasize again, image_to_usb.sh
completely replaces the contents of your USB disk. Make sure there is
nothing important on your USB disk before you run this command.
SIDE NOTES:
Install your image to the SSDIn developer mode, your Chrome OS Notebook gives you an option to use a recovery image every time the machine boots. To install your recovery image, do the following:
If you reboot now, you'll be booting from your image (you may need to wait past the recovery screen). Congratulations!
IMPORTANT NOTE: You must stay in Developer Mode to continue booting your image. Since your image was not signed by the release keys (it's self-signed image), it will only boot in Developer Mode. If you want to go back to Release Mode, just copy (/bin/dd) a recovery image directly to a USB drive, without making any modifications to it.
Getting to a command prompt on Chromium OSSince you set the shared user password (with set_shared_user_password.sh) when you built your image, you have the ability to login as the chronos user:
Because you built an image with developer tools, you also have an alternate way to get a terminal prompt. The alternate shell is a little nicer (in the very least, it keeps your screen from dimming on you), even if it is a little harder to get to. To use this alternate shell:
Installing your Chromium OS image to your hard diskIf you followed the set of instructions for a Chrome OS Notebook, the image is already on your hard disk. However, if you booted Chromium OS straight from a USB key, you might want to put your image onto the hard disk.
Once you've booted from your USB key and gotten to the command prompt, you can install your Chromium OS image to the hard disk on your computer with this command:
/usr/sbin/chromeos-installIMPORTANT NOTE: Installing Chromium OS onto your hard disk will WIPE YOUR HARD DISK CLEAN.
Building an image to run in a virtual machineMany times it is easier to simply run Chromium OS in a virtual machine like kvm. You can adapt the previously built Chromium OS image so that it is usable by
kvm (which uses qemu images) by entering this command from the ~/trunk/src/scripts directory:./image_to_vm.sh --board=${BOARD}This command creates the file ~/trunk/src/build/images/${BOARD}/latest/chromiumos_qemu_image.bin.
SIDE NOTES:
Making changes to packages whose source code is checked into Chromium OS git repositories
|
In your local commit logs make sure to add a | Option | Description |
| -clang | Invoke Clang front-end with -fsyntax-only and all other options specified on the command line. On successful completion of Clang compile, continue the build with gcc or g++. The presence of '-print-*', '-dump*', '@*', '-E', '-' or '-M' will disable clang invocation. |
| -Xclang-only=<option> | This is a special option that can be used to pass <option> to Clang and not to gcc or g++. This can be used, for example, to turn off a specific Clang warning. Example: -Xclang-only=-Wno-c++11-extensions will add -Wno-c++11-extensions to the Clang invocation. |
| -print-cmdline | In addition to doing the builds, print the exact command-line used for both Clang and gcc. |
You can test your package with Clang before adding '-clang' to your ebuild or Makefiles using the CFLAGS or CXXFLAGS variable. While using this, you need to be careful not to overwrite existing CFLAGS or CXXFLAGS. Here's an example:
(cr) $ CFLAGS="$(portageq-$board envvar CFLAGS) -clang" CXXFLAGS="$(portageq-$board envvar CXXFLAG) -clang" emerge-$board chromeos-chrome
After your package builds cleanly with Clang, you can add '-clang' to your e-build.
Local Debugging
Debugging x86 binaries on your workstation.
If you build your projects incrementally, write unit tests and use them to drive your development, you may want to debug your code without shipping it over to a running device or VM.gdb_x86_local sets gdb up to load and run your target-compiled binaries.
(cr) ~/trunk/src/platform/shill $ gdb_x86_local -h
USAGE: /usr/bin/gdb_x86_local [flags] argsflags: --board: The board to debug for. (default: '') --sysroot: Where your target binaries are. (default: '') --debug_file_dir: Where your split-out debug symbols are. (default: '') -h,--[no]help: show this help (default: false)"--board" is required, the other args are not. The following will start gdb with your incrementally-compiled unittest binary.
(cr) ~/trunk/src/platform/shill $ gdb_x86_local --board x86-generic shill_unittest [corefile]Remote Debugging
Setting up remote debugging by hand.
If you want to manually run through all the steps necessary to set up your system for remote debugging and start the debugger, see Remote Debugging in Chromium OS.Automated remote debugging using gdb_remote script.
gdb_remote is a script that automates many of the steps necessary for setting up remote debugging with gdb. It should already be installed in your chroot. If you do not have the script, update your repository to get the latest changes, then re-build your packages:repo sync./build_packages --board=...
This should install gdb_remote in the /usr/bin directory inside the chroot. The gdb_remote script takes several options. --board and --remote_file are required, the rest are optional:
"--remote" is the ip_address for your VM or notebook. It defaults to the localhost (for running the VM); if you are not debugging in the VM, then you need to specify the ip_address of the notebook you are using.
"--port" is the ssh port that will be used for communication between gdb and gdbserver. It defaults to 1234, but you can specify another port number to use if you wish.
"--remote_file" is the complete pathname, on the notebook or in the VM, of the binary to be debugged.
"--remote_pid" defaults to 0, which means gdbserver will start the specified binary running; if you want to attach to an already running binary (e.g. chrome), you need to specify the PID of the running binary (in the VM or notebook) to which to attach. The --remote_file parameter is not required if --remote_pid is passed.
When you invoke gdb_remote, it will connect to the notebook or VM (automatically setting up port-forwarding on the VM), make sure the port is entered into the iptables, and start up gdbserver, using the specified port and binary, either attaching to the binary (if a remote_pid was specified) or starting up the binary, and waiting for gdb to connect.
It will then write a special .gdbinit file for you that sets up the sysroot and debug file directory for gdb and creates and executes a gdb_macro named 'remote_connect', and will start up the cross-built gdb for you.
Examples of debugging using the gdb_remote script.
Below are two examples of using gdb_remote to start up debugging sessions. The first example shows connecting to a VM and having gdbserver start up a fresh copy of the binary to be debugged. The second example shows connecting to an external notebook and having gdbserver attach to an existing process:Example 1:
$ gdb_remote --board=${BOARD} --remote_file=/bin/lsVerifying IP address localhost (this will take a few seconds)...
Starting up gdbserver on your remote device.
Warning: Permanently added '[localhost]:9222' (RSA) to the list of known hosts.
Warning: Permanently added '[localhost]:9222' (RSA) to the list of known hosts.
gdbserver is now running remotely. Output will be written to
/tmp/gdbserver.out on your remote device.
To connect to gdbserver, type 'remote_connect' at the gdb prompt.
GNU gdb (Gentoo 7.2 vanilla) 7.2-gg15
Copyright (C) 2010 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
Type "show copying" and "show warranty" for licensing/warranty details.
This GDB was configured as "--host=x86_64-pc-linux-gnu
--target=i686-pc-linux-gnu".
<http://bugs.gentoo.org/>
0x777459c0 in print_statistics () from /build/x86-mario/lib/ld-linux.so.2
(gdb)
Breakpoint 1 at 0x8830: file ls.c, line 1197.
(gdb)
b mainBreakpoint 1 at 0x8830: file ls.c, line 1197.
(gdb)
Example 2:
$ gdb_remote --board=${BOARD} --remote_pid=626 --remote=123.45.678.99Verifying IP address 123.45.678.99 (this will take a few seconds)...
Starting up gdbserver on your remote device.
gdbserver is now running remotely. Output will be written to
/tmp/gdbserver.out on your remote device.
To connect to gdbserver, type 'remote_connect' at the gdb prompt.
GNU gdb (Gentoo 7.2 vanilla) 7.2-gg15
Copyright (C) 2010 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
Type "show copying" and "show warranty" for licensing/warranty details.
This GDB was configured as "--host=x86_64-pc-linux-gnu
--target=i686-pc-linux-gnu".
<http://bugs.gentoo.org/>
0x73706424 in __kernel_vsyscall ()
(gdb)
Troubleshooting
My build is failing, what's the problem?
Your build may break because of transient failures introduced when an upstream dependency is in-flight while your dependent is built. These types of failures are often manifested as missing files or configuration information. Try re-running your build.
If re-running doesn't help, check the buildbot to see if the problem exists there as well.
How do I fix network problems in the chroot?
TODO: This troubleshooting tip was from the old instructions. Is it still relevant?
When running
emerge inside the chroot, the command uses wget to fetch packages. The wget process is run as the portage user, and if that user is unable to talk on the network the command will be unable to resolve hostnames, among other things. This can happen if the machine is using a local firewall service such as UncomplicatedFireWall (ufw package on Ubuntu) that limits network traffic to a specific set of users.This network traffic limitation can be verified by looking at the output of iptables, for example with ufw:
$ sudo iptables -L ufw-after-output | grep ownerACCEPT all -- anywhere anywhere owner UID match rootACCEPT all -- anywhere anywhere owner UID match yournameOne way to get around this limitation is to add the
First, create the user on the build machine:
portage user to the list of allowed users:First, create the user on the build machine:
sudo useradd -d /var/tmp/portage -N -s /bin/false portageThen add the user to the list of allowed users in
/etc/ufw/after.rules and /etc/ufw/after6.rules:# allow outbound connections by portage user for building chromiumos-A ufw-after-output -m owner --uid-owner portage -j ACCEPTFinally, restart the firewall:
sudo restart ufwI lost my developer tools on the stateful partition, can I get them back?
This happens sometimes because the security system likes to wipe out the stateful partition and a lot of developer tools are in /usr/local/bin. But all is not lost because there is a tool for updating the stateful partition from an image created by the auto-update part of the dev_server. Sadly, it is normally found in /usr/local so will have been lost too and you need to copy it over manually. This works for me:
$ cd /tmp$ scp me@myworkstation:/path/to/chromiumos/chroot/build/x86-whatever/usr/bin/stateful_update .$ sudo sh stateful_update$ sudo rebootNote you can clobber the stateful partition (remove user accounts etc and force OOBE) as part of this process by using a flag:
$ cd /tmp
$ scp me@myworkstation:/path/to/chromiumos/chroot/build/x86-whatever/usr/bin/stateful_update .
$ sudo sh stateful_update --stateful_change=clean
$ sudo reboot
Running Tests
Many of the automated tests that are part of the Chromium OS project run using the autotest framework. See Autotest User Documentation for details.
Various quick links:
Getting an image that has been modified for test - This doesn't work if you want to create a recovery image and boot a Cr48 with it, see below
If you wish to produce a VM image instead, you should omit the --test flag to build_image and let ./image_to_vm.sh produce the test image:
./image_to_vm.sh --board=${BOARD} --test_image Note: this difference between ./image_to_usb.sh and ./image_to_vm.sh arises because ./image_to_vm.sh does not yet support the --image_name flag and by default looks for chromiumos_image.bin. We expect this to change in the future.
Note that creating a test image will change the root password of the image to test0000. The --test_image flag causes the image_to_xxx commands to make a copy of your chromiumos_image.bin file called chromiumos_test_image.bin (if that file doesn't already exist), modify that image for test, and use the test image as the source of the command.
SIDE NOTES:
- When creating a VM image for testing purposes, it is highly recommended that you expand its stateful partition with the
--statefulfs_sizeparameter. Otherwise, certain autotest scenarios will run out of stateful partition disk space since its default size on ChromeOS image files is equal to rootfs size of 2G. TODO: Is this still needed? I don't think so now that the default stateful size is 2G. - If the directory already has a file called chromiumos_test_image.bin, that file is reused. That means that calling both image_to_usb.sh and image_to_vm.sh doesn't waste time by creating the test image twice.
Creating a recovery image that has been modified for test
After building a test image using ./build_image test as described above, you may wish to encapsulate it within a recovery image:
./mod_image_for_recovery.sh \ --board=${BOARD} \ --nominimize_image \ --kernel_image ${RECOVERY_KERNEL} \ --image ~/trunk/src/build/images/${BOARD}/latest/chromiumos_test_image.bin \
--to ~/trunk/src/build/images/${BOARD}/latest/recovery_test_image.binYou can write this recovery image out to the USB device like so:
./image_to_usb.sh --board=${BOARD} --image_name=recovery_test_image.bin --to=${MY_USB_KEY_LOCATION}
- Your USB image will be a recovery mode/test image, but the ordinary image in your directory will be a non-test image.
- If you use devserver, this will serve the non-test image not the test-image.
- This means a machine installed with a test-enabled USB image will update to a non-test-enabled one.
Additional information
Switching Toolchain Compilers
At any given time in the chroot, to see what cross-compiler version is the current default one, do:
- For ARM: armv7a-cros-linux-gnueabi-gcc -v
- For x86: i686-pc-linux-gnu-gcc -v
- For amd64: x86_64-cros-linux-gnu-gcc -v
To list available compilers, type:
- src/platform/dev/cros_gcc_config -l
This will print the list of available compilers to switch to.
NOTE: It may take a while to install a new compiler if you haven't yet installed it in your chroot. You may have to run source /etc/profile, or exit your chroot and re-enter it, for the switch to take effect.
NOTE: If you use ./build_packages after switching the toolchain compiler, make sure to pass in --skip_toolchain_update.
Developer mode
It can be confusing to figure out what "developer mode" means: Some parts of this document talk about switching your hardware to developer mode, while other parts talk about entering developer mode by running an image built with the
--withdev flag. For the most part, the two actions enable the same set of things (like the shell command in crosh). Thus, you can think of either action as enabling developer mode.To provide some details:
- Putting your hardware into developer mode makes
/bin/cros_boot_modeprintdeveloper. It also makes the file/mnt/stateful_partition/.developer_modeappear. - Building with the
--withdevflag creates a file called/root/.dev_mode(in addition to adding a whole bunch of useful developer tools to your stateful partition). The presence of the /root/.dev_mode file enables developer mode and also prevents wiping of the stateful partition when you switch your hardware between developer mode and release mode.
Attribution requirements
When you produce a Chromium OS image, you need to fulfill various attribution requirements of third party licenses. Currently, the images generated by a build don't do this for you automatically. You must modify ~/chromium/src/chrome/browser/resources/chromeos/about_os_credits.html.Documentation on this site
You now understand the basics of building, running, modifying, and testing Chromium OS, but you've still got a lot to learn. Here are links to a few other pages on the chromium.org site that you are likely to find helpful (somewhat ordered by relevance):
- The Tips And Tricks for Chromium OS Developers page has a lot of useful information to help you optimize your workflow.
- If you haven't read the page about the devserver already, read it now.
- Learn about the Chromium OS directory structure.
- The Chromium OS developer FAQ might have useful info. TODO: Double-check that the FAQ is still accurate, and resolve it with this page.
- The Chromium OS portage build FAQ might also have useful info. TODO: Double-check that the FAQ is still accurate, and resolve it with this page.
- If you have questions about the
--noenable_rootfs_verificationoption, you might find answers on this thread on chromium-os-dev. - Running Smoke Suite on a VM Image has good information about how to get up and running with autotest tests and VMs.
- Debugging Tips contains information about how to debug the Chromium browser on your Chromium OS device. TODO: Validate that the instructions are still accurate.
- Working on a Branch has tips for working on branches.
- Git server-side information talks about adding new git repositories.
- The Portage Package Upgrade Process documents how our Portage packages can be upgraded when they fall out of date with respect to upstream.
External documentation
Below are a few links to external sites that you might also find helpful (somewhat ordered by relevance):- Definitely look at the Chromium OS dev group to see what people are talking about.
- Check out the Chromium OS bug tracker to report bugs, look for known issues, or look for things to fix.
- Get an idea of what's actively happening by looking at the Chromium Code Reviews site. (Note that this is the combined site for both Chromium and Chromium OS.)
- Browse the source code on the Chromium OS gitweb.
- Check the current status of the builds by looking at the Chromium OS build waterfall.
- Check out the #chromium-os channel on freenode.net (this is the IRC channel that Chromium OS developers like to hang out on).
- If you're learning git, check out Git for Computer Scientists, Git Magic, or the Git Manual.
- The Gentoo Development Guide might be useful for (TODO: short description)
- The Gentoo Embedded Handbook might be useful for (TODO: short description)
- The Gentoo Cross Development Guide might be useful for (TODO: short description)
- The Gentoo Wiki on Cross-Compiling might be useful for (TODO: short description)
- The Gentoo Package Manager Specification might be useful for (TODO: short description)
- The repo man page might help you if you're curious about repo. Or you can go straight to the repo source code.
- The repo-discuss group is a good place to talk about repo.