| # Adding third_party Libraries | |
| [TOC] | |
| 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 `//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. | |
| ## Put the code in //third_party | |
| By default, all code should be checked into [//third_party](../third_party/), | |
| for the reasons given above. Other locations are only appropriate in a few | |
| situations and need explicit approval; don't assume that because there's some | |
| other directory with third_party in the name it's okay to put new things | |
| there. | |
| ## Before you start | |
| To make sure the inclusion of a new third_party project makes sense for the | |
| Chromium project, you should first obtain | |
| [Chrome Eng Review](../ENG_REVIEW_OWNERS) approval. Please include the following information in an | |
| email to chrome-eng-review@google.com: | |
| * Motivation of your project | |
| * Design docs | |
| * Additional checkout size | |
| * Build time increase | |
| * Binary size increase on Android ([official](https://www.chromium.org/developers/gn-build-configuration) builds) | |
| * Binary size increase on Windows | |
| Googlers can access [go/chrome-eng-review](https://goto.google.com/chrome-eng-review) and review | |
| existing topics in g/chrome-eng-review, and can also come to office hours to ask | |
| questions. | |
| ### A note on size constraints | |
| The size of Chromium derived executables can impact overall performance of those binaries as they | |
| need to run on a wide range of devices including those with extremely limited RAM. Additionally, we | |
| have experience from Windows of the binary size impacting successful patch rate of updates as well | |
| as constraints from the Android Ecosystem where APKs included in the system image have hard | |
| limits on their size due to allocation size of the system partition. For more details and | |
| guidelines on size increases see | |
| [//docs/speed/binary_size/binary_size_explainer.md](binary_size_explainer) and Googlers can | |
| additionally check [go/chrome-binary-size](go/chrome-binary-size) | |
| ## Get the code | |
| There are two common ways to depend on third-party code: you can reference a | |
| Git repo directly (via entries in the DEPS file) or you can check in a | |
| snapshot. The former is preferable in most cases: | |
| 1. If you are actively developing in the upstream repo, then having the DEPS | |
| file include the upstream (that's been mirrored to GoB, see below) can be a | |
| way to include those changes into Chromium at a particular revision. The | |
| DEPS file will be updated to a new revision when you are ready to "roll" the | |
| new version into Chromium. This also avoids duplicate copies of the code | |
| showing up in multiple repos leading to contributor confusion. | |
| 1. This interacts favorably with our upstream tracking automation. We | |
| automatically consume the upstream Git hashes and match them against a | |
| database of known upstreams to tracking drift between Chromium and upstream | |
| sources. | |
| 1. This makes adding deps that don't need local changes easier. E.g. some of | |
| our automation automatically converts non-GN build rules into GN build rules | |
| without any additional CLs. | |
| Checking in a snapshot is useful if this is effectively taking on maintenance | |
| of an unmaintained project (e.g. an ancient library that we're going to GN-ify | |
| that hasn't been updated in years). And, of course, if the code you need isn't | |
| in a Git repo, then you have to snapshot. | |
| ### Node packages | |
| To include a Node package, add the dependency to the | |
| [Node package.json](../third_party/node/package.json). Make sure to update | |
| the corresponding [`npm_exclude.txt`](../third_party/node/npm_exclude.txt) | |
| and [`npm_include.txt`](../third_party/node/npm_include.txt) to make the code | |
| available during checkout. | |
| ### Pulling the code via DEPS | |
| If the code is in a Git repo that you want to mirror, please file an [infra git | |
| ticket](https://bugs.chromium.org/p/chromium/issues/entry?template=Infra-Git) | |
| to get the repo mirrored onto chromium.googlesource.com; we don't allow direct | |
| dependencies on non-Google-hosted repositories, so that we can still build | |
| if an external repository goes down. | |
| Once the mirror is set up, add an entry to [//DEPS](../DEPS) so that gclient | |
| will pull it in. If the code is only needed on some platforms, add a condition | |
| to the deps entry so that developers on other platforms don't pull in things | |
| they don't need. | |
| As for specifying the path where the library is fetched, a path like | |
| `//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. | |
| Lastly, add the new directory to Chromium's `//third_party/.gitignore`, so that | |
| it won't show up as untracked files when you run `git status` on the main | |
| repository. | |
| ### Checking in the code directly | |
| If you are checking in a snapshot, 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 | |
| `sha512sum` or `openssl dgst -sha512`. If retrieving from a git | |
| repository, please list the revision that the code was pulled from. | |
| If you are checking the files in directly, you do not need an entry in DEPS | |
| and do not need to modify `//third_party/.gitignore`. | |
| ### Checking in large files | |
| _Accessible to Googlers only. Non-Googlers can email one of the people in | |
| third_party/OWNERS for help. | |
| See [Moving large files to Google Storage](https://goto.google.com/checking-in-large-files) | |
| ## Document the code's context | |
| ### Add OWNERS | |
| Your OWNERS file must either list two Chromium developer accounts as the first | |
| two lines or include a `file:` directive to an OWNERS file within the | |
| `third_party` directory that itself conforms to this criterion. 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 | |
| [//third_party/README.chromium.template](../third_party/README.chromium.template) | |
| for a list of fields to include. A presubmit check will check this has the right | |
| format. | |
| README.chromium files contain a field indicating whether the package is | |
| security-critical or not. A package is security-critical if it is compiled | |
| into the product and does any of the following: | |
| * Accepts untrustworthy inputs from the internet | |
| * Parses or interprets complex input formats | |
| * Sends data to internet servers | |
| * Collects new data | |
| * Influences or sets security-related policy (including the user experience) | |
| One of the fields is CPEPrefix. This is used by Chromium and Google systems to | |
| spot known upstream security vulnerabilities, and ensure we merge the fixes | |
| into our third-party copy. These systems are not foolproof, so as the OWNER, | |
| it's up to you to keep an eye out rather than solely relying on these | |
| automated systems. But, adding CPEs decreases the chances of us missing | |
| vulnerabilities, so they should always be added if possible. | |
| The CPE is a common format shared across the industry; you can look up the CPE | |
| for your package [here](https://nvd.nist.gov/products/cpe/search). Please use | |
| CPE format 2.2. When searching for a CPE, you may find that there is not yet | |
| a CPE for the specific upstream version you're using. This is normal, as CPEs | |
| are typically allocated only when a vulnerability is found. You should follow | |
| the version number convention such that, when that does occur in future, we'll | |
| be notified. If no CPE is available, please specify "unknown". | |
| If you're using a patched or modified version which is halfway between two | |
| public versions, please "round downwards" to the lower of the public versions | |
| (it's better for us to be notified of false-positive vulnerabilities than | |
| false-negatives). | |
| ### Add a LICENSE file and run related checks | |
| You need a LICENSE file. Example: | |
| [//third_party/libjpeg/LICENSE](../third_party/libjpeg/LICENSE). | |
| Run `//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. | |
| If the library will never be shipped as a part of Chrome (e.g. build-time tools, | |
| testing tools), make sure to set "License File" as "NOT_SHIPPED" so that the | |
| license is not included in about:credits page ([more on this below](#credits)). | |
| ## Get a review | |
| All third party additions and substantive changes like re-licensing need the | |
| following sign-offs. Some of these are accessible to Googlers only. | |
| Non-Googlers can email one of the people in | |
| [//third_party/OWNERS](../third_party/OWNERS) for help. | |
| * Make sure you have the approval from Chrome Eng Review as mentioned | |
| [above](#before-you-start). | |
| * Get security@chromium.org (or chrome-security@google.com, Google-only) | |
| approval. Email the list with relevant details and a link to the CL. | |
| 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. | |
| * Add chromium-third-party@google.com as a reviewer on your change. This | |
| will trigger an automatic round-robin assignment to a reviewer who will check | |
| licensing matters. These reviewers may not be able to +1 a change so look for | |
| verbal approval in the comments. (This list does not receive or deliver | |
| email, so only use it as a reviewer, not for other communication. Internally, | |
| see [cl/221704656](https://cl/221704656) for details about how | |
| this is configured.). If you have questions about the third-party process, | |
| ask one of the [//third_party/OWNERS](../third_party/OWNERS) instead. | |
| * Lastly, if all other steps are complete, get a positive code review from a | |
| member of [//third_party/OWNERS](../third_party/OWNERS) to land the change. | |
| Please send separate emails to the eng review and security@chromium.org. | |
| You can skip the eng review and security@chromium.org when you are only moving | |
| existing directories in Chromium to //third_party/. | |
| Subsequent changes don't normally require third-party-owners or security | |
| approval; you can modify the code as much as you want. When you update code, be | |
| mindful of security-related mailing lists for the project and relevant CVE to | |
| update your package. | |
| ## How we ensure that the right credits are displayed {#credits} | |
| As we said at the beginning, it is important that Chrome displays the | |
| right credit and attributions for all of the third_party code we use. | |
| To view this in chrome, you can open chrome://credits. | |
| That page displays a resource embedded in the browser as part of the | |
| [//components/resources/components_resources.grd](../components/resources/components_resource.grd) | |
| GRIT file; the actual HTML text is generated in the | |
| [//components/resources:about_credits](../components/resources/BUILD.gn) | |
| build target using a template from the output of the | |
| [//tools/licenses.py](../tools/licenses.py) script. Assuming you've followed | |
| the rules above to ensure that you have the proper LICENSE file and it passes | |
| the checks, it'll be included automatically. |