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 IDK (aka the “Partner 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 ${BUILD_DIR}/sdk/archive/fuchsia_idk.tgz.
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 public or 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.
The sdk_collection template is used to declare a group of atoms (or molecules). It will also create an “export directory” that follows the standard IDK layout for all its elements, under $OUTPUT_DIR/sdk/exported/<name>.
There is an sdk_collection for each combination of supported target CPU architecture and API level. 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.
//build/sdk/generate_idk generates the final IDK in $BUILD_DIR/sdk/exported/<name> by merging the collections for all supported target CPU architectures and API levels into a single IDK. The idk_archive template can then be used to compress it into a .tar.gz file.
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 sdk_documentation template.
Component manifest shards being added to the SDK should use the sdk_component_manifest template.
Other static data (e.g. configuration or LICENSE files) being added to the SDK should use the sdk_data template.
A target //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 sdk_molecule() or sdk_collection() dependency.
Each SDK atom target (e.g. foo_sdk) generates two manifest files:
A 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.
Each sdk_collection("foo") target also generates sibling targets that other parts of the build system (and sometimes internal scripts) rely on:
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 $OUTPUT_DIR/sdk/archive/<name>.tar.gz.
warn_on_sdk_changesFor 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.