GN快速入门指南

GN快速入门指南

运行GN

你只需要从命令行运行gn。在depot_tools目录有一个同名脚本gn.py。这个脚本将在包含当前目录的源代码树中找到二进制文件并运行它。

建立一个构建

在GYP中，系统会为您生成Debug和Release建立目录并相应地进行配置。GN不这样做。相反，你可以使用你想要的任何配置来设置你想要的目录。当在该目录中构建时，如果Ninja文件过时会自动重新生成。

创建一个构建目录：

gn gen out/my_build

传递构建参数

通过运行以下命令在build目录中设置生成参数：

gn args out/my_build

这将启动一个编辑器。在这个文件中键入构建参数，如下所示：

is_component_build = true
is_debug = false

您可以通过输入以下命令来查看可用参数列表及其默认值

gn args --list out/my_build

请注意，您必须指定此命令的构建目录，因为可用的参数可以根据设置的构建目录进行更改。

Chrome开发人员还可以阅读Chrome特定的构建配置说明以获取更多信息。

交叉编译到目标操作系统或体系结构

运行gn args out/Default（根据需要替换您的构建目录），并为常见的交叉编译选项添加以下一行或多行。

target_os =“chromeos”
target_os =“android”

target_cpu =“arm”
target_cpu =“x86”
target_cpu =“x64”

有关更多信息，请参阅GNCrossCompiles。

配置goma

运行gn args out/Default（根据需要替换您的构建目录）。加：

use_goma = true
goma_dir ="〜/foo/bar/goma"

如果你的goma在默认位置（~/goma），那么你可以省略该goma_dir行。

配置组件模式

这是一个像goma标志一样的构建参数。运行gn args out/Default并添加：

is_component_build = true

一步步

添加一个构建文件

创建一个tools/gn/tutorial/BUILD.gn文件并输入以下内容：

executable("hello_world") {
  sources = [
    "hello_world.cc"
  ]
}

该目录中应该已经有一个hello_world.cc文件，包含你所期望的。就是这样！现在我们只需要告诉构建这个文件。打开BUILD.gn根目录中的文件，并将此目标的标签添加到其中一个根组的依赖关系（“组”目标是一个元目标，它只是其他目标的集合）：

group("root") {
  deps = [
    ...
    "//url"，
    "//tools/gn/tutorial:hello_world"
  ]
}

您可以看到您的目标标签是“//”（表示源根目录），后面是目录名称，冒号和目标名称。

测试你的添加

从源根目录中打开命令行：

gn gen out/Default
ninja -C out/Default hello_world
out/Default/hello_world

GN鼓励目标名称不是全球唯一的静态库。要构建其中之一，您可以将不带前导“//”的标签传递给Ninja：

ninja -C out/Default tools/gn/tutorial:hello_world

声明依赖关系

让我们来做一个静态库，它有一个函数向随机的人打招呼。该目录中有一个源文件hello.cc，它具有执行此操作的功能。打开tools/gn/tutorial/BUILD.gn文件并将静态库添加到现有文件的底部：

static_library（“hello”）{
  sources = [
    "hello.cc"
  ]
}

现在让我们添加一个依赖于这个库的可执行文件：

executable("say_hello"){
  sources = [
    "say_hello.cc"
  ]
  deps = [
    ":hello"，
  ]
}

这个可执行文件包含一个源文件，并依赖于前一个静态库。静态库在deps使用它的标签引用。您可以使用完整的标签，//tools/gn/tutorial:hello但是如果您在同一个构建文件中引用目标，则可以使用快捷方式:hello。

测试静态库版本

从源根目录中运行命令行：

ninja -C out/Default say_hello
out/Default/say_hello

请注意，您不必重新运行GN。当任何构建文件发生变化时，GN将自动重建Ninja文件。当Ninja在执行开始时打印[1/1] Regenerating ninja files时，就是这种情况。

编译器设置

我们的hello 库有一个新功能，能够同时向两个人打招呼。这个特性是通过定义TWO_PEOPLE来控制的。我们可以像这样添加定义：

static_library（“hello”）{
  sources = [
    "hello.cc"
  ]
  defines = [
    "TWO_PEOPLE"
  ]
}

把设置放在配置中

然而，库的用户也需要知道这个定义，并把它放在静态库目标中，只为那里的文件定义它。如果其他人包括hello.h，他们将不会看到新的定义。要看到新的定义，每个人都必须定义TWO_PEOPLE。

GN有一个叫“config”的概念封装设置。我们来创建一个定义我们的预处理器的定义：

config("hello_config"){
  defines = [
    "TWO_PEOPLE"
  ]
}

要将这些设置应用于目标，只需要将配置标签添加到目标中的配置列表中即可：

static_library（“hello”）{
  ...
  configs + = [
    “：hello_config”
  ]
}

请注意，您需要“+ =”而不是“=”，因为构建配置具有应用于每个设置默认构建内容的目标的默认配置集。你想添加到这个列表而不是覆盖它。要查看默认配置，可以使用print构建文件中的函数或desc命令行子命令（请参阅下面的两个示例）。

依赖配置

这很好地封装了我们的设置，但仍然需要每个使用我们库的用户来设置自己的配置。如果依赖于我们的hello库的每个人都能自动获得这个信息，那就太好了。将您的库定义更改为：

static_library（“hello”）{
  sources = [
    “hello.cc”
  ]
  all_dependent_configs = [
    “：hello_config”
  ]
}

这应用hello_config于hello目标本身，加上所有目标的传递依赖于目前的目标。现在依赖我们的每个人都会得到我们的设置。你也可以设置public_configs只适用于直接依赖你的目标（不是过渡性）。

现在，如果您编译并运行，您将看到两个人的新版本：

> ninja -C out/Default say_hello
ninja: Entering directory 'out/Default'
[1/1] Regenerating ninja files
[4/4] LINK say_hello
> out/Default/say_hello
Hello, Bill and Joy.

添加一个新的构建参数

通过declare_args可以声明你接受哪些参数，并指定默认值。

declare_args（）{
  enable_teleporter = true
  enable_doom_melon = false
}

请参阅有关gn help buildargs如何工作的概述。请参阅gn help declare_args声明它们的具体内容。

在一个给定的范围内多次声明一个给定的参数是一个错误，因此应该在范围和命名参数中小心使用。

不知道发生了什么事？

您可以在详细模式下运行GN，以查看有关正在执行的操作的许多消息。使用-v。

打印调试

有一个print命令仅写入标准输出：

static_library（"hello"）{
  ...
  print（CONFIGS）
}

这将打印适用于您的目标（包括默认的）的所有配置。

“desc”命令

您可以运行gn desc <build_dir> <targetname>以获取有关给定目标的信息：

gn desc out/Default //tools/gn/tutorial:say_hello

将打印出大量令人兴奋的信息。您也可以只打印一个部分。假设你想知道你的TWO_PEOPLE定义来自哪个say_hello目标：

> gn desc out/Default //tools/gn/tutorial:say_hello defines --blame
...lots of other stuff omitted...
  From //tools/gn/tutorial:hello_config
       (Added by //tools/gn/tutorial/BUILD.gn:12)
    TWO_PEOPLE

你可以看到，TWO_PEOPLE是由一个配置定义的，你也可以看到哪一行导致配置被应用到你的目标（在本例中，是all_dependent_configs行）。

另一个特别有趣的变量

gn desc out/Default //base:base_i18n deps --tree

通过gn help desc了解更多信息。

性能

通过使用–time命令行标志运行它，可以看到花了多长时间。这将输出各种事物的时间统计。

您还可以跟踪构建文件的执行方式：

gn --tracelog = mylog.trace

并且您可以在Chrome的about:tracing页面中加载生成的文件来查看所有内容。