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 ${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), 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 $OUTPUT_DIR/sdk/exported/<name>.
The idk template generates the final IDK in $BUILD_DIR/sdk/exported/<name> by building its constituent sdk_atoms for all supported target CPU architectures and API levels, and merging them all together into a single IDK. The idk_archive template can then be used to compress it into a .tar.gz file.
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 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_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 fx or 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 $OUTPUT_DIR/sdk/archive/<name>.tar.gz.
By default, target foo only depends on foo_final_manifest and 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 only be done using the idk_archive() GN template instead.
Historically, there have been a number of “custom IDKs” with different requirements. This led to more complexity and confusion than it was worth, given that only 2 or 3 were actually in use/not deprecated.
If you think you need a custom IDK, please send an email to fuchsia-idk@google.com.
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.