文章目录
1 Introduction
2 Build flow
3 Naming things
3.1 File names
3.2 Labels
3.3 Variables
4 Targets
5 Configs
6 Toolchains
7 Templates
1 Introduction
GN is a meta build system that generates files for Ninja.
- Download the latest version of GN binary for Linux, macOS and Windows.
- Download GN binary for Linux without google.
Using built-in help:
$ gn help
Commands (type "gn help <command>" for more details):
<font color=yellow>analyze</font>: Analyze which targets are affected by a list of files.
args: Display or configure arguments declared by the build.
...
2 Build flow
- Look for
.gn
file in the current directory and walk up the directory tree until one is found. Set this directory to be the “source root” and interpret this file to find the name of the build config file.- Execute the build config file.
- Load the
BUILD.gn
file in the root directory.- Recursively load the
BUILD.gn
in other directories to resolve all current dependencies.- When a target’s dependencies are resolved, write out the
.ninja
file to disk.- When all targets are resolved, write out the root
build.ninja
file.
- Some important files for gn build system
.gn
: Describe the location of theBUILDCONFIG.gn
file
BUILDCONFIG.gn
: Sets up global variables and default settings.
BUILD.gn
: Describe your build target in each directory.
*.gni
: Describe some shared variables or templates. - Setting up a build
$ gn gen out/ --args='target_os="linux" target_cpu="x64"'
For more details: gn help gen
and gn help args
.
3 Naming things
3.1 File names
- Relative to current build file’s directory:
"foo.cc"
、"src/foo.cc"
- Source-tree absolute names:
//base/test/foo.cc"
3.2 Labels
Everything that can participate in the dependency graph (**[targets](#targets), [configs](#configs), and [toolchains](#toolchains)**) are identified by labels.- Full label:
//chrome/browser:version
Looks for “version” in //chrome/browser/BUILD.gn - Implicit name:
//base
Shorthand for //base:base - In current file:
:baz
Shorthand for “baz” in current file
Attention: //
represents the “source root”.
3.3 Variables
Variables in GN are all string type. There are three types of variables:
- build arguments: Declared by
declare_args()
function as the default value, can be override on command line or in a toolchain’s arguments. - global variables: Directly declared in a
BUILDCONFIG.gn
file. - local variables: Directly declared in
BUILD.gn
file.
4 Targets
A target is a node in the build graph, which usually represents some kind of executable or library file that will be generated. Targets depend on other targets.
Some built-in targets(see gn help <targettype>
for more help):
action
: Run a script to generate a file.executable
: Generates an executable file.group
: Declare a named group of targets.shared_library
: A .dll or .so.static_library
: A .lib or .a file.target
: Declare an target with the given programmatic type.
Toy example:
executable("toyapp") {
sources = [
"src/a.cpp",
"src/main.cpp",
]
cflags = [ "-Wall" ]
defins = [ "EVIL_BIT=1" ]
include_dirs = [ "." ]
deps = [ "//base" ]
}
5 Configs
Configs are named objects that specify sets of **flags, include directories, and defines**. They can be applied to targets.(see gn help config
for more help)
config("myconfig") {
includes = [ "src/include" ]
defines = [ "ENABLE_DOOM_MELON" ]
}
Apply to a target:
executable("doom_melon") {
configs += [ ":myconfig" ]
}
6 Toolchains
A toolchain is a set of commands and build flags used to compile the source code. The toolchain()
function defines these commands.
(See gn help toolchain
for more help.)
-
Functions and variables
tool()
: specifies the commands to run for a given step. See "gn help tool
for more help".
tool(<tool type>) { <tool variables ...> }
toolchain_args
: Overrides for build arguments to pass to the toolchain when invoking it.deps
: Dependencies of this toolchain. To avoid circular dependencies these must be targets defined in another toolchain.
deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ]
-
Example
toolchain("32") {
tool("cc") {
...
}
... more tools ..
# Arguments to the build when re-invoking as a secondary toolchain.
toolchain_args() {
toolchain_cpu = "x86"
}
}
-
Specify a toolchain
- Default toolchain: A default toolchain must be set in build config file(
BUILDCONFIG.gn
) withset_default_toolchain()
. - Secondary toolchain:
- Default toolchain: A default toolchain must be set in build config file(
7 Templates
Templates are GN’s primary way to re-use code (create customed target type), typically defined in a *.gni
file.
- Two magic variables:
target_name
,invoker
template("grit") {
action(target_name) {
script = "//tool/grit.py"
sources = [ invoker.source ]
}
}
grit("components_strings") {
source = "components.grd"
outputs = [...]
}
In this example, target_name
variable expands to “components_strings”, source variable is passed via invoker
.