Dev-Install: Installing Developer and Test packages onto a Chrome OS device

Overview

For developers of Chromium OS there are many helpful packages included as part of developer and test images that are not included as part of Chrome OS. Bootstrapping and getting these back into the system can be very difficult without re-imaging the entire device. Ideally, you'd be able to get these packages back but still auto-update the rest of the system. Dev-install solves this use case. In essence it restores /usr/local back to that of a developer image.

The requirements are:

In developer mode.

The installation of software is done through Gentoo's emerge. In order to get emerge configured, follow the following steps:

Boot the machine and go to a shell (login and go to crosh (ctrl+alt+t) or change to virtual terminal 2 (CTRL+ALT+F2))
Change to root and initialize the login environment variables:
```
$ sudo su -
```
Execute the dev_install script. This script does everything automatically and asks you if you want to install chromeos-dev (it will take a while if you choose to):
```
# dev_install [--reinstall if done before]
```
Use emerge as usual. For example, to get qemacs install:
```
# emerge qemacs
```
Done! Now you can emerge any package in chromeos-dev or chromeos-test.

If you ever want to revert to having a pristine base image you can just run (which is the same as deleting everything under /usr/local):

# dev_install --uninstall

What can you do

In general, anything that works in /usr/local from chromeos-dev / chromeos-test should work. Consider the following examples:

sshfs-fuse -- allows you to mount a remote folder using ssh onto your chromebook.
gmerge -- allows you to contact a developer machine to build and re-install a developer package. gmerge allows overrides to set your developer machine / board to whatever you have configured on your developer machine. Want some portage package? Install it via the devserver!

To see what is installable, check /etc/portage/make.profile/package.installable.

General Troubleshooting

dev_install will assume that /usr/local is empty if the directory for portage (/usr/local/etc/portage) is not there. If that's not the case and that leads to problems during the bootstrapping process you can ask dev_install to wipe /usr/local first by using:

# dev_install --reinstall

Another source of problems is dev_install trying to connect to an incorrect BINHOST. The symptom for this is dev_install exiting after trying to extract the first download package (the package file downloaded with curl in /usr/local/portage/packages/... will contain a html error message). The binhost is generated by the release builders, so it is possible that a developer builds a new image with a release number that it's the same as a failed builbot. For example, in /etc/lsb-release the version number reads 0.15.912 but the builder with that version number failed. The are two possible fixes:

repo sync to another build number.

Use another binhost with the --binhost_version option or --binhost:

# dev_install --binhost_version 1120.0
# dev_install --binhost https://commondatastorage.googleapis.com/chromeos-dev-installer/board/x86-mario/full-1120.0.0/packages

Behind the scenes

If you want to know what's going on in dev_install, this is the overall view of the process:

Based on the board and the release number in /etc/lsb-release find the appropriate BINHOST, unless --binhost or --binhost_version command line arguments are used.
Bootstrap emerge by downloading the packages listed in /etc/portage/bootstrap.packages from the BINHOST.
Configure emerge (write make.conf to /usr/local/etc/portage and symlink /etc/portage/make.profile) to install new software to /usr/local.

bootstrap.packages is generated during the build image process. It is a text file that contains a list of packages with version numbers that portage needs (portage included) and that are not already in the base image. All the packages in the base image (except the virtual ones) are listed /etc/portage/make.profile/package.provided so emerge will no try to install them and assume they are installed while resolving dependencies

Known bugs

label:dev_install on crbug.com

Who to contact for more info (@chromium)

Please use the main list: chromium-os-dev@chromium.org