Adding a new CIPD dependency

1. Set up a new directory for your dependency

You‘ll first want somewhere in the repository in which your dependency will live. For third-party dependencies, this should typically be a subdirectory of //third_party. You’ll need to add the same set of things to that directory that you'd add for a non-CIPD dependency -- OWNERS, README.chromium, etc.

For example, if you want to add a package named sample_cipd_dep, you might create the following:

2. Acquire whatever you want to package

Build it, download it, whatever. Once you've done that, lay it out in your local checkout the way you want it to be laid out in a typical checkout.

Staying with the example from above, if you want to add a package named sample_cipd_dep that consists of two JARs, foo.jar and bar.jar, you might lay them out like so:

third_party/
sample_cipd_dep/
...
lib/
bar.jar
foo.jar

3. Create a cipd.yaml file

CIPD knows how to create your package based on a .yaml file you provide to it. The .yaml file should take the following form:

# Comments are allowed.
# The package name is required. Third-party chromium dependencies should
# unsurprisingly all be prefixed with chromium/third_party/.
package: chromium/third_party/sample_cipd_dep
# The description is optional and is solely for the reader's benefit. It
# isn't used in creating the CIPD package.
description: A sample CIPD dependency.
# The root is optional and, if unspecified, defaults to ".". It specifies the
# root directory of the files and directories specified below in "data".
#
# You won't typically need to specify this explicitly.
root: "."
# The install mode is optional. If provided, it specifies how CIPD should
# install a package: "copy", which will copy the contents of the package
# to the installation directory; and "symlink", which will create symlinks
# to the contents of the package in the CIPD root inside the installation
# directory.
#
# You won't typically need to specify this explicitly.
install_mode: "symlink"
# The data is required and described what should be included in the CIPD
# package.
data:
# Data can include directories, files, or a version file.
- dir: "directory_name"
# Directories can include an optional "exclude" list of regexes.
# Files or directories within the given directory that match any of
# the provided regexes will not be included in the CIPD package.
exclude:
- .*\.pyc
- exclude_me
- keep_this/but_not_this
- file: keep_this_file.bin
# If included, CIPD will dump package version information to this path
# at package installation.
- version_file: CIPD_VERSION.json

For example, for sample_cipd_dep, we might write the following .yaml file:

This will result in CIPD package chromium/third_party/sample_cipd_dep at TX7HeY1_1JLwFVx-xiETOpT8YK4W5CbyO26SpmaMA0IC being installed in src/third_party/sample_cipd_dep (relative to the gclient root directory).

Updating a CIPD dependency

To modify a CIPD dependency, follow steps 2, 3, and 4 above, then modify the version listed in DEPS.

Miscellaneous

Permissions in CIPD

You can check a package's ACLs with cipd acl-list:

$ cipd acl-list chromium/third_party/sample_cipd_dep
...

Permissions in CIPD are handled hierarchically. You can check entries higher in the package hierarcy with cipd acl-list, too:

Troubleshooting

A file maintained by CIPD is missing, and gclient sync doesn't recreate it.

CIPD currently caches installation state. Modifying packages managed by CIPD will invalidate this cache in a way that CIPD doesn't detect - i.e., CIPD will assume that anything it installed is still installed, even if you deleted it. To clear the cache and force a full reinstallation, delete your $GCLIENT_ROOT/.cipd directory.

Note that there is a bug on file to add a mode to CIPD that is not so trusting of its own cache.