cros deploy

Overview

cros deploy is a script to deploy (install) a package to your ChromiumOS device. It copies the binary packages built in your chroot to the target device and installs (emerges) on the device.

Note: cros deploy does not build packages for you. Please make sure you have built all the requested packages using emerge before invoking cros deploy.

Note: To be able to write to your rootfs partition, cros deploy may remount your rootfs partition as read-write or disable the rootfs verification on your device.

Note: cros deploy does not currently support deploying kernel packages. See the Kernel Development guide for supported methods.

Requirements

Chroot: cros deploy needs to run in chroot.
A SSH-able ChromiumOS device: Any ChromiumOS test image will work (base or dev images won't).

If your device is currently running a non-test image, you may want to use a USB stick to image the device.

Example usage

$ cros deploy <device> <package>...

<device>: The IP or hostname of the device, in the form ssh://hostname[:port] or hostname[:port], where port is the port number used for SSH. (It can be omitted and defaults to 22.)
<package>: One or more packages to install.

For example, to install the cherrypy package to your device (with IP address ${DUT_IP}):

$ cros deploy ${DUT_IP} cherrypy

How to specify package names

cros deploy does its best to figure out what packages you want to install, even when you do not enter a complete or unique package name. When there is ambiguity, it may prompt you to choose.

A unique package name should include three parts: ${category}/${package}-${version}. For example, dev-python/cherrypy-3.1.2.

cros deploy accepts any of the following formats:

${category}/${package}-${version}
${category}/${package}
${package}-${version}
${package}

When the given input such as ${package} (e.g. cherrypy) is unique, which is the common case, cros deploy automatically selects the right package for you. If, however, ${package} exists in multiple categories, cros deploy prompts you to choose. For example,

Multiple matches found for cherrypy:
  [0]: dev-python/cherrypy
  [1]: foo/cherrypy
Enter your choice to continue [0-1]: 1

When there are multiple versions available, cros deploy chooses the best visible one. For example, if you cros workon a package, cros deploy will try to use the 9999 version instead.

Known problems and fixes

Failed to emerge package

Errors like the one below are likely caused by emerge missing on the target system. (This can happen if the stateful partition is wiped after the OS image has been deployed. Also remember that the target needs to run a test image.)

13:14:55: ERROR: Failed to emerge package chromeos-chrome-46.0.2472.0_rc-r1.tbz2
13:14:56: ERROR: Oops. Something went wrong.
13:14:56: ERROR: cros deploy failed before completing.
13:14:56: ERROR: <class 'chromite.lib.cros_build_lib.RunCommandError'>: return code: 127
Failed command "ssh -p 22 '-oConnectionAttempts=4' '-oUserKnownHostsFile=/dev/null' '-oProtocol=2' '-oConnectTimeout=30' '-oServerAliveCountMax=3' '-oStrictHostKeyChecking=no' '-oServerAliveInterval=10' '-oNumberOfPasswordPrompts=0' -i /tmp/ssh-tmpb5S6kc/testing_rsa root@172.26.58.201 -- 'FEATURES=-sandbox' 'PORTAGE_CONFIGROOT=/usr/local' "CONFIG_PROTECT='-*'" 'PKGDIR=/usr/local/tmp/cros-deploy/tmp.6xIVEajmyJ/packages' 'PORTDIR=/usr/local/tmp/cros-deploy/tmp.6xIVEajmyJ' 'PORTAGE_TMPDIR=/usr/local/tmp/cros-deploy/tmp.6xIVEajmyJ/portage-tmp' emerge --usepkg /usr/local/tmp/cros-deploy/tmp.6xIVEajmyJ/packages/chromeos-base/chromeos-chrome-46.0.2472.0_rc-r1.tbz2 '--root=/'", cwd=None, extra env={'LC_MESSAGES': 'C'}

No space left on device

The following mostly occurs when deploying large packages such as Chrome:

rsync: write failed on "/usr/local/tmp/cros-deploy/tmp.Ts2Ayh1nKT/packages/chromeos-base/chromeos-chrome-46.0.2472.0_rc-r1.tbz2": No space left on device (28)
rsync error: error in file IO (code 11) at receiver.c(393) [receiver=3.1.1]
rsync: [sender] write error: Broken pipe (32)
13:21:46: ERROR: Oops. Something went wrong.
13:21:46: ERROR: cros deploy failed before completing.
13:21:46: ERROR: <class 'chromite.lib.cros_build_lib.RunCommandError'>: return code: 11

This happens because the target's /usr/local/tmp has insufficient space to download the package. A workaround is pointing /usr/local/tmp to /tmp:

$ rm -r /usr/local/tmp
$ ln -s /tmp /usr/local/tmp