tree: cf67858822e38dd08fa2a62ccbbe8afa4ca77cbd [path history] [tgz]
  1. meta/
  2. plasa/
  3. tests/
  6. config.gni
  12. generate_final_idk.gni
  14. idk.gni
  15. idk_archive.gni
  16. manifest_schema.json
  17. METADATA.textproto
  18. OWNERS
  19. physical_device.gni
  20. product_bundle.gni
  21. product_bundle_transfer_manifest.gni
  22. product_metadata.gni
  24. sdk_alias.gni
  25. sdk_atom.gni
  26. sdk_atom_alias.gni
  27. sdk_collection.gni
  30. sdk_component_manifests.gni
  31. sdk_data.gni
  32. sdk_documentation.gni
  33. sdk_final_manifest_golden.gni
  34. sdk_host_tool.gni
  35. sdk_molecule.gni
  36. sdk_noop_atom.gni
  37. sdk_prebuilt_executable.gni
  40. virtual_device.gni

SDK build tools

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.

Building the Fuchsia Core IDK

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

Building the Fuchsia Bazel SDK

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/ 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 [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.

Declaring SDK elements

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 ideally only be done using the generate_final_idk() GN template instead.

Creating a custom IDK

Once elements have been set up for inclusion in an IDK, declaring such an IDK only takes a few steps:

  1. Identify the collections needed in the IDK. Create a new collection, or add atoms to an existing one if needed.

  2. Create a final_fuchsia_idk("my_idk") target under //sdk/

  3. If this new IDK only contains public or partner atoms, add its collections to the _fuchsia_sdk_deps list defined in //sdk/ to ensure its archives will be built and uploaded to cloud storage by the Fuchsia SDK CI builders.

  4. Alternatively, or if this is not possible (e.g. if this new IDK is defined in //vendor/.., which cannot be referenced from //sdk/, add it to the sdk_archive_labels list in your file.

From there, the archive can be built locally with fx build my_idk and will be available as $OUTPUT_DIR/sdk/archive/my_idk.tar.gz.

Using a custom SDK in the build

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.

GN build arguments


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.