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.

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

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

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!

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