This directory contains templates and scripts used to build and consume IDKs in the Fuchsia GN build.
Note: Fuchsia SDKs, like the GN SDK, or the Bazel SDK, are generated by processing the content of an IDK archive. This process is out of scope for this document, which only describes how an IDK is assembled.
The build output of “an IDK build” is a tarball containing files collected from the source tree and the output directory, augmented with metadata files.
Metadata includes the nature of an element (e.g. programming language(s), runtime type), its relationship with other elements (e.g. dependencies, supporting tools), the context in which the element was constructed (e.g. target architecture, high-level compilation options), etc...
As described by the IDK standard layout specification, a single
$IDK/meta/manifest.json file lists all SDK elements, with references to individual
meta.json files for each one of them.
Schemas for the various types of SDK elements are available under //build/sdk/meta/, and provide an external contract for SDK-generating tools outside the Fuchsia build.
The simplest way to build the Fuchsia “Core” IDK, is to run the following command:
fx build final_fuchsia_idk
This generates the IDK, validates its content by running the Bazel SDK test suite locally, then creates a compressed archive that goes under
During local development, creation of the compressed archive can be skipped by using one of the following targets instead:
# Creates the IDK's export directory, under $BUILD_DIR/sdk/exported/fuchsia_idk # but does not validate its result. fx build final_fuchsia_idk.exported # Same, but also validates its result by running the Bazel SDK test suite. fx build final_fuchsia_idk.validation
Due to technical limitations at the GN / Bazel boundary, the Fuchsia Bazel SDK is currently not built from the Fuchsia “Core” IDK. For more details, see //build/bazel_sdk/README.md and //build/bazel/fuchsia_bazel_sdk.gni.
Individual elements are declared using the
sdk_atom template. It should be rare for a developer to directly use that template though: in most instances its use should be wrapped by another higher-level template, such as language-based templates (e.g.
sdk_source_set() for C++).
Each atom has an
id, a unique identifier for the element within the SDK, such as
sdk://pkg/foo, which determines its output location in the final IDK archive. It also has a
category, to restrict its availability outside of the Fuchsia team. In particular only atoms in the
partner category should be part of an IDK distributed to third-party teams. Apart from that, categories are internal to the Fuchsia build system (i.e. they do not appear in SDK metadata files).
Groups of atoms are declared with the
sdk_molecule template. A molecule can also depend on other molecules. Molecules are a great way to provide hierarchy to SDK atoms, but they do not have an id, as they are only used as a grouping mechanism within the Fuchsia build.
sdk_collection template is used to declare a group of atoms (or molecules), while verifying that its content matches a given API/ABI. It will also create an “export directory” that follows the standard IDK layout for all its elements, under
generate_final_idk][generate_final_idk] template is used to generate and validate the final IDK archive, by merging the content of one or more collections. It also ensures that all prebuilt binaries are provided for all supported target CPU architectures (achieved by performing specific sub-builds of the same collections), that are all stored in the same compressed archive output.
It is possible to see an SDK collection as a “partial IDK” since it only contains a subset of atoms that go into the final IDK, but only provides prebuilts for the current build configuration's
target_cpu, and for the current SDK API level / build variant.
There are a few GN templates developers should use to enable the inclusion of their code in an SDK:
Some language-specific targets are also SDK-ready:
In order to add documentation to an SDK, use the
Other static data (e.g. configuration or LICENSE files) being added to the SDK should use the
//foo/bar declared with one of these templates will yield an additional target
//foo/bar:bar_sdk which is an atom ready to be included as an
Each SDK atom target (e.g.
foo_sdk) generates two manifest files:
meta.json file that follows one of the standard schemas available under
//sdk/meta/, which will be included in the final IDK output.
An internal JSON manifest file, under
gen/.../foo.sdk which describes the atom and all its transitive dependencies. Unlike the
meta.json file, this file should not be used outside of a Fuchsia checkout, and its content / schema may change at any time.
sdk_collection("foo") target also generates sibling targets that other parts of the build system (and sometimes internal scripts) rely on:
foo_final_manifest: Creates a internal JSON manifest at
$OUTPUT_DIR/sdk/manifest/<name>. This is seldom used by other parts of the build systems, or tools like
ffx when it runs from a Fuchsia checkout.
foo_export: Creates the collection's export directory under
$OUTPUT_DIR/sdk/exported/<name>. This contains files that follow the standard IDK layout, including a top-level
meta/manifest.json file describing all elements available from the collection.
These export directories are seldom used by other parts of the build system, but should not be considered as official distribution artifacts.
foo_archive: Creates a compressed archive from the content of the collection under
By default, target
foo only depends on
foo_export. They can depend optionally on
foo_archive though this is not the default.
Note that sdk collection archives only contain binaries for the current
target_cpu value, and current API level. In theory they should not exist, nor distributed outside of the Fuchsia tree, though they currently are for historical reasons.
They are nonetheless deprecated. Generating archives should ideally only be done using the
generate_final_idk() GN template instead.
Once elements have been set up for inclusion in an IDK, declaring such an IDK only takes a few steps:
Identify the collections needed in the IDK. Create a new collection, or add atoms to an existing one if needed.
final_fuchsia_idk("my_idk") target under
If this new IDK only contains public or partner atoms, add its collections to the
_fuchsia_sdk_deps list defined in
//sdk/BUILD.gn to ensure its archives will be built and uploaded to cloud storage by the Fuchsia SDK CI builders.
Alternatively, or if this is not possible (e.g. if this new IDK is defined in //vendor/.., which cannot be referenced from //sdk/BUILD.gn), add it to the
sdk_archive_labels list in your
From there, the archive can be built locally with
fx build my_idk and will be available as
Any IDK or
sdk_collection target creates an “export” directory following the standard IDK layout, under
$OUTPUT_DIR/sdk/exported/<name>/. This can be used to build certain third-party code which otherwise relies on an official IDK.
For each element in the SDK, a reference file representing its API is checked into the source tree. If the API is modified but the reference file is not updated, the build will fail. Set this argument to
true in order to turn the errors into mere warnings.