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:

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:

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