Fuchsia builds use Generate Ninja (GN), a meta-build system that generates build files consumed by Ninja, which executes the actual build. The build system provides the tools to configure the build for a specific product and templates to build code for Fuchsia targets.
Build targets
You define individual build targets for GN using BUILD.gn
files located with
your project source code. The Fuchsia build system provides templates as GN
imports (.gni
) for you to declare Fuchsia artifacts, such as:
fuchsia_component()
: Defines an executable component, containing the manifest, program binary, and resources.fuchsia_package()
: Defines a package containing one or more components for distribution in a package repository.fuchsia_test_package()
: Defines a package containing test components.
Below is an example of a BUILD.gn
file for a simple component package with
tests:
import("//build/components.gni")
executable("bin") {
sources = [ "main.cc" ]
}
fuchsia_component("hello-world-component") {
deps = [ ":bin" ]
manifest = "meta/hello-world.cml"
}
fuchsia_package("hello-world") {
deps = [
":hello-world-component",
]
}
fuchsia_component("hello-world-test-component") {
testonly = true
deps = [ ":bin_test" ]
manifest = "meta/hello-world-bin-test.cml"
}
fuchsia_test_package("hello-world-tests") {
test_components = [ ":hello-world-test-component" ]
}
A unique label composed of the target's name and the path to its BUILD.gn
file identifies everything that can participate in the build. In the above
example, the hello-world
target might have a label that looks like
this: //src/examples/basic:hello-world
.
Build configuration
The GN front-end configures the build according to the chosen Fuchsia
product configuration, collecting all the necessary packages and components
required by the build. These targets are defined in various BUILD.gn
files
throughout the source tree. The output of the GN step is an optimized set of
instructions for Ninja in the build directory.
The build system invokes GN when you run the fx set
command to configure
the build.
fx set minimal.x64
You should run the GN configuration step anytime you want to adjust the product
configuration or the packages available to the build. GN is also invoked
automatically during a build anytime one of the BUILD.gn
files in the current
configuration is changed.
Boards and products
The Fuchsia build system defines the baseline configuration for a Fuchsia build
as a combination of a product and board. Together, these elements form
the build configuration you provide to fx set
.
Boards define the architecture that the build targets, which may affect what drivers are included and influence device specific kernel parameters.
This codelab targets the qemu-x64
board, which supports the Fuchsia emulator
(FEMU) running on x64 architecture.
A product defines the software configuration that a build produces. This configuration may include what services are available and the user-facing experience.
This codelab targets the minimal_eng
product.
Build
Once the GN build configuration is complete, Ninja consumes the generated build files and runs the appropriate compile, link, and packaging commands to generate the Fuchsia image.
The build system invokes Ninja when you run the fx build
command to execute
the current build configuration.
fx build
Exercise: Build Minimal
In this exercise, you'll build the minimal_eng
product configuration from
source to run on the qemu-x64
emulator board.
Configure the build
Set up the build environment for the minimal
product and qemu-x64
board:
fx set minimal.x64
This command runs GN on the set of targets defined in the product's build configuration to produce the build instructions. It does not actually perform the build, but instead defines the parameters of what is considered buildable.
Inspect the build configuration
Once the build is configured, use fx list-packages
to print the set of
packages the build is aware of:
fx list-packages
This is a useful tool to determine if a package you need was properly included in the build configuration.
Build Fuchsia Minimal
Build the Minimal target with fx build
:
fx build
Restart the emulator
Run the following command to close any emulator instances you currently have open:
ffx emu stop --all
Start a new emulator instance:
ffx emu start --headless
When startup is complete, the emulator prints the following message and returns:
Logging to "$HOME/.local/share/Fuchsia/ffx/emu/instances/fuchsia-emulator/emulator.log" Waiting for Fuchsia to start (up to 60 seconds)........ Emulator is ready.
Inspect the device
Open another terminal window and run the following command to print the details of your device target:
ffx target show
Look for the build configuration of the target output:
Version: "2000-01-01T12:00:00+00:00"
Product: "minimal_eng"
Board: "qemu-x64"
Commit: "2000-01-01T12:00:00+00:00"
Notice that the configuration points to the build you just completed on your machine.
You are now running your own build of Fuchsia!