sdk/docs/root.md

# Fuchsia Integrator Development Kit (IDK)

This archive contains the Fuchsia Integrator Development Kit (IDK),
which is a small set of Fuchsia-specific libraries and tools required to start
building and running programs for Fuchsia.

The Fuchsia IDK 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 IDK contains
metadata that may be used to produce support for a large variety of build
systems, thereby producing various SDK distributions.
Having the IDK cleanly separated from these various distributions allows
for very flexible release schemes and iteration cycles.

Most developers who wish to build something for Fuchsia should not need to
deal directly with the IDK.
They will instead consume a transformed version of it, for instance within the
development environment and ecosystem supporting a given language runtime.
Maintainers of development environments who wish to add support for Fuchsia are
the main audience for the IDK.
See [the section below](#ingestion) for a description of how to process this
SDK.

As such, the Fuchsia IDK is the representation of the Fuchsia platform developers'
contract with other developers who work with Fuchsia.
While that contract is absolutely necessary, as this IDK contains the very bits
that are unique to Fuchsia, it is not sufficient and will be complemented by
other "contracts".
The Fuchsia IDK is mirroring the Fuchsia platform in that respect: highly
composable and extensible, with a clear separation of concerns.

## Structure

From this point on, the root of the IDK archive will be referred to as `//`.

### Metadata

Metadata is present throughout this IDK in the form of JSON files.
Every element in this IDK has its own metadata file: for example, a FIDL library
`//fidl/fuchsia.foobar` has its metadata encoded in
`//fidl/fuchsia.foobar/meta.json`.

Every metadata file follows a JSON schema available under `//meta/schemas`: for
example, a FIDL library's metadata file conforms to
`//meta/schemas/fidl_library.json`.
Schemas act as the documentation for the metadata and may be used to facilitate
the IDK ingestion process.

### Documentation

General documentation is available under [`//docs`](docs/README.md).
Some individual IDK elements will also provide documentation directly under the
path where they are hosted in the SDK.

### Target prebuilts

Target prebuilts are hosted under `//arch/<architecture>`.
This includes a full-fledged sysroot for each available architecture.

### Source libraries

The IDK contains sources for a large number of FIDL libraries (under
`//fidl`) as well as a few C/C++ libraries (under `//pkg`).

### Host tools

Multiple host-side tools can be found under `//tools`.
This includes tools for building programs, deploying to a device, debugging,
etc...
Some information about how to use these tools can be found under `//docs`.

### Images

`//device` contains metadata describing device configurations matching a given
version of the IDK.
This metadata contains pointers to images that can be flashed onto said devices.


## Ingestion

This section describes the process of consuming the IDK and turning
it into a SDK that is specific to a development environment so it can be used
directly by developers.

The main entry point for the ingestion process is a file at
`//meta/manifest.json`.
As with every metadata file in the SDK, the manifest follows a JSON schema which
is included under `//meta/schemas/manifest.json`.

This file contains a list of all the elements included in this IDK, represented
by the path to their respective metadata file.
Each element file is guaranteed to contain a top-level `type` attribute, which
may be used to apply different treatments to different element types, e.g.
generating a build file for a FIDL library vs. just moving a host tool to a
convenient location in the final development environment.

The existence of the various metadata files as well as the exhaustiveness of
their contents should make it so that the ingestion process may be fully
automated.
JSON schemas may even be used to generate code representing the metadata
containers and let the ingestion program handle idiomatic data structures
instead of raw JSON representations.

The metadata schemas will evolve over time.
In order to allow consumers of that metadata to adjust to schema changes, the
main metadata file contains a property named `schema_version` which is an opaque
version identifier for these schemas.
This version identifier will be modified every time the metadata schemas evolve
in a way that requires the attention of a developer.
IDK consumers may record the version identifier of the metadata they used to last
ingest an IDK and compare that version identifier to next SDK's version
identifier in order to detect when developer action may be required.