This directory contains templates and scripts used to build and consume SDKs in the Fuchsia GN build.
This document describes a new SDK design that is intended to replace the existing one described in README.md. It is a work in progress and may change frequently until fully implemented.
The Fuchsia SDK is a collection of modules, each serving a specific purpose and possibly depending on other modules. For example, the “host_tools_linux_x64” module contains binaries that allow a Linux x86-64 host to interact with a Fuchsia device.
Each SDK module contains several SDK elements. An element is the unit of compilation and distribution, i.e. it is the smallest buildable unit that can be processed by SDK-compatible tooling. Each element usually corresponds to an individual non-SDK build target, such as a library or binary. Continuing the example above, each binary in the host tool module comes from a single SDK element.
The output of an SDK build is metadata files that describe the contents of the modules and elements and can be used to package them for distribution.
Element metadata includes the contents of the element, its stability category (see the “Stability categories” section below), its dependencies on other elements, the SDK version it was built for, and element type-specific information such as target platform.
Module metadata is similar to element metadata, except the “contents” of a module are elements and modules rather than files.
Schemas for the various types of SDK metadata are available under meta/ and //sdk/schema/.
The SDK has a canonical layout described by the elements' metadata that SDK distributions should follow. However, note that neither SDK elements nor modules produce self-contained, distributable artifacts such as tarballs. In fact, the contents of an element may be scattered throughout the GN output directory.
Instead, the metadata output from the SDK build includes all the information needed for tools and infrastructure to package modules and elements. This greatly reduces the amount of work done during the SDK build process. It also allows modules to overlap with one another without creating duplicate artifacts.
SDK elements are declared using specializations of the sdk_element template, such as host_tool_sdk_element, which then construct the required sdk_element. Developers should rarely instantiate the sdk_element template directly.
SDK modules are declared using the sdk_module template, similar to the GN group target type, and may include SDK elements and other SDK modules.
SDK element templates declares a category parameter which allows developers to control who may be able to use their element. Possible values, from most restrictive to least restrictive:
excluded: The element may not be included in the SDK.experimental: The element is available with no quality or stability guarantees.internal: The element is available within the Fuchsia tree only.cts: The element may be used in the Fuchsia Compatibility Test Suite.partner: The element may be used by select partners.public: The element may be used by anyone.Many SDK elements support build-time API change detection by allowing developers to declare which files make up their element's API and then comparing the hashes of those files to canonical hashes listed in a file. The file containing the canonical hashes is known as the API file.
API files are JSON files that contain a map of filenames to MD5 hashes. They are checked into the Fuchsia tree, usually next to the BUILD.gn file defining their corresponding SDK element. When the element is built, the newly-built files are hashed and compared to the API file. Differences result in a build error.
This system can be used, for example, to prevent accidental changes to C++ header files. All elements that are part of a published SDK module should have an API file.
Details on how to use API files are included in the SDK element build templates.