It usually makes sense to have more build files closer to the code than fewer ones at the toplevel (this is in contrast with what we did with GYP). This makes things easier to find and owners reviews easier since changes are more focused.
Output names (the part after the colon in a label) of executables and shared libraries must be globally unique since they all go in the root directory. Prefer to do this by giving a target a short (possibly non-unique) name that makes writing dependencies clearer, and setting the output_name
variable to something unique.
For example, it looks much better to write a dependency as "//mojo/public/bindings"
rather than "//mojo/public/bindings:mojo_bindings"
. So in the file //mojo/public/bindings/BUILD.gn
: shared_library("bindings") { # Very non-unique name "bindings" makes the most sense in this context. output_name = "mojo_bindings" # Give target a unique output name to avoid collisions. ... }
This will produce a file mojo_bindings.so
in the root build directory.
_config
following it.Example for the src/foo/BUILD.gn
file:
# Copyright 2013 The Chromium Authors. All rights reserved. # Use of this source code is governed by a BSD-style license that can be # found in the LICENSE file. # Config for foo is named foo_config and immediately precedes it in the file. config("foo_config") { } # Target matching path name is the first target. executable("foo") { } # Test for foo follows it. test("foo_unittests") { } config("bar_config") { } source_set("bar") { }
output_name
/ visibility
/ testonly
sources
cflags
, include_dirs
, defines
, configs
etc. in whatever order makes sense to you.public_deps
deps
Simple conditions affecting just one variable (e.g. adding a single source or adding a flag for one particular OS) can go beneath the variable they affect. More complicated conditions affecting more than one thing should go at the bottom.
Conditions should be written to minimize the number of conditional blocks.
lower_case_with_underscores
deps = [ "afile.cc", "bar.cc", # Note trailing comma on last element. ]
Alphabetize the list elements unless there is a more obvious ordering. In some cases, it makes more sense to put more than one list member on a line if they clearly go together (for example, two short compiler flags that must go next to each other).
Prefer use the multi-line style for lists of more than one elements. Lists with single-elements can be written on one line if desired:
all_dependent_configs = [ ":foo_config" ] # No trailing comma.
sources = [ "main.cc", ] if (use_aura) { sources += [ "thing_aura.cc" ] } if (use_gtk) { sources += [ "thing_gtk.cc" ] }
:foo
).deps = [ ":a_thing", ":mystatic", "//foo/bar:other_thing", "//foo/baz:that_thing", ]
Use fully-qualified paths for imports:
import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory
Use source_set
rather than static_library
unless you have a reason to do otherwise. A static library is a standalone library which can be slow to generate. A source set just links all the object files from that target into the targets depending on it, which saves the “lib” step.