155 Of the supported build systems, GN is the most full-featured, followed by CMake,
159   A quick note on terminology: the word "target" is overloaded within GN/Bazel (and
160   Pigweed)---it can refer to either a GN/Bazel build target, such as a ``source_set``
164   To avoid confusing the two, we refer to the former as "GN/Bazel targets" and the
167 .. _docs-build-system-gn:
169 GN  section in Pigweed's build systems
171 A perhaps unfamiliar name, `GN (Generate Ninja)`_ is a meta-build system that
173 first experimented with GN after hearing about it from another team, and we
174 quickly came to appreciate its speed and simplicity. GN has become Pigweed's
180 .. _GN (Generate Ninja): https://gn.googlesource.com/gn
183 The GN build  argument
185 This section describes Pigweed's GN build structure, how it is used upstream,
187 containing some details about how GN works in general, this section is not
188 intended to be a guide on how to use GN. To learn more about the tool itself,
189 refer to the official `GN reference`_.
191 .. _GN reference: https://gn.googlesource.com/gn/+/HEAD/docs/reference.md
193 Entrypoint: .gn
195 The entrypoint to a GN build is the ``.gn`` file, which defines a project's root
198 ``.gn`` must point to the location of a ``BUILDCONFIG.gn`` file for the project.
201 Downstream projects may additionally use ``.gn`` to set global overrides for
209    buildconfig = "//BUILDCONFIG.gn"
216 Configuration: BUILDCONFIG.gn
218 The file ``BUILDCONFIG.gn`` configures the GN build by defining any desired
220 conventionally placed at the root. ``.gn`` points GN to this file.
222 ``BUILDCONFIG.gn`` is evaluated before any other GN files, and variables defined
223 within it are placed into GN's global scope, becoming available in every file
226 The options configured in this file differ from those in ``.gn`` in two ways:
228 1. ``BUILDCONFIG.gn`` is evaluated for every GN toolchain (and Pigweed target),
229    whereas ``.gn`` is only evaluated once. This allows ``BUILDCONFIG.gn`` to set
231 2. In ``.gn``, only GN build arguments can be overridden. ``BUILDCONFIG.gn``
235 instead of globals in ``BUILDCONFIG.gn`` (something Pigweed's build previously
237 may make sense to define project-specific constants in ``BUILDCONFIG.gn``.
239 Pigweed's upstream ``BUILDCONFIG.gn`` does not define any variables; it just
240 sets Pigweed's default toolchain, which GN requires.
244 Top-level GN targets: //BUILD.gn
246 The root ``BUILD.gn`` file defines all of the libraries, images, tests, and
248 ``BUILDCONFIG.gn``, with the active toolchain (which is the default toolchain
251 ``//BUILD.gn`` is responsible for enumerating each of the Pigweed targets built
253 GN target groups with each Pigweed target's toolchain. For example, in upstream,
254 all of Pigweed's GN targets are contained within the ``pigweed_default`` group.
268 group for each of their Pigweed targets that builds a common GN target with the
272 within ``//BUILD.gn``, as it does not configure any build parameters, and
273 therefore should not evaluate any other GN files. The pattern that Pigweed uses
296   which doesn't define any tools. ``//BUILD.gn`` contains conditions which check
297   that the current toolchain is not the default before declaring any GN target
299   files. All GN targets added to the build must be placed under one of these
304 The root ``BUILD.gn`` file can define a special group named ``default``. If
312 Pigweed's ``//BUILD.gn`` defines the ``pw_DEFAULT_C_OPTIMIZATION_LEVEL`` build
322 Pigweed defines versions of its groups in ``//BUILD.gn`` for each optimization
329 Upstream GN target groups
331 In upstream, Pigweed splits its top-level GN targets into a few logical groups,
332 which are described below. In order to build a GN target, it *must* be listed in
337   Pigweed's top-level ``BUILD.gn`` file should not be used by downstream
415 Other BUILD files: //\*\*/BUILD.gn
417 The rest of the ``BUILD.gn`` files in the tree define libraries, configs, and
423 location in the GN build tree. Currently, this file only contains a single build
424 argument, which must be set to the GN build path to the root of the Pigweed
430 where it or its modules is located. Therefore, Pigweed's upstream BUILD.gn files
434 To depend on Pigweed modules from GN code, import Pigweed's overrides file and
440    # prevent gn format from reordering this import, it must be separated by a
445 GN target type wrappers
448 around builtin GN target types such as ``source_set`` and ``executable``. These
453   ``pw_*`` target types (e.g. ``pw_source_set``) in your BUILD.gn files instead
454   of GN builtins.
459 are essentially GN toolchains which set special arguments telling Pigweed how to
465 Pigweed's ``BUILDCONFIG.gn`` sets the project's default toolchain to an "empty"
479   Additionally, there are some cases where GN treats default and non-default
486   GN-based project).
496 1. Define your executable GN target using the ``pw_executable`` template.
500       # //foo/BUILD.gn
506 2. In the root ``BUILD.gn`` file, add the executable's GN target to the ``apps``
511       # //BUILD.gn
528    Ninja. When building a GN target manually, the Pigweed target for which it
540      rather than a GN path. This path can be found by running ``gn outputs``.
550    ``gn_path`` is the GN path to the BUILD.gn file defining the executable,
551    and ``executable`` is the executable's GN target name (potentially with an