Third-party code is part of the Fuchsia checkout but is neither copyrighted by the Fuchsia authors nor subject to Fuchsia's license. In other words, any code that is not 100% owned by the Fuchsia authors is managed as third-party code.
The Fuchsia project maintains copies of third-party code dependencies under the //third_party/
directory in the checkout. This is also known as vendoring. Vendoring ensures that third-party code is served from Fuchsia-owned source repositories and is served at revisions that are known to work with other code in the Fuchsia checkout.
When adding third-party code, follow the steps below to ensure the code complies with the Fuchsia project policies.
All external code must go through the Open Source Review Board (OSRB) process to be added to the Fuchsia Platform Source Tree. Once the OSRB request is approved, continue with the steps below.
If you are adding Rust, Go or Python dependencies, follow the guides below:
Rust: Follow the external Rust crates guide.
Go: See //third_party/golibs/
.
Python: Follow the external Python packages guide.
For all other languages, continue with the steps below.
All external code must follow the third_party source layout below (using googletest
as example):
root [fuchsia.googlesource.com/fuchsia] third_party/ googletest/ src/ [fuchsia.googlesource.com/third_party/github.com/google/googletest] BUILD.gn OWNERS README.fuchsia
//third_party/googletest/src/
is the root of the Fuchsia-owned mirror repository, that contains a copy of the upstream repository for googletest
. (Note: For Python repositories, replace /src
with /<module_name>
to follow Python's convention. This convention is expected by common Python tools like pyright.)
The //third_party/googletest/
directory is part of the fuchsia.git
repository.
//third_party/googletest/BUILD.gn
defines build targets for the googletest
library. Since this file belongs to fuchsia.git
(not the googletest
repository), it can be updated in lockstep with other Fuchsia BUILD.gn
files that depend on googletest
. This makes build refactors and other large-scale changes easier.
Additional files that are required to adapt the third-party code to the Fuchsia project may be present under (in this case) //third_party/googletest
.
Each dependency must have an associated OWNERS
file. Because it's defined in fuchsia.git
, it is possible to include owners from other files elsewhere in the Fuchsia project.
The OWNERS file must either list two Fuchsia developer accounts as the first two lines or include a file:
directive to another OWNERS file. This will ensure accountability for maintenance of the code over time.
The OWNERS are typically the owners of the code that use the dependency, unless specified otherwise.
The dependency's OWNERS help keep Fuchsia and its users safe by:
You need a README.fuchsia file with information about the project from which you're reusing code. Check out README.fuchsia
for the list of required fields to include.
All third-party additions and substantive changes like re-licensing need the following sign-offs:
README.fuchsia
), include someone in security-dev@fuchsia.dev
to review the change.Most third-party dependencies can follow the layout described above. However, a small fraction of dependencies that are subject to uncommon circumstances are managed differently.
Having exotic dependencies can increase complexity and maintenance costs, which are incurred by direct dependencies of the third-party code. Additionally, they add complexity to common global maintenance tasks such as:
Please exercise careful deliberation when stepping off the beaten path.
Bringing all the existing //third_party code to the layout documented above is WIP, and contributions are welcome.
To migrate legacy third-party repositories to this layout, follow these steps:
Move Fuchsia-specific BUILD.gn
files to //build/secondary
.
BUILD.gn
files from //third_party/<name>
to //build/secondary/third_party/<name>
. If there is more than one BUILD.gn
file, maintain the same subtree under //build/secondary
.BUILD.gn
files, update references to paths to third-party files in the form of //third_party/<name>/
to the form of //third_party/<name>/src/
.OWNERS
from //third_party/<name>
to //build/secondary/<name>
, or create it if it does not exist. Review the OWNERS
file to ensure that it follows the best practices.README.fuchsia
from //third_party/<name>
to //build/secondary/<name>
. Review the contents of this file and ensure that the metadata is correct. In uncommon cases there are modifications made to third-party code in third-party repositories, and such changes are listed in README.fuchsia
. Local modifications will often require you to make special accommodations that are not covered in this guide.//third_party/<name>
for any other first party .gni
files and move those to //build/secondary/<name>
as well.//build/secondary/third_party/<name>/BUILD.gn
(and other files containing source paths such as .gni
files) to use the new source location //third_party/<name>/src
. This requires updating all sources, including directory paths and more.Example: https://fxrev.dev/622785
Note: CQ won't catch errors in this change (for example, typos in paths) because the secondary build files are not yet active. You can validate that your BUILD.gn
files are correct by staging the next commit (update the integration manifest), running jiri update -local-manifest
, then building (such as with fx build
).
Update the integration manifest.
Note: This step can only be performed in Google's internal repositories at the moment.
Replace path
(not name
) of the existing third-party project at //third_party/<name>
with //third_party/<name>/src
, while keeping the revision unchanged. With this change merged, the Fuchsia build will switch to using the BUILD.gn
files from the previous step.
Example: http://tqr/457911
Move Fuchsia-specific files added in step 1 to //third_party/<name>
.
Now that third-party code is nested under //third_party/<name>/src
and //third_party/<name>
is part of fuchsia.git
, you can undo the transitional step 1.
Wait for the integration manifest change to merge and roll, then run jiri update
. Or stage the integration manifest change from the previous step in your local checkout, then run jiri update -local-manifest
.
Move BUILD.gn
and other Fuchsia-specific files from //build/secondary/<name>
to //third_party/<name>
.
Update //.gitignore
so that //third_party/<name>
is tracked but //third_party/<name>/src
is not tracked.
Example: https://fxrev.dev/622789
Turn //third_party/<name>/src
into a mirror.
Note: This step can only be performed in Google's internal repositories at the moment.
Change //third_party/<name>/src
to track upstream such that it only has upstream changes in its git log
. You can do this by updating the integration manifest to reference an upstream commit hash.
Example: http://tqr/427570