Introduction
This guide describes how to work on Chromium OS. If you want to
help develop Chromium OS and you're looking for information about how to
get started, you're in the right place.
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 & content
This 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:
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:
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.).
Preliminary requirements
Finally, if you build a Chromium OS image, please read this important note about attribution requirements. You must have Linux to develop Chromium OS. Specifically, the supported environment is:
Most developers working on Chromium OS
are using Lucid (the LTS version of Ubuntu) and will not be updating to
10.10. 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 Lucid. Please note that Ubuntu 9.10 (Karmic) is known not to
work.
32-bit systems may 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.
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 Ubuntu and Google packages to
develop Chromium OS (installation instructions are provided below):
Getting the source code To 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.
Install the git revision control system. On Ubuntu, the magic incantation to do this is:
sudo aptitude install git-core gitk git-gui
This command also installs git's graphical front end (git gui) and revision history browser (gitk).
Setup 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"
IMPORTANT NOTE: If you are new to Chromium OS, you are NOT a committer. Skip this step (go to "decide where your source will live"). Feel free to revisit this step if/when you .
Create your ssh key
Committers access the git repositories through an ssh connection, which means you need to setup an ssh key. Create a key using ssh-keygen. You will be asked for a password – please create one in order to protect your key. Don't worry, with the keychain program (see below) you won't need to enter this password very often.
Submit your public key to the gitmaster
ssh-keygen -t rsa -f ~/.ssh/chromium
You must submit the public key that was generated (in ~/.ssh/chromium.pub)
to the Chromium OS gitmaster and wait until this key is accepted.
Whoever approved you as a committer should have given you instructions
on how to do this. They are purposely not listed here to avoid lots of
spamming of the gitmaster.
Automate usage of your key with keychain
You 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 ~/.bashrc file:
eval `keychain --eval ~/.ssh/chromium`
Run the above keychain command now so that your current terminal will have access.
SIDE NOTES:
Run the following command: uname -m
You should see the result: x86_64 If you see something else (for example, i686,
which means you are on a 32-bit machine or a 64-bit machine running a
32-bit OS) then you won't be able to build Chromium OS. The project
would happily welcome patches to fix this.
Chromium 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}/chromiumos
IMPORTANT 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/chromiumos
ln -s /usr/local/path/to/source/chromiumos ${HOME}/chromiumos
SIDE NOTE: There were some suggestions about putting the source in ${HOME}/trunk (and the instructions suggested this for a while). Having the source in ${HOME}/trunk allows
you to have some sloppiness later (you can enter the same commands
inside the build chroot and outside). Though this is convenient, it is
dangerous because it might lead to you to submit a change to a build
script that works on your machine, but that doesn't work on other
machines (where the source code is not in ${HOME}/trunk).
Before you get the source code, you must decide whether you want to the "minilayout" or the "full layout:"
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.
Chromium OS uses to sync down source code. repo is effectively a wrapper for the that helps deal with a large number of git repositories. You already installed repo when you installed depot_tools above. 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.org You 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== Once the keys are added to your known_hosts file, 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 -m minilayout.xml repo sync Option #2: If you want a copy of the full layout, enter the following commands:
cd ${HOME}/chromiumos
repo init -u
repo sync
Googlers: See 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 OS
Create a chroot To make sure everyone uses the same exact environment and tools to build Chromium OS, all building is done inside a .
This chroot is its own little world: it contains its own compiler, its
own tools (its own copy of bash, it's 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 commands to setup the chroot are:
cd src/scripts
./make_chroot
This command 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 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:
Enter the chroot
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 using one of the
commands in the src/scripts directory:
./enter_chroot.sh
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.
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
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:
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):
BOARD=x86-generic
This 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 board
When you're done, unmount the root filesystem:To 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:
On 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.sh
You will be prompted for a password, which will be stored in encrypted form in /etc/shared_user_password.txt.
SIDE NOTES:
To build all the packages for your board, run the following command from inside the ~/trunk/src/scripts directory:
./build_packages --board=${BOARD} --oldchromebinary
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:
Once the build_packages step is finished, you can make an image by running the command below from inside the ~/trunk/src/scripts directory:
./build_image --board=${BOARD} --withdev --noenable_rootfs_verification
This
command creates an image with developer tools that allow you to freely
modify the root file system. The image that is produced will not be a
secure version of Chromium OS, but will give you fairly liberal access.
If you would like a more secure, locked-down version of Chromium OS, you
should leave off the --withdev and --noenable_rootfs_verification options.
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(!).
If you want, you can look at the rootfs of the disk image that you just created by using the following commands:
cd ~/trunk/src/build/images/${BOARD}/latest
./unpack_partitions.sh chromiumos_image.bin
mkdir -p rootfs
sudo mount -o loop part_3 rootfs
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/rootfs
This
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
If you don't want to unpack the partitions (which takes up extra disk space), you can also mount directly without unpacking:
cd ~/trunk/src/build/images/${BOARD}/latest
ROOTA_START=`grep 'ROOT-A' unpack_partitions.sh | awk '{print $2;}'`
mkdir -p rootfs sudo mount -o loop,offset=$((512 * ${ROOTA_START})) chromiumos_image.bin rootfs
Again, don't forget to unmount the root filesystem when you're done:
sudo umount ~/trunk/src/build/images/${BOARD}/latest/rootfs
TODO: I think most/all of the above is handled in src/scripts/mount_gpt_image.sh. Rewrite the above using that script.
Running your image Getting your image running on a computer without verified boot If 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 disk
The 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 disk
You 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 boot
You 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 Mode
This 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 Notebook
The 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 (AKA Mario) by running the steps below from inside the chroot:
curl > ~/trunk/mario_recovery_kernel.zip
unzip -d ~/trunk ~/trunk/mario_recovery_kernel.zip
RECOVERY_KERNEL=~/trunk/mario_recovery_kernel.bin
The 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.bin
SIDE NOTE: If you're interested in creating a test image (used for allowing Chromium OS to talk to autotest), you can use mod_image_for_test.sh to manually modify your image before combining it with the recovery image. TODO: Document this.
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 SSD
In 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) the .bin file that you first extracted from the .zip file
above directly to a USB drive, without making any modifications to it.
Since 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:
If 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-install
IMPORTANT NOTE: Installing Chromium OS onto your hard disk will WIPE YOUR HARD DISK CLEAN.
Many 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:
Keep the tree green
Now that you can build and run Chromium OS, you're ready to start making changes to the code.
Before you start, take a moment to understand Chromium's source management strategy of "keeping the tree green." For the Chromium OS project, keeping the tree green means:
This strategy has
many benefits, including avoiding separate build trains for parallel
development (and the cost of supporting such development), as well as avoiding large,
costly merges from forked branches.
SIDE NOTE: "Keep the tree green" means something a bit different for Chromium OS than for Chromium, which is much further along in its life cycle. The steps in this section describe how to make changes to a
Chromium OS package whose source is checked into the Chromium OS source
control system. Specifically, this is a package where:
cros_workon --board=${BOARD} list --all
Run cros_workon start The first thing you need to do is to mark the package as active. Use the command below, replacing ${PACKAGE_NAME} with your package name (e.g., chromeos-wm):
cros_workon --board=${BOARD} start ${PACKAGE_NAME}
This command:
Run repo sync After running cros_workon, sync down the sources. This is critical if you're using the minilayout,
but is probably a good idea in any case to make sure that you're
working with the latest code (it'll help avoid merge conflicts later).
Run the command below from outside the chroot, anywhere under your~/chromiumos directory:
repo sync
Figure out where the ebuild / source code for the project is located
It can be a little tricky to figure out
where the source code and ebuild for your project is located. Luckily,
some magic portage commands can help you.
To find out where the ebuild lives:
equery-${BOARD} which ${PACKAGE_NAME}
As an example, for PACKAGE_NAME=chromeos-wm, the above command might display:
/home/.../trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-wm/chromeos-wm-9999.ebuild SIDE NOTE: If you run the same command without running cros_workon first, you can see the difference:
/home/.../trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-wm/chromeos-wm-0.0.1-r134.ebuild
To find out where the source code lives (and what git repo it's under):
ebuild-${BOARD} `equery-${BOARD} which ${PACKAGE_NAME}` info
Trying this command with PACKAGE_NAME=chromeos-wm, you might see something like:
CROS_WORKON_SRCDIR="/home/.../trunk/src/platform/window_manager"
CROS_WORKON_PROJECT="chromiumos/third_party/window_manager"
SIDE NOTE: The shell script below can be interesting/useful if you want to see info about all packages (it's a little slow, though):
ALL_PACKAGES=`cros_workon --board=${BOARD} list --all`
for package in ${ALL_PACKAGES}; do ebuildPath=`equery-${BOARD} which ${package}` eval `ebuild-${BOARD} "${ebuildPath}" info` echo "${package} - $CROS_WORKON_PROJECT - $CROS_WORKON_SRCDIR" done Create a branch for your changes Since Chromium OS uses repo/git, you should always create a local branch whenever you make changes.
You can run the command to create a local branch from outside the chroot (anywhere under your ~/chromiumos directory), or from within the chroot. In the command below, replace ${CROS_WORKON_PROJECT} with the project name you found in the previous step, and replace ${BRANCH_NAME} with a name that is meaningful to you and that describes your changes (nobody else will see this name): repo start ${BRANCH_NAME} ${CROS_WORKON_PROJECT}
If you want to work on something that is not checked into the
Chromium OS tree (e.g., ebuild files in third_party/chromium-overlay),
cd to the directory where you want to make your change, and use '.' in
place of ${CROS_WORKON_PROJECT}, as shown below:
repo start ${BRANCH_NAME} .
The branch that this creates will be based on the remote branch. If
you've made any other local changes, they will not be present in this
branch.
Make your changes
You should be able to make your changes to the source code now. To incrementally compile your changes, use
./bin/cros_workon_make --board=${BOARD} ${PACKAGE_NAME}
This will build your package inside your source directory. Change a
single file, and it will rebuild only that file and re-link. If your
package contains test binaries, using
./bin/cros_workon_make --board=${BOARD} ${PACKAGE_NAME} --tests
will build and run those binaries as well. Call cros_workon_make --help to see other options that are supported.
You probably want to get your changes onto your device now. You can certainly now rebuild an image with build_image and then reimage your device. ...but you might also want to take a peek at the devserver instructions if you want something a little quicker.
Set your editor
Many of the commands below (in particular git) open up an editor. You probably want to run one of the three commands below depending on your favorite editor.
If you're not a *nix expert, nano is a reasonable editor:
export EDITOR='nano'
If you love vi:
export EDITOR='vi'
If you love emacs (and don't want an XWindow to open up every time you do something):
export EDITOR='emacs -nw'
You should probably add one of those lines to your .bashrc (or similar file) too.
When your changes look good, commit them to your local branch using git. Full documentation of how to use git is
beyond the scope of this guide, but you might be able to commit your
changes by running something like the command below from the project
directory:
git commit -a
The git commit
command brings up a text editor. You should describe your changes,
save, and exit the editor. Note that the description you provide is only
for your own use. When you upload your changes for code review, the repo upload command grabs all of your previous descriptions, and gives you a chance to edit them.
Once your changes are committed locally, upload your changes using repo upload. The repo upload command
takes all of the changes that are unmerged and asks them if you want to
upload them. You can specifically say to only look for unmerged
changes in your current repo by passing in '.'. Please note that you
must have a Gerrit account before you can upload changes.
repo upload [.|project-name] Note it important to note that repo uses the Change-Id in your git commits to track code reviews. So in order to work on a CL the standard work flow is to use git commit --amend rather than make a new commit. This differs from our old git-cl style.  In your local commit logs make sure to add a BUG= field and TEST= field. For BUG=, you should put something that looks like: BUG=bug-tracker:number.
You can get a tracker name by looking in the upper-left corner of the
tracker page (e.g. in the image on the right, the tracker name is
"chromium-os"). If your changes are related to more than one tracker
issue, you can list all the issues separated with commas.For TEST=, you should describe what you did to test the changes.
Here's what a sample description should look like:
# Enter a description of the change.
# This will displayed on the codereview site.
# The first line will also be used as the subject of the review.
Here's a SHORT, one-line summary of my change.
And here are more details
...this can be as long as I want.
BUG=chromium-os:99999, chromium:88888
TEST=Ran all the white box tests Change-Id: I8d7f86d716f1da76f4c85259f401c3ccc9a031ff Once you run repo upload, this uploads the changes and
prints out a URL for the code review (if its a new code review). Go to
that URL (log in with your chromium.org account, which you might want to
do in an "incognito" window in Chrome), and use the "Review->Publish Comments" link to mail your changes to your reviewers.
You should pick reviewers that know the code you're working on well
and that will do the best reviews. Picking reviewers who will just
rubber-stamp your changes is a bad idea. The point of submitting changes
is to submit good code, not to submit as much code as you can. If you
don't know who should review your changes, start by looking at the git log for the project that you're working on. Simply type the command below in a directory related to your project:
git log
Your reviewers will likely provide comments about changes that you
should make before submitting your code. You should make such changes,
submit them locally, and then re-upload your changes for code review
by amending your changes to your git commit and re-running repo upload. While you're working on your changes, you might want to go back to
the mainline for a little while (maybe you want to see if some bug you
are seeing is related to your changes, or if the bug was always there).
If you want to go back to the mainline without abandoning your changes,
you can run the following command from within a directory associated
with your project:
git checkout cros/master
When you're done, you can get back to your changes by running:
git checkout ${BRANCH_NAME}
Work on something else while you're waiting If you want to start on another (unrelated) change while waiting for your code review, you can repo start another
branch. When you want to get back to your first branch, run the
following command from within a directory associated with your project:
git checkout ${BRANCH_NAME}
Eventually, all your reviewers will be happy and will give you
a Looks Good and Approved (the latter is only available to owners of
the code) message in Gerrit. If they choose to test it they can also
mark Verify. Both Looks Good and Approved + Verified must be set in
order to commit your CL. Once they are set you'll see a Submit Patch
(or Publish and Submit in the review panel) appear for your patch.
Gerrit will then commit your CL for you. Note
it is possible that your change is rejected because of a merge
conflict. If it is, rebase against any new changes and re-upload your
patch. This patch will have to be re-approved before it is allowed to
be committed. IMPORTANT NOTE: After you push your changes, make sure that you can be reached (by IM, phone, IRC, etc.) in case something is wrong. DO NOT push your changes and then go to lunch or go home for the day! After you commit, make sure you didn't break the build by checking the .
(Non-committers) Submit your changes
If you're not a committer, you must push your changes by submitting a patch to the the Chromium OS dev group.
However, the patch should go through the standard Gerrit review
process before-hand and you'll have to ask one of the reviewers (who is a
committer) to submit it for you.
After you're done with your changes, you're ready to clean up. The most important thing to do is to tell cros_workon that you're done by running the following command:
cros_workon --board=${BOARD} stop ${PACKAGE_NAME}
This command tells cros_workon to stop forcing the -9999.ebuild and to stop forcing a build from source every time.
You can also delete the branch that repo created. There are a number of ways to do so; here is one way:
repo abandon ${BRANCH_NAME} ${CROS_WORKON_PROJECT}
SIDE NOTES:
Making changes to non-cros_workon-able packages
If you want to make to changes to something other than packages
whose source is checked into the Chromium OS source control system, you
can follow the instructions in the previous section, but skip the cros_workon step. Note specifically that you still need to run repo start to create a branch for your changes.
The types of changes that fall into this category include:
TODO: This section is currently a placeholder, waiting for someone to fill it in. However, a few notes:
TODO: Document this better, and add the new cros_workon_make.
SIDE NOTE:To build an individual portage package, for a particular board, use emerge-${BOARD}.
For example, if you want to build dash to test on your device:
emerge-${BOARD} dash
If you want to make modifications to the Chromium web browser and
run your custom version of the Chromium web browser on Chromium OS, see .
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, 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 owner
ACCEPT all -- anywhere anywhere owner UID match root
ACCEPT all -- anywhere anywhere owner UID match yourname
One way to get around this limitation is to add the 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 portage
Then 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 ACCEPT
Finally, restart the firewall:
sudo restart ufw
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 reboot Note 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 Many of the automated tests that are part of the Chromium OS project run using the autotest framework. TODO: add more details.
In order to run the autotests on your Chromium OS machine (or virtual
machine), you must use 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
The easiest way to get an image that has been modified for testing is to add the --test_image flag to either image_to_vm.sh or image_to_usb.sh, like so:
./image_to_usb.sh --board=${BOARD} --test_image --to=${MY_USB_KEY_LOCATION}
...or...
./image_to_vm.sh --board=${BOARD} --test_image
Note that the --test_image flag 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:
After building your usual image, you need to create a test version of it. By default mod_image_for_test.sh blows away your existing image, you probably don't want that but see below, so we copy it first.
cp ~/trunk/src/build/images/${BOARD}/latest/chromiumos_image.bin \
~/trunk/src/build/images/${BOARD}/latest/chromiumos_test_image.bin Now we can modify that to turn it into an actual test image:
./mod_image_for_test.sh \
--board=${BOARD} \ --image ~/trunk/src/build/images/${BOARD}/latest/chromiumos_test_image.bin ./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.bin ./image_to_usb.sh --board=${BOARD} --image_name=recovery_test_image.bin --to=${MY_USB_KEY_LOCATION}
Creating a new test
TODO: Validate that these instructions are still right. They were copied from an old instructions page.
To create a new test, follow these steps:
To create a new ebuild, you must use the autotest eclass, which
wraps all the necessary steps to compile your tests. If you are starting
a new repository with tests, you may have to create a new ebuild.
Please refer to existing ebuilds for details.
If you create a new ebuild for test X, you must run cros_workon start X. Mysterious failures mode will occur otherwise.
TODO: Validate that these instructions are still right. They were copied from an old instructions page.
Run the command below and look at the "USE=" output. The command tells emerge to "pretend" to build the tests and print out verbose output. Replace ${EBUILD_NAME} with the name of an ebuild containing tests (see just below), like autotest-tests.
emerge-${BOARD} -pv ${EBUILD_NAME}
The only ebuilds containing tests are:
The document Running Smoke Suite On a VM Image contains the most up-to-date information about autotests.
TODO: It would be nice if some of that information migrated here?
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:
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):
External documentation Below are a few links to external sites that you might also find helpful (somewhat ordered by relevance):
|