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
repository itself follows the structure of an area, but also has additional
structure unique to the top level.
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
src that hold further top-level areas, e.g. in
Being open source code
third_party is available to all areas.
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
vendor/* directories contain closed-source code, organized by the vendor
of that code. Nothing outside of
//vendor can depend on
Dependencies between different vendors is supported,
vendor/A can have a
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
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:
- Bringup. This source tree configuration contains enough code to build the bringup product.
- Open Source. This source tree configuration contains all the open source code in the Fuchsia Source Tree.
- All Source. This source tree configuration contains all the open and closed source code in the Fuchsia Source Tree.
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:
- Each area or subarea must have a list of owners
- Build file defining the canonical targets for the area. The area owners may add additional targets to this in addition to the canonical targets.
- This directory should contain docs for people working in this area
- Docs for end-developers (or people working in other areas of Fuchsia) should be in the top-level docs or sdk repository
- This directory contains bundles of package targets in this area. Each area
should contain at least a
testsbundle with unit tests for the area, but may include other bundles.
- This directory contains bundles of package targets in this area. Each area should contain at least a
- In some cases, an area might have internal FIDL interfaces that are not exposed to other areas or to end-developers. Rather than put those interfaces in the SDK, an area can put those interfaces in this directory.
- This directory contains integration tests that span multiple source code directories within the area
- If disparate areas can have tests in subdirectories, it is suggested to add OWNERS files for different test directories to clarify ownership.
- Unit tests that cover a single binary or library are better placed alongside the code they test
- This directory contains utilities and libraries useful for writing tests in this area and subareas.
- Targets in this directory can only be depended on by testonly targets.
- Most third_party dependencies should be in separate repositories
- Include third_party dependencies in an area only if all of the following:
- The code is required to be in a third_party directory by policy
- You intend to fork upstream (i.e., make major changes and not plan to integrate future changes from upstream)
- You make a new name for the code that (a) does not match upstream and (b) does not appear in any other third_party directory anywhere in the Fuchsia Source Tree
- The code is open source
- This directory contains command-line tools provided by the area. These are usually things that can (or must) be built for the development host rather than for Fuchsia. They may or may not be used directly in the area's own build, but can also be used by developers. They may or may not be published in an SDK. Special-purpose tools that are used in the build but really are not intended for developers to use directly should be kept near their uses rather than here.
- This should contain a a subdirectory named for each tool (or collection
of related tools with a natural collective name), rather than putting all
of the area's tools together into the top
- Subareas should follow the generic area template
- Do not create deeply nested area structures (e.g., three should be enough)
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.
fuchsia.git repository, there exist directories with
OWNERS that are
not considered areas, e.g. the top level
products directory, or subdirectories
One exception is the
//src/tests directory where tests from different areas
that cover multiple aspects of the system (not just a particular area) are
expected to live. Because of this, every area should add OWNERS files for any
tests that live in this directory.
In addition to depending on itself, an area can depend only on the top-level
third_party directories, as well as the
of its ancestors:
Targets in an area that are marked testonly in the build system may
additionally depend on the
testing directory in that area and ancestors:
(../)+testing/(testonly=true targets only)
Each area and subarea must define the following canonical targets in their top-level BUILD.gn file:
- All of the tests within this area
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
(except for the prebuilt directory, which is populated from CIPD).
[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:
- Added to an existing directory in fuchsia.git
- Added to a new top-level area or subarea of an existing area
- Added to an existing repository
- Added to a new repository (requires approval by top-level OWNERS)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.