Fuchsia source tree

In this section, you will learn about the organization of the Fuchsia source code and the tools used to manage the open source project.

Source code management

Fuchsia uses the jiri tool to manage git repositories in the Fuchsia project. It synchronizes a local checkout of the source code with the Global Integration manifest and provides the necessary facilities to contribute changes back to Fuchsia. Global Integration is the central ledger that defines the current state of the various projects in the Fuchsia tree.

You initialize a local jiri checkout using the import command with an XML manifest that declares all the repositories and how they are organized. The import for the default Global Integration manifest is as follows:

jiri import -name=integration flower https://fuchsia.googlesource.com/integration

This command adds the manifest to a local .jiri_manifest file at the root of your local checkout.

<manifest>
  <imports>
    <import manifest="flower" name="integration"
            remote="https://fuchsia.googlesource.com/integration" />
  </imports>
</manifest>

Once a local checkout is initialized on your development machine, jiri can pull the latest changes from Global Integration at any time with one command:

jiri update

Source code layout

Fuchsia is a large open source project. As with any large software project, it can be easy to get lost without a roadmap to guide you. This section contains an overview of a local Fuchsia checkout, with a summary of the various elements you can expect to find along the way:

path	description
`boards`	Contains all the default board configurations supported and maintained by the Fuchsia team.
`build`	Shared configurations and default templates for the Fuchsia build system.
`bundles`	Top-level groupings of build target labels typically included together in a build configuration. See Bundles for more details.
`docs`	The Fuchsia documentation, including the source material for the Fuchsia.dev developer site.
`examples`	Sample software components showcasing various aspects of the Fuchsia platform.
`products`	Contains all the default product configurations supported and maintained by the Fuchsia team.
`scripts`	Various developer tools to simplify working with the Fuchsia source tree, including the subcommands used in fx workflows.
`sdk`	Contains the source of the Fuchsia platform APIs including the FIDL protocol definitions and the build targets use to create the Fuchsia SDK distribution archives.
`src`	Source code of Fuchsia, including components, services, and tools running on the target device. This is the stem of the flower.
`tools`	Fuchsia developer tools running on the host machine.
`vendor`	Reserved location for vendor-specific binaries and customizations for product builds. The build system supports discovery of configuration files under `vendor/products` and `vendor/boards` to build Fuchsia for vendor-specific device targets.
`zircon`	Source code for Fuchsia's Zircon core, including the kernel.

The source code of the Fuchsia platform breaks down further into the various components and services running on the device. Below is not a complete list, but may provide some interesting places to begin exploring:

path	description
`src/bringup`	Core system binaries used to bring up the system's user space environment.
`src/camera`	Support services for camera device drivers.
`src/cobalt`	Fuchsia service used to log, collect and analyze metrics.
`src/connectivity`	Networking protocol support and device drivers.
`src/developer`	Developer tools running on the target, including ffx.
`src/devices`	Device driver support libraries for common hardware subsystems.
`src/diagnostics`	Diagnostic support services such as logging, crash reporting, snapshots, and statistics.
`src/factory`	Components implementing access to factory config data storage.
`src/fonts`	Provider for built-in system fonts.
`src/graphics`	Support services for display device drivers.
`src/identity`	User account handling and identity token management.
`src/media`	Media codecs and playback services.
`src/power`	Power management services.
`src/starnix`	POSIX compatibility libraries.
`src/recovery`	Recovery system and factory reset services.
`src/security`	Security policies and analysis tools.
`src/session`	Infrastructure and tools for managing session components.
`src/storage`	Support for filesystems and volume management.
`src/sys`	Component framework and services for package management.
`src/tests`	Platform end to end (E2E) integration tests.
`src/ui`	Services to support graphical user interface (GUI), including Scenic.
`src/virtualization`	Hypervisor support for VM guests.
`src/zircon`	Libraries for interacting with the Zircon kernel.

Exercise: Navigate the source tree

In this exercise, you'll explore your local checkout of the Fuchsia source tree using the command line tools available in the environment. Becoming familiar with these tools will make you more productive as you begin to contribute to the codebase.

Search the tree

If you're not sure where to start, you can use the fd utility to perform fuzzy searches for directories, then navigate to the location of a search result.

Run the following command to run an fd search for session_manager:

fd session_manager

This tool is configured in your environment using fx-env.sh. If you are unable to access the fd command, ensure you have set up your environment.

The utility prints a few possible options for you to choose from. Select option 2 to navigate to src/session/bin/session_manager:

[1] src/session/bin/session_manager
[2] src/session/tests/session_manager

This enables you to easily find and navigate the piece of code where you want to work. If the search is specific enough to return a single result, fd will navigate you there automatically.

Run the following command to perform a search for archivist — Fuchsia's diagnostics service for collecting log data, snapshots, and lifecycle events:

fd archivist

Notice that the command didn't actually print any results, but your working directory was automatically set to src/diagnostics/archivist!

Tip: You can run fd without any arguments to jump back to the source root from anywhere.

This is helpful to get you started, but there are several things you may want to search for in the Fuchsia tree that require searching inside files.

Search within source files

To search the tree for patterns within specific source files, use the fx grep command.

Run a search in the tree looking for references to the hello-world example using fx grep:

fx grep hello-world

This returns a long list of references from across the tree, because this example is referenced in documentation, build files, and other sources.

You can refine the search using filters to help narrow in on the protocol definition. Perform the same search again, but this time only in GN build files using a filter:

fx grep hello-world -- build

The results indicate that the protocol definition is located at examples/hello_world. You can combine this information with fd to navigate there:

fd hello_world

Overview

Build system