GN build

文章目錄
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

1. 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.
2. Execute the build config file.
3. Load the BUILD.gn file in the root directory.
4. Recursively load the BUILD.gn in other directories to resolve all current dependencies.
5. When a target’s dependencies are resolved, write out the .ninja file to disk.
6. When all targets are resolved, write out the root build.ninja file.

• Some important files for gn build system
  .gn: Describe the location of the BUILDCONFIG.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) with set_default_toolchain().
  • Secondary toolchain:

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.