docs/concepts/source_code/layout.md

# 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](https://fuchsia.googlesource.com/fuchsia). 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](/products/core.gni)
product), whereas others are more elaborate (e.g., the
[workstation](/products/workstation.gni) 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](/products/bringup.gni) 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](third-party-metadata.md) 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](owners.md) 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](owners.md)
 * `BUILD.gn`
    * Build file defining the [canonical targets](#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](/docs/concepts/packages/package_url.md#package_name).

#### Example

The following is an example for a directory called `fortune`.

```gn
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)