| OLD | NEW |
| 1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
| 4 | 4 |
| 5 #include "tools/gn/variables.h" | 5 #include "tools/gn/variables.h" |
| 6 | 6 |
| 7 namespace variables { | 7 namespace variables { |
| 8 | 8 |
| 9 // Built-in variables ---------------------------------------------------------- | 9 // Built-in variables ---------------------------------------------------------- |
| 10 | 10 |
| 11 const char kHostCpu[] = "host_cpu"; | 11 const char kHostCpu[] = "host_cpu"; |
| 12 const char kHostCpu_HelpShort[] = | 12 const char kHostCpu_HelpShort[] = |
| 13 "host_cpu: [string] The processor architecture that GN is running on."; | 13 "host_cpu: [string] The processor architecture that GN is running on."; |
| 14 const char kHostCpu_Help[] = | 14 const char kHostCpu_Help[] = |
| 15 "host_cpu: The processor architecture that GN is running on.\n" | 15 R"(host_cpu: The processor architecture that GN is running on. |
| 16 "\n" | 16 |
| 17 " This is value is exposed so that cross-compile toolchains can\n" | 17 This is value is exposed so that cross-compile toolchains can access the host |
| 18 " access the host architecture when needed.\n" | 18 architecture when needed. |
| 19 "\n" | 19 |
| 20 " The value should generally be considered read-only, but it can be\n" | 20 The value should generally be considered read-only, but it can be overriden |
| 21 " overriden in order to handle unusual cases where there might\n" | 21 in order to handle unusual cases where there might be multiple plausible |
| 22 " be multiple plausible values for the host architecture (e.g., if\n" | 22 values for the host architecture (e.g., if you can do either 32-bit or 64-bit |
| 23 " you can do either 32-bit or 64-bit builds). The value is not used\n" | 23 builds). The value is not used internally by GN for any purpose. |
| 24 " internally by GN for any purpose.\n" | 24 |
| 25 "\n" | 25 Some possible values |
| 26 "Some possible values:\n" | 26 |
| 27 " - \"x64\"\n" | 27 - "x64" |
| 28 " - \"x86\"\n"; | 28 - "x86" |
| 29 )"; |
| 29 | 30 |
| 30 const char kHostOs[] = "host_os"; | 31 const char kHostOs[] = "host_os"; |
| 31 const char kHostOs_HelpShort[] = | 32 const char kHostOs_HelpShort[] = |
| 32 "host_os: [string] The operating system that GN is running on."; | 33 "host_os: [string] The operating system that GN is running on."; |
| 33 const char kHostOs_Help[] = | 34 const char kHostOs_Help[] = |
| 34 "host_os: [string] The operating system that GN is running on.\n" | 35 R"(host_os: [string] The operating system that GN is running on. |
| 35 "\n" | 36 |
| 36 " This value is exposed so that cross-compiles can access the host\n" | 37 This value is exposed so that cross-compiles can access the host build |
| 37 " build system's settings.\n" | 38 system's settings. |
| 38 "\n" | 39 |
| 39 " This value should generally be treated as read-only. It, however,\n" | 40 This value should generally be treated as read-only. It, however, is not used |
| 40 " is not used internally by GN for any purpose.\n" | 41 internally by GN for any purpose. |
| 41 "\n" | 42 |
| 42 "Some possible values:\n" | 43 Some possible values |
| 43 " - \"linux\"\n" | 44 |
| 44 " - \"mac\"\n" | 45 - "linux" |
| 45 " - \"win\"\n"; | 46 - "mac" |
| 47 - "win" |
| 48 )"; |
| 46 | 49 |
| 47 const char kInvoker[] = "invoker"; | 50 const char kInvoker[] = "invoker"; |
| 48 const char kInvoker_HelpShort[] = | 51 const char kInvoker_HelpShort[] = |
| 49 "invoker: [string] The invoking scope inside a template."; | 52 "invoker: [string] The invoking scope inside a template."; |
| 50 const char kInvoker_Help[] = | 53 const char kInvoker_Help[] = |
| 51 "invoker: [string] The invoking scope inside a template.\n" | 54 R"(invoker: [string] The invoking scope inside a template. |
| 52 "\n" | 55 |
| 53 " Inside a template invocation, this variable refers to the scope of\n" | 56 Inside a template invocation, this variable refers to the scope of the |
| 54 " the invoker of the template. Outside of template invocations, this\n" | 57 invoker of the template. Outside of template invocations, this variable is |
| 55 " variable is undefined.\n" | 58 undefined. |
| 56 "\n" | 59 |
| 57 " All of the variables defined inside the template invocation are\n" | 60 All of the variables defined inside the template invocation are accessible as |
| 58 " accessible as members of the \"invoker\" scope. This is the way that\n" | 61 members of the "invoker" scope. This is the way that templates read values |
| 59 " templates read values set by the callers.\n" | 62 set by the callers. |
| 60 "\n" | 63 |
| 61 " This is often used with \"defined\" to see if a value is set on the\n" | 64 This is often used with "defined" to see if a value is set on the invoking |
| 62 " invoking scope.\n" | 65 scope. |
| 63 "\n" | 66 |
| 64 " See \"gn help template\" for more examples.\n" | 67 See "gn help template" for more examples. |
| 65 "\n" | 68 |
| 66 "Example\n" | 69 Example |
| 67 "\n" | 70 |
| 68 " template(\"my_template\") {\n" | 71 template("my_template") { |
| 69 " print(invoker.sources) # Prints [ \"a.cc\", \"b.cc\" ]\n" | 72 print(invoker.sources) # Prints [ "a.cc", "b.cc" ] |
| 70 " print(defined(invoker.foo)) # Prints false.\n" | 73 print(defined(invoker.foo)) # Prints false. |
| 71 " print(defined(invoker.bar)) # Prints true.\n" | 74 print(defined(invoker.bar)) # Prints true. |
| 72 " }\n" | 75 } |
| 73 "\n" | 76 |
| 74 " my_template(\"doom_melon\") {\n" | 77 my_template("doom_melon") { |
| 75 " sources = [ \"a.cc\", \"b.cc\" ]\n" | 78 sources = [ "a.cc", "b.cc" ] |
| 76 " bar = 123\n" | 79 bar = 123 |
| 77 " }\n"; | 80 } |
| 81 )"; |
| 78 | 82 |
| 79 const char kTargetCpu[] = "target_cpu"; | 83 const char kTargetCpu[] = "target_cpu"; |
| 80 const char kTargetCpu_HelpShort[] = | 84 const char kTargetCpu_HelpShort[] = |
| 81 "target_cpu: [string] The desired cpu architecture for the build."; | 85 "target_cpu: [string] The desired cpu architecture for the build."; |
| 82 const char kTargetCpu_Help[] = | 86 const char kTargetCpu_Help[] = |
| 83 "target_cpu: The desired cpu architecture for the build.\n" | 87 R"(target_cpu: The desired cpu architecture for the build. |
| 84 "\n" | 88 |
| 85 " This value should be used to indicate the desired architecture for\n" | 89 This value should be used to indicate the desired architecture for the |
| 86 " the primary objects of the build. It will match the cpu architecture\n" | 90 primary objects of the build. It will match the cpu architecture of the |
| 87 " of the default toolchain, but not necessarily the current toolchain.\n" | 91 default toolchain, but not necessarily the current toolchain. |
| 88 "\n" | 92 |
| 89 " In many cases, this is the same as \"host_cpu\", but in the case\n" | 93 In many cases, this is the same as "host_cpu", but in the case of |
| 90 " of cross-compiles, this can be set to something different. This\n" | 94 cross-compiles, this can be set to something different. This value is |
| 91 " value is different from \"current_cpu\" in that it does not change\n" | 95 different from "current_cpu" in that it does not change based on the current |
| 92 " based on the current toolchain. When writing rules, \"current_cpu\"\n" | 96 toolchain. When writing rules, "current_cpu" should be used rather than |
| 93 " should be used rather than \"target_cpu\" most of the time.\n" | 97 "target_cpu" most of the time. |
| 94 "\n" | 98 |
| 95 " This value is not used internally by GN for any purpose, so it\n" | 99 This value is not used internally by GN for any purpose, so it may be set to |
| 96 " may be set to whatever value is needed for the build.\n" | 100 whatever value is needed for the build. GN defaults this value to the empty |
| 97 " GN defaults this value to the empty string (\"\") and the\n" | 101 string ("") and the configuration files should set it to an appropriate value |
| 98 " configuration files should set it to an appropriate value\n" | 102 (e.g., setting it to the value of "host_cpu") if it is not overridden on the |
| 99 " (e.g., setting it to the value of \"host_cpu\") if it is not\n" | 103 command line or in the args.gn file. |
| 100 " overridden on the command line or in the args.gn file.\n" | 104 |
| 101 "\n" | 105 Possible values |
| 102 " Where practical, use one of the following list of common values:\n" | 106 |
| 103 "\n" | 107 - "x86" |
| 104 "Possible values:\n" | 108 - "x64" |
| 105 " - \"x86\"\n" | 109 - "arm" |
| 106 " - \"x64\"\n" | 110 - "arm64" |
| 107 " - \"arm\"\n" | 111 - "mipsel" |
| 108 " - \"arm64\"\n" | 112 )"; |
| 109 " - \"mipsel\"\n"; | |
| 110 | 113 |
| 111 const char kTargetName[] = "target_name"; | 114 const char kTargetName[] = "target_name"; |
| 112 const char kTargetName_HelpShort[] = | 115 const char kTargetName_HelpShort[] = |
| 113 "target_name: [string] The name of the current target."; | 116 "target_name: [string] The name of the current target."; |
| 114 const char kTargetName_Help[] = | 117 const char kTargetName_Help[] = |
| 115 "target_name: [string] The name of the current target.\n" | 118 R"(target_name: [string] The name of the current target. |
| 116 "\n" | 119 |
| 117 " Inside a target or template invocation, this variable refers to the\n" | 120 Inside a target or template invocation, this variable refers to the name |
| 118 " name given to the target or template invocation. Outside of these,\n" | 121 given to the target or template invocation. Outside of these, this variable |
| 119 " this variable is undefined.\n" | 122 is undefined. |
| 120 "\n" | 123 |
| 121 " This is most often used in template definitions to name targets\n" | 124 This is most often used in template definitions to name targets defined in |
| 122 " defined in the template based on the name of the invocation. This\n" | 125 the template based on the name of the invocation. This is necessary both to |
| 123 " is necessary both to ensure generated targets have unique names and\n" | 126 ensure generated targets have unique names and to generate a target with the |
| 124 " to generate a target with the exact name of the invocation that\n" | 127 exact name of the invocation that other targets can depend on. |
| 125 " other targets can depend on.\n" | 128 |
| 126 "\n" | 129 Be aware that this value will always reflect the innermost scope. So when |
| 127 " Be aware that this value will always reflect the innermost scope. So\n" | 130 defining a target inside a template, target_name will refer to the target |
| 128 " when defining a target inside a template, target_name will refer to\n" | 131 rather than the template invocation. To get the name of the template |
| 129 " the target rather than the template invocation. To get the name of the\n" | 132 invocation in this case, you should save target_name to a temporary variable |
| 130 " template invocation in this case, you should save target_name to a\n" | 133 outside of any target definitions. |
| 131 " temporary variable outside of any target definitions.\n" | 134 |
| 132 "\n" | 135 See "gn help template" for more examples. |
| 133 " See \"gn help template\" for more examples.\n" | 136 |
| 134 "\n" | 137 Example |
| 135 "Example\n" | 138 |
| 136 "\n" | 139 executable("doom_melon") { |
| 137 " executable(\"doom_melon\") {\n" | 140 print(target_name) # Prints "doom_melon". |
| 138 " print(target_name) # Prints \"doom_melon\".\n" | 141 } |
| 139 " }\n" | 142 |
| 140 "\n" | 143 template("my_template") { |
| 141 " template(\"my_template\") {\n" | 144 print(target_name) # Prints "space_ray" when invoked below. |
| 142 " print(target_name) # Prints \"space_ray\" when invoked below.\n" | 145 |
| 143 "\n" | 146 executable(target_name + "_impl") { |
| 144 " executable(target_name + \"_impl\") {\n" | 147 print(target_name) # Prints "space_ray_impl". |
| 145 " print(target_name) # Prints \"space_ray_impl\".\n" | 148 } |
| 146 " }\n" | 149 } |
| 147 " }\n" | 150 |
| 148 "\n" | 151 my_template("space_ray") { |
| 149 " my_template(\"space_ray\") {\n" | 152 } |
| 150 " }\n"; | 153 )"; |
| 151 | 154 |
| 152 const char kTargetOs[] = "target_os"; | 155 const char kTargetOs[] = "target_os"; |
| 153 const char kTargetOs_HelpShort[] = | 156 const char kTargetOs_HelpShort[] = |
| 154 "target_os: [string] The desired operating system for the build."; | 157 "target_os: [string] The desired operating system for the build."; |
| 155 const char kTargetOs_Help[] = | 158 const char kTargetOs_Help[] = |
| 156 "target_os: The desired operating system for the build.\n" | 159 R"(target_os: The desired operating system for the build. |
| 157 "\n" | 160 |
| 158 " This value should be used to indicate the desired operating system\n" | 161 This value should be used to indicate the desired operating system for the |
| 159 " for the primary object(s) of the build. It will match the OS of\n" | 162 primary object(s) of the build. It will match the OS of the default |
| 160 " the default toolchain.\n" | 163 toolchain. |
| 161 "\n" | 164 |
| 162 " In many cases, this is the same as \"host_os\", but in the case of\n" | 165 In many cases, this is the same as "host_os", but in the case of |
| 163 " cross-compiles, it may be different. This variable differs from\n" | 166 cross-compiles, it may be different. This variable differs from "current_os" |
| 164 " \"current_os\" in that it can be referenced from inside any\n" | 167 in that it can be referenced from inside any toolchain and will always return |
| 165 " toolchain and will always return the initial value.\n" | 168 the initial value. |
| 166 "\n" | 169 |
| 167 " This should be set to the most specific value possible. So,\n" | 170 This should be set to the most specific value possible. So, "android" or |
| 168 " \"android\" or \"chromeos\" should be used instead of \"linux\"\n" | 171 "chromeos" should be used instead of "linux" where applicable, even though |
| 169 " where applicable, even though Android and ChromeOS are both Linux\n" | 172 Android and ChromeOS are both Linux variants. This can mean that one needs to |
| 170 " variants. This can mean that one needs to write\n" | 173 write |
| 171 "\n" | 174 |
| 172 " if (target_os == \"android\" || target_os == \"linux\") {\n" | 175 if (target_os == "android" || target_os == "linux") { |
| 173 " # ...\n" | 176 # ... |
| 174 " }\n" | 177 } |
| 175 "\n" | 178 |
| 176 " and so forth.\n" | 179 and so forth. |
| 177 "\n" | 180 |
| 178 " This value is not used internally by GN for any purpose, so it\n" | 181 This value is not used internally by GN for any purpose, so it may be set to |
| 179 " may be set to whatever value is needed for the build.\n" | 182 whatever value is needed for the build. GN defaults this value to the empty |
| 180 " GN defaults this value to the empty string (\"\") and the\n" | 183 string ("") and the configuration files should set it to an appropriate value |
| 181 " configuration files should set it to an appropriate value\n" | 184 (e.g., setting it to the value of "host_os") if it is not set via the command |
| 182 " (e.g., setting it to the value of \"host_os\") if it is not\n" | 185 line or in the args.gn file. |
| 183 " set via the command line or in the args.gn file.\n" | 186 |
| 184 "\n" | 187 Possible values |
| 185 " Where practical, use one of the following list of common values:\n" | 188 |
| 186 "\n" | 189 - "android" |
| 187 "Possible values:\n" | 190 - "chromeos" |
| 188 " - \"android\"\n" | 191 - "ios" |
| 189 " - \"chromeos\"\n" | 192 - "linux" |
| 190 " - \"ios\"\n" | 193 - "nacl" |
| 191 " - \"linux\"\n" | 194 - "mac" |
| 192 " - \"nacl\"\n" | 195 - "win" |
| 193 " - \"mac\"\n" | 196 )"; |
| 194 " - \"win\"\n"; | |
| 195 | 197 |
| 196 const char kCurrentCpu[] = "current_cpu"; | 198 const char kCurrentCpu[] = "current_cpu"; |
| 197 const char kCurrentCpu_HelpShort[] = | 199 const char kCurrentCpu_HelpShort[] = |
| 198 "current_cpu: [string] The processor architecture of the current " | 200 "current_cpu: [string] The processor architecture of the current " |
| 199 "toolchain."; | 201 "toolchain."; |
| 200 const char kCurrentCpu_Help[] = | 202 const char kCurrentCpu_Help[] = |
| 201 "current_cpu: The processor architecture of the current toolchain.\n" | 203 R"(current_cpu: The processor architecture of the current toolchain. |
| 202 "\n" | 204 |
| 203 " The build configuration usually sets this value based on the value\n" | 205 The build configuration usually sets this value based on the value of |
| 204 " of \"host_cpu\" (see \"gn help host_cpu\") and then threads\n" | 206 "host_cpu" (see "gn help host_cpu") and then threads this through the |
| 205 " this through the toolchain definitions to ensure that it always\n" | 207 toolchain definitions to ensure that it always reflects the appropriate |
| 206 " reflects the appropriate value.\n" | 208 value. |
| 207 "\n" | 209 |
| 208 " This value is not used internally by GN for any purpose. It is\n" | 210 This value is not used internally by GN for any purpose. It is set it to the |
| 209 " set it to the empty string (\"\") by default but is declared so\n" | 211 empty string ("") by default but is declared so that it can be overridden on |
| 210 " that it can be overridden on the command line if so desired.\n" | 212 the command line if so desired. |
| 211 "\n" | 213 |
| 212 " See \"gn help target_cpu\" for a list of common values returned.\n"; | 214 See "gn help target_cpu" for a list of common values returned.)"; |
| 213 | 215 |
| 214 const char kCurrentOs[] = "current_os"; | 216 const char kCurrentOs[] = "current_os"; |
| 215 const char kCurrentOs_HelpShort[] = | 217 const char kCurrentOs_HelpShort[] = |
| 216 "current_os: [string] The operating system of the current toolchain."; | 218 "current_os: [string] The operating system of the current toolchain."; |
| 217 const char kCurrentOs_Help[] = | 219 const char kCurrentOs_Help[] = |
| 218 "current_os: The operating system of the current toolchain.\n" | 220 R"(current_os: The operating system of the current toolchain. |
| 219 "\n" | 221 |
| 220 " The build configuration usually sets this value based on the value\n" | 222 The build configuration usually sets this value based on the value of |
| 221 " of \"target_os\" (see \"gn help target_os\"), and then threads this\n" | 223 "target_os" (see "gn help target_os"), and then threads this through the |
| 222 " through the toolchain definitions to ensure that it always reflects\n" | 224 toolchain definitions to ensure that it always reflects the appropriate |
| 223 " the appropriate value.\n" | 225 value. |
| 224 "\n" | 226 |
| 225 " This value is not used internally by GN for any purpose. It is\n" | 227 This value is not used internally by GN for any purpose. It is set it to the |
| 226 " set it to the empty string (\"\") by default but is declared so\n" | 228 empty string ("") by default but is declared so that it can be overridden on |
| 227 " that it can be overridden on the command line if so desired.\n" | 229 the command line if so desired. |
| 228 "\n" | 230 |
| 229 " See \"gn help target_os\" for a list of common values returned.\n"; | 231 See "gn help target_os" for a list of common values returned. |
| 232 )"; |
| 230 | 233 |
| 231 const char kCurrentToolchain[] = "current_toolchain"; | 234 const char kCurrentToolchain[] = "current_toolchain"; |
| 232 const char kCurrentToolchain_HelpShort[] = | 235 const char kCurrentToolchain_HelpShort[] = |
| 233 "current_toolchain: [string] Label of the current toolchain."; | 236 "current_toolchain: [string] Label of the current toolchain."; |
| 234 const char kCurrentToolchain_Help[] = | 237 const char kCurrentToolchain_Help[] = |
| 235 "current_toolchain: Label of the current toolchain.\n" | 238 R"(current_toolchain: Label of the current toolchain. |
| 236 "\n" | 239 |
| 237 " A fully-qualified label representing the current toolchain. You can\n" | 240 A fully-qualified label representing the current toolchain. You can use this |
| 238 " use this to make toolchain-related decisions in the build. See also\n" | 241 to make toolchain-related decisions in the build. See also |
| 239 " \"default_toolchain\".\n" | 242 "default_toolchain". |
| 240 "\n" | 243 |
| 241 "Example\n" | 244 Example |
| 242 "\n" | 245 |
| 243 " if (current_toolchain == \"//build:64_bit_toolchain\") {\n" | 246 if (current_toolchain == "//build:64_bit_toolchain") { |
| 244 " executable(\"output_thats_64_bit_only\") {\n" | 247 executable("output_thats_64_bit_only") { |
| 245 " ...\n"; | 248 ... |
| 249 )"; |
| 246 | 250 |
| 247 const char kDefaultToolchain[] = "default_toolchain"; | 251 const char kDefaultToolchain[] = "default_toolchain"; |
| 248 const char kDefaultToolchain_HelpShort[] = | 252 const char kDefaultToolchain_HelpShort[] = |
| 249 "default_toolchain: [string] Label of the default toolchain."; | 253 "default_toolchain: [string] Label of the default toolchain."; |
| 250 const char kDefaultToolchain_Help[] = | 254 const char kDefaultToolchain_Help[] = |
| 251 "default_toolchain: [string] Label of the default toolchain.\n" | 255 R"(default_toolchain: [string] Label of the default toolchain. |
| 252 "\n" | 256 |
| 253 " A fully-qualified label representing the default toolchain, which may\n" | 257 A fully-qualified label representing the default toolchain, which may not |
| 254 " not necessarily be the current one (see \"current_toolchain\").\n"; | 258 necessarily be the current one (see "current_toolchain"). |
| 259 )"; |
| 255 | 260 |
| 256 const char kPythonPath[] = "python_path"; | 261 const char kPythonPath[] = "python_path"; |
| 257 const char kPythonPath_HelpShort[] = | 262 const char kPythonPath_HelpShort[] = |
| 258 "python_path: [string] Absolute path of Python."; | 263 "python_path: [string] Absolute path of Python."; |
| 259 const char kPythonPath_Help[] = | 264 const char kPythonPath_Help[] = |
| 260 "python_path: Absolute path of Python.\n" | 265 R"(python_path: Absolute path of Python. |
| 261 "\n" | 266 |
| 262 " Normally used in toolchain definitions if running some command\n" | 267 Normally used in toolchain definitions if running some command requires |
| 263 " requires Python. You will normally not need this when invoking scripts\n" | 268 Python. You will normally not need this when invoking scripts since GN |
| 264 " since GN automatically finds it for you.\n"; | 269 automatically finds it for you. |
| 270 )"; |
| 265 | 271 |
| 266 const char kRootBuildDir[] = "root_build_dir"; | 272 const char kRootBuildDir[] = "root_build_dir"; |
| 267 const char kRootBuildDir_HelpShort[] = | 273 const char kRootBuildDir_HelpShort[] = |
| 268 "root_build_dir: [string] Directory where build commands are run."; | 274 "root_build_dir: [string] Directory where build commands are run."; |
| 269 const char kRootBuildDir_Help[] = | 275 const char kRootBuildDir_Help[] = |
| 270 "root_build_dir: [string] Directory where build commands are run.\n" | 276 R"(root_build_dir: [string] Directory where build commands are run. |
| 271 "\n" | 277 |
| 272 " This is the root build output directory which will be the current\n" | 278 This is the root build output directory which will be the current directory |
| 273 " directory when executing all compilers and scripts.\n" | 279 when executing all compilers and scripts. |
| 274 "\n" | 280 |
| 275 " Most often this is used with rebase_path (see \"gn help rebase_path\")\n" | 281 Most often this is used with rebase_path (see "gn help rebase_path") to |
| 276 " to convert arguments to be relative to a script's current directory.\n"; | 282 convert arguments to be relative to a script's current directory. |
| 283 )"; |
| 277 | 284 |
| 278 const char kRootGenDir[] = "root_gen_dir"; | 285 const char kRootGenDir[] = "root_gen_dir"; |
| 279 const char kRootGenDir_HelpShort[] = | 286 const char kRootGenDir_HelpShort[] = |
| 280 "root_gen_dir: [string] Directory for the toolchain's generated files."; | 287 "root_gen_dir: [string] Directory for the toolchain's generated files."; |
| 281 const char kRootGenDir_Help[] = | 288 const char kRootGenDir_Help[] = |
| 282 "root_gen_dir: Directory for the toolchain's generated files.\n" | 289 R"(root_gen_dir: Directory for the toolchain's generated files. |
| 283 "\n" | 290 |
| 284 " Absolute path to the root of the generated output directory tree for\n" | 291 Absolute path to the root of the generated output directory tree for the |
| 285 " the current toolchain. An example would be \"//out/Debug/gen\" for the\n" | 292 current toolchain. An example would be "//out/Debug/gen" for the default |
| 286 " default toolchain, or \"//out/Debug/arm/gen\" for the \"arm\"\n" | 293 toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain. |
| 287 " toolchain.\n" | 294 |
| 288 "\n" | 295 This is primarily useful for setting up include paths for generated files. If |
| 289 " This is primarily useful for setting up include paths for generated\n" | 296 you are passing this to a script, you will want to pass it through |
| 290 " files. If you are passing this to a script, you will want to pass it\n" | 297 rebase_path() (see "gn help rebase_path") to convert it to be relative to the |
| 291 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" | 298 build directory. |
| 292 " to be relative to the build directory.\n" | 299 |
| 293 "\n" | 300 See also "target_gen_dir" which is usually a better location for generated |
| 294 " See also \"target_gen_dir\" which is usually a better location for\n" | 301 files. It will be inside the root generated dir. |
| 295 " generated files. It will be inside the root generated dir.\n"; | 302 )"; |
| 296 | 303 |
| 297 const char kRootOutDir[] = "root_out_dir"; | 304 const char kRootOutDir[] = "root_out_dir"; |
| 298 const char kRootOutDir_HelpShort[] = | 305 const char kRootOutDir_HelpShort[] = |
| 299 "root_out_dir: [string] Root directory for toolchain output files."; | 306 "root_out_dir: [string] Root directory for toolchain output files."; |
| 300 const char kRootOutDir_Help[] = | 307 const char kRootOutDir_Help[] = |
| 301 "root_out_dir: [string] Root directory for toolchain output files.\n" | 308 R"(root_out_dir: [string] Root directory for toolchain output files. |
| 302 "\n" | 309 |
| 303 " Absolute path to the root of the output directory tree for the current\n" | 310 Absolute path to the root of the output directory tree for the current |
| 304 " toolchain. It will not have a trailing slash.\n" | 311 toolchain. It will not have a trailing slash. |
| 305 "\n" | 312 |
| 306 " For the default toolchain this will be the same as the root_build_dir.\n" | 313 For the default toolchain this will be the same as the root_build_dir. An |
| 307 " An example would be \"//out/Debug\" for the default toolchain, or\n" | 314 example would be "//out/Debug" for the default toolchain, or |
| 308 " \"//out/Debug/arm\" for the \"arm\" toolchain.\n" | 315 "//out/Debug/arm" for the "arm" toolchain. |
| 309 "\n" | 316 |
| 310 " This is primarily useful for setting up script calls. If you are\n" | 317 This is primarily useful for setting up script calls. If you are passing this |
| 311 " passing this to a script, you will want to pass it through\n" | 318 to a script, you will want to pass it through rebase_path() (see "gn help |
| 312 " rebase_path() (see \"gn help rebase_path\") to convert it\n" | 319 rebase_path") to convert it to be relative to the build directory. |
| 313 " to be relative to the build directory.\n" | 320 |
| 314 "\n" | 321 See also "target_out_dir" which is usually a better location for output |
| 315 " See also \"target_out_dir\" which is usually a better location for\n" | 322 files. It will be inside the root output dir. |
| 316 " output files. It will be inside the root output dir.\n" | 323 |
| 317 "\n" | 324 Example |
| 318 "Example\n" | 325 |
| 319 "\n" | 326 action("myscript") { |
| 320 " action(\"myscript\") {\n" | 327 # Pass the output dir to the script. |
| 321 " # Pass the output dir to the script.\n" | 328 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ] |
| 322 " args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n" | 329 } |
| 323 " }\n"; | 330 )"; |
| 324 | 331 |
| 325 const char kTargetGenDir[] = "target_gen_dir"; | 332 const char kTargetGenDir[] = "target_gen_dir"; |
| 326 const char kTargetGenDir_HelpShort[] = | 333 const char kTargetGenDir_HelpShort[] = |
| 327 "target_gen_dir: [string] Directory for a target's generated files."; | 334 "target_gen_dir: [string] Directory for a target's generated files."; |
| 328 const char kTargetGenDir_Help[] = | 335 const char kTargetGenDir_Help[] = |
| 329 "target_gen_dir: Directory for a target's generated files.\n" | 336 R"(target_gen_dir: Directory for a target's generated files. |
| 330 "\n" | 337 |
| 331 " Absolute path to the target's generated file directory. This will be\n" | 338 Absolute path to the target's generated file directory. This will be the |
| 332 " the \"root_gen_dir\" followed by the relative path to the current\n" | 339 "root_gen_dir" followed by the relative path to the current build file. If |
| 333 " build file. If your file is in \"//tools/doom_melon\" then\n" | 340 your file is in "//tools/doom_melon" then target_gen_dir would be |
| 334 " target_gen_dir would be \"//out/Debug/gen/tools/doom_melon\". It will\n" | 341 "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash. |
| 335 " not have a trailing slash.\n" | 342 |
| 336 "\n" | 343 This is primarily useful for setting up include paths for generated files. If |
| 337 " This is primarily useful for setting up include paths for generated\n" | 344 you are passing this to a script, you will want to pass it through |
| 338 " files. If you are passing this to a script, you will want to pass it\n" | 345 rebase_path() (see "gn help rebase_path") to convert it to be relative to the |
| 339 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" | 346 build directory. |
| 340 " to be relative to the build directory.\n" | 347 |
| 341 "\n" | 348 See also "gn help root_gen_dir". |
| 342 " See also \"gn help root_gen_dir\".\n" | 349 |
| 343 "\n" | 350 Example |
| 344 "Example\n" | 351 |
| 345 "\n" | 352 action("myscript") { |
| 346 " action(\"myscript\") {\n" | 353 # Pass the generated output dir to the script. |
| 347 " # Pass the generated output dir to the script.\n" | 354 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]" |
| 348 " args = [ \"-o\", rebase_path(target_gen_dir, root_build_dir) ]" | 355 } |
| 349 "\n" | 356 )"; |
| 350 " }\n"; | |
| 351 | 357 |
| 352 const char kTargetOutDir[] = "target_out_dir"; | 358 const char kTargetOutDir[] = "target_out_dir"; |
| 353 const char kTargetOutDir_HelpShort[] = | 359 const char kTargetOutDir_HelpShort[] = |
| 354 "target_out_dir: [string] Directory for target output files."; | 360 "target_out_dir: [string] Directory for target output files."; |
| 355 const char kTargetOutDir_Help[] = | 361 const char kTargetOutDir_Help[] = |
| 356 "target_out_dir: [string] Directory for target output files.\n" | 362 R"(target_out_dir: [string] Directory for target output files. |
| 357 "\n" | 363 |
| 358 " Absolute path to the target's generated file directory. If your\n" | 364 Absolute path to the target's generated file directory. If your current |
| 359 " current target is in \"//tools/doom_melon\" then this value might be\n" | 365 target is in "//tools/doom_melon" then this value might be |
| 360 " \"//out/Debug/obj/tools/doom_melon\". It will not have a trailing\n" | 366 "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash. |
| 361 " slash.\n" | 367 |
| 362 "\n" | 368 This is primarily useful for setting up arguments for calling scripts. If you |
| 363 " This is primarily useful for setting up arguments for calling\n" | 369 are passing this to a script, you will want to pass it through rebase_path() |
| 364 " scripts. If you are passing this to a script, you will want to pass it\n" | 370 (see "gn help rebase_path") to convert it to be relative to the build |
| 365 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" | 371 directory. |
| 366 " to be relative to the build directory.\n" | 372 |
| 367 "\n" | 373 See also "gn help root_out_dir". |
| 368 " See also \"gn help root_out_dir\".\n" | 374 |
| 369 "\n" | 375 Example |
| 370 "Example\n" | 376 |
| 371 "\n" | 377 action("myscript") { |
| 372 " action(\"myscript\") {\n" | 378 # Pass the output dir to the script. |
| 373 " # Pass the output dir to the script.\n" | 379 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]" |
| 374 " args = [ \"-o\", rebase_path(target_out_dir, root_build_dir) ]" | 380 |
| 375 "\n" | 381 } |
| 376 " }\n"; | 382 )"; |
| 377 | 383 |
| 378 // Target variables ------------------------------------------------------------ | 384 // Target variables ------------------------------------------------------------ |
| 379 | 385 |
| 380 #define COMMON_ORDERING_HELP \ | 386 #define COMMON_ORDERING_HELP \ |
| 381 "\n" \ | 387 "\n" \ |
| 382 "Ordering of flags and values\n" \ | 388 "Ordering of flags and values\n" \ |
| 383 "\n" \ | 389 "\n" \ |
| 384 " 1. Those set on the current target (not in a config).\n" \ | 390 " 1. Those set on the current target (not in a config).\n" \ |
| 385 " 2. Those set on the \"configs\" on the target in order that the\n" \ | 391 " 2. Those set on the \"configs\" on the target in order that the\n" \ |
| 386 " configs appear in the list.\n" \ | 392 " configs appear in the list.\n" \ |
| 387 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \ | 393 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \ |
| 388 " that the configs appear in the list.\n" \ | 394 " that the configs appear in the list.\n" \ |
| 389 " 4. Those set on the \"public_configs\" on the target in order that\n" \ | 395 " 4. Those set on the \"public_configs\" on the target in order that\n" \ |
| 390 " those configs appear in the list.\n" \ | 396 " those configs appear in the list.\n" \ |
| 391 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \ | 397 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \ |
| 392 " the \"deps\" list. This is done recursively. If a config appears\n" \ | 398 " the \"deps\" list. This is done recursively. If a config appears\n" \ |
| 393 " more than once, only the first occurance will be used.\n" \ | 399 " more than once, only the first occurance will be used.\n" \ |
| 394 " 6. public_configs pulled from dependencies, in the order of the\n" \ | 400 " 6. public_configs pulled from dependencies, in the order of the\n" \ |
| 395 " \"deps\" list. If a dependency is public, they will be applied\n" \ | 401 " \"deps\" list. If a dependency is public, they will be applied\n" \ |
| 396 " recursively.\n" | 402 " recursively.\n" |
| 397 | 403 |
| 398 const char kAllDependentConfigs[] = "all_dependent_configs"; | 404 const char kAllDependentConfigs[] = "all_dependent_configs"; |
| 399 const char kAllDependentConfigs_HelpShort[] = | 405 const char kAllDependentConfigs_HelpShort[] = |
| 400 "all_dependent_configs: [label list] Configs to be forced on dependents."; | 406 "all_dependent_configs: [label list] Configs to be forced on dependents."; |
| 401 const char kAllDependentConfigs_Help[] = | 407 const char kAllDependentConfigs_Help[] = |
| 402 "all_dependent_configs: Configs to be forced on dependents.\n" | 408 R"(all_dependent_configs: Configs to be forced on dependents. |
| 403 "\n" | 409 |
| 404 " A list of config labels.\n" | 410 A list of config labels. |
| 405 "\n" | 411 |
| 406 " All targets depending on this one, and recursively, all targets\n" | 412 All targets depending on this one, and recursively, all targets depending on |
| 407 " depending on those, will have the configs listed in this variable\n" | 413 those, will have the configs listed in this variable added to them. These |
| 408 " added to them. These configs will also apply to the current target.\n" | 414 configs will also apply to the current target. |
| 409 "\n" | 415 |
| 410 " This addition happens in a second phase once a target and all of its\n" | 416 This addition happens in a second phase once a target and all of its |
| 411 " dependencies have been resolved. Therefore, a target will not see\n" | 417 dependencies have been resolved. Therefore, a target will not see these |
| 412 " these force-added configs in their \"configs\" variable while the\n" | 418 force-added configs in their "configs" variable while the script is running, |
| 413 " script is running, and then can not be removed. As a result, this\n" | 419 and then can not be removed. As a result, this capability should generally |
| 414 " capability should generally only be used to add defines and include\n" | 420 only be used to add defines and include directories necessary to compile a |
| 415 " directories necessary to compile a target's headers.\n" | 421 target's headers. |
| 416 "\n" | 422 |
| 417 " See also \"public_configs\".\n" | 423 See also "public_configs". |
| 424 )" |
| 418 COMMON_ORDERING_HELP; | 425 COMMON_ORDERING_HELP; |
| 419 | 426 |
| 420 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; | 427 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; |
| 421 const char kAllowCircularIncludesFrom_HelpShort[] = | 428 const char kAllowCircularIncludesFrom_HelpShort[] = |
| 422 "allow_circular_includes_from: [label list] Permit includes from deps."; | 429 "allow_circular_includes_from: [label list] Permit includes from deps."; |
| 423 const char kAllowCircularIncludesFrom_Help[] = | 430 const char kAllowCircularIncludesFrom_Help[] = |
| 424 "allow_circular_includes_from: Permit includes from deps.\n" | 431 R"(allow_circular_includes_from: Permit includes from deps. |
| 425 "\n" | 432 |
| 426 " A list of target labels. Must be a subset of the target's \"deps\".\n" | 433 A list of target labels. Must be a subset of the target's "deps". These |
| 427 " These targets will be permitted to include headers from the current\n" | 434 targets will be permitted to include headers from the current target despite |
| 428 " target despite the dependency going in the opposite direction.\n" | 435 the dependency going in the opposite direction. |
| 429 "\n" | 436 |
| 430 " When you use this, both targets must be included in a final binary\n" | 437 When you use this, both targets must be included in a final binary for it to |
| 431 " for it to link. To keep linker errors from happening, it is good\n" | 438 link. To keep linker errors from happening, it is good practice to have all |
| 432 " practice to have all external dependencies depend only on one of\n" | 439 external dependencies depend only on one of the two targets, and to set the |
| 433 " the two targets, and to set the visibility on the other to enforce\n" | 440 visibility on the other to enforce this. Thus the targets will always be |
| 434 " this. Thus the targets will always be linked together in any output.\n" | 441 linked together in any output. |
| 435 "\n" | 442 |
| 436 "Details\n" | 443 Details |
| 437 "\n" | 444 |
| 438 " Normally, for a file in target A to include a file from target B,\n" | 445 Normally, for a file in target A to include a file from target B, A must list |
| 439 " A must list B as a dependency. This invariant is enforced by the\n" | 446 B as a dependency. This invariant is enforced by the "gn check" command (and |
| 440 " \"gn check\" command (and the --check flag to \"gn gen\" -- see\n" | 447 the --check flag to "gn gen" -- see "gn help check"). |
| 441 " \"gn help check\").\n" | 448 |
| 442 "\n" | 449 Sometimes, two targets might be the same unit for linking purposes (two |
| 443 " Sometimes, two targets might be the same unit for linking purposes\n" | 450 source sets or static libraries that would always be linked together in a |
| 444 " (two source sets or static libraries that would always be linked\n" | 451 final executable or shared library) and they each include headers from the |
| 445 " together in a final executable or shared library) and they each\n" | 452 other: you want A to be able to include B's headers, and B to include A's |
| 446 " include headers from the other: you want A to be able to include B's\n" | 453 headers. This is not an ideal situation but is sometimes unavoidable. |
| 447 " headers, and B to include A's headers. This is not an ideal situation\n" | 454 |
| 448 " but is sometimes unavoidable.\n" | 455 This list, if specified, lists which of the dependencies of the current |
| 449 "\n" | 456 target can include header files from the current target. That is, if A |
| 450 " This list, if specified, lists which of the dependencies of the\n" | 457 depends on B, B can only include headers from A if it is in A's |
| 451 " current target can include header files from the current target.\n" | 458 allow_circular_includes_from list. Normally includes must follow the |
| 452 " That is, if A depends on B, B can only include headers from A if it is\n" | 459 direction of dependencies, this flag allows them to go in the opposite |
| 453 " in A's allow_circular_includes_from list. Normally includes must\n" | 460 direction. |
| 454 " follow the direction of dependencies, this flag allows them to go\n" | 461 |
| 455 " in the opposite direction.\n" | 462 Danger |
| 456 "\n" | 463 |
| 457 "Danger\n" | 464 In the above example, A's headers are likely to include headers from A's |
| 458 "\n" | 465 dependencies. Those dependencies may have public_configs that apply flags, |
| 459 " In the above example, A's headers are likely to include headers from\n" | 466 defines, and include paths that make those headers work properly. |
| 460 " A's dependencies. Those dependencies may have public_configs that\n" | 467 |
| 461 " apply flags, defines, and include paths that make those headers work\n" | 468 With allow_circular_includes_from, B can include A's headers, and |
| 462 " properly.\n" | 469 transitively from A's dependencies, without having the dependencies that |
| 463 "\n" | 470 would bring in the public_configs those headers need. The result may be |
| 464 " With allow_circular_includes_from, B can include A's headers, and\n" | 471 errors or inconsistent builds. |
| 465 " transitively from A's dependencies, without having the dependencies\n" | 472 |
| 466 " that would bring in the public_configs those headers need. The result\n" | 473 So when you use allow_circular_includes_from, make sure that any compiler |
| 467 " may be errors or inconsistent builds.\n" | 474 settings, flags, and include directories are the same between both targets |
| 468 "\n" | 475 (consider putting such things in a shared config they can both reference). |
| 469 " So when you use allow_circular_includes_from, make sure that any\n" | 476 Make sure the dependencies are also the same (you might consider a group to |
| 470 " compiler settings, flags, and include directories are the same between\n" | 477 collect such dependencies they both depend on). |
| 471 " both targets (consider putting such things in a shared config they can\n" | 478 |
| 472 " both reference). Make sure the dependencies are also the same (you\n" | 479 Example |
| 473 " might consider a group to collect such dependencies they both\n" | 480 |
| 474 " depend on).\n" | 481 source_set("a") { |
| 475 "\n" | 482 deps = [ ":b", ":a_b_shared_deps" ] |
| 476 "Example\n" | 483 allow_circular_includes_from = [ ":b" ] |
| 477 "\n" | 484 ... |
| 478 " source_set(\"a\") {\n" | 485 } |
| 479 " deps = [ \":b\", \":a_b_shared_deps\" ]\n" | 486 |
| 480 " allow_circular_includes_from = [ \":b\" ]\n" | 487 source_set("b") { |
| 481 " ...\n" | 488 deps = [ ":a_b_shared_deps" ] |
| 482 " }\n" | 489 # Sources here can include headers from a despite lack of deps. |
| 483 "\n" | 490 ... |
| 484 " source_set(\"b\") {\n" | 491 } |
| 485 " deps = [ \":a_b_shared_deps\" ]\n" | 492 |
| 486 " # Sources here can include headers from a despite lack of deps.\n" | 493 group("a_b_shared_deps") { |
| 487 " ...\n" | 494 public_deps = [ ":c" ] |
| 488 " }\n" | 495 } |
| 489 "\n" | 496 )"; |
| 490 " group(\"a_b_shared_deps\") {\n" | |
| 491 " public_deps = [ \":c\" ]\n" | |
| 492 " }\n"; | |
| 493 | 497 |
| 494 const char kArflags[] = "arflags"; | 498 const char kArflags[] = "arflags"; |
| 495 const char kArflags_HelpShort[] = | 499 const char kArflags_HelpShort[] = |
| 496 "arflags: [string list] Arguments passed to static_library archiver."; | 500 "arflags: [string list] Arguments passed to static_library archiver."; |
| 497 const char kArflags_Help[] = | 501 const char kArflags_Help[] = |
| 498 "arflags: Arguments passed to static_library archiver.\n" | 502 R"(arflags: Arguments passed to static_library archiver. |
| 499 "\n" | 503 |
| 500 " A list of flags passed to the archive/lib command that creates static\n" | 504 A list of flags passed to the archive/lib command that creates static |
| 501 " libraries.\n" | 505 libraries. |
| 502 "\n" | 506 |
| 503 " arflags are NOT pushed to dependents, so applying arflags to source\n" | 507 arflags are NOT pushed to dependents, so applying arflags to source sets or |
| 504 " sets or any other target type will be a no-op. As with ldflags,\n" | 508 any other target type will be a no-op. As with ldflags, you could put the |
| 505 " you could put the arflags in a config and set that as a public or\n" | 509 arflags in a config and set that as a public or "all dependent" config, but |
| 506 " \"all dependent\" config, but that will likely not be what you want.\n" | 510 that will likely not be what you want. If you have a chain of static |
| 507 " If you have a chain of static libraries dependent on each other,\n" | 511 libraries dependent on each other, this can cause the flags to propagate up |
| 508 " this can cause the flags to propagate up to other static libraries.\n" | 512 to other static libraries. Due to the nature of how arflags are typically |
| 509 " Due to the nature of how arflags are typically used, you will normally\n" | 513 used, you will normally want to apply them directly on static_library targets |
| 510 " want to apply them directly on static_library targets themselves.\n" | 514 themselves. |
| 515 )" |
| 511 COMMON_ORDERING_HELP; | 516 COMMON_ORDERING_HELP; |
| 512 | 517 |
| 513 const char kArgs[] = "args"; | 518 const char kArgs[] = "args"; |
| 514 const char kArgs_HelpShort[] = | 519 const char kArgs_HelpShort[] = |
| 515 "args: [string list] Arguments passed to an action."; | 520 "args: [string list] Arguments passed to an action."; |
| 516 const char kArgs_Help[] = | 521 const char kArgs_Help[] = |
| 517 "args: Arguments passed to an action.\n" | 522 R"(args: Arguments passed to an action. |
| 518 "\n" | 523 |
| 519 " For action and action_foreach targets, args is the list of arguments\n" | 524 For action and action_foreach targets, args is the list of arguments to pass |
| 520 " to pass to the script. Typically you would use source expansion (see\n" | 525 to the script. Typically you would use source expansion (see "gn help |
| 521 " \"gn help source_expansion\") to insert the source file names.\n" | 526 source_expansion") to insert the source file names. |
| 522 "\n" | 527 |
| 523 " See also \"gn help action\" and \"gn help action_foreach\".\n"; | 528 See also "gn help action" and "gn help action_foreach". |
| 529 )"; |
| 524 | 530 |
| 525 const char kAssertNoDeps[] = "assert_no_deps"; | 531 const char kAssertNoDeps[] = "assert_no_deps"; |
| 526 const char kAssertNoDeps_HelpShort[] = | 532 const char kAssertNoDeps_HelpShort[] = |
| 527 "assert_no_deps:Â [label pattern list] Ensure no deps on these targets."; | 533 "assert_no_deps:Â [label pattern list] Ensure no deps on these targets."; |
| 528 const char kAssertNoDeps_Help[] = | 534 const char kAssertNoDeps_Help[] = |
| 529 "assert_no_deps: Ensure no deps on these targets.\n" | 535 R"(assert_no_deps: Ensure no deps on these targets. |
| 530 "\n" | 536 |
| 531 " A list of label patterns.\n" | 537 A list of label patterns. |
| 532 "\n" | 538 |
| 533 " This list is a list of patterns that must not match any of the\n" | 539 This list is a list of patterns that must not match any of the transitive |
| 534 " transitive dependencies of the target. These include all public,\n" | 540 dependencies of the target. These include all public, private, and data |
| 535 " private, and data dependencies, and cross shared library boundaries.\n" | 541 dependencies, and cross shared library boundaries. This allows you to express |
| 536 " This allows you to express that undesirable code isn't accidentally\n" | 542 that undesirable code isn't accidentally added to downstream dependencies in |
| 537 " added to downstream dependencies in a way that might otherwise be\n" | 543 a way that might otherwise be difficult to notice. |
| 538 " difficult to notice.\n" | 544 |
| 539 "\n" | 545 Checking does not cross executable boundaries. If a target depends on an |
| 540 " Checking does not cross executable boundaries. If a target depends on\n" | 546 executable, it's assumed that the executable is a tool that is producing part |
| 541 " an executable, it's assumed that the executable is a tool that is\n" | 547 of the build rather than something that is linked and distributed. This |
| 542 " producing part of the build rather than something that is linked and\n" | 548 allows assert_no_deps to express what is distributed in the final target |
| 543 " distributed. This allows assert_no_deps to express what is distributed\n" | 549 rather than depend on the internal build steps (which may include |
| 544 " in the final target rather than depend on the internal build steps\n" | 550 non-distributable code). |
| 545 " (which may include non-distributable code).\n" | 551 |
| 546 "\n" | 552 See "gn help label_pattern" for the format of the entries in the list. These |
| 547 " See \"gn help label_pattern\" for the format of the entries in the\n" | 553 patterns allow blacklisting individual targets or whole directory |
| 548 " list. These patterns allow blacklisting individual targets or whole\n" | 554 hierarchies. |
| 549 " directory hierarchies.\n" | 555 |
| 550 "\n" | 556 Sometimes it is desirable to enforce that many targets have no dependencies |
| 551 " Sometimes it is desirable to enforce that many targets have no\n" | 557 on a target or set of targets. One efficient way to express this is to create |
| 552 " dependencies on a target or set of targets. One efficient way to\n" | 558 a group with the assert_no_deps rule on it, and make that group depend on all |
| 553 " express this is to create a group with the assert_no_deps rule on\n" | 559 targets you want to apply that assertion to. |
| 554 " it, and make that group depend on all targets you want to apply that\n" | 560 |
| 555 " assertion to.\n" | 561 Example |
| 556 "\n" | 562 |
| 557 "Example\n" | 563 executable("doom_melon") { |
| 558 "\n" | 564 deps = [ "//foo:bar" ] |
| 559 " executable(\"doom_melon\") {\n" | 565 ... |
| 560 " deps = [ \"//foo:bar\" ]\n" | 566 assert_no_deps = [ |
| 561 " ...\n" | 567 "//evil/*", # Don't link any code from the evil directory. |
| 562 " assert_no_deps = [\n" | 568 "//foo:test_support", # This target is also disallowed. |
| 563 " \"//evil/*\", # Don't link any code from the evil directory.\n" | 569 ] |
| 564 " \"//foo:test_support\", # This target is also disallowed.\n" | 570 } |
| 565 " ]\n" | 571 )"; |
| 566 " }\n"; | |
| 567 | 572 |
| 568 const char kBundleRootDir[] = "bundle_root_dir"; | 573 const char kBundleRootDir[] = "bundle_root_dir"; |
| 569 const char kBundleRootDir_HelpShort[] = | 574 const char kBundleRootDir_HelpShort[] = |
| 570 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle."; | 575 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle."; |
| 571 const char kBundleRootDir_Help[] = | 576 const char kBundleRootDir_Help[] = |
| 572 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.\n" | 577 R"(bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle. |
| 573 "\n" | 578 |
| 574 " A string corresponding to a path in root_build_dir.\n" | 579 A string corresponding to a path in root_build_dir. |
| 575 "\n" | 580 |
| 576 " This string is used by the \"create_bundle\" target to expand the\n" | 581 This string is used by the "create_bundle" target to expand the |
| 577 " {{bundle_root_dir}} of the \"bundle_data\" target it depends on.\n" | 582 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must |
| 578 " This must correspond to a path under root_build_dir.\n" | 583 correspond to a path under root_build_dir. |
| 579 "\n" | 584 |
| 580 "Example\n" | 585 Example |
| 581 "\n" | 586 |
| 582 " bundle_data(\"info_plist\") {\n" | 587 bundle_data("info_plist") { |
| 583 " sources = [ \"Info.plist\" ]\n" | 588 sources = [ "Info.plist" ] |
| 584 " outputs = [ \"{{bundle_root_dir}}/Info.plist\" ]\n" | 589 outputs = [ "{{bundle_root_dir}}/Info.plist" ] |
| 585 " }\n" | 590 } |
| 586 "\n" | 591 |
| 587 " create_bundle(\"doom_melon.app\") {\n" | 592 create_bundle("doom_melon.app") { |
| 588 " deps = [ \":info_plist\" ]\n" | 593 deps = [ ":info_plist" ] |
| 589 " bundle_root_dir = root_build_dir + \"/doom_melon.app/Contents\"\n" | 594 bundle_root_dir = root_build_dir + "/doom_melon.app/Contents" |
| 590 " bundle_resources_dir = bundle_root_dir + \"/Resources\"\n" | 595 bundle_resources_dir = bundle_root_dir + "/Resources" |
| 591 " bundle_executable_dir = bundle_root_dir + \"/MacOS\"\n" | 596 bundle_executable_dir = bundle_root_dir + "/MacOS" |
| 592 " bundle_plugins_dir = bundle_root_dir + \"/PlugIns\"\n" | 597 bundle_plugins_dir = bundle_root_dir + "/PlugIns" |
| 593 " }\n"; | 598 } |
| 599 )"; |
| 594 | 600 |
| 595 const char kBundleResourcesDir[] = "bundle_resources_dir"; | 601 const char kBundleResourcesDir[] = "bundle_resources_dir"; |
| 596 const char kBundleResourcesDir_HelpShort[] = | 602 const char kBundleResourcesDir_HelpShort[] = |
| 597 "bundle_resources_dir: " | 603 "bundle_resources_dir: " |
| 598 "Expansion of {{bundle_resources_dir}} in create_bundle."; | 604 "Expansion of {{bundle_resources_dir}} in create_bundle."; |
| 599 const char kBundleResourcesDir_Help[] = | 605 const char kBundleResourcesDir_Help[] = |
| 600 "bundle_resources_dir: " | 606 R"(bundle_resources_dir: Expansion of {{bundle_resources_dir}} in |
| 601 "Expansion of {{bundle_resources_dir}} in create_bundle.\n" | 607 create_bundle. |
| 602 "\n" | 608 |
| 603 " A string corresponding to a path in $root_build_dir.\n" | 609 A string corresponding to a path in $root_build_dir. |
| 604 "\n" | 610 |
| 605 " This string is used by the \"create_bundle\" target to expand the\n" | 611 This string is used by the "create_bundle" target to expand the |
| 606 " {{bundle_resources_dir}} of the \"bundle_data\" target it depends on.\n" | 612 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must |
| 607 " This must correspond to a path under \"bundle_root_dir\".\n" | 613 correspond to a path under "bundle_root_dir". |
| 608 "\n" | 614 |
| 609 " See \"gn help bundle_root_dir\" for examples.\n"; | 615 See "gn help bundle_root_dir" for examples. |
| 616 )"; |
| 610 | 617 |
| 611 const char kBundleDepsFilter[] = "bundle_deps_filter"; | 618 const char kBundleDepsFilter[] = "bundle_deps_filter"; |
| 612 const char kBundleDepsFilter_HelpShort[] = | 619 const char kBundleDepsFilter_HelpShort[] = |
| 613 "bundle_deps_filter: [label list] A list of labels that are filtered out."; | 620 "bundle_deps_filter: [label list] A list of labels that are filtered out."; |
| 614 const char kBundleDepsFilter_Help[] = | 621 const char kBundleDepsFilter_Help[] = |
| 615 "bundle_deps_filter: [label list] A list of labels that are filtered out.\n" | 622 R"(bundle_deps_filter: [label list] A list of labels that are filtered out. |
| 616 "\n" | 623 |
| 617 " A list of target labels.\n" | 624 A list of target labels. |
| 618 "\n" | 625 |
| 619 " This list contains target label patterns that should be filtered out\n" | 626 This list contains target label patterns that should be filtered out when |
| 620 " when creating the bundle. Any target matching one of those label will\n" | 627 creating the bundle. Any target matching one of those label will be removed |
| 621 " be removed from the dependencies of the create_bundle target.\n" | 628 from the dependencies of the create_bundle target. |
| 622 "\n" | 629 |
| 623 " This is mostly useful when creating application extension bundle as\n" | 630 This is mostly useful when creating application extension bundle as the |
| 624 " the application extension has access to runtime resources from the\n" | 631 application extension has access to runtime resources from the application |
| 625 " application bundle and thus do not require a second copy.\n" | 632 bundle and thus do not require a second copy. |
| 626 "\n" | 633 |
| 627 " See \"gn help create_bundle\" for more information.\n" | 634 See "gn help create_bundle" for more information. |
| 628 "\n" | 635 |
| 629 "Example\n" | 636 Example |
| 630 "\n" | 637 |
| 631 " create_bundle(\"today_extension\") {\n" | 638 create_bundle("today_extension") { |
| 632 " deps = [\n" | 639 deps = [ |
| 633 " \"//base\"\n" | 640 "//base" |
| 634 " ]\n" | 641 ] |
| 635 " bundle_root_dir = \"$root_out_dir/today_extension.appex\"\n" | 642 bundle_root_dir = "$root_out_dir/today_extension.appex" |
| 636 " bundle_deps_filter = [\n" | 643 bundle_deps_filter = [ |
| 637 " # The extension uses //base but does not use any function calling\n" | 644 # The extension uses //base but does not use any function calling into |
| 638 " # into third_party/icu and thus does not need the icudtl.dat file.\n" | 645 # third_party/icu and thus does not need the icudtl.dat file. |
| 639 " \"//third_party/icu:icudata\",\n" | 646 "//third_party/icu:icudata", |
| 640 " ]\n" | 647 ] |
| 641 " }\n"; | 648 } |
| 649 )"; |
| 642 | 650 |
| 643 const char kBundleExecutableDir[] = "bundle_executable_dir"; | 651 const char kBundleExecutableDir[] = "bundle_executable_dir"; |
| 644 const char kBundleExecutableDir_HelpShort[] = | 652 const char kBundleExecutableDir_HelpShort[] = |
| 645 "bundle_executable_dir: " | 653 "bundle_executable_dir: " |
| 646 "Expansion of {{bundle_executable_dir}} in create_bundle"; | 654 "Expansion of {{bundle_executable_dir}} in create_bundle"; |
| 647 const char kBundleExecutableDir_Help[] = | 655 const char kBundleExecutableDir_Help[] = |
| 648 "bundle_executable_dir: " | 656 R"(bundle_executable_dir: Expansion of {{bundle_executable_dir}} in |
| 649 "Expansion of {{bundle_executable_dir}} in create_bundle.\n" | 657 create_bundle. |
| 650 "\n" | 658 |
| 651 " A string corresponding to a path in $root_build_dir.\n" | 659 A string corresponding to a path in $root_build_dir. |
| 652 "\n" | 660 |
| 653 " This string is used by the \"create_bundle\" target to expand the\n" | 661 This string is used by the "create_bundle" target to expand the |
| 654 " {{bundle_executable_dir}} of the \"bundle_data\" target it depends on.\n" | 662 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This |
| 655 " This must correspond to a path under \"bundle_root_dir\".\n" | 663 must correspond to a path under "bundle_root_dir". |
| 656 "\n" | 664 |
| 657 " See \"gn help bundle_root_dir\" for examples.\n"; | 665 See "gn help bundle_root_dir" for examples. |
| 666 )"; |
| 658 | 667 |
| 659 const char kBundlePlugInsDir[] = "bundle_plugins_dir"; | 668 const char kBundlePlugInsDir[] = "bundle_plugins_dir"; |
| 660 const char kBundlePlugInsDir_HelpShort[] = | 669 const char kBundlePlugInsDir_HelpShort[] = |
| 661 "bundle_plugins_dir: " | 670 "bundle_plugins_dir: " |
| 662 "Expansion of {{bundle_plugins_dir}} in create_bundle."; | 671 "Expansion of {{bundle_plugins_dir}} in create_bundle."; |
| 663 const char kBundlePlugInsDir_Help[] = | 672 const char kBundlePlugInsDir_Help[] = |
| 664 "bundle_plugins_dir: " | 673 R"(bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle. |
| 665 "Expansion of {{bundle_plugins_dir}} in create_bundle.\n" | 674 |
| 666 "\n" | 675 A string corresponding to a path in $root_build_dir. |
| 667 " A string corresponding to a path in $root_build_dir.\n" | 676 |
| 668 "\n" | 677 This string is used by the "create_bundle" target to expand the |
| 669 " This string is used by the \"create_bundle\" target to expand the\n" | 678 {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must |
| 670 " {{bundle_plugins_dir}} of the \"bundle_data\" target it depends on.\n" | 679 correspond to a path under "bundle_root_dir". |
| 671 " This must correspond to a path under \"bundle_root_dir\".\n" | 680 |
| 672 "\n" | 681 See "gn help bundle_root_dir" for examples. |
| 673 " See \"gn help bundle_root_dir\" for examples.\n"; | 682 )"; |
| 674 | 683 |
| 675 const char kCflags[] = "cflags"; | 684 const char kCflags[] = "cflags"; |
| 676 const char kCflags_HelpShort[] = | 685 const char kCflags_HelpShort[] = |
| 677 "cflags: [string list] Flags passed to all C compiler variants."; | 686 "cflags: [string list] Flags passed to all C compiler variants."; |
| 678 const char kCommonCflagsHelp[] = | 687 const char kCommonCflagsHelp[] = |
| 679 "cflags*: Flags passed to the C compiler.\n" | 688 R"(cflags*: Flags passed to the C compiler. |
| 680 "\n" | 689 |
| 681 " A list of strings.\n" | 690 A list of strings. |
| 682 "\n" | 691 |
| 683 " \"cflags\" are passed to all invocations of the C, C++, Objective C,\n" | 692 "cflags" are passed to all invocations of the C, C++, Objective C, and |
| 684 " and Objective C++ compilers.\n" | 693 Objective C++ compilers. |
| 685 "\n" | 694 |
| 686 " To target one of these variants individually, use \"cflags_c\",\n" | 695 To target one of these variants individually, use "cflags_c", "cflags_cc", |
| 687 " \"cflags_cc\", \"cflags_objc\", and \"cflags_objcc\",\n" | 696 "cflags_objc", and "cflags_objcc", respectively. These variant-specific |
| 688 " respectively. These variant-specific versions of cflags* will be\n" | 697 versions of cflags* will be appended on the compiler command line after |
| 689 " appended on the compiler command line after \"cflags\".\n" | 698 "cflags". |
| 690 "\n" | 699 |
| 691 " See also \"asmflags\" for flags for assembly-language files.\n" | 700 See also "asmflags" for flags for assembly-language files. |
| 701 )" |
| 692 COMMON_ORDERING_HELP; | 702 COMMON_ORDERING_HELP; |
| 693 const char* kCflags_Help = kCommonCflagsHelp; | 703 const char* kCflags_Help = kCommonCflagsHelp; |
| 694 | 704 |
| 695 const char kAsmflags[] = "asmflags"; | 705 const char kAsmflags[] = "asmflags"; |
| 696 const char kAsmflags_HelpShort[] = | 706 const char kAsmflags_HelpShort[] = |
| 697 "asmflags: [string list] Flags passed to the assembler."; | 707 "asmflags: [string list] Flags passed to the assembler."; |
| 698 const char* kAsmflags_Help = | 708 const char* kAsmflags_Help = |
| 699 "asmflags: Flags passed to the assembler.\n" | 709 R"(asmflags: Flags passed to the assembler. |
| 700 "\n" | 710 |
| 701 " A list of strings.\n" | 711 A list of strings. |
| 702 "\n" | 712 |
| 703 " \"asmflags\" are passed to any invocation of a tool that takes an\n" | 713 "asmflags" are passed to any invocation of a tool that takes an .asm or .S |
| 704 " .asm or .S file as input.\n" | 714 file as input. |
| 715 )" |
| 705 COMMON_ORDERING_HELP; | 716 COMMON_ORDERING_HELP; |
| 706 | 717 |
| 707 const char kCflagsC[] = "cflags_c"; | 718 const char kCflagsC[] = "cflags_c"; |
| 708 const char kCflagsC_HelpShort[] = | 719 const char kCflagsC_HelpShort[] = |
| 709 "cflags_c: [string list] Flags passed to the C compiler."; | 720 "cflags_c: [string list] Flags passed to the C compiler."; |
| 710 const char* kCflagsC_Help = kCommonCflagsHelp; | 721 const char* kCflagsC_Help = kCommonCflagsHelp; |
| 711 | 722 |
| 712 const char kCflagsCC[] = "cflags_cc"; | 723 const char kCflagsCC[] = "cflags_cc"; |
| 713 const char kCflagsCC_HelpShort[] = | 724 const char kCflagsCC_HelpShort[] = |
| 714 "cflags_cc: [string list] Flags passed to the C++ compiler."; | 725 "cflags_cc: [string list] Flags passed to the C++ compiler."; |
| 715 const char* kCflagsCC_Help = kCommonCflagsHelp; | 726 const char* kCflagsCC_Help = kCommonCflagsHelp; |
| 716 | 727 |
| 717 const char kCflagsObjC[] = "cflags_objc"; | 728 const char kCflagsObjC[] = "cflags_objc"; |
| 718 const char kCflagsObjC_HelpShort[] = | 729 const char kCflagsObjC_HelpShort[] = |
| 719 "cflags_objc: [string list] Flags passed to the Objective C compiler."; | 730 "cflags_objc: [string list] Flags passed to the Objective C compiler."; |
| 720 const char* kCflagsObjC_Help = kCommonCflagsHelp; | 731 const char* kCflagsObjC_Help = kCommonCflagsHelp; |
| 721 | 732 |
| 722 const char kCflagsObjCC[] = "cflags_objcc"; | 733 const char kCflagsObjCC[] = "cflags_objcc"; |
| 723 const char kCflagsObjCC_HelpShort[] = | 734 const char kCflagsObjCC_HelpShort[] = |
| 724 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler."; | 735 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler."; |
| 725 const char* kCflagsObjCC_Help = kCommonCflagsHelp; | 736 const char* kCflagsObjCC_Help = kCommonCflagsHelp; |
| 726 | 737 |
| 727 const char kCheckIncludes[] = "check_includes"; | 738 const char kCheckIncludes[] = "check_includes"; |
| 728 const char kCheckIncludes_HelpShort[] = | 739 const char kCheckIncludes_HelpShort[] = |
| 729 "check_includes: [boolean] Controls whether a target's files are checked."; | 740 "check_includes: [boolean] Controls whether a target's files are checked."; |
| 730 const char kCheckIncludes_Help[] = | 741 const char kCheckIncludes_Help[] = |
| 731 "check_includes: [boolean] Controls whether a target's files are checked.\n" | 742 R"(check_includes: [boolean] Controls whether a target's files are checked. |
| 732 "\n" | 743 |
| 733 " When true (the default), the \"gn check\" command (as well as\n" | 744 When true (the default), the "gn check" command (as well as "gn gen" with the |
| 734 " \"gn gen\" with the --check flag) will check this target's sources\n" | 745 --check flag) will check this target's sources and headers for proper |
| 735 " and headers for proper dependencies.\n" | 746 dependencies. |
| 736 "\n" | 747 |
| 737 " When false, the files in this target will be skipped by default.\n" | 748 When false, the files in this target will be skipped by default. This does |
| 738 " This does not affect other targets that depend on the current target,\n" | 749 not affect other targets that depend on the current target, it just skips |
| 739 " it just skips checking the includes of the current target's files.\n" | 750 checking the includes of the current target's files. |
| 740 "\n" | 751 |
| 741 " If there are a few conditionally included headers that trip up\n" | 752 If there are a few conditionally included headers that trip up checking, you |
| 742 " checking, you can exclude headers individually by annotating them with\n" | 753 can exclude headers individually by annotating them with "nogncheck" (see "gn |
| 743 " \"nogncheck\" (see \"gn help nogncheck\").\n" | 754 help nogncheck"). |
| 744 "\n" | 755 |
| 745 " The topic \"gn help check\" has general information on how checking\n" | 756 The topic "gn help check" has general information on how checking works and |
| 746 " works and advice on how to pass a check in problematic cases.\n" | 757 advice on how to pass a check in problematic cases. |
| 747 "\n" | 758 |
| 748 "Example\n" | 759 Example |
| 749 "\n" | 760 |
| 750 " source_set(\"busted_includes\") {\n" | 761 source_set("busted_includes") { |
| 751 " # This target's includes are messed up, exclude it from checking.\n" | 762 # This target's includes are messed up, exclude it from checking. |
| 752 " check_includes = false\n" | 763 check_includes = false |
| 753 " ...\n" | 764 ... |
| 754 " }\n"; | 765 } |
| 766 )"; |
| 755 | 767 |
| 756 const char kCodeSigningArgs[] = "code_signing_args"; | 768 const char kCodeSigningArgs[] = "code_signing_args"; |
| 757 const char kCodeSigningArgs_HelpShort[] = | 769 const char kCodeSigningArgs_HelpShort[] = |
| 758 "code_signing_args: [string list] Arguments passed to code signing script."; | 770 "code_signing_args: [string list] Arguments passed to code signing script."; |
| 759 const char kCodeSigningArgs_Help[] = | 771 const char kCodeSigningArgs_Help[] = |
| 760 "code_signing_args: [string list] Arguments passed to code signing " | 772 R"(code_signing_args: [string list] Arguments passed to code signing script. |
| 761 "script.\n" | 773 |
| 762 "\n" | 774 For create_bundle targets, code_signing_args is the list of arguments to pass |
| 763 " For create_bundle targets, code_signing_args is the list of arguments\n" | 775 to the code signing script. Typically you would use source expansion (see "gn |
| 764 " to pass to the code signing script. Typically you would use source\n" | 776 help source_expansion") to insert the source file names. |
| 765 " expansion (see \"gn help source_expansion\") to insert the source file\n" | 777 |
| 766 " names.\n" | 778 See also "gn help create_bundle". |
| 767 "\n" | 779 )"; |
| 768 " See also \"gn help create_bundle\".\n"; | |
| 769 | 780 |
| 770 const char kCodeSigningScript[] = "code_signing_script"; | 781 const char kCodeSigningScript[] = "code_signing_script"; |
| 771 const char kCodeSigningScript_HelpShort[] = | 782 const char kCodeSigningScript_HelpShort[] = |
| 772 "code_signing_script: [file name] Script for code signing."; | 783 "code_signing_script: [file name] Script for code signing."; |
| 773 const char kCodeSigningScript_Help[] = | 784 const char kCodeSigningScript_Help[] = |
| 774 "code_signing_script: [file name] Script for code signing." | 785 R"(code_signing_script: [file name] Script for code signing." |
| 775 "\n" | 786 |
| 776 " An absolute or buildfile-relative file name of a Python script to run\n" | 787 An absolute or buildfile-relative file name of a Python script to run for a |
| 777 " for a create_bundle target to perform code signing step.\n" | 788 create_bundle target to perform code signing step. |
| 778 "\n" | 789 |
| 779 " See also \"gn help create_bundle\".\n"; | 790 See also "gn help create_bundle". |
| 791 )"; |
| 780 | 792 |
| 781 const char kCodeSigningSources[] = "code_signing_sources"; | 793 const char kCodeSigningSources[] = "code_signing_sources"; |
| 782 const char kCodeSigningSources_HelpShort[] = | 794 const char kCodeSigningSources_HelpShort[] = |
| 783 "code_signing_sources: [file list] Sources for code signing step."; | 795 "code_signing_sources: [file list] Sources for code signing step."; |
| 784 const char kCodeSigningSources_Help[] = | 796 const char kCodeSigningSources_Help[] = |
| 785 "code_signing_sources: [file list] Sources for code signing step.\n" | 797 R"(code_signing_sources: [file list] Sources for code signing step. |
| 786 "\n" | 798 |
| 787 " A list of files used as input for code signing script step of a\n" | 799 A list of files used as input for code signing script step of a create_bundle |
| 788 " create_bundle target. Non-absolute paths will be resolved relative to\n" | 800 target. Non-absolute paths will be resolved relative to the current build |
| 789 " the current build file.\n" | 801 file. |
| 790 "\n" | 802 |
| 791 " See also \"gn help create_bundle\".\n"; | 803 See also "gn help create_bundle". |
| 804 )"; |
| 792 | 805 |
| 793 const char kCodeSigningOutputs[] = "code_signing_outputs"; | 806 const char kCodeSigningOutputs[] = "code_signing_outputs"; |
| 794 const char kCodeSigningOutputs_HelpShort[] = | 807 const char kCodeSigningOutputs_HelpShort[] = |
| 795 "code_signing_outputs: [file list] Output files for code signing step."; | 808 "code_signing_outputs: [file list] Output files for code signing step."; |
| 796 const char kCodeSigningOutputs_Help[] = | 809 const char kCodeSigningOutputs_Help[] = |
| 797 "code_signing_outputs: [file list] Output files for code signing step.\n" | 810 R"(code_signing_outputs: [file list] Output files for code signing step. |
| 798 "\n" | 811 |
| 799 " Outputs from the code signing step of a create_bundle target. Must\n" | 812 Outputs from the code signing step of a create_bundle target. Must refer to |
| 800 " refer to files in the build directory.\n" | 813 files in the build directory. |
| 801 "\n" | 814 |
| 802 " See also \"gn help create_bundle\".\n"; | 815 See also "gn help create_bundle". |
| 816 )"; |
| 803 | 817 |
| 804 const char kCompleteStaticLib[] = "complete_static_lib"; | 818 const char kCompleteStaticLib[] = "complete_static_lib"; |
| 805 const char kCompleteStaticLib_HelpShort[] = | 819 const char kCompleteStaticLib_HelpShort[] = |
| 806 "complete_static_lib: [boolean] Links all deps into a static library."; | 820 "complete_static_lib: [boolean] Links all deps into a static library."; |
| 807 const char kCompleteStaticLib_Help[] = | 821 const char kCompleteStaticLib_Help[] = |
| 808 "complete_static_lib: [boolean] Links all deps into a static library.\n" | 822 R"(complete_static_lib: [boolean] Links all deps into a static library. |
| 809 "\n" | 823 |
| 810 " A static library normally doesn't include code from dependencies, but\n" | 824 A static library normally doesn't include code from dependencies, but instead |
| 811 " instead forwards the static libraries and source sets in its deps up\n" | 825 forwards the static libraries and source sets in its deps up the dependency |
| 812 " the dependency chain until a linkable target (an executable or shared\n" | 826 chain until a linkable target (an executable or shared library) is reached. |
| 813 " library) is reached. The final linkable target only links each static\n" | 827 The final linkable target only links each static library once, even if it |
| 814 " library once, even if it appears more than once in its dependency\n" | 828 appears more than once in its dependency graph. |
| 815 " graph.\n" | 829 |
| 816 "\n" | 830 In some cases the static library might be the final desired output. For |
| 817 " In some cases the static library might be the final desired output.\n" | 831 example, you may be producing a static library for distribution to third |
| 818 " For example, you may be producing a static library for distribution to\n" | 832 parties. In this case, the static library should include code for all |
| 819 " third parties. In this case, the static library should include code\n" | 833 dependencies in one complete package. However, complete static libraries |
| 820 " for all dependencies in one complete package. However, complete static\n" | 834 themselves are never linked into other complete static libraries. All |
| 821 " libraries themselves are never linked into other complete static\n" | 835 complete static libraries are for distribution and linking them in would |
| 822 " libraries. All complete static libraries are for distribution and\n" | 836 cause code duplication in this case. If the static library is not for |
| 823 " linking them in would cause code duplication in this case. If the\n" | 837 distribution, it should not be complete. |
| 824 " static library is not for distribution, it should not be complete.\n" | 838 |
| 825 "\n" | 839 GN treats non-complete static libraries as source sets when they are linked |
| 826 " GN treats non-complete static libraries as source sets when they are\n" | 840 into complete static libraries. This is done because some tools like AR do |
| 827 " linked into complete static libraries. This is done because some tools\n" | 841 not handle dependent static libraries properly. This makes it easier to write |
| 828 " like AR do not handle dependent static libraries properly. This makes\n" | 842 "alink" rules. |
| 829 " it easier to write \"alink\" rules.\n" | 843 |
| 830 "\n" | 844 In rare cases it makes sense to list a header in more than one target if it |
| 831 " In rare cases it makes sense to list a header in more than one\n" | 845 could be considered conceptually a member of both. libraries. |
| 832 " target if it could be considered conceptually a member of both.\n" | 846 |
| 833 " libraries.\n" | 847 Example |
| 834 "\n" | 848 |
| 835 "Example\n" | 849 static_library("foo") { |
| 836 "\n" | 850 complete_static_lib = true |
| 837 " static_library(\"foo\") {\n" | 851 deps = [ "bar" ] |
| 838 " complete_static_lib = true\n" | 852 } |
| 839 " deps = [ \"bar\" ]\n" | 853 )"; |
| 840 " }\n"; | |
| 841 | 854 |
| 842 const char kConfigs[] = "configs"; | 855 const char kConfigs[] = "configs"; |
| 843 const char kConfigs_HelpShort[] = | 856 const char kConfigs_HelpShort[] = |
| 844 "configs: [label list] Configs applying to this target or config."; | 857 "configs: [label list] Configs applying to this target or config."; |
| 845 const char kConfigs_Help[] = | 858 const char kConfigs_Help[] = |
| 846 "configs: Configs applying to this target or config.\n" | 859 R"(configs: Configs applying to this target or config. |
| 847 "\n" | 860 |
| 848 " A list of config labels.\n" | 861 A list of config labels. |
| 849 "\n" | 862 |
| 850 "Configs on a target\n" | 863 Configs on a target |
| 851 "\n" | 864 |
| 852 " When used on a target, the include_dirs, defines, etc. in each config\n" | 865 When used on a target, the include_dirs, defines, etc. in each config are |
| 853 " are appended in the order they appear to the compile command for each\n" | 866 appended in the order they appear to the compile command for each file in the |
| 854 " file in the target. They will appear after the include_dirs, defines,\n" | 867 target. They will appear after the include_dirs, defines, etc. that the |
| 855 " etc. that the target sets directly.\n" | 868 target sets directly. |
| 856 "\n" | 869 |
| 857 " Since configs apply after the values set on a target, directly setting\n" | 870 Since configs apply after the values set on a target, directly setting a |
| 858 " a compiler flag will prepend it to the command line. If you want to\n" | 871 compiler flag will prepend it to the command line. If you want to append a |
| 859 " append a flag instead, you can put that flag in a one-off config and\n" | 872 flag instead, you can put that flag in a one-off config and append that |
| 860 " append that config to the target's configs list.\n" | 873 config to the target's configs list. |
| 861 "\n" | 874 |
| 862 " The build configuration script will generally set up the default\n" | 875 The build configuration script will generally set up the default configs |
| 863 " configs applying to a given target type (see \"set_defaults\").\n" | 876 applying to a given target type (see "set_defaults"). When a target is being |
| 864 " When a target is being defined, it can add to or remove from this\n" | 877 defined, it can add to or remove from this list. |
| 865 " list.\n" | 878 |
| 866 "\n" | 879 Configs on a config |
| 867 "Configs on a config\n" | 880 |
| 868 "\n" | 881 It is possible to create composite configs by specifying configs on a config. |
| 869 " It is possible to create composite configs by specifying configs on a\n" | 882 One might do this to forward values, or to factor out blocks of settings from |
| 870 " config. One might do this to forward values, or to factor out blocks\n" | 883 very large configs into more manageable named chunks. |
| 871 " of settings from very large configs into more manageable named chunks.\n" | 884 |
| 872 "\n" | 885 In this case, the composite config is expanded to be the concatenation of its |
| 873 " In this case, the composite config is expanded to be the concatenation\n" | 886 own values, and in order, the values from its sub-configs *before* anything |
| 874 " of its own values, and in order, the values from its sub-configs\n" | 887 else happens. This has some ramifications: |
| 875 " *before* anything else happens. This has some ramifications:\n" | 888 |
| 876 "\n" | 889 - A target has no visibility into a config's sub-configs. Target code only |
| 877 " - A target has no visibility into a config's sub-configs. Target\n" | 890 sees the name of the composite config. It can't remove sub-configs or opt |
| 878 " code only sees the name of the composite config. It can't remove\n" | 891 in to only parts of it. The composite config may not even be defined |
| 879 " sub-configs or opt in to only parts of it. The composite config may\n" | 892 before the target is. |
| 880 " not even be defined before the target is.\n" | 893 |
| 881 "\n" | 894 - You can get duplication of values if a config is listed twice, say, on a |
| 882 " - You can get duplication of values if a config is listed twice, say,\n" | 895 target and in a sub-config that also applies. In other cases, the configs |
| 883 " on a target and in a sub-config that also applies. In other cases,\n" | 896 applying to a target are de-duped. It's expected that if a config is |
| 884 " the configs applying to a target are de-duped. It's expected that\n" | 897 listed as a sub-config that it is only used in that context. (Note that |
| 885 " if a config is listed as a sub-config that it is only used in that\n" | 898 it's possible to fix this and de-dupe, but it's not normally relevant and |
| 886 " context. (Note that it's possible to fix this and de-dupe, but it's\n" | 899 complicates the implementation.) |
| 887 " not normally relevant and complicates the implementation.)\n" | 900 )" |
| 888 COMMON_ORDERING_HELP | 901 COMMON_ORDERING_HELP |
| 889 "\n" | 902 R"( |
| 890 "Example\n" | 903 Example |
| 891 "\n" | 904 |
| 892 " # Configs on a target.\n" | 905 # Configs on a target. |
| 893 " source_set(\"foo\") {\n" | 906 source_set("foo") { |
| 894 " # Don't use the default RTTI config that BUILDCONFIG applied to us.\n" | 907 # Don't use the default RTTI config that BUILDCONFIG applied to us. |
| 895 " configs -= [ \"//build:no_rtti\" ]\n" | 908 configs -= [ "//build:no_rtti" ] |
| 896 "\n" | 909 |
| 897 " # Add some of our own settings.\n" | 910 # Add some of our own settings. |
| 898 " configs += [ \":mysettings\" ]\n" | 911 configs += [ ":mysettings" ] |
| 899 " }\n" | 912 } |
| 900 "\n" | 913 |
| 901 " # Create a default_optimization config that forwards to one of a set\n" | 914 # Create a default_optimization config that forwards to one of a set of more |
| 902 " # of more specialized configs depending on build flags. This pattern\n" | 915 # specialized configs depending on build flags. This pattern is useful |
| 903 " # is useful because it allows a target to opt in to either a default\n" | 916 # because it allows a target to opt in to either a default set, or a more |
| 904 " # set, or a more specific set, while avoid duplicating the settings in\n" | 917 # specific set, while avoid duplicating the settings in two places. |
| 905 " # two places.\n" | 918 config("super_optimization") { |
| 906 " config(\"super_optimization\") {\n" | 919 cflags = [ ... ] |
| 907 " cflags = [ ... ]\n" | 920 } |
| 908 " }\n" | 921 config("default_optimization") { |
| 909 " config(\"default_optimization\") {\n" | 922 if (optimize_everything) { |
| 910 " if (optimize_everything) {\n" | 923 configs = [ ":super_optimization" ] |
| 911 " configs = [ \":super_optimization\" ]\n" | 924 } else { |
| 912 " } else {\n" | 925 configs = [ ":no_optimization" ] |
| 913 " configs = [ \":no_optimization\" ]\n" | 926 } |
| 914 " }\n" | 927 } |
| 915 " }\n"; | 928 )"; |
| 916 | 929 |
| 917 const char kConsole[] = "console"; | 930 const char kConsole[] = "console"; |
| 918 const char kConsole_HelpShort[] = | 931 const char kConsole_HelpShort[] = |
| 919 "console: [boolean] Run this action in the console pool."; | 932 "console: [boolean] Run this action in the console pool."; |
| 920 const char kConsole_Help[] = | 933 const char kConsole_Help[] = |
| 921 "console: Run this action in the console pool.\n" | 934 R"(console: Run this action in the console pool. |
| 922 "\n" | 935 |
| 923 " Boolean. Defaults to false.\n" | 936 Boolean. Defaults to false. |
| 924 "\n" | 937 |
| 925 " Actions marked \"console = true\" will be run in the built-in ninja\n" | 938 Actions marked "console = true" will be run in the built-in ninja "console" |
| 926 " \"console\" pool. They will have access to real stdin and stdout, and\n" | 939 pool. They will have access to real stdin and stdout, and output will not be |
| 927 " output will not be buffered by ninja. This can be useful for\n" | 940 buffered by ninja. This can be useful for long-running actions with progress |
| 928 " long-running actions with progress logs, or actions that require user \n" | 941 logs, or actions that require user input. |
| 929 " input.\n" | 942 |
| 930 "\n" | 943 Only one console pool target can run at any one time in Ninja. Refer to the |
| 931 " Only one console pool target can run at any one time in Ninja. Refer\n" | 944 Ninja documentation on the console pool for more info. |
| 932 " to the Ninja documentation on the console pool for more info.\n" | 945 |
| 933 "\n" | 946 Example |
| 934 "Example\n" | 947 |
| 935 "\n" | 948 action("long_action_with_progress_logs") { |
| 936 " action(\"long_action_with_progress_logs\") {\n" | 949 console = true |
| 937 " console = true\n" | 950 } |
| 938 " }\n"; | 951 )"; |
| 939 | 952 |
| 940 const char kData[] = "data"; | 953 const char kData[] = "data"; |
| 941 const char kData_HelpShort[] = | 954 const char kData_HelpShort[] = |
| 942 "data: [file list] Runtime data file dependencies."; | 955 "data: [file list] Runtime data file dependencies."; |
| 943 const char kData_Help[] = | 956 const char kData_Help[] = |
| 944 "data: Runtime data file dependencies.\n" | 957 R"(data: Runtime data file dependencies. |
| 945 "\n" | 958 |
| 946 " Lists files or directories required to run the given target. These are\n" | 959 Lists files or directories required to run the given target. These are |
| 947 " typically data files or directories of data files. The paths are\n" | 960 typically data files or directories of data files. The paths are interpreted |
| 948 " interpreted as being relative to the current build file. Since these\n" | 961 as being relative to the current build file. Since these are runtime |
| 949 " are runtime dependencies, they do not affect which targets are built\n" | 962 dependencies, they do not affect which targets are built or when. To declare |
| 950 " or when. To declare input files to a script, use \"inputs\".\n" | 963 input files to a script, use "inputs". |
| 951 "\n" | 964 |
| 952 " Appearing in the \"data\" section does not imply any special handling\n" | 965 Appearing in the "data" section does not imply any special handling such as |
| 953 " such as copying them to the output directory. This is just used for\n" | 966 copying them to the output directory. This is just used for declaring runtime |
| 954 " declaring runtime dependencies. Runtime dependencies can be queried\n" | 967 dependencies. Runtime dependencies can be queried using the "runtime_deps" |
| 955 " using the \"runtime_deps\" category of \"gn desc\" or written during\n" | 968 category of "gn desc" or written during build generation via |
| 956 " build generation via \"--runtime-deps-list-file\".\n" | 969 "--runtime-deps-list-file". |
| 957 "\n" | 970 |
| 958 " GN doesn't require data files to exist at build-time. So actions that\n" | 971 GN doesn't require data files to exist at build-time. So actions that produce |
| 959 " produce files that are in turn runtime dependencies can list those\n" | 972 files that are in turn runtime dependencies can list those generated files |
| 960 " generated files both in the \"outputs\" list as well as the \"data\"\n" | 973 both in the "outputs" list as well as the "data" list. |
| 961 " list.\n" | 974 |
| 962 "\n" | 975 By convention, directories are listed with a trailing slash: |
| 963 " By convention, directories are listed with a trailing slash:\n" | 976 data = [ "test/data/" ] |
| 964 " data = [ \"test/data/\" ]\n" | 977 However, no verification is done on these so GN doesn't enforce this. The |
| 965 " However, no verification is done on these so GN doesn't enforce this.\n" | 978 paths are just rebased and passed along when requested. |
| 966 " The paths are just rebased and passed along when requested.\n" | 979 |
| 967 "\n" | 980 Note: On iOS and OS X, create_bundle targets will not be recursed into when |
| 968 " Note: On iOS and OS X, create_bundle targets will not be recursed\n" | 981 gathering data. See "gn help create_bundle" for details. |
| 969 " into when gathering data. See \"gn help create_bundle\" for details.\n" | 982 |
| 970 "\n" | 983 See "gn help runtime_deps" for how these are used. |
| 971 " See \"gn help runtime_deps\" for how these are used.\n"; | 984 )"; |
| 972 | 985 |
| 973 const char kDataDeps[] = "data_deps"; | 986 const char kDataDeps[] = "data_deps"; |
| 974 const char kDataDeps_HelpShort[] = | 987 const char kDataDeps_HelpShort[] = |
| 975 "data_deps: [label list] Non-linked dependencies."; | 988 "data_deps: [label list] Non-linked dependencies."; |
| 976 const char kDataDeps_Help[] = | 989 const char kDataDeps_Help[] = |
| 977 "data_deps: Non-linked dependencies.\n" | 990 R"(data_deps: Non-linked dependencies. |
| 978 "\n" | 991 |
| 979 " A list of target labels.\n" | 992 A list of target labels. |
| 980 "\n" | 993 |
| 981 " Specifies dependencies of a target that are not actually linked into\n" | 994 Specifies dependencies of a target that are not actually linked into the |
| 982 " the current target. Such dependencies will be built and will be\n" | 995 current target. Such dependencies will be built and will be available at |
| 983 " available at runtime.\n" | 996 runtime. |
| 984 "\n" | 997 |
| 985 " This is normally used for things like plugins or helper programs that\n" | 998 This is normally used for things like plugins or helper programs that a |
| 986 " a target needs at runtime.\n" | 999 target needs at runtime. |
| 987 "\n" | 1000 |
| 988 " Note: On iOS and OS X, create_bundle targets will not be recursed\n" | 1001 Note: On iOS and OS X, create_bundle targets will not be recursed into when |
| 989 " into when gathering data_deps. See \"gn help create_bundle\" for\n" | 1002 gathering data_deps. See "gn help create_bundle" for details. |
| 990 " details.\n" | 1003 |
| 991 "\n" | 1004 See also "gn help deps" and "gn help data". |
| 992 " See also \"gn help deps\" and \"gn help data\".\n" | 1005 |
| 993 "\n" | 1006 Example |
| 994 "Example\n" | 1007 |
| 995 "\n" | 1008 executable("foo") { |
| 996 " executable(\"foo\") {\n" | 1009 deps = [ "//base" ] |
| 997 " deps = [ \"//base\" ]\n" | 1010 data_deps = [ "//plugins:my_runtime_plugin" ] |
| 998 " data_deps = [ \"//plugins:my_runtime_plugin\" ]\n" | 1011 } |
| 999 " }\n"; | 1012 )"; |
| 1000 | 1013 |
| 1001 const char kDefines[] = "defines"; | 1014 const char kDefines[] = "defines"; |
| 1002 const char kDefines_HelpShort[] = | 1015 const char kDefines_HelpShort[] = |
| 1003 "defines: [string list] C preprocessor defines."; | 1016 "defines: [string list] C preprocessor defines."; |
| 1004 const char kDefines_Help[] = | 1017 const char kDefines_Help[] = |
| 1005 "defines: C preprocessor defines.\n" | 1018 R"(defines: C preprocessor defines. |
| 1006 "\n" | 1019 |
| 1007 " A list of strings\n" | 1020 A list of strings |
| 1008 "\n" | 1021 |
| 1009 " These strings will be passed to the C/C++ compiler as #defines. The\n" | 1022 These strings will be passed to the C/C++ compiler as #defines. The strings |
| 1010 " strings may or may not include an \"=\" to assign a value.\n" | 1023 may or may not include an "=" to assign a value. |
| 1024 )" |
| 1011 COMMON_ORDERING_HELP | 1025 COMMON_ORDERING_HELP |
| 1012 "\n" | 1026 R"( |
| 1013 "Example\n" | 1027 Example |
| 1014 "\n" | 1028 |
| 1015 " defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n"; | 1029 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ] |
| 1030 )"; |
| 1016 | 1031 |
| 1017 const char kDepfile[] = "depfile"; | 1032 const char kDepfile[] = "depfile"; |
| 1018 const char kDepfile_HelpShort[] = | 1033 const char kDepfile_HelpShort[] = |
| 1019 "depfile: [string] File name for input dependencies for actions."; | 1034 "depfile: [string] File name for input dependencies for actions."; |
| 1020 const char kDepfile_Help[] = | 1035 const char kDepfile_Help[] = |
| 1021 "depfile: [string] File name for input dependencies for actions.\n" | 1036 R"(depfile: [string] File name for input dependencies for actions. |
| 1022 "\n" | 1037 |
| 1023 " If nonempty, this string specifies that the current action or\n" | 1038 If nonempty, this string specifies that the current action or action_foreach |
| 1024 " action_foreach target will generate the given \".d\" file containing\n" | 1039 target will generate the given ".d" file containing the dependencies of the |
| 1025 " the dependencies of the input. Empty or unset means that the script\n" | 1040 input. Empty or unset means that the script doesn't generate the files. |
| 1026 " doesn't generate the files.\n" | 1041 |
| 1027 "\n" | 1042 A depfile should be used only when a target depends on files that are not |
| 1028 " A depfile should be used only when a target depends on files that are\n" | 1043 already specified by a target's inputs and sources. Likewise, depfiles should |
| 1029 " not already specified by a target's inputs and sources. Likewise,\n" | 1044 specify only those dependencies not already included in sources or inputs. |
| 1030 " depfiles should specify only those dependencies not already included\n" | 1045 |
| 1031 " in sources or inputs.\n" | 1046 The .d file should go in the target output directory. If you have more than |
| 1032 "\n" | 1047 one source file that the script is being run over, you can use the output |
| 1033 " The .d file should go in the target output directory. If you have more\n" | 1048 file expansions described in "gn help action_foreach" to name the .d file |
| 1034 " than one source file that the script is being run over, you can use\n" | 1049 according to the input." |
| 1035 " the output file expansions described in \"gn help action_foreach\" to\n" | 1050 |
| 1036 " name the .d file according to the input." | 1051 The format is that of a Makefile and all paths must be relative to the root |
| 1037 "\n" | 1052 build directory. Only one output may be listed and it must match the first |
| 1038 " The format is that of a Makefile and all paths must be relative to the\n" | 1053 output of the action. |
| 1039 " root build directory. Only one output may be listed and it must match\n" | 1054 |
| 1040 " the first output of the action.\n" | 1055 Although depfiles are created by an action, they should not be listed in the |
| 1041 "\n" | 1056 action's "outputs" unless another target will use the file as an input. |
| 1042 " Although depfiles are created by an action, they should not be listed\n" | 1057 |
| 1043 " in the action's \"outputs\" unless another target will use the file as\n" | 1058 Example |
| 1044 " an input.\n" | 1059 |
| 1045 "\n" | 1060 action_foreach("myscript_target") { |
| 1046 "Example\n" | 1061 script = "myscript.py" |
| 1047 "\n" | 1062 sources = [ ... ] |
| 1048 " action_foreach(\"myscript_target\") {\n" | 1063 |
| 1049 " script = \"myscript.py\"\n" | 1064 # Locate the depfile in the output directory named like the |
| 1050 " sources = [ ... ]\n" | 1065 # inputs but with a ".d" appended. |
| 1051 "\n" | 1066 depfile = "$relative_target_output_dir/{{source_name}}.d" |
| 1052 " # Locate the depfile in the output directory named like the\n" | 1067 |
| 1053 " # inputs but with a \".d\" appended.\n" | 1068 # Say our script uses "-o <d file>" to indicate the depfile. |
| 1054 " depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n" | 1069 args = [ "{{source}}", "-o", depfile ] |
| 1055 "\n" | 1070 } |
| 1056 " # Say our script uses \"-o <d file>\" to indicate the depfile.\n" | 1071 )"; |
| 1057 " args = [ \"{{source}}\", \"-o\", depfile ]\n" | |
| 1058 " }\n"; | |
| 1059 | 1072 |
| 1060 const char kDeps[] = "deps"; | 1073 const char kDeps[] = "deps"; |
| 1061 const char kDeps_HelpShort[] = | 1074 const char kDeps_HelpShort[] = |
| 1062 "deps: [label list] Private linked dependencies."; | 1075 "deps: [label list] Private linked dependencies."; |
| 1063 const char kDeps_Help[] = | 1076 const char kDeps_Help[] = |
| 1064 "deps: Private linked dependencies.\n" | 1077 R"(deps: Private linked dependencies. |
| 1065 "\n" | 1078 |
| 1066 " A list of target labels.\n" | 1079 A list of target labels. |
| 1067 "\n" | 1080 |
| 1068 " Specifies private dependencies of a target. Private dependencies are\n" | 1081 Specifies private dependencies of a target. Private dependencies are |
| 1069 " propagated up the dependency tree and linked to dependant targets, but\n" | 1082 propagated up the dependency tree and linked to dependant targets, but do not |
| 1070 " do not grant the ability to include headers from the dependency.\n" | 1083 grant the ability to include headers from the dependency. Public configs are |
| 1071 " Public configs are not forwarded.\n" | 1084 not forwarded. |
| 1072 "\n" | 1085 |
| 1073 "Details of dependency propagation\n" | 1086 Details of dependency propagation |
| 1074 "\n" | 1087 |
| 1075 " Source sets, shared libraries, and non-complete static libraries\n" | 1088 Source sets, shared libraries, and non-complete static libraries will be |
| 1076 " will be propagated up the dependency tree across groups, non-complete\n" | 1089 propagated up the dependency tree across groups, non-complete static |
| 1077 " static libraries and source sets.\n" | 1090 libraries and source sets. |
| 1078 "\n" | 1091 |
| 1079 " Executables, shared libraries, and complete static libraries will\n" | 1092 Executables, shared libraries, and complete static libraries will link all |
| 1080 " link all propagated targets and stop propagation. Actions and copy\n" | 1093 propagated targets and stop propagation. Actions and copy steps also stop |
| 1081 " steps also stop propagation, allowing them to take a library as an\n" | 1094 propagation, allowing them to take a library as an input but not force |
| 1082 " input but not force dependants to link to it.\n" | 1095 dependants to link to it. |
| 1083 "\n" | 1096 |
| 1084 " Propagation of all_dependent_configs and public_configs happens\n" | 1097 Propagation of all_dependent_configs and public_configs happens independently |
| 1085 " independently of target type. all_dependent_configs are always\n" | 1098 of target type. all_dependent_configs are always propagated across all types |
| 1086 " propagated across all types of targets, and public_configs\n" | 1099 of targets, and public_configs are always propagated across public deps of |
| 1087 " are always propagated across public deps of all types of targets.\n" | 1100 all types of targets. |
| 1088 "\n" | 1101 |
| 1089 " Data dependencies are propagated differently. See\n" | 1102 Data dependencies are propagated differently. See "gn help data_deps" and |
| 1090 " \"gn help data_deps\" and \"gn help runtime_deps\".\n" | 1103 "gn help runtime_deps". |
| 1091 "\n" | 1104 |
| 1092 " See also \"public_deps\".\n"; | 1105 See also "public_deps". |
| 1106 )"; |
| 1093 | 1107 |
| 1094 const char kIncludeDirs[] = "include_dirs"; | 1108 const char kIncludeDirs[] = "include_dirs"; |
| 1095 const char kIncludeDirs_HelpShort[] = | 1109 const char kIncludeDirs_HelpShort[] = |
| 1096 "include_dirs: [directory list] Additional include directories."; | 1110 "include_dirs: [directory list] Additional include directories."; |
| 1097 const char kIncludeDirs_Help[] = | 1111 const char kIncludeDirs_Help[] = |
| 1098 "include_dirs: Additional include directories.\n" | 1112 R"(include_dirs: Additional include directories. |
| 1099 "\n" | 1113 |
| 1100 " A list of source directories.\n" | 1114 A list of source directories. |
| 1101 "\n" | 1115 |
| 1102 " The directories in this list will be added to the include path for\n" | 1116 The directories in this list will be added to the include path for the files |
| 1103 " the files in the affected target.\n" | 1117 in the affected target. |
| 1118 )" |
| 1104 COMMON_ORDERING_HELP | 1119 COMMON_ORDERING_HELP |
| 1105 "\n" | 1120 R"( |
| 1106 "Example\n" | 1121 Example |
| 1107 "\n" | 1122 |
| 1108 " include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n"; | 1123 include_dirs = [ "src/include", "//third_party/foo" ] |
| 1124 )"; |
| 1109 | 1125 |
| 1110 const char kInputs[] = "inputs"; | 1126 const char kInputs[] = "inputs"; |
| 1111 const char kInputs_HelpShort[] = | 1127 const char kInputs_HelpShort[] = |
| 1112 "inputs: [file list] Additional compile-time dependencies."; | 1128 "inputs: [file list] Additional compile-time dependencies."; |
| 1113 const char kInputs_Help[] = | 1129 const char kInputs_Help[] = |
| 1114 "inputs: Additional compile-time dependencies.\n" | 1130 R"(inputs: Additional compile-time dependencies. |
| 1115 "\n" | 1131 |
| 1116 " Inputs are compile-time dependencies of the current target. This means\n" | 1132 Inputs are compile-time dependencies of the current target. This means that |
| 1117 " that all inputs must be available before compiling any of the sources\n" | 1133 all inputs must be available before compiling any of the sources or executing |
| 1118 " or executing any actions.\n" | 1134 any actions. |
| 1119 "\n" | 1135 |
| 1120 " Inputs are typically only used for action and action_foreach targets.\n" | 1136 Inputs are typically only used for action and action_foreach targets. |
| 1121 "\n" | 1137 |
| 1122 "Inputs for actions\n" | 1138 Inputs for actions |
| 1123 "\n" | 1139 |
| 1124 " For action and action_foreach targets, inputs should be the inputs to\n" | 1140 For action and action_foreach targets, inputs should be the inputs to script |
| 1125 " script that don't vary. These should be all .py files that the script\n" | 1141 that don't vary. These should be all .py files that the script uses via |
| 1126 " uses via imports (the main script itself will be an implicit dependency" | 1142 imports (the main script itself will be an implicit dependency of the action |
| 1127 "\n" | 1143 so need not be listed). |
| 1128 " of the action so need not be listed).\n" | 1144 |
| 1129 "\n" | 1145 For action targets, inputs and sources are treated the same, but from a style |
| 1130 " For action targets, inputs and sources are treated the same, but from\n" | 1146 perspective, it's recommended to follow the same rule as action_foreach and |
| 1131 " a style perspective, it's recommended to follow the same rule as\n" | 1147 put helper files in the inputs, and the data used by the script (if any) in |
| 1132 " action_foreach and put helper files in the inputs, and the data used\n" | 1148 sources. |
| 1133 " by the script (if any) in sources.\n" | 1149 |
| 1134 "\n" | 1150 Note that another way to declare input dependencies from an action is to have |
| 1135 " Note that another way to declare input dependencies from an action\n" | 1151 the action write a depfile (see "gn help depfile"). This allows the script to |
| 1136 " is to have the action write a depfile (see \"gn help depfile\"). This\n" | 1152 dynamically write input dependencies, that might not be known until actually |
| 1137 " allows the script to dynamically write input dependencies, that might\n" | 1153 executing the script. This is more efficient than doing processing while |
| 1138 " not be known until actually executing the script. This is more\n" | 1154 running GN to determine the inputs, and is easier to keep in-sync than |
| 1139 " efficient than doing processing while running GN to determine the\n" | 1155 hardcoding the list. |
| 1140 " inputs, and is easier to keep in-sync than hardcoding the list.\n" | 1156 |
| 1141 "\n" | 1157 Script input gotchas |
| 1142 "Script input gotchas\n" | 1158 |
| 1143 "\n" | 1159 It may be tempting to write a script that enumerates all files in a directory |
| 1144 " It may be tempting to write a script that enumerates all files in a\n" | 1160 as inputs. Don't do this! Even if you specify all the files in the inputs or |
| 1145 " directory as inputs. Don't do this! Even if you specify all the files\n" | 1161 sources in the GN target (or worse, enumerate the files in an exec_script |
| 1146 " in the inputs or sources in the GN target (or worse, enumerate the\n" | 1162 call when running GN, which will be slow), the dependencies will be broken. |
| 1147 " files in an exec_script call when running GN, which will be slow), the\n" | 1163 |
| 1148 " dependencies will be broken.\n" | 1164 The problem happens if a file is ever removed because the inputs are not |
| 1149 "\n" | 1165 listed on the command line to the script. Because the script hasn't changed |
| 1150 " The problem happens if a file is ever removed because the inputs are\n" | 1166 and all inputs are up to date, the script will not re-run and you will get a |
| 1151 " not listed on the command line to the script. Because the script\n" | 1167 stale build. Instead, either list all inputs on the command line to the |
| 1152 " hasn't changed and all inputs are up to date, the script will not\n" | 1168 script, or if there are many, create a separate list file that the script |
| 1153 " re-run and you will get a stale build. Instead, either list all\n" | 1169 reads. As long as this file is listed in the inputs, the build will detect |
| 1154 " inputs on the command line to the script, or if there are many, create\n" | 1170 when it has changed in any way and the action will re-run. |
| 1155 " a separate list file that the script reads. As long as this file is\n" | 1171 |
| 1156 " listed in the inputs, the build will detect when it has changed in any\n" | 1172 Inputs for binary targets |
| 1157 " way and the action will re-run.\n" | 1173 |
| 1158 "\n" | 1174 Any input dependencies will be resolved before compiling any sources. |
| 1159 "Inputs for binary targets\n" | 1175 Normally, all actions that a target depends on will be run before any files |
| 1160 "\n" | 1176 in a target are compiled. So if you depend on generated headers, you do not |
| 1161 " Any input dependencies will be resolved before compiling any sources.\n" | 1177 typically need to list them in the inputs section. |
| 1162 " Normally, all actions that a target depends on will be run before any\n" | 1178 |
| 1163 " files in a target are compiled. So if you depend on generated headers,\n" | 1179 Inputs for binary targets will be treated as implicit dependencies, meaning |
| 1164 " you do not typically need to list them in the inputs section.\n" | 1180 that changes in any of the inputs will force all sources in the target to be |
| 1165 "\n" | 1181 recompiled. If an input only applies to a subset of source files, you may |
| 1166 " Inputs for binary targets will be treated as implicit dependencies,\n" | 1182 want to split those into a separate target to avoid unnecessary recompiles. |
| 1167 " meaning that changes in any of the inputs will force all sources in\n" | 1183 |
| 1168 " the target to be recompiled. If an input only applies to a subset of\n" | 1184 Example |
| 1169 " source files, you may want to split those into a separate target to\n" | 1185 |
| 1170 " avoid unnecessary recompiles.\n" | 1186 action("myscript") { |
| 1171 "\n" | 1187 script = "domything.py" |
| 1172 "Example\n" | 1188 inputs = [ "input.data" ] |
| 1173 "\n" | 1189 } |
| 1174 " action(\"myscript\") {\n" | 1190 )"; |
| 1175 " script = \"domything.py\"\n" | |
| 1176 " inputs = [ \"input.data\" ]\n" | |
| 1177 " }\n"; | |
| 1178 | 1191 |
| 1179 const char kLdflags[] = "ldflags"; | 1192 const char kLdflags[] = "ldflags"; |
| 1180 const char kLdflags_HelpShort[] = | 1193 const char kLdflags_HelpShort[] = |
| 1181 "ldflags: [string list] Flags passed to the linker."; | 1194 "ldflags: [string list] Flags passed to the linker."; |
| 1182 const char kLdflags_Help[] = | 1195 const char kLdflags_Help[] = |
| 1183 "ldflags: Flags passed to the linker.\n" | 1196 R"(ldflags: Flags passed to the linker. |
| 1184 "\n" | 1197 |
| 1185 " A list of strings.\n" | 1198 A list of strings. |
| 1186 "\n" | 1199 |
| 1187 " These flags are passed on the command-line to the linker and generally\n" | 1200 These flags are passed on the command-line to the linker and generally |
| 1188 " specify various linking options. Most targets will not need these and\n" | 1201 specify various linking options. Most targets will not need these and will |
| 1189 " will use \"libs\" and \"lib_dirs\" instead.\n" | 1202 use "libs" and "lib_dirs" instead. |
| 1190 "\n" | 1203 |
| 1191 " ldflags are NOT pushed to dependents, so applying ldflags to source\n" | 1204 ldflags are NOT pushed to dependents, so applying ldflags to source sets or |
| 1192 " sets or static libraries will be a no-op. If you want to apply ldflags\n" | 1205 static libraries will be a no-op. If you want to apply ldflags to dependent |
| 1193 " to dependent targets, put them in a config and set it in the\n" | 1206 targets, put them in a config and set it in the all_dependent_configs or |
| 1194 " all_dependent_configs or public_configs.\n" | 1207 public_configs. |
| 1208 )" |
| 1195 COMMON_ORDERING_HELP; | 1209 COMMON_ORDERING_HELP; |
| 1196 | 1210 |
| 1197 #define COMMON_LIB_INHERITANCE_HELP \ | 1211 #define COMMON_LIB_INHERITANCE_HELP \ |
| 1198 "\n" \ | 1212 "\n" \ |
| 1199 " libs and lib_dirs work differently than other flags in two respects.\n" \ | 1213 " libs and lib_dirs work differently than other flags in two respects.\n" \ |
| 1200 " First, then are inherited across static library boundaries until a\n" \ | 1214 " First, then are inherited across static library boundaries until a\n" \ |
| 1201 " shared library or executable target is reached. Second, they are\n" \ | 1215 " shared library or executable target is reached. Second, they are\n" \ |
| 1202 " uniquified so each one is only passed once (the first instance of it\n" \ | 1216 " uniquified so each one is only passed once (the first instance of it\n" \ |
| 1203 " will be the one used).\n" | 1217 " will be the one used).\n" |
| 1204 | 1218 |
| 1205 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \ | 1219 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \ |
| 1206 "\n" \ | 1220 "\n" \ |
| 1207 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \ | 1221 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \ |
| 1208 " dependencies (as described above) are applied last assuming they\n" \ | 1222 " dependencies (as described above) are applied last assuming they\n" \ |
| 1209 " are not already in the list.\n" | 1223 " are not already in the list.\n" |
| 1210 | 1224 |
| 1211 const char kLibDirs[] = "lib_dirs"; | 1225 const char kLibDirs[] = "lib_dirs"; |
| 1212 const char kLibDirs_HelpShort[] = | 1226 const char kLibDirs_HelpShort[] = |
| 1213 "lib_dirs: [directory list] Additional library directories."; | 1227 "lib_dirs: [directory list] Additional library directories."; |
| 1214 const char kLibDirs_Help[] = | 1228 const char kLibDirs_Help[] = |
| 1215 "lib_dirs: Additional library directories.\n" | 1229 R"(lib_dirs: Additional library directories. |
| 1216 "\n" | 1230 |
| 1217 " A list of directories.\n" | 1231 A list of directories. |
| 1218 "\n" | 1232 |
| 1219 " Specifies additional directories passed to the linker for searching\n" | 1233 Specifies additional directories passed to the linker for searching for the |
| 1220 " for the required libraries. If an item is not an absolute path, it\n" | 1234 required libraries. If an item is not an absolute path, it will be treated as |
| 1221 " will be treated as being relative to the current build file.\n" | 1235 being relative to the current build file. |
| 1236 )" |
| 1222 COMMON_LIB_INHERITANCE_HELP | 1237 COMMON_LIB_INHERITANCE_HELP |
| 1223 COMMON_ORDERING_HELP | 1238 COMMON_ORDERING_HELP |
| 1224 LIBS_AND_LIB_DIRS_ORDERING_HELP | 1239 LIBS_AND_LIB_DIRS_ORDERING_HELP |
| 1225 "\n" | 1240 R"( |
| 1226 "Example\n" | 1241 Example |
| 1227 "\n" | 1242 |
| 1228 " lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n"; | 1243 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ] |
| 1244 )"; |
| 1229 | 1245 |
| 1230 const char kLibs[] = "libs"; | 1246 const char kLibs[] = "libs"; |
| 1231 const char kLibs_HelpShort[] = | 1247 const char kLibs_HelpShort[] = |
| 1232 "libs: [string list] Additional libraries to link."; | 1248 "libs: [string list] Additional libraries to link."; |
| 1233 const char kLibs_Help[] = | 1249 const char kLibs_Help[] = |
| 1234 "libs: Additional libraries to link.\n" | 1250 R"(libs: Additional libraries to link. |
| 1235 "\n" | 1251 |
| 1236 " A list of library names or library paths.\n" | 1252 A list of library names or library paths. |
| 1237 "\n" | 1253 |
| 1238 " These libraries will be linked into the final binary (executable or\n" | 1254 These libraries will be linked into the final binary (executable or shared |
| 1239 " shared library) containing the current target.\n" | 1255 library) containing the current target. |
| 1256 )" |
| 1240 COMMON_LIB_INHERITANCE_HELP | 1257 COMMON_LIB_INHERITANCE_HELP |
| 1241 "\n" | 1258 R"( |
| 1242 "Types of libs\n" | 1259 Types of libs |
| 1243 "\n" | 1260 |
| 1244 " There are several different things that can be expressed in libs:\n" | 1261 There are several different things that can be expressed in libs: |
| 1245 "\n" | 1262 |
| 1246 " File paths\n" | 1263 File paths |
| 1247 " Values containing '/' will be treated as references to files in\n" | 1264 Values containing '/' will be treated as references to files in the |
| 1248 " the checkout. They will be rebased to be relative to the build\n" | 1265 checkout. They will be rebased to be relative to the build directory and |
| 1249 " directory and specified in the \"libs\" for linker tools. This\n" | 1266 specified in the "libs" for linker tools. This facility should be used |
| 1250 " facility should be used for libraries that are checked in to the\n" | 1267 for libraries that are checked in to the version control. For libraries |
| 1251 " version control. For libraries that are generated by the build,\n" | 1268 that are generated by the build, use normal GN deps to link them. |
| 1252 " use normal GN deps to link them.\n" | 1269 |
| 1253 "\n" | 1270 System libraries |
| 1254 " System libraries\n" | 1271 Values not containing '/' will be treated as system library names. These |
| 1255 " Values not containing '/' will be treated as system library names.\n" | 1272 will be passed unmodified to the linker and prefixed with the |
| 1256 " These will be passed unmodified to the linker and prefixed with\n" | 1273 "lib_prefix" attribute of the linker tool. Generally you would set the |
| 1257 " the \"lib_prefix\" attribute of the linker tool. Generally you\n" | 1274 "lib_dirs" so the given library is found. Your BUILD.gn file should not |
| 1258 " would set the \"lib_dirs\" so the given library is found. Your\n" | 1275 specify the switch (like "-l"): this will be encoded in the "lib_prefix" |
| 1259 " BUILD.gn file should not specify the switch (like \"-l\"): this\n" | 1276 of the tool. |
| 1260 " will be encoded in the \"lib_prefix\" of the tool.\n" | 1277 |
| 1261 "\n" | 1278 Apple frameworks |
| 1262 " Apple frameworks\n" | 1279 System libraries ending in ".framework" will be special-cased: the switch |
| 1263 " System libraries ending in \".framework\" will be special-cased:\n" | 1280 "-framework" will be prepended instead of the lib_prefix, and the |
| 1264 " the switch \"-framework\" will be prepended instead of the\n" | 1281 ".framework" suffix will be trimmed. This is to support the way Mac links |
| 1265 " lib_prefix, and the \".framework\" suffix will be trimmed. This is\n" | 1282 framework dependencies. |
| 1266 " to support the way Mac links framework dependencies.\n" | 1283 )" |
| 1267 COMMON_ORDERING_HELP | 1284 COMMON_ORDERING_HELP |
| 1268 LIBS_AND_LIB_DIRS_ORDERING_HELP | 1285 LIBS_AND_LIB_DIRS_ORDERING_HELP |
| 1269 "\n" | 1286 R"( |
| 1270 "Examples\n" | 1287 Examples |
| 1271 "\n" | 1288 |
| 1272 " On Windows:\n" | 1289 On Windows: |
| 1273 " libs = [ \"ctl3d.lib\" ]\n" | 1290 libs = [ "ctl3d.lib" ] |
| 1274 "\n" | 1291 |
| 1275 " On Linux:\n" | 1292 On Linux: |
| 1276 " libs = [ \"ld\" ]\n"; | 1293 libs = [ "ld" ] |
| 1294 )"; |
| 1277 | 1295 |
| 1278 const char kOutputExtension[] = "output_extension"; | 1296 const char kOutputExtension[] = "output_extension"; |
| 1279 const char kOutputExtension_HelpShort[] = | 1297 const char kOutputExtension_HelpShort[] = |
| 1280 "output_extension: [string] Value to use for the output's file extension."; | 1298 "output_extension: [string] Value to use for the output's file extension."; |
| 1281 const char kOutputExtension_Help[] = | 1299 const char kOutputExtension_Help[] = |
| 1282 "output_extension: Value to use for the output's file extension.\n" | 1300 R"(output_extension: Value to use for the output's file extension. |
| 1283 "\n" | 1301 |
| 1284 " Normally the file extension for a target is based on the target\n" | 1302 Normally the file extension for a target is based on the target type and the |
| 1285 " type and the operating system, but in rare cases you will need to\n" | 1303 operating system, but in rare cases you will need to override the name (for |
| 1286 " override the name (for example to use \"libfreetype.so.6\" instead\n" | 1304 example to use "libfreetype.so.6" instead of libfreetype.so on Linux). |
| 1287 " of libfreetype.so on Linux).\n" | 1305 |
| 1288 "\n" | 1306 This value should not include a leading dot. If undefined, the default |
| 1289 " This value should not include a leading dot. If undefined, the default\n" | 1307 specified on the tool will be used. If set to the empty string, no output |
| 1290 " specified on the tool will be used. If set to the empty string, no\n" | 1308 extension will be used. |
| 1291 " output extension will be used.\n" | 1309 |
| 1292 "\n" | 1310 The output_extension will be used to set the "{{output_extension}}" expansion |
| 1293 " The output_extension will be used to set the \"{{output_extension}}\"\n" | 1311 which the linker tool will generally use to specify the output file name. See |
| 1294 " expansion which the linker tool will generally use to specify the\n" | 1312 "gn help tool". |
| 1295 " output file name. See \"gn help tool\".\n" | 1313 |
| 1296 "\n" | 1314 Example |
| 1297 "Example\n" | 1315 |
| 1298 "\n" | 1316 shared_library("freetype") { |
| 1299 " shared_library(\"freetype\") {\n" | 1317 if (is_linux) { |
| 1300 " if (is_linux) {\n" | 1318 # Call the output "libfreetype.so.6" |
| 1301 " # Call the output \"libfreetype.so.6\"\n" | 1319 output_extension = "so.6" |
| 1302 " output_extension = \"so.6\"\n" | 1320 } |
| 1303 " }\n" | 1321 ... |
| 1304 " ...\n" | 1322 } |
| 1305 " }\n" | 1323 |
| 1306 "\n" | 1324 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel |
| 1307 " # On Windows, generate a \"mysettings.cpl\" control panel applet.\n" | 1325 # applets are actually special shared libraries. |
| 1308 " # Control panel applets are actually special shared libraries.\n" | 1326 if (is_win) { |
| 1309 " if (is_win) {\n" | 1327 shared_library("mysettings") { |
| 1310 " shared_library(\"mysettings\") {\n" | 1328 output_extension = "cpl" |
| 1311 " output_extension = \"cpl\"\n" | 1329 ... |
| 1312 " ...\n" | 1330 } |
| 1313 " }\n" | 1331 } |
| 1314 " }\n"; | 1332 )"; |
| 1315 | 1333 |
| 1316 const char kOutputDir[] = "output_dir"; | 1334 const char kOutputDir[] = "output_dir"; |
| 1317 const char kOutputDir_HelpShort[] = | 1335 const char kOutputDir_HelpShort[] = |
| 1318 "output_dir: [directory] Directory to put output file in."; | 1336 "output_dir: [directory] Directory to put output file in."; |
| 1319 const char kOutputDir_Help[] = | 1337 const char kOutputDir_Help[] = |
| 1320 "output_dir: [directory] Directory to put output file in.\n" | 1338 R"(output_dir: [directory] Directory to put output file in. |
| 1321 "\n" | 1339 |
| 1322 " For library and executable targets, overrides the directory for the\n" | 1340 For library and executable targets, overrides the directory for the final |
| 1323 " final output. This must be in the root_build_dir or a child thereof.\n" | 1341 output. This must be in the root_build_dir or a child thereof. |
| 1324 "\n" | 1342 |
| 1325 " This should generally be in the root_out_dir or a subdirectory thereof\n" | 1343 This should generally be in the root_out_dir or a subdirectory thereof (the |
| 1326 " (the root_out_dir will be the same as the root_build_dir for the\n" | 1344 root_out_dir will be the same as the root_build_dir for the default |
| 1327 " default toolchain, and will be a subdirectory for other toolchains).\n" | 1345 toolchain, and will be a subdirectory for other toolchains). Not putting the |
| 1328 " Not putting the output in a subdirectory of root_out_dir can result\n" | 1346 output in a subdirectory of root_out_dir can result in collisions between |
| 1329 " in collisions between different toolchains, so you will need to take\n" | 1347 different toolchains, so you will need to take steps to ensure that your |
| 1330 " steps to ensure that your target is only present in one toolchain.\n" | 1348 target is only present in one toolchain. |
| 1331 "\n" | 1349 |
| 1332 " Normally the toolchain specifies the output directory for libraries\n" | 1350 Normally the toolchain specifies the output directory for libraries and |
| 1333 " and executables (see \"gn help tool\"). You will have to consult that\n" | 1351 executables (see "gn help tool"). You will have to consult that for the |
| 1334 " for the default location. The default location will be used if\n" | 1352 default location. The default location will be used if output_dir is |
| 1335 " output_dir is undefined or empty.\n" | 1353 undefined or empty. |
| 1336 "\n" | 1354 |
| 1337 "Example\n" | 1355 Example |
| 1338 "\n" | 1356 |
| 1339 " shared_library(\"doom_melon\") {\n" | 1357 shared_library("doom_melon") { |
| 1340 " output_dir = \"$root_out_dir/plugin_libs\"\n" | 1358 output_dir = "$root_out_dir/plugin_libs" |
| 1341 " ...\n" | 1359 ... |
| 1342 " }\n"; | 1360 } |
| 1361 )"; |
| 1343 | 1362 |
| 1344 const char kOutputName[] = "output_name"; | 1363 const char kOutputName[] = "output_name"; |
| 1345 const char kOutputName_HelpShort[] = | 1364 const char kOutputName_HelpShort[] = |
| 1346 "output_name: [string] Name for the output file other than the default."; | 1365 "output_name: [string] Name for the output file other than the default."; |
| 1347 const char kOutputName_Help[] = | 1366 const char kOutputName_Help[] = |
| 1348 "output_name: Define a name for the output file other than the default.\n" | 1367 R"(output_name: Define a name for the output file other than the default. |
| 1349 "\n" | 1368 |
| 1350 " Normally the output name of a target will be based on the target name,\n" | 1369 Normally the output name of a target will be based on the target name, so the |
| 1351 " so the target \"//foo/bar:bar_unittests\" will generate an output\n" | 1370 target "//foo/bar:bar_unittests" will generate an output file such as |
| 1352 " file such as \"bar_unittests.exe\" (using Windows as an example).\n" | 1371 "bar_unittests.exe" (using Windows as an example). |
| 1353 "\n" | 1372 |
| 1354 " Sometimes you will want an alternate name to avoid collisions or\n" | 1373 Sometimes you will want an alternate name to avoid collisions or if the |
| 1355 " if the internal name isn't appropriate for public distribution.\n" | 1374 internal name isn't appropriate for public distribution. |
| 1356 "\n" | 1375 |
| 1357 " The output name should have no extension or prefixes, these will be\n" | 1376 The output name should have no extension or prefixes, these will be added |
| 1358 " added using the default system rules. For example, on Linux an output\n" | 1377 using the default system rules. For example, on Linux an output name of "foo" |
| 1359 " name of \"foo\" will produce a shared library \"libfoo.so\". There\n" | 1378 will produce a shared library "libfoo.so". There is no way to override the |
| 1360 " is no way to override the output prefix of a linker tool on a per-\n" | 1379 output prefix of a linker tool on a per- target basis. If you need more |
| 1361 " target basis. If you need more flexibility, create a copy target\n" | 1380 flexibility, create a copy target to produce the file you want. |
| 1362 " to produce the file you want.\n" | 1381 |
| 1363 "\n" | 1382 This variable is valid for all binary output target types. |
| 1364 " This variable is valid for all binary output target types.\n" | 1383 |
| 1365 "\n" | 1384 Example |
| 1366 "Example\n" | 1385 |
| 1367 "\n" | 1386 static_library("doom_melon") { |
| 1368 " static_library(\"doom_melon\") {\n" | 1387 output_name = "fluffy_bunny" |
| 1369 " output_name = \"fluffy_bunny\"\n" | 1388 } |
| 1370 " }\n"; | 1389 )"; |
| 1371 | 1390 |
| 1372 const char kOutputPrefixOverride[] = "output_prefix_override"; | 1391 const char kOutputPrefixOverride[] = "output_prefix_override"; |
| 1373 const char kOutputPrefixOverride_HelpShort[] = | 1392 const char kOutputPrefixOverride_HelpShort[] = |
| 1374 "output_prefix_override: [boolean] Don't use prefix for output name."; | 1393 "output_prefix_override: [boolean] Don't use prefix for output name."; |
| 1375 const char kOutputPrefixOverride_Help[] = | 1394 const char kOutputPrefixOverride_Help[] = |
| 1376 "output_prefix_override: Don't use prefix for output name.\n" | 1395 R"(output_prefix_override: Don't use prefix for output name. |
| 1377 "\n" | 1396 |
| 1378 " A boolean that overrides the output prefix for a target. Defaults to\n" | 1397 A boolean that overrides the output prefix for a target. Defaults to false. |
| 1379 " false.\n" | 1398 |
| 1380 "\n" | 1399 Some systems use prefixes for the names of the final target output file. The |
| 1381 " Some systems use prefixes for the names of the final target output\n" | 1400 normal example is "libfoo.so" on Linux for a target named "foo". |
| 1382 " file. The normal example is \"libfoo.so\" on Linux for a target\n" | 1401 |
| 1383 " named \"foo\".\n" | 1402 The output prefix for a given target type is specified on the linker tool |
| 1384 "\n" | 1403 (see "gn help tool"). Sometimes this prefix is undesired. |
| 1385 " The output prefix for a given target type is specified on the linker\n" | 1404 |
| 1386 " tool (see \"gn help tool\"). Sometimes this prefix is undesired.\n" | 1405 See also "gn help output_extension". |
| 1387 "\n" | 1406 |
| 1388 " See also \"gn help output_extension\".\n" | 1407 Example |
| 1389 "\n" | 1408 |
| 1390 "Example\n" | 1409 shared_library("doom_melon") { |
| 1391 "\n" | 1410 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag |
| 1392 " shared_library(\"doom_melon\") {\n" | 1411 # will produce "doom_melon.so". |
| 1393 " # Normally this will produce \"libdoom_melon.so\" on Linux, setting\n" | 1412 output_prefix_override = true |
| 1394 " # Setting this flag will produce \"doom_melon.so\".\n" | 1413 ... |
| 1395 " output_prefix_override = true\n" | 1414 } |
| 1396 " ...\n" | 1415 )"; |
| 1397 " }\n"; | |
| 1398 | 1416 |
| 1399 const char kOutputs[] = "outputs"; | 1417 const char kOutputs[] = "outputs"; |
| 1400 const char kOutputs_HelpShort[] = | 1418 const char kOutputs_HelpShort[] = |
| 1401 "outputs: [file list] Output files for actions and copy targets."; | 1419 "outputs: [file list] Output files for actions and copy targets."; |
| 1402 const char kOutputs_Help[] = | 1420 const char kOutputs_Help[] = |
| 1403 "outputs: Output files for actions and copy targets.\n" | 1421 R"(outputs: Output files for actions and copy targets. |
| 1404 "\n" | 1422 |
| 1405 " Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n" | 1423 Outputs is valid for "copy", "action", and "action_foreach" target types and |
| 1406 " target types and indicates the resulting files. Outputs must always\n" | 1424 indicates the resulting files. Outputs must always refer to files in the |
| 1407 " refer to files in the build directory.\n" | 1425 build directory. |
| 1408 "\n" | 1426 |
| 1409 " copy\n" | 1427 copy |
| 1410 " Copy targets should have exactly one entry in the outputs list. If\n" | 1428 Copy targets should have exactly one entry in the outputs list. If there is |
| 1411 " there is exactly one source, this can be a literal file name or a\n" | 1429 exactly one source, this can be a literal file name or a source expansion. |
| 1412 " source expansion. If there is more than one source, this must\n" | 1430 If there is more than one source, this must contain a source expansion to |
| 1413 " contain a source expansion to map a single input name to a single\n" | 1431 map a single input name to a single output name. See "gn help copy". |
| 1414 " output name. See \"gn help copy\".\n" | 1432 |
| 1415 "\n" | 1433 action_foreach |
| 1416 " action_foreach\n" | 1434 Action_foreach targets must always use source expansions to map input files |
| 1417 " Action_foreach targets must always use source expansions to map\n" | 1435 to output files. There can be more than one output, which means that each |
| 1418 " input files to output files. There can be more than one output,\n" | 1436 invocation of the script will produce a set of files (presumably based on |
| 1419 " which means that each invocation of the script will produce a set of\n" | 1437 the name of the input file). See "gn help action_foreach". |
| 1420 " files (presumably based on the name of the input file). See\n" | 1438 |
| 1421 " \"gn help action_foreach\".\n" | 1439 action |
| 1422 "\n" | 1440 Action targets (excluding action_foreach) must list literal output file(s) |
| 1423 " action\n" | 1441 with no source expansions. See "gn help action". |
| 1424 " Action targets (excluding action_foreach) must list literal output\n" | 1442 )"; |
| 1425 " file(s) with no source expansions. See \"gn help action\".\n"; | |
| 1426 | 1443 |
| 1427 const char kPrecompiledHeader[] = "precompiled_header"; | 1444 const char kPrecompiledHeader[] = "precompiled_header"; |
| 1428 const char kPrecompiledHeader_HelpShort[] = | 1445 const char kPrecompiledHeader_HelpShort[] = |
| 1429 "precompiled_header: [string] Header file to precompile."; | 1446 "precompiled_header: [string] Header file to precompile."; |
| 1430 const char kPrecompiledHeader_Help[] = | 1447 const char kPrecompiledHeader_Help[] = |
| 1431 "precompiled_header: [string] Header file to precompile.\n" | 1448 R"(precompiled_header: [string] Header file to precompile. |
| 1432 "\n" | 1449 |
| 1433 " Precompiled headers will be used when a target specifies this\n" | 1450 Precompiled headers will be used when a target specifies this value, or a |
| 1434 " value, or a config applying to this target specifies this value.\n" | 1451 config applying to this target specifies this value. In addition, the tool |
| 1435 " In addition, the tool corresponding to the source files must also\n" | 1452 corresponding to the source files must also specify precompiled headers (see |
| 1436 " specify precompiled headers (see \"gn help tool\"). The tool\n" | 1453 "gn help tool"). The tool will also specify what type of precompiled headers |
| 1437 " will also specify what type of precompiled headers to use.\n" | 1454 to use. |
| 1438 "\n" | 1455 |
| 1439 " The precompiled header/source variables can be specified on a target\n" | 1456 The precompiled header/source variables can be specified on a target or a |
| 1440 " or a config, but must be the same for all configs applying to a given\n" | 1457 config, but must be the same for all configs applying to a given target since |
| 1441 " target since a target can only have one precompiled header.\n" | 1458 a target can only have one precompiled header. |
| 1442 "\n" | 1459 |
| 1443 "MSVC precompiled headers\n" | 1460 MSVC precompiled headers |
| 1444 "\n" | 1461 |
| 1445 " When using MSVC-style precompiled headers, the \"precompiled_header\"\n" | 1462 When using MSVC-style precompiled headers, the "precompiled_header" value is |
| 1446 " value is a string corresponding to the header. This is NOT a path\n" | 1463 a string corresponding to the header. This is NOT a path to a file that GN |
| 1447 " to a file that GN recognises, but rather the exact string that appears\n" | 1464 recognises, but rather the exact string that appears in quotes after an |
| 1448 " in quotes after an #include line in source code. The compiler will\n" | 1465 #include line in source code. The compiler will match this string against |
| 1449 " match this string against includes or forced includes (/FI).\n" | 1466 includes or forced includes (/FI). |
| 1450 "\n" | 1467 |
| 1451 " MSVC also requires a source file to compile the header with. This must\n" | 1468 MSVC also requires a source file to compile the header with. This must be |
| 1452 " be specified by the \"precompiled_source\" value. In contrast to the\n" | 1469 specified by the "precompiled_source" value. In contrast to the header value, |
| 1453 " header value, this IS a GN-style file name, and tells GN which source\n" | 1470 this IS a GN-style file name, and tells GN which source file to compile to |
| 1454 " file to compile to make the .pch file used for subsequent compiles.\n" | 1471 make the .pch file used for subsequent compiles. |
| 1455 "\n" | 1472 |
| 1456 " If you use both C and C++ sources, the precompiled header and source\n" | 1473 If you use both C and C++ sources, the precompiled header and source file |
| 1457 " file will be compiled using both tools. You will want to make sure\n" | 1474 will be compiled using both tools. You will want to make sure to wrap C++ |
| 1458 " to wrap C++ includes in __cplusplus #ifdefs so the file will compile\n" | 1475 includes in __cplusplus #ifdefs so the file will compile in C mode. |
| 1459 " in C mode.\n" | 1476 |
| 1460 "\n" | 1477 For example, if the toolchain specifies MSVC headers: |
| 1461 " For example, if the toolchain specifies MSVC headers:\n" | 1478 |
| 1462 "\n" | 1479 toolchain("vc_x64") { |
| 1463 " toolchain(\"vc_x64\") {\n" | 1480 ... |
| 1464 " ...\n" | 1481 tool("cxx") { |
| 1465 " tool(\"cxx\") {\n" | 1482 precompiled_header_type = "msvc" |
| 1466 " precompiled_header_type = \"msvc\"\n" | 1483 ... |
| 1467 " ...\n" | 1484 |
| 1468 "\n" | 1485 You might make a config like this: |
| 1469 " You might make a config like this:\n" | 1486 |
| 1470 "\n" | 1487 config("use_precompiled_headers") { |
| 1471 " config(\"use_precompiled_headers\") {\n" | 1488 precompiled_header = "build/precompile.h" |
| 1472 " precompiled_header = \"build/precompile.h\"\n" | 1489 precompiled_source = "//build/precompile.cc" |
| 1473 " precompiled_source = \"//build/precompile.cc\"\n" | 1490 |
| 1474 "\n" | 1491 # Either your source files should #include "build/precompile.h" |
| 1475 " # Either your source files should #include \"build/precompile.h\"\n" | 1492 # first, or you can do this to force-include the header. |
| 1476 " # first, or you can do this to force-include the header.\n" | 1493 cflags = [ "/FI$precompiled_header" ] |
| 1477 " cflags = [ \"/FI$precompiled_header\" ]\n" | 1494 } |
| 1478 " }\n" | 1495 |
| 1479 "\n" | 1496 And then define a target that uses the config: |
| 1480 " And then define a target that uses the config:\n" | 1497 |
| 1481 "\n" | 1498 executable("doom_melon") { |
| 1482 " executable(\"doom_melon\") {\n" | 1499 configs += [ ":use_precompiled_headers" ] |
| 1483 " configs += [ \":use_precompiled_headers\" ]\n" | 1500 ... |
| 1484 " ...\n" | 1501 )"; |
| 1485 "\n"; | |
| 1486 | 1502 |
| 1487 const char kPrecompiledSource[] = "precompiled_source"; | 1503 const char kPrecompiledSource[] = "precompiled_source"; |
| 1488 const char kPrecompiledSource_HelpShort[] = | 1504 const char kPrecompiledSource_HelpShort[] = |
| 1489 "precompiled_source: [file name] Source file to precompile."; | 1505 "precompiled_source: [file name] Source file to precompile."; |
| 1490 const char kPrecompiledSource_Help[] = | 1506 const char kPrecompiledSource_Help[] = |
| 1491 "precompiled_source: [file name] Source file to precompile.\n" | 1507 R"(precompiled_source: [file name] Source file to precompile. |
| 1492 "\n" | 1508 |
| 1493 " The source file that goes along with the precompiled_header when\n" | 1509 The source file that goes along with the precompiled_header when using |
| 1494 " using \"msvc\"-style precompiled headers. It will be implicitly added\n" | 1510 "msvc"-style precompiled headers. It will be implicitly added to the sources |
| 1495 " to the sources of the target. See \"gn help precompiled_header\".\n"; | 1511 of the target. See "gn help precompiled_header". |
| 1512 )"; |
| 1496 | 1513 |
| 1497 const char kProductType[] = "product_type"; | 1514 const char kProductType[] = "product_type"; |
| 1498 const char kProductType_HelpShort[] = | 1515 const char kProductType_HelpShort[] = |
| 1499 "product_type: [string] Product type for Xcode projects."; | 1516 "product_type: [string] Product type for Xcode projects."; |
| 1500 const char kProductType_Help[] = | 1517 const char kProductType_Help[] = |
| 1501 "product_type: Product type for Xcode projects.\n" | 1518 R"(product_type: Product type for Xcode projects. |
| 1502 "\n" | 1519 |
| 1503 " Correspond to the type of the product of a create_bundle target. Only\n" | 1520 Correspond to the type of the product of a create_bundle target. Only |
| 1504 " meaningful to Xcode (used as part of the Xcode project generation).\n" | 1521 meaningful to Xcode (used as part of the Xcode project generation). |
| 1505 "\n" | 1522 |
| 1506 " When generating Xcode project files, only create_bundle target with\n" | 1523 When generating Xcode project files, only create_bundle target with a |
| 1507 " a non-empty product_type will have a corresponding target in Xcode\n" | 1524 non-empty product_type will have a corresponding target in Xcode project. |
| 1508 " project.\n"; | 1525 )"; |
| 1509 | 1526 |
| 1510 const char kPublic[] = "public"; | 1527 const char kPublic[] = "public"; |
| 1511 const char kPublic_HelpShort[] = | 1528 const char kPublic_HelpShort[] = |
| 1512 "public: [file list] Declare public header files for a target."; | 1529 "public: [file list] Declare public header files for a target."; |
| 1513 const char kPublic_Help[] = | 1530 const char kPublic_Help[] = |
| 1514 "public: Declare public header files for a target.\n" | 1531 R"(public: Declare public header files for a target. |
| 1515 "\n" | 1532 |
| 1516 " A list of files that other targets can include. These permissions are\n" | 1533 A list of files that other targets can include. These permissions are checked |
| 1517 " checked via the \"check\" command (see \"gn help check\").\n" | 1534 via the "check" command (see "gn help check"). |
| 1518 "\n" | 1535 |
| 1519 " If no public files are declared, other targets (assuming they have\n" | 1536 If no public files are declared, other targets (assuming they have visibility |
| 1520 " visibility to depend on this target can include any file in the\n" | 1537 to depend on this target can include any file in the sources list. If this |
| 1521 " sources list. If this variable is defined on a target, dependent\n" | 1538 variable is defined on a target, dependent targets may only include files on |
| 1522 " targets may only include files on this whitelist.\n" | 1539 this whitelist. |
| 1523 "\n" | 1540 |
| 1524 " Header file permissions are also subject to visibility. A target\n" | 1541 Header file permissions are also subject to visibility. A target must be |
| 1525 " must be visible to another target to include any files from it at all\n" | 1542 visible to another target to include any files from it at all and the public |
| 1526 " and the public headers indicate which subset of those files are\n" | 1543 headers indicate which subset of those files are permitted. See "gn help |
| 1527 " permitted. See \"gn help visibility\" for more.\n" | 1544 visibility" for more. |
| 1528 "\n" | 1545 |
| 1529 " Public files are inherited through the dependency tree. So if there is\n" | 1546 Public files are inherited through the dependency tree. So if there is a |
| 1530 " a dependency A -> B -> C, then A can include C's public headers.\n" | 1547 dependency A -> B -> C, then A can include C's public headers. However, the |
| 1531 " However, the same is NOT true of visibility, so unless A is in C's\n" | 1548 same is NOT true of visibility, so unless A is in C's visibility list, the |
| 1532 " visibility list, the include will be rejected.\n" | 1549 include will be rejected. |
| 1533 "\n" | 1550 |
| 1534 " GN only knows about files declared in the \"sources\" and \"public\"\n" | 1551 GN only knows about files declared in the "sources" and "public" sections of |
| 1535 " sections of targets. If a file is included that is not known to the\n" | 1552 targets. If a file is included that is not known to the build, it will be |
| 1536 " build, it will be allowed.\n" | 1553 allowed. |
| 1537 "\n" | 1554 |
| 1538 "Examples\n" | 1555 Examples |
| 1539 "\n" | 1556 |
| 1540 " These exact files are public:\n" | 1557 These exact files are public: |
| 1541 " public = [ \"foo.h\", \"bar.h\" ]\n" | 1558 public = [ "foo.h", "bar.h" ] |
| 1542 "\n" | 1559 |
| 1543 " No files are public (no targets may include headers from this one):\n" | 1560 No files are public (no targets may include headers from this one): |
| 1544 " public = []\n"; | 1561 public = [] |
| 1562 )"; |
| 1545 | 1563 |
| 1546 const char kPublicConfigs[] = "public_configs"; | 1564 const char kPublicConfigs[] = "public_configs"; |
| 1547 const char kPublicConfigs_HelpShort[] = | 1565 const char kPublicConfigs_HelpShort[] = |
| 1548 "public_configs: [label list] Configs applied to dependents."; | 1566 "public_configs: [label list] Configs applied to dependents."; |
| 1549 const char kPublicConfigs_Help[] = | 1567 const char kPublicConfigs_Help[] = |
| 1550 "public_configs: Configs to be applied on dependents.\n" | 1568 R"(public_configs: Configs to be applied on dependents. |
| 1551 "\n" | 1569 |
| 1552 " A list of config labels.\n" | 1570 A list of config labels. |
| 1553 "\n" | 1571 |
| 1554 " Targets directly depending on this one will have the configs listed in\n" | 1572 Targets directly depending on this one will have the configs listed in this |
| 1555 " this variable added to them. These configs will also apply to the\n" | 1573 variable added to them. These configs will also apply to the current target. |
| 1556 " current target.\n" | 1574 |
| 1557 "\n" | 1575 This addition happens in a second phase once a target and all of its |
| 1558 " This addition happens in a second phase once a target and all of its\n" | 1576 dependencies have been resolved. Therefore, a target will not see these |
| 1559 " dependencies have been resolved. Therefore, a target will not see\n" | 1577 force-added configs in their "configs" variable while the script is running, |
| 1560 " these force-added configs in their \"configs\" variable while the\n" | 1578 and then can not be removed. As a result, this capability should generally |
| 1561 " script is running, and then can not be removed. As a result, this\n" | 1579 only be used to add defines and include directories necessary to compile a |
| 1562 " capability should generally only be used to add defines and include\n" | 1580 target's headers. |
| 1563 " directories necessary to compile a target's headers.\n" | 1581 |
| 1564 "\n" | 1582 See also "all_dependent_configs". |
| 1565 " See also \"all_dependent_configs\".\n" | 1583 )" |
| 1566 COMMON_ORDERING_HELP; | 1584 COMMON_ORDERING_HELP; |
| 1567 | 1585 |
| 1568 const char kPublicDeps[] = "public_deps"; | 1586 const char kPublicDeps[] = "public_deps"; |
| 1569 const char kPublicDeps_HelpShort[] = | 1587 const char kPublicDeps_HelpShort[] = |
| 1570 "public_deps: [label list] Declare public dependencies."; | 1588 "public_deps: [label list] Declare public dependencies."; |
| 1571 const char kPublicDeps_Help[] = | 1589 const char kPublicDeps_Help[] = |
| 1572 "public_deps: Declare public dependencies.\n" | 1590 R"(public_deps: Declare public dependencies. |
| 1573 "\n" | 1591 |
| 1574 " Public dependencies are like private dependencies (see\n" | 1592 Public dependencies are like private dependencies (see "gn help deps") but |
| 1575 " \"gn help deps\") but additionally express that the current target\n" | 1593 additionally express that the current target exposes the listed deps as part |
| 1576 " exposes the listed deps as part of its public API.\n" | 1594 of its public API. |
| 1577 "\n" | 1595 |
| 1578 " This has several ramifications:\n" | 1596 This has several ramifications: |
| 1579 "\n" | 1597 |
| 1580 " - public_configs that are part of the dependency are forwarded\n" | 1598 - public_configs that are part of the dependency are forwarded to direct |
| 1581 " to direct dependents.\n" | 1599 dependents. |
| 1582 "\n" | 1600 |
| 1583 " - Public headers in the dependency are usable by dependents\n" | 1601 - Public headers in the dependency are usable by dependents (includes do |
| 1584 " (includes do not require a direct dependency or visibility).\n" | 1602 not require a direct dependency or visibility). |
| 1585 "\n" | 1603 |
| 1586 " - If the current target is a shared library, other shared libraries\n" | 1604 - If the current target is a shared library, other shared libraries that it |
| 1587 " that it publicly depends on (directly or indirectly) are\n" | 1605 publicly depends on (directly or indirectly) are propagated up the |
| 1588 " propagated up the dependency tree to dependents for linking.\n" | 1606 dependency tree to dependents for linking. |
| 1589 "\n" | 1607 |
| 1590 "Discussion\n" | 1608 Discussion |
| 1591 "\n" | 1609 |
| 1592 " Say you have three targets: A -> B -> C. C's visibility may allow\n" | 1610 Say you have three targets: A -> B -> C. C's visibility may allow B to depend |
| 1593 " B to depend on it but not A. Normally, this would prevent A from\n" | 1611 on it but not A. Normally, this would prevent A from including any headers |
| 1594 " including any headers from C, and C's public_configs would apply\n" | 1612 from C, and C's public_configs would apply only to B. |
| 1595 " only to B.\n" | 1613 |
| 1596 "\n" | 1614 If B lists C in its public_deps instead of regular deps, A will now inherit |
| 1597 " If B lists C in its public_deps instead of regular deps, A will now\n" | 1615 C's public_configs and the ability to include C's public headers. |
| 1598 " inherit C's public_configs and the ability to include C's public\n" | 1616 |
| 1599 " headers.\n" | 1617 Generally if you are writing a target B and you include C's headers as part |
| 1600 "\n" | 1618 of B's public headers, or targets depending on B should consider B and C to |
| 1601 " Generally if you are writing a target B and you include C's headers\n" | 1619 be part of a unit, you should use public_deps instead of deps. |
| 1602 " as part of B's public headers, or targets depending on B should\n" | 1620 |
| 1603 " consider B and C to be part of a unit, you should use public_deps\n" | 1621 Example |
| 1604 " instead of deps.\n" | 1622 |
| 1605 "\n" | 1623 # This target can include files from "c" but not from |
| 1606 "Example\n" | 1624 # "super_secret_implementation_details". |
| 1607 "\n" | 1625 executable("a") { |
| 1608 " # This target can include files from \"c\" but not from\n" | 1626 deps = [ ":b" ] |
| 1609 " # \"super_secret_implementation_details\".\n" | 1627 } |
| 1610 " executable(\"a\") {\n" | 1628 |
| 1611 " deps = [ \":b\" ]\n" | 1629 shared_library("b") { |
| 1612 " }\n" | 1630 deps = [ ":super_secret_implementation_details" ] |
| 1613 "\n" | 1631 public_deps = [ ":c" ] |
| 1614 " shared_library(\"b\") {\n" | 1632 } |
| 1615 " deps = [ \":super_secret_implementation_details\" ]\n" | 1633 )"; |
| 1616 " public_deps = [ \":c\" ]\n" | |
| 1617 " }\n"; | |
| 1618 | 1634 |
| 1619 const char kResponseFileContents[] = "response_file_contents"; | 1635 const char kResponseFileContents[] = "response_file_contents"; |
| 1620 const char kResponseFileContents_HelpShort[] = | 1636 const char kResponseFileContents_HelpShort[] = |
| 1621 "response_file_contents: [string list] Contents of .rsp file for actions."; | 1637 "response_file_contents: [string list] Contents of .rsp file for actions."; |
| 1622 const char kResponseFileContents_Help[] = | 1638 const char kResponseFileContents_Help[] = |
| 1623 "response_file_contents: Contents of a response file for actions.\n" | 1639 R"*(response_file_contents: Contents of a response file for actions. |
| 1624 "\n" | 1640 |
| 1625 " Sometimes the arguments passed to a script can be too long for the\n" | 1641 Sometimes the arguments passed to a script can be too long for the system's |
| 1626 " system's command-line capabilities. This is especially the case on\n" | 1642 command-line capabilities. This is especially the case on Windows where the |
| 1627 " Windows where the maximum command-line length is less than 8K. A\n" | 1643 maximum command-line length is less than 8K. A response file allows you to |
| 1628 " response file allows you to pass an unlimited amount of data to a\n" | 1644 pass an unlimited amount of data to a script in a temporary file for an |
| 1629 " script in a temporary file for an action or action_foreach target.\n" | 1645 action or action_foreach target. |
| 1630 "\n" | 1646 |
| 1631 " If the response_file_contents variable is defined and non-empty, the\n" | 1647 If the response_file_contents variable is defined and non-empty, the list |
| 1632 " list will be treated as script args (including possibly substitution\n" | 1648 will be treated as script args (including possibly substitution patterns) |
| 1633 " patterns) that will be written to a temporary file at build time.\n" | 1649 that will be written to a temporary file at build time. The name of the |
| 1634 " The name of the temporary file will be substituted for\n" | 1650 temporary file will be substituted for "{{response_file_name}}" in the script |
| 1635 " \"{{response_file_name}}\" in the script args.\n" | 1651 args. |
| 1636 "\n" | 1652 |
| 1637 " The response file contents will always be quoted and escaped\n" | 1653 The response file contents will always be quoted and escaped according to |
| 1638 " according to Unix shell rules. To parse the response file, the Python\n" | 1654 Unix shell rules. To parse the response file, the Python script should use |
| 1639 " script should use \"shlex.split(file_contents)\".\n" | 1655 "shlex.split(file_contents)". |
| 1640 "\n" | 1656 |
| 1641 "Example\n" | 1657 Example |
| 1642 "\n" | 1658 |
| 1643 " action(\"process_lots_of_files\") {\n" | 1659 action("process_lots_of_files") { |
| 1644 " script = \"process.py\",\n" | 1660 script = "process.py", |
| 1645 " inputs = [ ... huge list of files ... ]\n" | 1661 inputs = [ ... huge list of files ... ] |
| 1646 "\n" | 1662 |
| 1647 " # Write all the inputs to a response file for the script. Also,\n" | 1663 # Write all the inputs to a response file for the script. Also, |
| 1648 " # make the paths relative to the script working directory.\n" | 1664 # make the paths relative to the script working directory. |
| 1649 " response_file_contents = rebase_path(inputs, root_build_dir)\n" | 1665 response_file_contents = rebase_path(inputs, root_build_dir) |
| 1650 "\n" | 1666 |
| 1651 " # The script expects the name of the response file in --file-list.\n" | 1667 # The script expects the name of the response file in --file-list. |
| 1652 " args = [\n" | 1668 args = [ |
| 1653 " \"--enable-foo\",\n" | 1669 "--enable-foo", |
| 1654 " \"--file-list={{response_file_name}}\",\n" | 1670 "--file-list={{response_file_name}}", |
| 1655 " ]\n" | 1671 ] |
| 1656 " }\n"; | 1672 } |
| 1673 )*"; |
| 1657 | 1674 |
| 1658 const char kScript[] = "script"; | 1675 const char kScript[] = "script"; |
| 1659 const char kScript_HelpShort[] = | 1676 const char kScript_HelpShort[] = |
| 1660 "script: [file name] Script file for actions."; | 1677 "script: [file name] Script file for actions."; |
| 1661 const char kScript_Help[] = | 1678 const char kScript_Help[] = |
| 1662 "script: Script file for actions.\n" | 1679 R"(script: Script file for actions. |
| 1663 "\n" | 1680 |
| 1664 " An absolute or buildfile-relative file name of a Python script to run\n" | 1681 An absolute or buildfile-relative file name of a Python script to run for a |
| 1665 " for a action and action_foreach targets (see \"gn help action\" and\n" | 1682 action and action_foreach targets (see "gn help action" and "gn help |
| 1666 " \"gn help action_foreach\").\n"; | 1683 action_foreach"). |
| 1684 )"; |
| 1667 | 1685 |
| 1668 const char kSources[] = "sources"; | 1686 const char kSources[] = "sources"; |
| 1669 const char kSources_HelpShort[] = | 1687 const char kSources_HelpShort[] = |
| 1670 "sources: [file list] Source files for a target."; | 1688 "sources: [file list] Source files for a target."; |
| 1671 const char kSources_Help[] = | 1689 const char kSources_Help[] = |
| 1672 "sources: Source files for a target\n" | 1690 R"(sources: Source files for a target |
| 1673 "\n" | 1691 |
| 1674 " A list of files. Non-absolute paths will be resolved relative to the\n" | 1692 A list of files. Non-absolute paths will be resolved relative to the current |
| 1675 " current build file.\n" | 1693 build file. |
| 1676 "\n" | 1694 |
| 1677 "Sources for binary targets\n" | 1695 Sources for binary targets |
| 1678 "\n" | 1696 |
| 1679 " For binary targets (source sets, executables, and libraries), the\n" | 1697 For binary targets (source sets, executables, and libraries), the known file |
| 1680 " known file types will be compiled with the associated tools. Unknown\n" | 1698 types will be compiled with the associated tools. Unknown file types and |
| 1681 " file types and headers will be skipped. However, you should still\n" | 1699 headers will be skipped. However, you should still list all C/C+ header files |
| 1682 " list all C/C+ header files so GN knows about the existance of those\n" | 1700 so GN knows about the existance of those files for the purposes of include |
| 1683 " files for the purposes of include checking.\n" | 1701 checking. |
| 1684 "\n" | 1702 |
| 1685 " As a special case, a file ending in \".def\" will be treated as a\n" | 1703 As a special case, a file ending in ".def" will be treated as a Windows |
| 1686 " Windows module definition file. It will be appended to the link\n" | 1704 module definition file. It will be appended to the link line with a |
| 1687 " line with a preceeding \"/DEF:\" string. There must be at most one\n" | 1705 preceeding "/DEF:" string. There must be at most one .def file in a target |
| 1688 " .def file in a target and they do not cross dependency boundaries\n" | 1706 and they do not cross dependency boundaries (so specifying a .def file in a |
| 1689 " (so specifying a .def file in a static library or source set will have\n" | 1707 static library or source set will have no effect on the executable or shared |
| 1690 " no effect on the executable or shared library they're linked into).\n" | 1708 library they're linked into). |
| 1691 "\n" | 1709 |
| 1692 "Sources for non-binary targets\n" | 1710 Sources for non-binary targets |
| 1693 "\n" | 1711 |
| 1694 " action_foreach\n" | 1712 action_foreach |
| 1695 " The sources are the set of files that the script will be executed\n" | 1713 The sources are the set of files that the script will be executed over. The |
| 1696 " over. The script will run once per file.\n" | 1714 script will run once per file. |
| 1697 "\n" | 1715 |
| 1698 " action\n" | 1716 action |
| 1699 " The sources will be treated the same as inputs. See " | 1717 The sources will be treated the same as inputs. See "gn help inputs" for |
| 1700 "\"gn help inputs\"\n" | 1718 more information and usage advice. |
| 1701 " for more information and usage advice.\n" | 1719 |
| 1702 "\n" | 1720 copy |
| 1703 " copy\n" | 1721 The source are the source files to copy. |
| 1704 " The source are the source files to copy.\n"; | 1722 )"; |
| 1705 | 1723 |
| 1706 const char kTestonly[] = "testonly"; | 1724 const char kTestonly[] = "testonly"; |
| 1707 const char kTestonly_HelpShort[] = | 1725 const char kTestonly_HelpShort[] = |
| 1708 "testonly: [boolean] Declares a target must only be used for testing."; | 1726 "testonly: [boolean] Declares a target must only be used for testing."; |
| 1709 const char kTestonly_Help[] = | 1727 const char kTestonly_Help[] = |
| 1710 "testonly: Declares a target must only be used for testing.\n" | 1728 R"(testonly: Declares a target must only be used for testing. |
| 1711 "\n" | 1729 |
| 1712 " Boolean. Defaults to false.\n" | 1730 Boolean. Defaults to false. |
| 1713 "\n" | 1731 |
| 1714 " When a target is marked \"testonly = true\", it must only be depended\n" | 1732 When a target is marked "testonly = true", it must only be depended on by |
| 1715 " on by other test-only targets. Otherwise, GN will issue an error\n" | 1733 other test-only targets. Otherwise, GN will issue an error that the |
| 1716 " that the depenedency is not allowed.\n" | 1734 depenedency is not allowed. |
| 1717 "\n" | 1735 |
| 1718 " This feature is intended to prevent accidentally shipping test code\n" | 1736 This feature is intended to prevent accidentally shipping test code in a |
| 1719 " in a final product.\n" | 1737 final product. |
| 1720 "\n" | 1738 |
| 1721 "Example\n" | 1739 Example |
| 1722 "\n" | 1740 |
| 1723 " source_set(\"test_support\") {\n" | 1741 source_set("test_support") { |
| 1724 " testonly = true\n" | 1742 testonly = true |
| 1725 " ...\n" | 1743 ... |
| 1726 " }\n"; | 1744 } |
| 1745 )"; |
| 1727 | 1746 |
| 1728 const char kVisibility[] = "visibility"; | 1747 const char kVisibility[] = "visibility"; |
| 1729 const char kVisibility_HelpShort[] = | 1748 const char kVisibility_HelpShort[] = |
| 1730 "visibility: [label list] A list of labels that can depend on a target."; | 1749 "visibility: [label list] A list of labels that can depend on a target."; |
| 1731 const char kVisibility_Help[] = | 1750 const char kVisibility_Help[] = |
| 1732 "visibility: A list of labels that can depend on a target.\n" | 1751 R"(visibility: A list of labels that can depend on a target. |
| 1733 "\n" | 1752 |
| 1734 " A list of labels and label patterns that define which targets can\n" | 1753 A list of labels and label patterns that define which targets can depend on |
| 1735 " depend on the current one. These permissions are checked via the\n" | 1754 the current one. These permissions are checked via the "check" command (see |
| 1736 " \"check\" command (see \"gn help check\").\n" | 1755 "gn help check"). |
| 1737 "\n" | 1756 |
| 1738 " If visibility is not defined, it defaults to public (\"*\").\n" | 1757 If visibility is not defined, it defaults to public ("*"). |
| 1739 "\n" | 1758 |
| 1740 " If visibility is defined, only the targets with labels that match it\n" | 1759 If visibility is defined, only the targets with labels that match it can |
| 1741 " can depend on the current target. The empty list means no targets\n" | 1760 depend on the current target. The empty list means no targets can depend on |
| 1742 " can depend on the current target.\n" | 1761 the current target. |
| 1743 "\n" | 1762 |
| 1744 " Tip: Often you will want the same visibility for all targets in a\n" | 1763 Tip: Often you will want the same visibility for all targets in a BUILD file. |
| 1745 " BUILD file. In this case you can just put the definition at the top,\n" | 1764 In this case you can just put the definition at the top, outside of any |
| 1746 " outside of any target, and the targets will inherit that scope and see\n" | 1765 target, and the targets will inherit that scope and see the definition. |
| 1747 " the definition.\n" | 1766 |
| 1748 "\n" | 1767 Patterns |
| 1749 "Patterns\n" | 1768 |
| 1750 "\n" | 1769 See "gn help label_pattern" for more details on what types of patterns are |
| 1751 " See \"gn help label_pattern\" for more details on what types of\n" | 1770 supported. If a toolchain is specified, only targets in that toolchain will |
| 1752 " patterns are supported. If a toolchain is specified, only targets\n" | 1771 be matched. If a toolchain is not specified on a pattern, targets in all |
| 1753 " in that toolchain will be matched. If a toolchain is not specified on\n" | 1772 toolchains will be matched. |
| 1754 " a pattern, targets in all toolchains will be matched.\n" | 1773 |
| 1755 "\n" | 1774 Examples |
| 1756 "Examples\n" | 1775 |
| 1757 "\n" | 1776 Only targets in the current buildfile ("private"): |
| 1758 " Only targets in the current buildfile (\"private\"):\n" | 1777 visibility = [ ":*" ] |
| 1759 " visibility = [ \":*\" ]\n" | 1778 |
| 1760 "\n" | 1779 No targets (used for targets that should be leaf nodes): |
| 1761 " No targets (used for targets that should be leaf nodes):\n" | 1780 visibility = [] |
| 1762 " visibility = []\n" | 1781 |
| 1763 "\n" | 1782 Any target ("public", the default): |
| 1764 " Any target (\"public\", the default):\n" | 1783 visibility = [ "*" ] |
| 1765 " visibility = [ \"*\" ]\n" | 1784 |
| 1766 "\n" | 1785 All targets in the current directory and any subdirectory: |
| 1767 " All targets in the current directory and any subdirectory:\n" | 1786 visibility = [ "./*" ] |
| 1768 " visibility = [ \"./*\" ]\n" | 1787 |
| 1769 "\n" | 1788 Any target in "//bar/BUILD.gn": |
| 1770 " Any target in \"//bar/BUILD.gn\":\n" | 1789 visibility = [ "//bar:*" ] |
| 1771 " visibility = [ \"//bar:*\" ]\n" | 1790 |
| 1772 "\n" | 1791 Any target in "//bar/" or any subdirectory thereof: |
| 1773 " Any target in \"//bar/\" or any subdirectory thereof:\n" | 1792 visibility = [ "//bar/*" ] |
| 1774 " visibility = [ \"//bar/*\" ]\n" | 1793 |
| 1775 "\n" | 1794 Just these specific targets: |
| 1776 " Just these specific targets:\n" | 1795 visibility = [ ":mything", "//foo:something_else" ] |
| 1777 " visibility = [ \":mything\", \"//foo:something_else\" ]\n" | 1796 |
| 1778 "\n" | 1797 Any target in the current directory and any subdirectory thereof, plus |
| 1779 " Any target in the current directory and any subdirectory thereof, plus\n" | 1798 any targets in "//bar/" and any subdirectory thereof. |
| 1780 " any targets in \"//bar/\" and any subdirectory thereof.\n" | 1799 visibility = [ "./*", "//bar/*" ] |
| 1781 " visibility = [ \"./*\", \"//bar/*\" ]\n"; | 1800 )"; |
| 1782 | 1801 |
| 1783 const char kWriteRuntimeDeps[] = "write_runtime_deps"; | 1802 const char kWriteRuntimeDeps[] = "write_runtime_deps"; |
| 1784 const char kWriteRuntimeDeps_HelpShort[] = | 1803 const char kWriteRuntimeDeps_HelpShort[] = |
| 1785 "write_runtime_deps: Writes the target's runtime_deps to the given path."; | 1804 "write_runtime_deps: Writes the target's runtime_deps to the given path."; |
| 1786 const char kWriteRuntimeDeps_Help[] = | 1805 const char kWriteRuntimeDeps_Help[] = |
| 1787 "write_runtime_deps: Writes the target's runtime_deps to the given path.\n" | 1806 R"(write_runtime_deps: Writes the target's runtime_deps to the given path. |
| 1788 "\n" | 1807 |
| 1789 " Does not synchronously write the file, but rather schedules it\n" | 1808 Does not synchronously write the file, but rather schedules it to be written |
| 1790 " to be written at the end of generation.\n" | 1809 at the end of generation. |
| 1791 "\n" | 1810 |
| 1792 " If the file exists and the contents are identical to that being\n" | 1811 If the file exists and the contents are identical to that being written, the |
| 1793 " written, the file will not be updated. This will prevent unnecessary\n" | 1812 file will not be updated. This will prevent unnecessary rebuilds of targets |
| 1794 " rebuilds of targets that depend on this file.\n" | 1813 that depend on this file. |
| 1795 "\n" | 1814 |
| 1796 " Path must be within the output directory.\n" | 1815 Path must be within the output directory. |
| 1797 "\n" | 1816 |
| 1798 " See \"gn help runtime_deps\" for how the runtime dependencies are\n" | 1817 See "gn help runtime_deps" for how the runtime dependencies are computed. |
| 1799 " computed.\n" | 1818 |
| 1800 "\n" | 1819 The format of this file will list one file per line with no escaping. The |
| 1801 " The format of this file will list one file per line with no escaping.\n" | 1820 files will be relative to the root_build_dir. The first line of the file will |
| 1802 " The files will be relative to the root_build_dir. The first line of\n" | 1821 be the main output file of the target itself. The file contents will be the |
| 1803 " the file will be the main output file of the target itself. The file\n" | 1822 same as requesting the runtime deps be written on the command line (see "gn |
| 1804 " contents will be the same as requesting the runtime deps be written on\n" | 1823 help --runtime-deps-list-file"). |
| 1805 " the command line (see \"gn help --runtime-deps-list-file\").\n"; | 1824 )"; |
| 1806 | 1825 |
| 1807 // ----------------------------------------------------------------------------- | 1826 // ----------------------------------------------------------------------------- |
| 1808 | 1827 |
| 1809 VariableInfo::VariableInfo() | 1828 VariableInfo::VariableInfo() |
| 1810 : help_short(""), | 1829 : help_short(""), |
| 1811 help("") { | 1830 help("") { |
| 1812 } | 1831 } |
| 1813 | 1832 |
| 1814 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help) | 1833 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help) |
| 1815 : help_short(in_help_short), | 1834 : help_short(in_help_short), |
| (...skipping 80 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1896 INSERT_VARIABLE(Testonly) | 1915 INSERT_VARIABLE(Testonly) |
| 1897 INSERT_VARIABLE(Visibility) | 1916 INSERT_VARIABLE(Visibility) |
| 1898 INSERT_VARIABLE(WriteRuntimeDeps) | 1917 INSERT_VARIABLE(WriteRuntimeDeps) |
| 1899 } | 1918 } |
| 1900 return info_map; | 1919 return info_map; |
| 1901 } | 1920 } |
| 1902 | 1921 |
| 1903 #undef INSERT_VARIABLE | 1922 #undef INSERT_VARIABLE |
| 1904 | 1923 |
| 1905 } // namespace variables | 1924 } // namespace variables |
| OLD | NEW |