tools/gn/docs/style_guide.md

   1 # GN Style Guide
   2
   3 [TOC]
   4 ## Naming and ordering within the file
   5
   6 ### Location of build files
   7
   8 It usually makes sense to have more build files closer to the code than
   9 fewer ones at the toplevel (this is in contrast with what we did with
  10 GYP). This makes things easier to find and owners reviews easier since
  11 changes are more focused.
  12
  13 ### Targets
  14
  15   * Most BUILD files should have a target with the same name of the
  16     directory. This target should be the first target.
  17   * Other targets should be in "some order that makes sense." Usually
  18     more important targets will be first, and unit tests will follow the
  19     corresponding target. If there's no clear ordering, consider
  20     alphabetical order.
  21   * Test support libraries should be source sets named "test\_support".
  22     So "//ui/compositor:test\_support". Test support libraries should
  23     include as public deps the non-test-support version of the library
  24     so tests need only depend on the test\_support target (rather than
  25     both).
  26
  27 Naming advice
  28
  29   * Targets and configs should be named using lowercase with underscores
  30     separating words, unless there is a strong reason to do otherwise.
  31   * Source sets, groups, and static libraries do not need globally unique names.
  32     Prefer to give such targets short, non-redundant names without worrying
  33     about global uniqueness. For example, it looks much better to write a
  34     dependency as `"//mojo/public/bindings"` rather than
  35     `"//mojo/public/bindings:mojo_bindings"
  36   * Shared libraries (and by extension, components) must have globally unique
  37     output names. Give such targets short non-unique names above, and then
  38     provide a globally unique `output_name` for that target.
  39   * Executables and tests should be given a globally unique name. Technically
  40     only the output names must be unique, but since only the output names
  41     appear in the shell and on bots, it's much less confusing if the name
  42     matches the other places the executable appears.
  43
  44 ### Configs
  45
  46   * A config associated with a single target should be named the same as
  47     the target with `_config` following it.
  48   * A config should appear immediately before the corresponding target
  49     that uses it.
  50
  51 ### Example
  52
  53 Example for the `src/foo/BUILD.gn` file:
  54
  55 ```
  56 # Copyright 2013 The Chromium Authors. All rights reserved.
  57 # Use of this source code is governed by a BSD-style license that can be
  58 # found in the LICENSE file.
  59
  60 # Config for foo is named foo_config and immediately precedes it in the file.
  61 config("foo_config") {
  62 }
  63
  64 # Target matching path name is the first target.
  65 executable("foo") {
  66 }
  67
  68 # Test for foo follows it.
  69 test("foo_unittests") {
  70 }
  71
  72 config("bar_config") {
  73 }
  74
  75 source_set("bar") {
  76 }
  77 ```
  78
  79 ## Ordering within a target
  80
  81   1. `output_name` / `visibility` / `testonly`
  82   2. `sources`
  83   3. `cflags`, `include_dirs`, `defines`, `configs` etc. in whatever
  84      order makes sense to you.
  85   4. `public_deps`
  86   5. `deps`
  87
  88 ### Conditions
  89
  90 Simple conditions affecting just one variable (e.g. adding a single
  91 source or adding a flag for one particular OS) can go beneath the
  92 variable they affect. More complicated conditions affecting more than
  93 one thing should go at the bottom.
  94
  95 Conditions should be written to minimize the number of conditional blocks.
  96
  97 ## Formatting and indenting
  98
  99   * Indents are two spaces, both for indented blocks and wrapped lines.
 100   * Variables are `lower_case_with_underscores`
 101   * Complicated conditions and if statements should generally follow the
 102     Google C++ style guide for formatting.
 103   * Comments should be complete sentences with periods at the end.
 104   * End-of-line-comments should have two spaces separating them and the
 105     code.
 106   * Compiler flags and such should always be commented with what they do
 107     and why the flag is needed.
 108   * Try to keep lines under 80 columns. If a file name or similar string
 109     puts you beyond 80 with reasonable indenting, it's OK, but most
 110     things can be wrapped nicely under that for the code review tool.
 111
 112 ### List formatting
 113
 114 ```
 115   deps = [
 116     "afile.cc",
 117     "bar.cc",  # Note trailing comma on last element.
 118   ]
 119 ```
 120
 121 Alphabetize the list elements unless there is a more obvious ordering.
 122 In some cases, it makes more sense to put more than one list member on a
 123 line if they clearly go together (for example, two short compiler flags
 124 that must go next to each other).
 125
 126 Prefer use the multi-line style for lists of more than one elements.
 127 Lists with single-elements can be written on one line if desired:
 128
 129 ```
 130   all_dependent_configs = [ ":foo_config" ]  # No trailing comma.
 131 ```
 132
 133 ### Sources
 134
 135   * Sources should always be alphabetized within a given list.
 136   * List sources only once. It is OK to conditionally include sources
 137     rather than listing them all at the top and then conditionally
 138     excluding them when they don't apply. Conditional inclusion is often
 139     clearer since a file is only listed once and it's easier to reason
 140     about when reading.
 141
 142 ```
 143   sources = [
 144     "main.cc",
 145   ]
 146   if (use_aura) {
 147     sources += [ "thing_aura.cc" ]
 148   }
 149   if (use_gtk) {
 150     sources += [ "thing_gtk.cc" ]
 151   }
 152 ```
 153
 154 ### Deps
 155
 156   * Deps should be in alphabetical order.
 157   * Deps within the current file should be written first and not
 158     qualified with the file name (just `:foo`).
 159   * Other deps should always use fully-qualified path names unless
 160     relative ones are required for some reason.
 161
 162 ```
 163   deps = [
 164     ":a_thing",
 165     ":mystatic",
 166     "//foo/bar:other_thing",
 167     "//foo/baz:that_thing",
 168   ]
 169 ```
 170
 171 ### Import
 172
 173 Use fully-qualified paths for imports:
 174
 175 ```
 176 import("//foo/bar/baz.gni")  # Even if this file is in the foo/bar directory
 177 ```
 178
 179 ## Usage
 180
 181 Use `source_set` rather than `static_library` unless you have a reason
 182 to do otherwise. A static library is a standalone library which can be
 183 slow to generate. A source set just links all the object files from that
 184 target into the targets depending on it, which saves the "lib" step.