We are currently migrating to this source code layout. Some aspects of this document reflect the current reality, but some aspects are still aspirational.
Most first-party, open-source code is in the “fuchsia.git” repository. Most code in this repository is organized into a recursive tree of areas.
Areas have a regular internal and dependency structure. The fuchsia.git
repository itself follows the structure of an area, but also has additional structure unique to the top level.
Specifically, the src
top level directory of fuchsia.git
can be considered the root area. It follows the structure required of an area, and is the place where sub areas are located. However, some directories required of an area also exist next to src
rather than inside it, e.g. third_party
. These can be thought of global ones for all areas to depend on. There are also other places outside src
that hold further top-level areas, e.g. in vendor/*
.
Source repositories, whether open- or closed-source, also follow the conventions for areas and are mapped into subdirectories of src
in fuchsia.git. Currently, we have small number of such “petal” repositories, but we will “promote” areas currently in the fuchsia.git
repository into separate repositories as the system stabilizes.
The products
directory contains a list of products that you can build. Some products are quite small and build quickly (e.g., the core product), whereas others are more elaborate (e.g., the workstation product).
Most third-party dependencies are stored in separate repositories. These repositories are included in a local checkout only when needed to support one of the following source tree configurations:
Most code is organized into a recursive tree of areas. Each area has a regular internal and dependency structure, which helps people understand code structure across the whole project.
Each area is required to have an OWNERS file as well as documentation and tests. Areas can also include binaries, libraries, drivers, and other source code. In addition, areas can have subareas, which repeat the pattern:
OWNERS
BUILD.gn
docs/
bundles/
tests
bundle with unit tests for the area, but may include other bundles.bin/
(optional)lib/
(optional)drivers/
(optional)examples/
(optional)fidl/
(optional)tests/
(optional)third_party/
(optional)[subareas]
(optional)Areas may use additional directories for internal organization in addition to the enumerated directories.
A directory inside an area that contains an OWNERS
file is considered a subarea and must adhere to the contract for areas. A directory lacking an OWNERS
file is considered part of the same area.
At the top of the fuchsia.git
repository, there exist directories with OWNERS
that are not considered areas, e.g. the products
directory.
In addition to depending on itself, an area can depend only on the top-level build
, buildtools
, sdk
, and third_party
directories, as well as the lib
directories of its ancestors:
//build
//buildtools
//sdk
//third_party
(../)+lib/
Each area and subarea must define the following canonical targets in their top-level BUILD.gn file:
tests
This section depicts the directory layout for the Fuchsia Source Tree. Non-bold entries are directories or files in the fuchsia.git repository. Bold entries are separate repositories that are mapped into the directory structure using jiri
(except for the prebuilt directory, which is populated from CIPD).
.clang-format
.dir-locals.el
.gitattributes
.gitignore
AUTHORS
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
OWNERS
PATENTS
README.md
rustfmt.toml
sdk/banjo/ddk.protocol.gpio/
sdk/banjo/...
sdk/fidl/fuchsia.media/
sdk/fidl/fuchsia.mediacodec/
sdk/fidl/...
sdk/lib/ddk/
sdk/lib/fit/
sdk/lib/fidl/
sdk/lib/zircon/
sdk/lib/...
.gn
BUILD.gn
build/
bundles/
configs/
infra/
configs/
generated/
integration/
products/
scripts/
docs/
examples/
third_party/
boringssl/
icu/
rust_crates/
...
prebuilt/
chromium/
dart/
flutter/
llvm/
tools/
banjo/
fidl/bin/backend/{c,cpp,dart,go,llcpp,rust}
fidl/bin/frontend/
fidl/docs/
fidl/examples/
fidl/tests/
src/
lib/
cobalt/
component/
connectivity/
developer/
experiences/
graphics/
identity/
ledger/
media/
modular/
storage/
updater/
virtualization/
zircon/docs/
zircon/kernel/
zircon/drivers/
zircon/userspace/
vendor/
[closed-source code from various vendors]
As the system stabilizes, we can promote areas out of fuchsia.git into separate repositories. Generally, we should promote an area to a separate repository when the interface between the area and the rest of the system is sufficiently stable (requires approval by top-level OWNERS).
New code can be: