Adding third_party Libraries

Quick links

Other sites

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.

For Developers‎ > ‎

Contents
1 Getting the Code
2 Put the Code in (the right) third_party
3 Document the Code's Context
3.1 Add OWNERS
3.2 Add a README.chromium
3.3 Add a LICENSE file and run related checks
3.4 Modify DEPS
4 Setting up ignore
5 Get a Review
6 Ask the infrastructure team to set the try server
7 Odds n' Ends
7.1 Handling licenses_check (checklicenses.py) failures
7.2 Handling webview_licenses.py failures

Using third party code can save time and is consistent with our values - no need to reinvent the wheel! We put all code that isn't written by Chromium developers into src/third_party (even if you end up modifying just a few functions). We do this to make it easy to track license compliance, security patches, and supply the right credit and attributions. It also makes it a lot easier for other projects that embed our code to track what is Chromium licensed and what is covered by other licenses.

Getting the Code

When you find code you want to use, get it. This often means downloading: from Sourceforge, from the hosting feature of Google Code, or from somewhere else. Sometimes it can mean negotiating a license with another company and receiving the code another way. Please describe the source in the README.chromium file, described below.

For security reasons, please retrieve the code as securely as you can, using HTTPS and GPG signatures if available.

If retrieving a tarball, please do not check the tarball itself into the tree, but do list the source and the SHA-512 hash (for verification) in the README.chromium and Change List. The SHA-512 hash can be computed via the shasum (sha512sum) or openssl utilities.

If retrieving from a git repository, please list the SHA-512 hash.

Put the Code in (the right) third_party

By default, all code should be checked into src/third_party. It is OK to have third_party subdirectories that are not top-level (e.g. src/net/third_party), but don't add more third_party directories than necessary.

Document the Code's Context

Add OWNERS

Your OWNERS file must include 2 Chromium developer accounts. This will ensure accountability for maintenance of the code over time. While there isn't always an ideal or obvious set of people that should go in OWNERS, this is critical for first-line triage of any issues that crop up in the code.

As an OWNER, you're expected to:

Remove the dependency when/if it is no longer needed
Update the dependency when a security or stability bug is fixed upstream
Help ensure the Chrome feature that uses the dependency continues to use the dependency in the best way, as the feature and the dependency change over time.

Add a README.chromium

You need a README.chromium file with information about the project from which you're re-using code. See README.chromium.template for a list of fields to include. A presubmit check will check this has the right format.

Add a LICENSE file and run related checks

You need a LICENSE file. Example: third_party/libjpeg/LICENSE.

Run the following scripts:

src/tools/licenses.py scan - This will complain about incomplete or missing data for third_party checkins. We use 'licenses.py credits' to generate the about:credits page in Google Chrome builds.
src/tools/checklicenses/checklicenses.py - See below for info how to handle possible failures.
If you are adding code that will be present in the content layer, please make sure that the license used is compliant with Android tree requirements because this code will also be used in Android WebView. You need to run src/android_webview/tools/webview_licenses.py scan

See the "Odds n Ends" Section below if you run into any failures running these.

Modify DEPS

If the code is applicable and will be compiled on all supported Chromium platforms (Windows, Mac, Linux, ChromeOS, iOS, Android), check it in to src/third_party.

If the code is only applicable to certain platforms, check it in to src/third_party and add an entry to the DEPS file that causes the code to be checked out from src/third_party into src/third_party by gclient.

Explanation: Checking it into src/third_party causes all developers to need to check out your code. This wastes disk space cause syncing to take longer for developers that don't need your code. When all platforms really do need the code, checking it in to src/third_party allows some slight improvements over DEPS.

As for specifying the path where the library is fetched, a path like src/third_party/<project_name>/src is highly recommended so that you can put the file like OWNERS or README.chromium at third_party/<project_name>. If you have a wrong path in DEPS and want to change the path of the existing library in DEPS, please ask the infrastructure team before committing the change.

Setting up ignore

You should add the new directory to .gitignore.

You also need to set the svn:ignore property on the folder. This requires an svn checkout and isn't reviewable. It's best to use a clean checkout to avoid accidentally pulling in other changes.

Here is a recipe for adding a dep that will get checked out into third_party/jarjar:

Do a bare checkout of the folder above. svn checkout --depth empty svn://svn.chromium.org/chrome/trunk/src/third_party
Edit the svn properties. cd third_party; svn propedit svn:ignore . (this list is usually sorted). If the path is like third_party/<project_name>/src, create a new directory and set svn:ignore there.
Double check with svn status and svn diff that you are only changing props.
Commit. svn commit (this will launch editor to create your message, and then commit directly without review)

Get a Review

All third party additions should go through a Chrome Eng Review before being checked in. The initial submission (and any substantive change, like relicensing) of third party code requires review from open-source-third-party-reviews@google.com and security@chromium.org.

Third party code is a hot spot for security vulnerabilities. When adding a new package that could potentially carry security risk, make sure to highlight risk to security@chromium.org. You may be asked to add a README.security or, in dangerous cases, README.SECURITY.URGENTLY file. When you update your code, be mindful of security-related mailing lists for the project and relevant CVE to update your package.

Subsequent changes don't require third-party-owners approval; you can modify the code as much as you want.

Ask the infrastructure team to set the try server

Before committing the DEPS, you need to ask the infra team to set the try server. Create a ticket for infra and ask the infra team.

Odds n' Ends

Handling licenses_check (checklicenses.py) failures

This is needed for Issue 28291: Pass the Ubuntu license check script:

If the failure looks like ...	... the right action is to ...
'filename' has non-whitelisted license 'UNKNOWN'	Ideally make the licensecheck.pl script recognize the license of that file. Often this requires adding a license header. Does it have license header? If it's third party code, ask the upstream project to make sure all their files have license headers. If the license header is there but is not recognized, we should try to patch licensecheck.pl. If in doubt please contact phajdan.jr@chromium.org
'filename' has non-whitelisted license 'X' and X is BSD-compatible	Add the license X to WHITELISTED_LICENSES in checklicenses.py . Make sure to respect the OWNERS of that file. You must get an approval before landing. CLs violating this requirement may be reverted.
'filename' has non-whitelisted license 'X' and X is not BSD-compatible (i.e. GPL)	Do you really need to add those files? Chromium is BSD-licensed so the resulting binaries can't use GPL code. Ideally we just shouldn't have those files at all in the tree. If in doubt, please ask mal@chromium.org

Handling webview_licenses.py failures

If the failure looks like ...	... the right action is to ...
Missing license file	Make sure that the license file is present. It should be called 'LICENSE', or otherwise README.chromium file must point to it explicitly.
The following files contain a third-party license but are not in a listed third-party directory...	Check if it's a false positive (e.g. 'copyright' word used in a string literal), if so, update src/android_webview/tools/third_party_files_whitelist.txt file. Otherwise, please move the code into third_party.