Google Chrome os Beta !!!!

Custom Search

ntro

This guide should be a place that developers can go for information about getting started with Chromium OS. The target audience of this guide is anyone who would like to obtain, build, or contribute to Chromium OS. This guide doesn't go into detail about everything, but attempts to give people a broad overview of common tasks.

Guiding principles of this document:

You should be updating this document to fix it as necessary. If something looks wrong but you don't know the right answer, at least put a red TODO saying that it looks wrong. If you see a red TODO and know the right answer, fix it!

Only people with @chromium.org accounts can change the page. Everyone else should please post to the Chromium OS dev group.

If possible, information should be placed directly in this page (it's OK if it grows big) and this should be the main place for general "getting started" information. Other pages should link back to this page. Where that's not possible, we should try to only point to small discrete chunks of information on other pages. Why? Following a web of links is very confusing for a new person, who really needs a linear flow.

Where possible, this page should describe a single way of doing things. Where options are given, it should be clear why someone following the instructions would pick one or the other. Where there is disagreement, an alternate option can be listed as a SIDE NOTE.

Audience of this document

This document is intended for consumption by anyone working on Chromium OS. This could be a new developer who is simply interested in the project and wants to see what the fuss is about or a developer who has been working with Chromium OS for a long time.

Due to the fact that a large number of the people working on Chromium OS work at Google, there may occasionally be a reference or two in this document that is only relevant to engineers at Google. These references should be kept at a minimum, since Chromium OS is an open source project and we want to be as open as possible.

Note: When you produce a Chromium OS image, you need to fulfill the various attribution requirements of the third party licenses. Currently, the images generated by a build don't automatically do this for you. You'll need to modify ~/chromium/src/chrome/browser/resources/about_os_credits.html.

Getting started with Chromium OS development

Prerequisites

You need to have Linux to develop for Chromium OS. Specifically, the supported environment is:

Ubuntu Linux (version 10.04 - Lucid) - 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.

A 64-bit system for performing the build (we hope to support 32-bit at some point).

An account with sudo access (root access is needed to run the chroot command and modify the mount table). NOTE: You shouldn't run any of the commands here as root--the commands themselves will run sudo to get root access when needed.

You will have a much nicer time if you have a fast multi-processor machine with lots of memory. 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. We recommend 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.

For the initial download (and any further updates) a good Internet connection helps. The minimum download is about 2GB.

The following Ubuntu packages are requirements for building Chromium OS (instructions for installing some of them are below):

git - Source control client

keychain - ssh key management (if you're a committer)

You'll also be instructed to install depot_tools, which is a Google-maintained set of tools used by Chromium OS.

Install depot_tools

To get started, you'll need to follow the instructions at install depot_tools. This is required so that you can use the 'repo' command to get/sync the source code.

Install git

You will also need to install the git revision control system. On Ubuntu, the magic incantation to do this is:

sudo aptitude install git gitk git-gui

This also installs git's graphical front end (git gui) and revision history browser (gitk).

Configure git

You should 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"

Preparations if you are committer

If you are new to Chromium OS, you are NOT a committer. You should skip this section. Feel free to revisit if/when you become a committer.

Creating your ssh key

Committers will access the git repositories through an ssh connection. That means we need to setup a ssh key. Create a key using ssh-keygen. You will be asked for a password. Please provide 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.

ssh-keygen -t rsa -f ~/.ssh/chromium

Submit your public key to the gitmaster

You'll need to give the public key that was generated (in ~/.ssh/chromium.pub) to the Chromium OS gitmaster and wait until it 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

We want you to protect your chromium ssh key with a password, but you don't want to type that password all the time. Enter the keychain command.

On Ubuntu, install it with this command (assumes apt is configured with universe):

sudo aptitude install keychain

Then, you use it by adding this to the end of your ~/.bashrc file:

eval `keychain --eval ~/.ssh/chromium`

You should also run the above keychain command yourself now so that your current terminal will have access.

SIDE NOTE: The keychain command is really just a wrapper around ssh-agent. You could use ssh-agent directly, but it's more complicated and thus doesn't belong in these instructions. If someone is passionate about ssh-agent, feel free to make a sub-page about how to use ssh-agent instead of keychain.

FAQ: People wonder why we tell you to password protect your key, then turn around and tell you how to avoid entering the password. The thing to note is that keychain only keeps the "decrypted" version of your ssh key in RAM (hopefully in protected memory). This is more secure, since someone who has physical access to your machine can access the disk without your password (by rebooting from a CD-based Linux distribution), but cannot access the RAM so easily.

Setup your ssh config

The last step in the preparations for committers is to make sure that you have the following bit of text in your ~/.ssh/config file:

Host gitrw.chromium.org
Port 9222 User git

  IdentityFile %d/.ssh/chromium





  # The remaining lines are optimizations for faster sync times.  They   # are not strictly necessary      # NOTE: You should _NOT_ have ControlMaster and ControlPath lines   # here.  The repo tool handles setting up ControlMaster and    # ControlPath and if you have something here it could potentially   # conflict with repo's configuration.

# Turn off negotiations that don't make sense for sync connections

GSSAPIAuthentication no   GSSAPIKeyExchange no          PasswordAuthentication no   RSAAuthentication yes   ForwardX11 no  ForwardX11Trusted no   ForwardAgent no   HostbasedAuthentication no   RhostsRSAAuthentication no   Protocol 2    # Prefer faster ciphers and MACs.     Ciphers arcfour256,aes128-ctr,aes192-ctr,aes256-ctr   MACs umac-64@openssh.com,hmac-md5,hmac-sha1

Decide where your source will live

There are always questions about where to place source code on your file system. The author of this document places his source in${HOME}/chromiumos, and this seems fairly common among Chromium OS developers. I would suggest placing your source there, and all commands in this document assume that. If you feel strongly, feel free to put your own source elsewhere.

IMPORTANT NOTE: If your home directory is on a 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 it won't actually work (the build uses 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 make a symbolic link to it from your home directory (this is suggested), like this:

mkdir -p /usr/local/path/to/source/chromiumos

ln -s /usr/local/path/to/source/chromiumos ${HOME}/chromiumos

...otherwise, you should make the directory like this:

mkdir -p ${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). That may be convenient, but is dangerous because it might lead to you submitting a change to a build script that works on your machine, but doesn't work on someone else's machine (who doesn't have the code in ${HOME}/trunk).

Decide if you want the minilayout

Before you can get the source code, you need to make a decision about whether you want to use the "minilayout" or the "full layout". The minilayout starts you out with the minimum amount of source code (you can hand-pick additional source code later with cros_workon). The full layout gets you all Chromium OS-related source code on your hard disk.

You should probably pick the full layout if:

You think you might want to grep through the source code to help you get oriented.

Note: we're trying to get something like codesearch.chromium.org set up for Chromium OS to remove this advantage of the full layout.

You just like to have all of the source you can.
You've got lots of extra disk space.
You've got a fast network connection. Note: the first sync will be very slow, but even subsequent syncs will be slow.

You should probably pick the minilayout if:

You have a slow network connection or a small hard disk.
You will probably just work on a few packages.
You would prefer your syncs to be quick.
You don't mind waiting a little longer for the first sync whenever you start working on a package you've never worked on before.

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

Chromium OS uses repo to sync down the sources. For those not familiar with repo, it 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.

There are 4 options, depending whether or not you are a committer (probably true if you're new to the project -- see above) and whether or not you want the minilayout (see above).

Option #1: If you are not a committer and want the minilayout, enter these commands:

cd ${HOME}/chromiumos

repo init -u http://git.chromium.org/git/manifest -m minilayout.xml

repo sync

Option #2: If you are a committer and want the full layout, your commands are:

cd ${HOME}/chromiumos

repo init -u ssh://git@gitrw.chromium.org:9222/manifest -m minilayout.xml

repo sync

Option #3: If you are not a committer and want the full layout, enter these commands:

cd ${HOME}/chromiumos

repo init -u http://git.chromium.org/git/manifest

repo sync

Option #4: If you are a committer and want the minilayout, your commands are:

cd ${HOME}/chromiumos

repo init -u ssh://git@gitrw.chromium.org:9222/manifest

repo sync

SIDE NOTE: If you want to build on a branch pass the branch name to repo init (e.g: repo init -u <URL> [-m minilayout.xml] -b 0.9.94.T)

When you use repo init it will ask you to confirm your name, email address and whether you want color in your terminal. This is a fast operation. The repo sync takes a lot longer. Depending on your internet speed, you might get a download rate of 200-400KB/s, but it will vary. For the minilayout it will download around 2GB in around an hour or so.

Create a chroot

To make sure that everyone uses the exact same tools and environment 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, it's own copy of sudo, ...). Now that we've synced down the sources, we 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 will take about half an hour on a four core machine. It will compile quite a bit of software which it installs into your chroot, and some additional items will need to be downloaded (around 300MB). While it is building you will see a regular update of the number of packages left to build. Once it is finished total disk space will be a little over 3GB.

The chroot lives at ${HOME}/chromiumos/chroot. Inside there 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 to the normal one you use on your machine.

SIDE NOTE: You shouldn't have to create the chroot very often. Most developers create it once and never touch it again unless someone explicitly sends out an email telling them to recreate their chroot. Since this is very disruptive to developers, it doesn't happen very often.

SIDE NOTE: If you've already got a chroot when you run make_chroot command, it will attempt to "update" your existing chroot. This works reasonably well in most cases. However, if you really want to force a clean chroot to be built, pass the --replace flag to make_chroot. This will delete any old chroot that might have been present, before re-creating a new one.

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 will probably prompt you for your password for the sudo command (entering the chroot requires root privileges), then print out a bunch of messages. Once it is done, that terminal is in the chroot and you'll be in the ~/trunk/src/scripts directory (where most build commands live). You are now in the chroot world and can only see a subset of the filesystem on your machine. Through some trickery (bind mounts) you will have access to the whole src directory from within the chroot - this is so you can build the software within the chroot.

In particular you should note 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. This means that changes that you make to the source code outside of the chroot immediately take effect inside the chroot.

While within 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 it outside the chroot. As a consolation, you can can use vim. If you desperate for emacs, try typing sudo emerge emacs. Of course it will build it from source so allow 5-10mins.

IMPORTANT NOTE: In this document, commands that are intended to be entered inside the chroot and paths that refer to paths inside the chroot will be colored purple.

IMPORTANT NOTE: If you need to delete your chroot later, make sure to use ./make_chroot --delete to do it properly. Using rm -rfcould end up deleting your source tree.

SIDE NOTE: Some commands can be run from outside the chroot, even if they expect to be run inside the chroot. These commands are smart enough to enter the chroot for the duration of the command.

SIDE NOTE: If you need to share lots of files inside and outside chroot (for example, settings for your favorite editor / tools, or files downloaded by browser outside chroot, ...), read the Tips and Tricks for more information.

SIDE NOTE: There is a file system loop because inside ~/trunk you will find the chroot again. Don't think about this for too long. If you try to use du -s ${HOME}/chromiumos/chroot/home you might get a message about a corrupted file system. This is nothing to worry about, and just means that your computer doesn't understand it either. [if you can understand this, try something harder]

Choose what board you want to build for

When you build Chromium OS, you will produce an disk image (usually just called an "image") that is appropriate for copying directly onto the boot disk of the computer you'd like to run Chromium OS. Depending on the specifics of the computer you're going to run Chromium OS on, you may want different things on that disk image. For instance, if your computer has an ARM processor, you'll want to make sure that everything on the disk is compatible with ARM. Similarly, if your computer has some specialized hardware, you'll need to include driver software for that hardware.

Different classes of computers are referred to by Chromium OS as different target "boards". The following are some example boards:

x86-generic - A good place to get started if you're running Chromium OS on a computer with a x86-compatible CPU.
arm-generic - A good place to get started if you're running Chromium OS on a computer with a ARM CPU.

You will need to choose a board for your first build. Don't worry too much--you can always build for another board later. If you want a list of known boards, you can look in ~/trunk/src/overlays:

You will need to to specify the name of the board to various steps in the build process. To facilitate this process, it can be helpful to keep the name of the board in a shell variable. This is not strictly necessary, but makes it so that you can simply copy and paste the commands below into your terminal program. ...so enter the following inside your chroot (note: change x86-generic to whatever board you want to build for):

BOARD=x86-generic

This setting will only hold while you stay in the chroot. As soon as you leave and come back, you will need to do this again.

Initialize the build for a board

To start building for a given board, you will want to issue the following command inside your chroot (you should be in the~/trunk/src/scripts directory):

./setup_board --board=${BOARD}

This will setup the board target with a default sysroot of /build/${BOARD}. It downloads a small amount of stuff and takes a few minutes.

SIDE NOTE: If you pass the "--default" flag to setup_board, it will place the board name in the file~/trunk/src/scripts/.default_board (it does the same as echo ${BOARD} > ~/trunk/src/scripts/.default_board). This will make it so that you don't need to specify a --board argument to all future commands. We don't do that in these instructions so that you can explicitly see what commands are actually board-specific.

SIDE NOTE: If you've already setup this board, the command will fail. If you really want to clobber your old board files and start fresh, try passing --force (which will delete the old /build/${BOARD} directory for you). Like enter_chroot.sh, most people only re-runsetup_board when told to (AKA they don't re-run it even after a repo sync).

SIDE NOTE: You can delete the board sysroot at any time with: sudo rm -rf /build/${BOARD}

Set the chronos user password

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 this user by entering this command 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 the "shared_user_password.txt" file in yoursrc/scripts directory.

SIDE NOTE: Remember that the "src/scripts" directory is the same physical directory both inside and outside the chroot (not colored purple here to emphasize that). That means that, even if you completely recreate your chroot, you don't have to run this command again. The only time you'd ever need to run it again is if you sync down fresh source code.

SIDE NOTE: If you don't set a shared user password, the password for the chronos account may end up being any number of things depending on some complicated (and constantly evolving) formula that includes whether you build a developer image, whether you boot into developer mode, and the current state of the scripts. The password might be empty, or a well-known string, or it might be impossible to login with chronos. I strongly suggest you just set a shared user password. TODO: put a link to some place with more info about this.

Enable a local user account (optional)

The local user account allows login with no password even if you can not connect to the Internet. If you are customizing Chromium OS and having trouble logging in due to your customizations, it may be handy to be able to bypass authentication and log yourself in as a test user. This is disabled by default for security reasons, but if you want to enable it for a backdoor user USERNAME, enter the following from inside the ~/trunk/src/scripts directory:

./enable_localaccount.sh USERNAME

SIDE NOTE: The author of this page has been developing for Chromium OS for quite a while and never needed to enter this command. TODO: Can this be moved elsewhere?

Build the packages for your board

To build up all of the packages for your board, you can 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, so you will want to run it whenever you change something and need it rebuilt (or after you run repo sync).

NOTE: The first time you run this command it will take a long time (around 90mins on a four core machine) as it must build every package. The first time you run build_packages it will download about 1.7GB of source packages and 1.3GB of binary packages. See here for more information about what build_packages actually does. In short it tries to download existing binary packages to avoid building anything (and puts them in /build/${BOARD}/packages for next time). Failing that it downloads source packages (and puts them in/var/lib/portage/distfiles-target) and builds them.

Normally, build_packages will build 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 NOTE: The --oldchromebinary flag is not strictly necessary but will make your build faster in some rare instances (when the Chrome/Chromium browser has recently been revved) at the cost of a slightly older version of Chrome/Chromium. This may become the default in the future.

SIDE NOTE: Even though there are some flags that can optimize your build (like --nowithdev, --nowithautotest, etc), you shouldn'tuse them (even if you don't plan on building a developer / test image). There are some issues with virtual packages that can cause some hard-to-debug differences if you use one of these options.

Build a disk image for your board

Once the build_packages step is done, you're ready to make an image by running this command from inside the ~/trunk/src/scripts directory:

./build_image --board=${BOARD} --withdev --noenable_rootfs_verification

This will create an image with developer tools that allows you to freely modify the root file system. The image produced won't 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, it will create a files that take up over 4GB of space (!).

Looking at your disk image (optional)

If you want, you can look at the rootfs of the disk image that you just created by using this set of commands:

cd ~/trunk/src/build/images/${BOARD}/latest

./unpack_partitions.sh chromiumos_image.bin

mkdir -p rootfs

sudo mount -o loop part_3 rootfs

This will do a loopback mount of the rootfs from your image to the location ~/trunk/src/build/images/${BOARD}/latest/rootfs in your chroot.

If you built an x86 Chromium OS image, you can probably even try chrooting into the image. 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 chroot ~/trunk/src/build/images/${BOARD}/latest/rootfs

Don't forget to umount the root filesystem 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 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.

Getting your image onto a USB key

You can boot Chromium OS either from real hardware, or from a virtual machine. If you'd like to boot real hardware with your image, the easiest way is to put it on a USB flash drive. The first step is to insert a USB flash disk (a 4GB or bigger) into your computer. This disk will be completely erased, so make sure it doesn't have anything important on it. Wait ~10 seconds for it to register, then type the following command from in the ~/trunk/src/scripts directory:

./image_to_usb.sh --board=${BOARD}

...since we didn't pass a --to parameter, the image_to_usb.sh command will list all USB disks that it could find. If yours isn't listed, wait a few seconds and try the command again. Once you've found your USB disk (mine usually to show up as /dev/sdc), you're ready to re-enter the command with a --to parameter (you should replace ${MY_USB_KEY_LOCATION} with the one 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 go.

IMPORTANT NOTE: Remember, running this command will completely replace the contents of your USB disk. Make sure there wasn't anything important on it.

SIDE NOTE: By default, image_to_usb.sh will use the latest image for the given board. If you want to specify a different image, you can specify it with --from.

SIDE NOTE: If you're interested in creating a test image (used for allowing Chromium OS to talk to autotest), see the Running Tests section.

Booting from your USB key

If you're on an x86-based PC/notebook, you should simply be able to configure your computer's BIOS to boot from your USB key. After you've done this, just plug your newly minted USB key in, reboot, and you're booting into Chromium OS. Your Chromium OS image may not have all the drivers to run all of the peripherals on your PC, but it should at least boot.

For specific information about what works on various different machines, see the Developer Hardware page.

Getting to a command prompt on Chromium OS

Since you set the shared user password (with set_shared_user_password.sh) when you built your image, you have the ability to login with the chronos user. After your computer has booted to the Chromium OS login screen, you can get a text-based login prompt by pressing [ Ctrl ] [ Alt ] [ F2 ] on your keyboard. Then, login with the chronos user and enter the password you set earlier.

Because you built an image with developer tools, you also have an alternate way to get a terminal prompt. I'll mention this as well, since 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 way:

Go through the standard Chromium OS login screen (you'll need to setup a network, etc) and get to the web browser. It's OK if you login as guest.
Press [ Ctrl ] [ Alt ] [ T ] to get the crosh shell.
Use the shell command to get the shell prompt. NOTE: you don't need to enter the chronos password here, though you will still need the password if you want to use the sudo command.

Installing your Chromium OS image to your hard disk

Once you've booted from your USB key and got to the command prompt, you can install your Chromium OS image to the hard disk on your computer. You can do that with the command:

/usr/sbin/chromeos-install

IMPORTANT NOTE: Installing Chromium OS onto your hard disk will WIPE YOUR HARD DISK CLEAN.

Building an image to run in a virtual machine

Many times it is easier to simply run Chromium OS in a virtual machine like kvm. You can to adapt the previously built Chromium OS image so that usable by kvm (which uses qemu images) by entering this command from the ~/trunk/src/scripts directory:

./image_to_vm.sh --board=${BOARD}

This will create the file ~/trunk/src/build/images/${BOARD}/latest/chromiumos_qemu_image.bin.

SIDE NOTE: If you want to adapt the image for other virtual machines, see the --format=vmware and --format=virtualbox options.

SIDE NOTE: You can specify source/destination paths with the --from and --to parameters.

SIDE NOTE: If you're interested in creating a test image (used for allowing Chromium OS to talk to autotest), see the Running Tests section.

Making changes

Now that you've got everything built, you're ready to start making some changes. Depending on what you're going to be changing, there are some special instructions you'll want to follow.

...but, before you make any changes, you should understand a few things. We are following Chromium's source management process of "Keep the tree green". This strategy has many benefits, including avoiding separate build trains for parallel development and the cost to support them, as well as avoiding large, costly merges from forked branches. Since we are earlier in our life than Chromium, Keep the tree green means something a bit different for us than it does for Chromium, which is much further along.

For us, Keep the tree green means:

Any new commits should not destabilize the build; images built from the tree should always have basic functionality working; there may be minor functionality not working, and it may be the case, for example, that you will need to use Terminal to fix or work around some of the problems.

If you must introduce unstable changes to the tree (this should be infrequent), then you use parameterization to hide new, unstable functionality behind a flag that's turned off by default. We may need to develop mechanisms for parameterizing different parts of the system (such as the init script).

We will produce internal "dev channel" releases directly from the tree, with a quick branch to check-point the release version. Any fixes required for a release will be pulled from the tree, avoiding merges back to tree.

Making changes to a package whose source is in our tree

If you'd like to make changes to a Chromium OS package whose source is in our tree, this is the workflow to look at. Specifically, this is a package where:

The ebuild for the package lives in the src/third_party/chromiumos-overlay or src/overlays/overlay-${BOARD}directories.
There is an ebuild for the package that ends with 9999.ebuild.
The ebuild inherits from the cros-workon class.
The ebuild has a KEYWORD in the ebuild containing this architecture name (like "x86").

You can see a list of all of these packages by running this from inside the ~/trunk/src/scripts directory:

./cros_workon --board=${BOARD} list --all

Run cros_workon start

The first thing you'll want to do is to mark the package as active, like this (replacing ${PACKAGE_NAME} with your package name, like chromeos-wm):

./cros_workon --board=${BOARD} start ${PACKAGE_NAME}

This will:

Indicate that we'd like to build the 9999 version of the ebuild instead of the stable, committed version.
Indicate that we'd like to build from source every time.
If you specified that you wanted the minilayout when you did your repo init, this will add a clause to your.repo/local_manifest.xml to tell repo to sync down the source code for this package next time you do a repo sync.

repo sync

After you've run cros_workon, you'll want to sync down 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). You'll want to run this from outside the chroot, anywhere under your ~/chromiumos directory:

repo sync

TODO: The old instructions had this warning in them:

if you run repo sync inside your chroot ensure your email is configured right in git (git config -l). If your local commit email differs from your git config email address or if your git config email address is unset a "repo sync" will discard your local commits. The make_chroot / enter_chroot commands have been enhanced to copy your global git config into the chroot, so this should just work.

...someone who knows better should figure out if this warning is still relevant and update this section.

Figure out where the ebuild / source code for the project is

It can be a little tricky to figure out where the source code and ebuild for your project is. Luckily, some magic portage commands can come to the rescue.

To find out where the ebuild lives:

equery-${BOARD} which ${PACKAGE_NAME}

...for PACKAGE_NAME=chromeos-wm, that gave me:
/home/.../trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-wm/chromeos-wm-9999.ebuild

NOTE: If I ran that same commands without doing a 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

Again trying with PACKAGE_NAME=chromeos-wm, I saw this:

CROS_WORKON_SRCDIR="/home/.../trunk/src/platform/window_manager"

CROS_WORKON_PROJECT="window_manager"

SIDE NOTE: This little shell script 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 and git-cl, you should always create a local branch whenever you make a change. You can run the command to do this from outside the chroot (anywhere under your ~/chromiumos directory) or from within the chroot. In the command, you'll want to 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 describes this change (nobody else will see this name):

repo start ${BRANCH_NAME} ${CROS_WORKON_PROJECT}

The branch created 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 (the git and git cl ones) will open up an editor. You probably will want to do one of these three commands (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.

Submit changes locally

When your changes look good, you should commit them to your local branch using git. Full documentation of how to use git is a bit beyond this guide, but you might be able to commit them by running something like this command from the project directory:

git commit -a

...the git commit command will bring up a text editor. You should describe your change, save, and exit the editor. Note that the description is only for your own use. When you upload your changes for code review, the git-cl command will grab all of your previous descriptions, but you will have a chance to edit them.

Upload your changes and get a code review (committers only)

Once your changes are committed locally, you'll want to upload your change using git-cl. The git-cl command is very un-git-like. It takes all of the changes in your local branch, munges them into one patch, then uploads that to the code review server. You should run the command from outside the chroot, from within a directory that's part of the project you're working on:

git cl upload

The git cl upload command will bring up a text editor. What you write here is important, since it will get sent to the code review server. The first line should be a short description of your change. Later lines can contain more descriptions. The text editor will also be populated with BUG= and TEST= lines.

For BUG=, you should put something that looks like: BUG=bug-tracker:number. If this change is related to more than one tracker issue, you can list them all separated with commas. You can get a tracker name by looking in the upper-left corner in the tracker page (see image on right).

For TEST=, you should describe what you did to test the change.

Here's what a sample would 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 is more details

...this can be as long as I want.

BUG=chromium-os:99999, chromium:88888

TEST=Ran all the white box tests

Save the file and exit the editor. This will upload the changes and print out a URL for the 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 "Publish+Mail Comments" to mail it to your reviewers.

You will likely get comments from reviewers on what you need to change before submitting. You should make these changes, submit them locally, then re-upload your changes for code review. Note that git-cl stores the code review "issue number" as meta data on your git branch. That means that each git branch is associated with one and only one code review. If you do a second git cl upload on your branch, it will amend your previous code review, not start another one.

Eventually, all your reviewers will be fat and happy and will tell you LGTM (looks good to me).

Try seeing the mainline again

While you're working on your change, 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 it was always there). If you want to go back to the mainline without abandoning your change, you can do the following from within a directory associated with your project:

git checkout cros/master

When you're done, you can get back to your change by doing:

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 review to happen, you can repo start another branch. When you want to get back to your branch later, you can do the following from within a directory associated with your project:

git checkout ${BRANCH_NAME}

Push your change

Once you've iterated a few times and your code reviewers are happy (you get Looks Good To Me from all of them), you can push your change to live with:

git cl push

You probably want to do a repo sync before the git cl push to make sure that nothing is broken. This could cause a merge conflict. TODO: Some short desc of how to deal with merge conflicts?

SIDE NOTE: Now that you've pushed, if (for some reason) you wanted to re-use your same branch for another code review, you could clear your code review with git cl issue 0.

Submitting changes (non-committers)

If you're not a committer, I believe that the process is to submit a patch to the the Chromium OS dev group.

TODO: put instructions for generating this patch. You might want to see git-format-patch?

Cleaning up after you're done with your change

Once you're done with your change, you're ready to clean up. The most important thing to do is to tell cros_workon that you're done by running this from inside the ~/trunk/src/scripts directory:

./cros_workon --board=${BOARD} stop ${PACKAGE_NAME}

...this will tell 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 that, but one of the ways is:

repo abandon ${BRANCH_NAME} ${CROS_WORKON_PROJECT}

SIDE NOTE: If you don't specify a project name with the repo abandon command, it will throw out any local changes across all projects. You might also want to look at git branch -D or repo prune.

SIDE NOTE: If you were running with the minilayout, doing a cros_workon stop won't remove your source code. It will continue to stay on your hard disk and get synced down.

Making sure your change didn't break things

After you commit, make sure you didn't break the build by checking the buildbot.

Making changes to something other than a package whose source is in our tree

If you want to make to changes to something other than the source code of a package, you can still follow most of the instructions above (in the Making changes to a package whose source is in our tree section). However, simply skip the cros_workon steps. Specifically, note that you still need the repo start step.

Things that fall into this category:

Build scripts (pretty much anything in src/scripts)
Changes to ebuild files themselves (like the ones under src/third_party/chromiumos-overlay)
Anything else?

Making changes to the way that the chroot is constructed

This section is currently a placeholder, waiting for someone to fill it in. However, a few notes:

Many of the commands that take a --board=${BOARD} parameter can also be passed a --host parameters. That will make the commands affect the host (AKA the chroot) rather than the board.

Most notably, cros_workon --host will say that you want to build a package used in the chroot from source.

If you modify the make_chroot script, remember that most developers won't get your change for a long time. People tend to build their chroot once, then never again. I believe that we're moving away from having the make_chroot script do much.

Building an individual package

TODO: Document this better..., and add the new cros_workon_make

Note: To build an individual package use emerge-${BOARD}. For example, if you want to build dash to test on your device:

emerge-${BOARD} dash

Working on a branch

It is required you have different checkouts (yes new chroots in a completely new directory) for every branch you are working on. This is to ensure all the prebuilts work automatically for you. You have to pass the -b <branch_name> option to repo during init and you will follow exactly the same workflow as above. (i.e cros_workon + repo start etc)

$ mkdir cros_0.9.110.B/ && cd cros_0.9.110.B/

$ repo init -u <URL> -b <branchname> [-m minilayout.xml]

$ #...follow steps above to edit/modify files i.e repo sync, cros_work start, repo start etc.

$ git cherry-pick -x <SHA1>  #To pull in changes that exist on another branch (TIP: git has all the objects from all branches)

$ git log # to verify the SHA1 exists on the branch.

$ git cl upload  #A new issue will be created for this branch commit

$ git cl push    # Make sure you have tested on your new branch - just cherry-picking doesn't guarantee it will build on the new branch

If you are a GIT Jedi master and a Portage black belt you can leverage the fact that all the branches checkouts actually checkout all the git objects, and the rest you can figure out :)

Troubleshooting

My build is failing, what's the problem?

It's possible that your build is broken because of transient failures introduced when a dependency is in-flight while its dependent is built. These often manifest as missing files or configuration information. Try re-running the 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 it will use wget to fetch packages. This wget process is run as the portage user, and if that user is unable to talk on the network it 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 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 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 it 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

And restart the firewall:

sudo restart ufw

Running Tests

Many of the automated tests that are part of the Chromium OS project run using the autotest framework. TODO: 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.

Getting an image that has been modified for test

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:

./image_to_usb.sh --board=${BOARD} --test_image --to=${MY_USB_KEY_LOCATION}

...or...

./image_to_vm.sh --board=${BOARD} --test_image

Adding the --test_image flag will cause 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) and then modify that image for test and use the test image as the source of the command.

SIDE NOTE: TODO: Is this still needed? I don't think so now that the default stateful size is 2G. When creating an VM image for testing purposes, it is highly recommended that you expand its stateful partition with the --statefulfs_size parameter. 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.

SIDE NOTE: If the directory already has a file called chromiumos_test_image.bin, it will be 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.

SIDE NOTE: If you are so inclined, you can call the mod_image_for_test.sh script directly. That will cause the script, by default, tomodify your existing chromiumos_image.bin for test. I don't see a lot of good reason to do this, unless you are low on disk space and know that you won't ever need the non-modified image.

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, the following steps have to be taken.

Create the source inside git repository R
Find out which ebuild builds test from repository R, if R is a new repository, create a new ebuild for it (see below).
Edit the ebuild, and add tests_${testname} into the IUSE_TESTS variable. Prefix your test with a + if you want it to be enabled by default.
Recompile (see modifying a test), make sure it runs, commit, etc.

To create a new ebuild, you need to utilize the autotest eclass, which wraps all the necessary steps to compile your tests. A new ebuild may have to be created if a new repository with tests is being started. Please refer to existing ebuilds for details.

If you create a new ebuild for test X, you will need to run cros_workon start X. Mysterious failures mode will occur otherwise.

Seeing which tests are implemented by an ebuild

TODO: Validate that these instructions are still right. They were copied from an old instructions page.

Run this command and look at the "USE=" output. The command tells emerge to "pretend" to build the tests and print out verbose output. You'll want to replace ${EBUILD_NAME} with the name of an ebuild containing tests (see just below), like autotest-tests:

emerge-${BOARD} -pv ${EBUILD_NAME}

As far as I know, the only ebuilds containing tests are:

chromeos-base/autotest-tests - the default set of tests, that did not fall anywhere else
chromeos-base/chromeos-chrome - chrome tests; the tests that are part of chrome

More testing tips

At the moment, I'd read the Running Smoke Suite On a VM Image page for more info about tests. It actually contains the most up-to-date info about autotests. TODO: It would be nice if some of that information migrated here?

Tips and Tricks

This section has been moved to its own page: Tips And Tricks for Chromium OS Developers.

Other notes

Developer mode

Sometimes in this document, we talk about "developer mode". It can be confusing about what developer mode is, since some instructions talk about developer mode being entered by running with an image that was built "--withdev" and others talk about switching your hardware to "developer mode". It turns out that, for most things, the two actions both enable the same set of things (like the shell command in crosh). Thus, we refer to either as being in "developer mode".

To get into details, putting your hardware into developer mode will make:

/bin/cros_boot_mode

...print developer. It will also make the file /mnt/stateful_partition/.developer_mode appear.

Building with --withdev will create 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 will enable developer mode and also prevent wiping of the stateful partition when you switch your hardware between developer mode and release mode.

donderdag 9 december 2010

woensdag 8 december 2010

Google chrome os web store

zondag 5 december 2010

zaterdag 4 december 2010

Google chrome os review

ntro

Audience of this document

Getting started with Chromium OS development

Prerequisites

Install depot_tools

Install git

Configure git

Preparations if you are committer

Creating your ssh key

Submit your public key to the gitmaster

Automate usage of your key with keychain

Setup your ssh config

Decide where your source will live

Decide if you want the minilayout

Get the source

Create a chroot

Enter the chroot

Choose what board you want to build for

Initialize the build for a board

Set the chronos user password

Enable a local user account (optional)

Build the packages for your board

Build a disk image for your board

Looking at your disk image (optional)

Getting your image onto a USB key

Booting from your USB key

Getting to a command prompt on Chromium OS

Installing your Chromium OS image to your hard disk

Building an image to run in a virtual machine

Making changes

Making changes to a package whose source is in our tree

Run cros_workon start

repo sync

Figure out where the ebuild / source code for the project is

Create a branch for your changes

Make your changes

Set your editor

Submit changes locally

Upload your changes and get a code review (committers only)

Try seeing the mainline again

Work on something else while you're waiting

Push your change

Submitting changes (non-committers)

Cleaning up after you're done with your change

Making sure your change didn't break things

Making changes to something other than a package whose source is in our tree

Making changes to the way that the chroot is constructed

Building an individual package

Working on a branch

Troubleshooting

My build is failing, what's the problem?

How do I fix network problems in the chroot?

Running Tests

Getting an image that has been modified for test

Creating a new test

Seeing which tests are implemented by an ebuild

More testing tips

Tips and Tricks

Other notes

Developer mode

More reading