This folder contains information about developing the Fuchsia SDK.
Fuchsia is taking a modular approach to building an SDK, just as it took one to building a new operating system.
At the center of this strategy is the Fuchsia Core SDK, distilled out of the present Git repository. This SDK contains a small set of libraries and tools required to start building and running programs that target Fuchsia. The contents of that SDK represent the most basic contract that the Fuchsia platform developers offer to prospective developers.
The Fuchsia Core SDK is not suitable for immediate consumption. It does not contain any reference to toolchains or build systems, and in fact does not require any specific instance of these. While this might be viewed as a drawback, this is actually a feature, an integral part of a layered approach to building a fully-functional SDK. Even though it is not tied to a particular build system, the Core SDK contains metadata that may be used to produce support for a large variety of build systems, thereby producing various SDK distributions. Having the Core SDK cleanly separated from these various distributions allows for very flexible release schemes and iteration cycles.
The present documentation focuses on the details of the creation process of the Core SDK. The documentation included in the Core SDK, hosted under //sdk/docs, contains information regarding how to work with the Core SDK. Lastly, some examples of SDK distributions can be found under //scripts/sdk; most notably it contains a frontend generating a workspace enabling Fuchsia development using Bazel - this distribution is currently used to test versions of the Core SDK before they are published.
By default, a piece of code in the Fuchsia tree cannot be added to any SDK: participation is a strictly opt-in decision. Additionally, this decision is encoded locally within the code's build file. This was done for multiple reasons:
In order to be made available in SDKs, a piece of code must follow a set of standards and guidelines.
The SDK creation pipeline consists of two pieces:
The backend really is just a specialized use of the build system. In other words, running the SDK backend amounts to passing the right set of arguments to the Fuchsia build system, which in turn produces an archive with a set layout. The inner workings of the backend are described here.
The backend does not just produce an SDK: it is also used as a control mechanism for API evolution. The API surface exposed by an SDK is captured in a set of reference files representing its elements: modifications to this surface need to be explicitly acknowledged by developers by updating the relevant reference files, whose latest version is also generated by the backend. The purpose of this mechanism is to detect and prevent accidental changes to the SDK as early as possible in the release cycle, as well as give us tools to observe and review the evolution of the API surface.
The term frontend is used to describe any process that ingests a Fuchsia SDK archive and applies transformations to it.
In the Fuchsia tree, frontends are used to generate SDK distributions, e.g. a Bazel-ready workspace.
Frontends may also be used to adapt a Fuchsia SDK archive for consumption in a particular development environment by for example generating build files for a given build system. The presence of extensive metadata in the archive itself allows for this kind of processing.
The Core SDK is represented by the //sdk:core target. That SDK is complemented by multiple SDK add-ons:
//sdk:e2e_testing: an end-to-end testing framework for Fuchsia;//sdk:modular_testing: an hermetic testing framework for the app framework;//sdk:images: a set of device images suitable for SDK development;//topaz/public/sdk:fuchsia_dart: a Dart SDK to build mods and agents. Internally these targets are all instances of the sdk GN template.The various targets representing SDKs are always included in the build graph. In order to build the contents of an SDK, build one of the targets above.
Note that this will generate and verify SDK contents, but won't actually build an archive with these contents. To build the archive, add the GN argument build_sdk_archives=true to your build configuration and run the build command again. The resulting archive will be located under <outdir>/sdk/archive/<name>.tar.gz.
The first step is to make that content available to SDKs. This is done by using a set of templates listed in the backend documentation. The next step is to add that content to an existing SDK definition. For a target //path/to/my:super_target, this is accomplished by making the implicit //path/to/my:super_target_sdk target a dependency of the sdk target.
Note that some content types require a .api source file describing the state of the SDK element's API. These files are produced by the build system. In order to seed the first version of such a file, let the build system tell you where it expects to find the file, then create this file and leave it empty, and finally run the build again: it will again tell you where to get the initial version from.
There exist some build steps to verify that the contents of an SDK don't get modified by accident. An unacknowledged modification results in a build failure until the relevant reference files are updated in the source tree. While locally iterating on some public API, having to repeatedly update reference files can be tedious. In order to turn the build errors into warnings, configure then build with this extra GN argument: warn_no_sdk_changes=true.
This is done by running a frontend. See the frontend documentation for more details.