Source code layout

Status

We are currently migrating to this source code layout. Some aspects of this document reflect the current reality, but some aspects are still aspirational.

Overview

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/*. 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 system stabilizes.

The vendor/* directories contain closed-source code, organized by the vendor of that code. Nothing outside of //vendor can depend on //vendor. Dependencies between different vendors is supported, vendor/A can have a dependency on vendor/B.

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:

• 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.

See the guidelines on writing the metadata for third-party code in README.fuchsia files.

Areas

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.

Directory Structure

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
  • Each area or subarea must have a list of owners
• BUILD.gn
  • Build file defining the canonical targets for the area. The area owners may add additional targets to this in addition to the canonical targets.
• docs/
  • 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
• bundles/
  • This directory contains bundles of package targets in this area. Each area should contain at least a tests bundle with unit tests for the area, but may include other bundles.
• bin/ (optional)
• lib/ (optional)
• drivers/ (optional)
• examples/ (optional)
• fidl/ (optional)
  • 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.
• tests/ (optional)
  • 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
• testing/ (optional)
  • 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.
• third_party/ (optional)
  • 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
• tools/ (optional)
  • 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 tools/BUILD.gn file.
• [subareas] (optional)
  • 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.

OWNERS

Each area and subarea must contains an OWNERS file. Directories may contain OWNERS without being considered areas, e.g. the top level products directory, or subdirectories of the /src/lib directory. A directory lacking an OWNERS file is considered to have the same owners as its parent directory of the same area.

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.

Dependency Structure

In addition to depending on itself, an area can depend only on the top-level build, sdk, and third_party directories, as well as the lib directories of its ancestors:

• //build
• //sdk
• //third_party
• (../)+lib/

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)

Canonical targets

Each area and subarea must define the following canonical targets in their top-level BUILD.gn file:

• <dir-name>

  • All directories should have a target with the same name as the directory. The directory target is essentially an “all” target, intended and used to produce “build-everything” builds.
    • All buildable artifacts defined in the directory and subdirectories.
    • All tests in the current directory and subdirectories.
  • The directory target should only produce maximal builds - it should not include configuration targets or changes that would modify the “product behavior” of a particular product - for example, including the directory target should not cause new software to be automatically started at boot time, or override default service topologies or service maps.
  • When a new sub-directory is added to an area, it should define this directory-name target, as well as including the directory name target in the parent directory target.

• tests

  • All of the tests within this area
  • When a new sub-directory is added with a new tests target, the tests target should be added to the parent directories tests target.

Naming conventions

Typically, when naming files and directories, the best practice is to use names that are short and clear. In those cases where a name is comprised of multiple words, those words should be separated by underscores .e.g long_file_name. However, package names should use dashes to separate words. For more information, see package name.

Example

The following is an example for a directory called fortune.

import("//build/config/fuchsia/rules.gni")
import("//src/sys/build/components.gni")

group("fortune") {
  testonly = true
  deps = [
    ":pkg",
    ":tests",
  ]
}

group("tests") {
  testonly = true
  deps = [
    ":fortune-tests"
  ]
}

executable("bin") {
  output_name = "fortune"

  sources = [
    "fortune.cc"
  ]
}

executable("test") {
  testonly = true
  output_name = "fortune-test"

  sources = [
    "test.cc"
  ]
}

fuchsia_component("component") {
  manifest = "meta/fortune.cmx"
  deps = [ ":bin" ]
}

fuchsia_package("pkg") {
  package_name = "fortune"
  deps = [ ":component" ]
}

fuchsia_unittest_package("fortune-tests") {
  deps = [ ":test" ]
}

Repository layout

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/
  • media/
  • modular/
  • storage/
  • testing/
  • updater/
  • virtualization/
  • zircon/kernel/
  • zircon/drivers/
  • zircon/userspace/
• vendor/
  • [closed-source code from various vendors]

Evolution

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)