Any code that you re-use should be in src/third_party. Even if you're just modifying a few functions to make things work in Chromium, the modified code should still live in src/third_party. Any code you incorporate comes with a copyright and a license that we want to comply with. It might be easier on you, as a developer, to check in to some other directory and note the original source in a header comment. This is certainly a lot easier if you're pulling in some code with slight modifications (even just deleting extra tab whitespace).
However, that makes it harder for us as a project to track license compliance and make sure we're providing the proper credits and attributions. It's doubly hard on projects that embed our code, because it makes it harder to sort out what's Chromium licensed and what's covered by other agreements.
So...
ALL THIRD PARTY CODE MUST BE CHECKED IN TO A THIRD PARTY DIRECTORY.
Thank you for re-using code when it makes sense (so we don't have to re-invent the wheel), and thank you for your help in keeping our licenses clean.
We need to make sure we respect the licenses of the code we use and make sure we maintain Chrome as a re-usable component in other products and projects.
It is OK to have third_party subdirectories that are not top-level, src/net/third_party is ok for example. But don't add more third_party directories than necessary.
Additional requirements:
- When checking in a third-party library
- 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.
- 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.
- You need a LICENSE file. See http://src.chromium.org/viewvc/chrome/trunk/src/third_party/libjpeg/LICENSE?revision=42288&view=markup
- You need to run '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.
- You need to run 'src/tools/checklicenses/checklicenses.py'. See section 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 section below for info how to handle possible failures. We run license checking on one of Android FYI bots, so any failures introduced will be discovered quickly.
- 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 is 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) - 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)
Getting a review- All third_party additions should go through a Chrome Eng Review before being checked in.
- Email open-source-third-party-reviews@google.com on the first change and any substantive changes (relicensing). You do not need reviews from open-source-third-party-reviews for changes to the code (but do follow normal code review processes)
- Talk to the Chromium Security Team and make sure they are ok with the new library.
| 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. 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. |
Making it possible to use system libraries
Chromium is an Open Source project. Linux distributions take the code and package it, and they don't like the usage of bundled libraries, which we're forced to do for Google Chrome because on Windows and Mac there is generally no concept of "system libraries" (in the Linux distro sense), and providing Google Chrome packages using system libraries to work on various distros would also be difficult (different distros use different, binary-incompatible versions of libraries, and also using different names for dependencies).
Note that this is not something new, and is already followed in our tree: bzip2, flac, icu, libevent, libjpeg, libpng, libwebp, libxml, libxslt, speex, v8, xdg-utils, yasm, zlib have -Duse_system_foo (e.g. use_system_icu) gyp flags that Linux distros can use. Of course Google Chrome continues to use bundled libraries.
You are expected to do this when the library is being checked into chromium (i.e. test whether your -Duse_system_foo option works, i.e. gyp succeeds, compilation of chrome succeeds, and resulting chrome works), but then you can expect Linux distros to report problems as they arise with more recent versions of the library, and provide patches. The use_system_foo switches are not officially supported.
1. There are many examples in the tree. Go to cs.chromium.org and search for use_system_speex, use_system_flac, use_system_yasm and so on.
2. In gyp, add a new variable:
'variables': {
'use_system_speex%': 0,
},
3. Create a big conditional:
'conditions': [
['use_system_speex==0', {
'targets': [
{
'target_name': 'libspeex',
'product_name': 'speex',
'type': '<(library)',
'sources': [
'libspeex/arch.h',
'libspeex/bits.c', ... ], } ], }, { # use_system_speex != 0 'targets': [
{
'target_name': 'libspeex',
'type': 'none',
'variables': {
'headers_root_path': 'include',
'header_filenames': [
'speex/speex_types.h',
'speex/speex_callbacks.h',
'speex/speex_config_types.h',
'speex/speex_stereo.h',
'speex/speex_echo.h',
'speex/speex_preprocess.h',
'speex/speex_jitter.h',
'speex/speex.h',
'speex/speex_resampler.h',
'speex/speex_buffer.h',
'speex/speex_header.h',
'speex/speex_bits.h',
],
},
'includes': [
'../../build/shim_headers.gypi',
], 'direct_dependent_settings': {
'cflags': [
'<!@(pkg-config --cflags speex)',
], },
'link_settings': {
'ldflags': [
'<!@(pkg-config --libs-only-L --libs-only-other speex)',
],
'libraries': [
'<!@(pkg-config --libs-only-l speex)',
],
},
}, }]
5. That's all! shim_headers.gypi and the variables block above take care of getting shim headers right.
If you're still unsure, just check in a gyp file with the skeleton above (with the use_system_foo big conditional). This helps with cleaner diffs when adding proper support later. |
