Getting and Building a Chromium-Based OS‎

Contents

1. 10. 1.10 Build image
3. 2. 3.2 Is there more documentation on repo ?
   8. 3.8 I miss the ability to see what the diffs are between my current branch and the master, even when there aren't any.

New Workflow

cros_workon is a workflow tool for ChromiumOS development. It is currently in beta. With cros_workon, developers subscribe to the packages they want to work on. The tools then only checkout the packages a developer is subscribed to and only builds the packages a developer is subscribed to. When using cros_workon, gclient is no longer used, and two new commands are used instead:

repo 

Usually run outside the chroot. It's used to check out and sync your repositories and manage the tracking branches for git. This is used instead of gclient. If run inside the chroot, make sure you have "git config -l" configured with your correct email address -- if not, you could lose local commits on repo sync.

src/scripts/cros_workon (will soon move be able to run cros_workon from anywhere in the chroot) 

Always run inside the chroot. It's used to unmask a package ebuild so that 1) repo will be prepared to sync a local copy of the source, and 2) build_packages will use the local source instead of the stable version.

In the examples below, the new commands are in bold. 

Migrating from old setup

If you have been using the old setup, do not try to reuse your old source directory.  Create a new one instead.

Initial Setup

Set up your .ssh/config file correctly.

Get the Source

We are using  as our new repository overlay tool. repo is used to checkout multiple repositories and sync them. It replaces the functionality that was previously provided by .

$ mkdir mychromiumos

$ cd mychromiumos

$ repo init -u  -m minilayout.xml

#internal users use: repo init -u ssh://gitrw.chromium.org:9222/manifest-internal -m minilayout.xml

$ repo sync

Create a chroot

To simplify dependencies, development is done inside a chroot. The following command creates the chroot for you.

$ cd src/scripts

$ ./make_chroot

or, faster:

$ cd src/scripts

$ ./make_chroot --fast

Enter the chroot

To enter the chroot in order to do development, run the following command:

$ ./enter_chroot.sh

Set up board

You need to run setup_board in order to install the toolchain (gcc/glibc) for the target you wish to work on. setup_board also creates the initial SYSROOT the target.

(chroot) $ ./setup_board --board=x86-generic --default

Build packages

The ChromiumOS equivalent of "make".

(chroot) $ ./build_packages

By default, build_packages will build the stable version of a package (i.e. from committed git sources) unless you are working on a package. If you are working on a package, build_packages will build using your local sources. See below.

Build image

The ChromiumOS equivalent of "make install".

(chroot) $ ./build_image

If you want to use the developer server (./start_devserver in the chroot) and gmerge on the device to build and merge changes that you make then you will need to disable the root filesystem signature checking. Give the flag (which will auto complete) to build_image.

(chroot) $ ./build_image --noenable_rootfs_verification

Start working on a package

In order to modify and build a local version of a package, you must first mark it active:

(chroot) $ ./cros_workon start  # Use the name of the Portage package, e.g chromeos-wm

This marks the ebuild for the given package so that build_packages will use your local changes instead of the stable, committed version.

If you don't know the package name, you can see all the available packages like this:

(chroot) $ ./cros_workon list --all

Special case: chromiumos-overlay is not in this list and cros_workon start/stop is not used.  Follow the instructions below under "Making and committing your changes".

Note: cros_workon requires either a "--host" or "--board PLATFORM" option, to indicate the target that will be affected by your local changes. Chances are that this argument is being silently provided by the contents of src/scripts/.default_board. If you need to work on package changes that should be built for multiple boards, you'll need to specify each board with separate "start" commands. For that to work, you'll need to delete the .default_board file.

Sync your package sources 

Now that you've specified which packages you want to edit, you'll need to ensure that you have a local copy of the sources checked out and up to date.

$ repo sync 

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/enter chroot commands have been enhanced to copy your global git config into the chroot, so this should just work.

Stop working on a package

This tells the buildsystem to use stable pre-built version of the package. build_packages will now ignore your local repository. Stopping doesn't delete your local copy, so don't be fooled into thinking it's still being used. 

(chroot) $ ./cros_workon stop 

Making and committing your changes (mostly the same as before)

Please ensure that you are working on a branch in order for git cl to function correctly. "repo" by default creates a detached head and will be listed as "no branch" when you do a "git branch -a". In the repository you are working on you will need to create a working branch with:

$ repo start   # Use the name of the repo minus the ".git", e.g. window_manager

Editing and submitting changes for review is the same as before:

# Edit, compile, test, repeat...

$ git commit -am "All your bugs are belong to us"

$ git cl upload --send-mail -r $reviewer

$ git cl push

Note: If you want to start a new branch while waiting on a CL review, use repo start to create it instead of git. This ensures that the proper tracking branch is created.

Re-syncing to a newer version of the ebuilds

This not only updates your git repo from the upstream source, but rebases your current branch as well. You may encounter merge problems, which you would resolve as usual.

$ repo sync

Cleaning up after a change is committed

Once you've committed your changes, you should delete the branch you were working in. Otherwise, Bad Things will happen to your repository.

$ repo abandon  []

If you don't specify a project name, the named branch will be deleted from all projects. This may not be what you want.

You do not need to run ./cros_workon stop. If you don't, build_packages will continue to build from your local source. If all you do is work on package foo, you'll start foo once and never worry. If you need to switch from one package to another, you'll want to stop the old package and start the new one.

(chroot) $ ./cros_workon stop 

(chroot) $ ./cros_workon start 

Autotest

Temporary Notice

Until the autotest is entirely converted, tested, and the new workflow is made default, there are no stable ebuilds for anything autotest-related, in order to not mess with the original workflow. Until that moment, the first thing that has to be done is to "workon" all autotest-related ebuilds. This also means that there will be no prebuilt packages yet.

$ cros_workon start autotest autotest-tests

$ repo sync

Running a test

The operation of autotest is significantly different in cros-workon. Tests are organized in ebuilds, where each ebuild implements certain number of tests. Tests consist of a build phase and run phase, where the first is executed by the ebuild, and the second by the "run_remote_tests.sh" script, with exactly the same syntax as before. Unlike before, tests have to be built with emerge-${board} before they can be ran using run_remote_tests.sh.

Currently, tests are organized within these ebuilds:

chromeos-base/autotest-tests

To see which tests are implemented by an ebuild, run the usual pretended emerge:

$ emerge-${board} -pv autotest-tests
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild   R   ] chromeos-base/autotest-tests-9999 to /build/x86-generic/ USE="autox hardened tpmtools xset -buildcheck -opengles" TESTS="audiovideo_FFMPEG audiovideo_PlaybackRecordSemiAuto audiovideo_V4L2 build_RootFilesystemSize compilebench dbench desktopui_BrowserTest desktopui_ChromeFirstRender desktopui_ChromeSemiAuto desktopui_FlashSanityCheck desktopui_IBusTest desktopui_KillRestart desktopui_PageCyclerTests desktopui_ScreenSaverUnlock desktopui_SpeechSynthesisSemiAuto desktopui_SunSpiderBench desktopui_UITest desktopui_UrlFetch desktopui_V8Bench desktopui_WindowManagerFocusNewWindows desktopui_WindowManagerHotkeys disktest factory_Camera factory_DeveloperRecovery factory_Display factory_Dummy factory_ExternalStorage factory_Fail factory_Keyboard factory_Leds factory_RebootStub factory_Review factory_ScriptWrapper factory_ShowTestResults factory_Touchpad factory_Wipe firmware_RomSize fsx graphics_GLBench graphics_TearTest graphics_WindowManagerGraphicsCapture hackbench hardware_Backlight hardware_BluetoothSemiAuto hardware_Components hardware_DeveloperRecovery hardware_DiskSize hardware_EepromWriteProtect hardware_GPIOSwitches hardware_GPS hardware_MemoryThroughput hardware_MemoryTotalSize hardware_Resolution hardware_SAT hardware_SsdDetection hardware_StorageFio hardware_UsbPlugIn hardware_VideoOutSemiAuto hardware_bma150 hardware_tsl2563 iperf logging_KernelCrash logging_LogVolume logging_UserCrash login_Backdoor login_BadAuthentication login_ChromeProfileSanitary login_CryptohomeIncognitoMounted login_CryptohomeMounted login_CryptohomeUnmounted login_LoginSuccess login_LogoutProcessCleanup login_RemoteLogin ltp netperf2 netpipe network_3GSmokeTest network_ConnmanIncludeExcludeMultiple network_DhclientLeaseTestCase network_DisableInterface network_NegotiatedLANSpeed network_Ping network_UdevRename network_WiFiCaps network_WiFiSmokeTest network_WifiAuthenticationTests network_WlanHasIP network_netperf2 platform_AccurateTime platform_AesThroughput platform_BootPerf platform_CheckErrorsInLog platform_CleanShutdown platform_CryptohomeChangePassword platform_CryptohomeMount platform_CryptohomeTestAuth platform_DMVerityCorruption platform_DaemonsRespawn platform_DiskIterate platform_FileNum platform_FilePerms platform_FileSize platform_KernelVersion platform_MemCheck platform_MiniJailCmdLine platform_MiniJailPidNamespace platform_MiniJailPtraceDisabled platform_MiniJailReadOnlyFS platform_MiniJailRootCapabilities platform_MiniJailUidGid platform_MiniJailVfsNamespace platform_NetParms platform_OSLimits platform_PartitionCheck platform_ProcessPrivileges platform_Shutdown platform_StackProtector platform_TempFS power_Backlight power_BatteryCharge power_CPUFreq power_CPUIdle power_Draw power_Idle power_LoadTest power_Resume power_StatsCPUFreq power_StatsCPUIdle power_StatsUSB power_Status power_x86Settings realtimecomm_GTalkAudioBench realtimecomm_GTalkAudioPlayground realtimecomm_GTalkPlayground realtimecomm_GTalkunittest security_RendererSandbox unixbench -example_UnitTest -firmware_VbootCrypto -graphics_GLAPICheck -graphics_O3DSelenium -graphics_SanAngeles -graphics_WebGLConformance -hardware_TPM -hardware_TPMFirmware" 0 kB [1]

All tests have a default state, either enabled (+) or disabled (-). The TESTS= variable is a USE_EXPAND. There are two ways to use these. 
Non-Incremental - Simply override the list by a new list 

TESTS="platform_MiniJailPidNamespace platform_MiniJailPtraceDisabled" emerge-${board} -pv autotest-tests

Incremental - All USE_EXPAND flags are also accessible as USE flags, with the appropriate prefix, and can be used incrementally with +, - 

USE="tests_platform_MiniJailPidNamespace tests_platform_MiniJailPtraceDisabled" emerge-${board} -pv autotest-tests

For operations across all tests, following incremental USE wildcard is supported by portage: "tests_*" 
Both Incremental and Non-Incremental methods can be set/overriden by: the ebuild (default values), make.conf, make.profile, /etc/portage, commandline (see above)

Modifying a test

To modify a test, the following steps have to be taken for each modification. Let's assume we're modifying test netperf2, and the ebuild which implements it is called autotest-tests.

1) Make sure you cros-workon start autotest-tests, if you aren't working on it

2) Modify source

3) Recompile the test

TESTS="netperf2" emerge-${board} autotest-tests

4) Run the test (NOTE: this step is identical to the gclient workflow, including the syntax)

./run_remote_tests.sh --remote= client/tests/netperf2/control.parallel

5) Goto 2) if more modifications are necessary

Creating a new test

To create a new test, the following steps have to be taken.

1) Create the source inside repository R

2) Find out which ebuild builds test from repository R, if R is a new repository, create a new ebuild for it (see below).

3) 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.

4) Recompile, 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.

Frequently Asked Questions

How do I configure repo to sync private repositories?

Create a file called .repo/local_manifest.xml and your private project into it. 

  
           fetch  = "ssh://gitrw.chromium.org"
           review = "" />

  
           name   = "nameofgitrepo"
           remote = "private" />

If you want to pull in from a different git server you will need to add a different remote for the project. Please type "repo manifest -o tmp.xml" to dump your current manifest to see an example. More documentation on the manifest file format is .

Is there more documentation on repo ?

Here is a .

You can also run "repo help --all" and "repo help "

Here is the 

Here is the repo-discuss Google Groups

I see "rpc 502" errors. What do I do ?

We have currently switched to using http for pulling code and ssh for pushing code (through git URL redirect) to scale better. But in some cases we have seen "rpc timeouts" with 502 errors.  502 errors are usually from the proxy server you are using. Please run repo with the --trace to see which particular repository you hit the error in and update the issue .

How do I set up git bash completion on Ubuntu?

Add the following lines to your ~/.bashrc 

if [ -f /etc/bash_completion ]; then

 . /etc/bash_completion

fi

How do I set up repo bash completion on Ubuntu?

Copy the attached bash_completion file under your home directory (e.g., under ~/etc) and add the following line to your ~/.bashrc:

[ -f "$HOME/etc/bash_completion" ] && . "$HOME/etc/bash_completion"

How do I modify my prompt to tell me which branch I'm in?

Add the following to your ~/.bash_profile: 

export PS1='\h:\W$(__git_ps1 "(%s)") \u\$ '

What happened to the 'wtf' command?

Use "repo status" instead. It shows almost the same information in a completely different format (of course).

I miss the ability to see what the diffs are between my current branch and the master, even when there aren't any.

Before: 

$ git branch -v

* foo    56cec58 Do something.

  master 56cec58 Do something.

But now the master status isn't shown: 

$ git branch -v

* foo    56cec58 Do something.

Yeah, I miss that too. gclient initialized the "head/master" branch that was based on the stable source, and it was up to you to remember to create a local branch to make changes. Now, that master branch doesn't exist, and the "cros/master" branch refers to the stable source. If someone knows the magic git incantation, please write it here.

I have a ton of repos in which I have created branches, done work, and committed locally. I need to determine which they are so that I can cros_workon them again.

repo branches is what you are asking for. Otherwise, repo forall would be your friend

Source code hierarchy

Get to know the source code. For an overview of what's where, see .

How do I manually uprev a package

During the course of the migration to the new workflow, you may need to manually uprev a package.  To do please use the following command:

~/src/scripts/cros_mark_as_stable -b -p -i

This will create a git branch in your chromiumos-overlay directory corresponding called stabilizing_branch which will contain the uprev changes.  Upload and commit this change.  If you'd like a reviewer, use [e-mail]

e.g. here's a scenario:

Let's say I have made a change to ~/src/platform/login-manager which corresponds to the chromeos-login package.  After I've committed my change, I should re-sync my login-manager directory, get the commit id for the commit I just committed (can use git log | head -1).  For the sake of this example let's say it's d52c5ea1bcdcc2e0ed2f62c3d50eb7e6bda691ca.  To manually uprev the package I'd run (assuming I'm using x86-generic):

~/src/scripts/cros_mark_as_stable -b x86-generic -p "chromeos-login" -i d52c5ea1bcdcc2e0ed2f62c3d50eb7e6bda691ca

Then I'd commit this change:

cd ~/src/third_party/chromiumos-overlay

git cl upload -r [e-mail] --send-mail

git cl push

How do I build Chromium from source?

The chromeos-base/chromeos-chrome ebuild contains a step for verifying that the libcros API is still compatible with the revision of Chromium being built.  In order for the ebuild to find the header files you'll need to "work on" the chromeos-chrome/libcros package.

./enter_chroot --chrome_root=/path/to/chrome/source/dir

# You only need to do this once!
./cros_workon start chromeos-base/libcros
repo sync

# If you want to always build from source you can export the variables:
export CHROME_ORIGIN=LOCAL_SOURCE
export FEATURES="-usersandbox"
export USE="-build_tests"
./build_packages

# If you want to only emerge the browser:
USE="-build_tests" FEATURES="-usersandbox" CHROME_ORIGIN=LOCAL_SOURCE emerge-x86-generic chromeos-base/chromeos-chrome

Additional instructions on building Chromium from source can be found .