OLD | NEW |
1 # Language Specification | 1 # Language Specification |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 | 4 |
5 ## Objective | 5 ## Objective |
6 | 6 |
7 Create a tool for the Chromium project that generates native Visual Studio, | 7 Create a tool for the Chromium project that generates native Visual Studio, |
8 Xcode and SCons and/or make build files from a platform-independent input | 8 Xcode and SCons and/or make build files from a platform-independent input |
9 format. Make the input format as reasonably general as possible without | 9 format. Make the input format as reasonably general as possible without |
10 spending extra time trying to "get everything right," except where not doing so | 10 spending extra time trying to "get everything right," except where not doing so |
(...skipping 118 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
129 ### Structural Elements | 129 ### Structural Elements |
130 | 130 |
131 ### Top-level Dictionary | 131 ### Top-level Dictionary |
132 | 132 |
133 This is the single dictionary in the `.gyp` file that defines the | 133 This is the single dictionary in the `.gyp` file that defines the |
134 targets and how they're to be built. | 134 targets and how they're to be built. |
135 | 135 |
136 The following keywords are meaningful within the top-level dictionary | 136 The following keywords are meaningful within the top-level dictionary |
137 definition: | 137 definition: |
138 | 138 |
139 |:------------- |:------------------| | 139 | *Keyword* | *Description* | |
| 140 |:------------------|:------------------| |
140 | `conditions` | A conditional section that may contain other items that ca
n be present in a top-level dictionary, on a conditional basis. See the "Condit
ionals" section below. | | 141 | `conditions` | A conditional section that may contain other items that ca
n be present in a top-level dictionary, on a conditional basis. See the "Condit
ionals" section below. | |
141 | `includes` | A list of `.gypi` files to be included in the top-level di
ctionary. | | 142 | `includes` | A list of `.gypi` files to be included in the top-level di
ctionary. | |
142 | `target_defaults` | A dictionary of default settings to be inherited by all ta
rgets in the top-level dictionary. See the "Settings keywords" section below. | | 143 | `target_defaults` | A dictionary of default settings to be inherited by all ta
rgets in the top-level dictionary. See the "Settings keywords" section below. | |
143 | `targets` | A list of target specifications. See the "targets" below.
| | 144 | `targets` | A list of target specifications. See the "targets" below.
| |
144 | `variables` | A dictionary containing variable definitions. Each key in
this dictionary is the name of a variable, and each value must be a string valu
e that the variable is to be set to. | | 145 | `variables` | A dictionary containing variable definitions. Each key in
this dictionary is the name of a variable, and each value must be a string valu
e that the variable is to be set to. | |
145 | 146 |
146 ### targets | 147 ### targets |
147 | 148 |
148 A list of dictionaries defining targets to be built by the files | 149 A list of dictionaries defining targets to be built by the files |
149 generated from this `.gyp` file. | 150 generated from this `.gyp` file. |
150 | 151 |
151 Targets may contain `includes`, `conditions`, and `variables` sections | 152 Targets may contain `includes`, `conditions`, and `variables` sections |
152 as permitted in the root dictionary. The following additional keywords | 153 as permitted in the root dictionary. The following additional keywords |
153 have structural meaning for target definitions: | 154 have structural meaning for target definitions: |
154 | 155 |
155 |:---------- |:------------------------------------------| | 156 | *Keyword* | *Description* | |
| 157 |:---------------------------- |:------------------------------------------| |
156 | `actions` | A list of special custom actions to perform on
a specific input file, or files, to produce output files. See the "Actions" sec
tion below. | | 158 | `actions` | A list of special custom actions to perform on
a specific input file, or files, to produce output files. See the "Actions" sec
tion below. | |
157 | `all_dependent_settings` | A dictionary of settings to be applied to all d
ependents of the target, transitively. This includes direct dependents and the
entire set of their dependents, and so on. This section may contain anything fo
und within a `target` dictionary, except `configurations`, `target_name`, and `t
ype` sections. Compare `direct_dependent_settings` and `link_settings`. | | 159 | `all_dependent_settings` | A dictionary of settings to be applied to all d
ependents of the target, transitively. This includes direct dependents and the
entire set of their dependents, and so on. This section may contain anything fo
und within a `target` dictionary, except `configurations`, `target_name`, and `t
ype` sections. Compare `direct_dependent_settings` and `link_settings`. | |
158 | `configurations` | A list of dictionaries defining build configura
tions for the target. See the "Configurations" section below. | | 160 | `configurations` | A list of dictionaries defining build configura
tions for the target. See the "Configurations" section below. | |
159 | `copies` | A list of copy actions to perform. See the "Cop
ies" section below. | | 161 | `copies` | A list of copy actions to perform. See the "Cop
ies" section below. | |
160 | `defines` | A list of preprocesor definitions to be passed
on the command line to the C/C++ compiler (via `-D` or `/D` options). | | 162 | `defines` | A list of preprocesor definitions to be passed
on the command line to the C/C++ compiler (via `-D` or `/D` options). | |
161 | `dependencies` | A list of targets on which this target depends.
Targets in other `.gyp` files are specified as `../path/to/other.gyp:target_we
_want`. | | 163 | `dependencies` | A list of targets on which this target depends.
Targets in other `.gyp` files are specified as `../path/to/other.gyp:target_we
_want`. | |
162 | `direct_dependent_settings` | A dictionary of settings to be applied to other
targets that depend on this target. These settings will only be applied to dir
ect dependents. This section may contain anything found within a `target` dicti
onary, except `configurations`, `target_name`, and `type` sections. Compare wit
h `all_dependent_settings` and `link_settings`. | | 164 | `direct_dependent_settings` | A dictionary of settings to be applied to other
targets that depend on this target. These settings will only be applied to dir
ect dependents. This section may contain anything found within a `target` dicti
onary, except `configurations`, `target_name`, and `type` sections. Compare wit
h `all_dependent_settings` and `link_settings`. | |
163 | `include_dirs` | A list of include directories to be passed on t
he command line to the C/C++ compiler (via `-I` or `/I` options). | | 165 | `include_dirs` | A list of include directories to be passed on t
he command line to the C/C++ compiler (via `-I` or `/I` options). | |
164 | `libraries` | A list of list of libraries (and/or frameworks)
on which this target depends. | | 166 | `libraries` | A list of list of libraries (and/or frameworks)
on which this target depends. | |
165 | `link_settings` | A dictionary of settings to be applied to targe
ts in which this target's contents are linked. `executable` and `shared_library
` targets are linkable, so if they depend on a non-linkable target such as a `st
atic_library`, they will adopt its `link_settings`. This section can contain an
ything found within a `target` dictionary, except `configurations`, `target_name
`, and `type` sections. Compare `all_dependent_settings` and `direct_dependent_
settings`. | | 167 | `link_settings` | A dictionary of settings to be applied to targe
ts in which this target's contents are linked. `executable` and `shared_library
` targets are linkable, so if they depend on a non-linkable target such as a `st
atic_library`, they will adopt its `link_settings`. This section can contain an
ything found within a `target` dictionary, except `configurations`, `target_name
`, and `type` sections. Compare `all_dependent_settings` and `direct_dependent_
settings`. | |
(...skipping 27 matching lines...) Expand all Loading... |
193 the same set of configurations. This continues to apply even when a | 195 the same set of configurations. This continues to apply even when a |
194 project spans across multiple `.gyp` files. | 196 project spans across multiple `.gyp` files. |
195 | 197 |
196 A configuration dictionary may contain anything that can be found within | 198 A configuration dictionary may contain anything that can be found within |
197 a target dictionary, except for `actions`, `all_dependent_settings`, | 199 a target dictionary, except for `actions`, `all_dependent_settings`, |
198 `configurations`, `dependencies`, `direct_dependent_settings`, | 200 `configurations`, `dependencies`, `direct_dependent_settings`, |
199 `libraries`, `link_settings`, `sources`, `target_name`, and `type`. | 201 `libraries`, `link_settings`, `sources`, `target_name`, and `type`. |
200 | 202 |
201 Configuration dictionaries may also contain these elements: | 203 Configuration dictionaries may also contain these elements: |
202 | 204 |
| 205 | *Keyword* | *Description* | |
203 |:---------------------|:----------------------------------------------------| | 206 |:---------------------|:----------------------------------------------------| |
204 | `configuration_name` | Required attribute. The name of the configuration. | | 207 | `configuration_name` | Required attribute. The name of the configuration. | |
205 | 208 |
206 ### Conditionals | 209 ### Conditionals |
207 | 210 |
208 Conditionals may appear within any dictionary in a `.gyp` file. There | 211 Conditionals may appear within any dictionary in a `.gyp` file. There |
209 are two tpes of conditionals, which differ only in the timing of their | 212 are two tpes of conditionals, which differ only in the timing of their |
210 processing. `conditons` sections are processed shortly after loading | 213 processing. `conditons` sections are processed shortly after loading |
211 `.gyp` files, and `target_conditons` sections are processed after all | 214 `.gyp` files, and `target_conditons` sections are processed after all |
212 dependencies have been computed. | 215 dependencies have been computed. |
(...skipping 11 matching lines...) Expand all Loading... |
224 global and/or local dictionaries that constructed from the `.gyp` input | 227 global and/or local dictionaries that constructed from the `.gyp` input |
225 data, and overrides the `__builtin__` dictionary, to prevent the | 228 data, and overrides the `__builtin__` dictionary, to prevent the |
226 execution of arbitrary Python code. | 229 execution of arbitrary Python code. |
227 | 230 |
228 ### Actions | 231 ### Actions |
229 | 232 |
230 An `actions` section provides a list of custom build actions to perform | 233 An `actions` section provides a list of custom build actions to perform |
231 on inputs, producing outputs. The `actions` section is organized as a | 234 on inputs, producing outputs. The `actions` section is organized as a |
232 list. Each item in the list is a dictionary having the following form: | 235 list. Each item in the list is a dictionary having the following form: |
233 | 236 |
| 237 | *Keyword* | *Type* | *Description* | |
234 |:--------------|:-------|:-----------------------------| | 238 |:--------------|:-------|:-----------------------------| |
235 | `action_name` | string | The name of the action. Depending on how actions are
implemented in the various generators, some may desire or require this property
to be set to a unique name; others may ignore this property entirely. | | 239 | `action_name` | string | The name of the action. Depending on how actions are
implemented in the various generators, some may desire or require this property
to be set to a unique name; others may ignore this property entirely. | |
236 | `inputs` | list | A list of pathnames treated as inputs to the custom a
ction. | | 240 | `inputs` | list | A list of pathnames treated as inputs to the custom a
ction. | |
237 | `outputs` | list | A list of pathnames that the custom action produces.
| | 241 | `outputs` | list | A list of pathnames that the custom action produces.
| |
238 | `action` | list | A command line invocation used to produce `outputs` f
rom `inputs`. For maximum cross-platform compatibility, invocations that requir
e a Python interpreter should be specified with a first element `"python"`. Thi
s will enable generators for environments with specialized Python installations
to be able to perform the action in an appropriate Python environment. | | 242 | `action` | list | A command line invocation used to produce `outputs` f
rom `inputs`. For maximum cross-platform compatibility, invocations that requir
e a Python interpreter should be specified with a first element `"python"`. Thi
s will enable generators for environments with specialized Python installations
to be able to perform the action in an appropriate Python environment. | |
239 | `message` | string | A message to be displayed to the user by the build sy
stem when the action is run. | | 243 | `message` | string | A message to be displayed to the user by the build sy
stem when the action is run. | |
240 | 244 |
241 Build environments will compare `inputs` and `outputs`. If any `output` | 245 Build environments will compare `inputs` and `outputs`. If any `output` |
242 is missing or is outdated relative to any `input`, the custom action | 246 is missing or is outdated relative to any `input`, the custom action |
243 will be invoked. If all `outputs` are present and newer than all | 247 will be invoked. If all `outputs` are present and newer than all |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
281 }, | 285 }, |
282 ], | 286 ], |
283 ``` | 287 ``` |
284 | 288 |
285 ### Rules | 289 ### Rules |
286 | 290 |
287 A `rules` section provides custom build action to perform on inputs, producing | 291 A `rules` section provides custom build action to perform on inputs, producing |
288 outputs. The `rules` section is organized as a list. Each item in the list is | 292 outputs. The `rules` section is organized as a list. Each item in the list is |
289 a dictionary having the following form: | 293 a dictionary having the following form: |
290 | 294 |
| 295 | *Keyword* | *Type* | *Description* | |
291 |:------------|:-------|:-----------------------------------------| | 296 |:------------|:-------|:-----------------------------------------| |
292 | `rule_name` | string | The name of the rule. Depending on how Rules are imple
mented in the various generators, some may desire or require this property to be
set to a unique name; others may ignore this property entirely. | | 297 | `rule_name` | string | The name of the rule. Depending on how Rules are imple
mented in the various generators, some may desire or require this property to be
set to a unique name; others may ignore this property entirely. | |
293 | `extension` | string | All source files of the current target with the given e
xtension will be treated successively as inputs to the rule. | | 298 | `extension` | string | All source files of the current target with the given e
xtension will be treated successively as inputs to the rule. | |
294 | `inputs` | list | Additional dependencies of the rule. | | 299 | `inputs` | list | Additional dependencies of the rule. | |
295 | `outputs` | list | A list of pathnames that the rule produces. Has access
to `RULE_INPUT_` variables (see below). | | 300 | `outputs` | list | A list of pathnames that the rule produces. Has access
to `RULE_INPUT_` variables (see below). | |
296 | `action` | list | A command line invocation used to produce `outputs` fro
m `inputs`. For maximum cross-platform compatibility, invocations that require
a Python interpreter should be specified with a first element `"python"`. This
will enable generators for environments with specialized Python installations to
be able to perform the action in an appropriate Python environment. Has access
to `RULE_INPUT_` variables (see below). | | 301 | `action` | list | A command line invocation used to produce `outputs` fro
m `inputs`. For maximum cross-platform compatibility, invocations that require
a Python interpreter should be specified with a first element `"python"`. This
will enable generators for environments with specialized Python installations to
be able to perform the action in an appropriate Python environment. Has access
to `RULE_INPUT_` variables (see below). | |
297 | `message` | string | A message to be displayed to the user by the build syst
em when the action is run. Has access to `RULE_INPUT_` variables (see below). | | 302 | `message` | string | A message to be displayed to the user by the build syst
em when the action is run. Has access to `RULE_INPUT_` variables (see below). | |
298 | 303 |
299 There are several variables available to `outputs`, `action`, and `message`. | 304 There are several variables available to `outputs`, `action`, and `message`. |
300 | 305 |
| 306 | *Variable* | *Description* | |
301 |:---------------------|:------------------------------------| | 307 |:---------------------|:------------------------------------| |
302 | `RULE_INPUT_PATH` | The full path to the current input. | | 308 | `RULE_INPUT_PATH` | The full path to the current input. | |
303 | `RULE_INPUT_DIRNAME` | The directory of the current input. | | 309 | `RULE_INPUT_DIRNAME` | The directory of the current input. | |
304 | `RULE_INPUT_NAME` | The file name of the current input. | | 310 | `RULE_INPUT_NAME` | The file name of the current input. | |
305 | `RULE_INPUT_ROOT` | The file name of the current input without extension. | | 311 | `RULE_INPUT_ROOT` | The file name of the current input without extension. | |
306 | `RULE_INPUT_EXT` | The file name extension of the current input. | | 312 | `RULE_INPUT_EXT` | The file name extension of the current input. | |
307 | 313 |
308 Rules can be thought of as Action generators. For each source selected | 314 Rules can be thought of as Action generators. For each source selected |
309 by `extension` an special action is created. This action starts out with | 315 by `extension` an special action is created. This action starts out with |
310 the same `inputs`, `outputs`, `action`, and `message` as the rule. The | 316 the same `inputs`, `outputs`, `action`, and `message` as the rule. The |
311 source is added to the action's `inputs`. The `outputs`, `action`, and | 317 source is added to the action's `inputs`. The `outputs`, `action`, and |
312 `message` are then handled the same but with the additional variables. | 318 `message` are then handled the same but with the additional variables. |
313 If the `_output` variable is used in the `action` or `message` the | 319 If the `_output` variable is used in the `action` or `message` the |
314 `RULE_INPUT_` variables in `output` will be expanded for the current | 320 `RULE_INPUT_` variables in `output` will be expanded for the current |
315 source. | 321 source. |
316 | 322 |
317 ### Copies | 323 ### Copies |
318 | 324 |
319 A `copies` section provides a simple means of copying files. The | 325 A `copies` section provides a simple means of copying files. The |
320 `copies` section is organized as a list. Each item in the list is a | 326 `copies` section is organized as a list. Each item in the list is a |
321 dictionary having the following form: | 327 dictionary having the following form: |
322 | 328 |
| 329 | *Keyword* | *Type* | *Description* | |
323 |:--------------|:-------|:------------------------------| | 330 |:--------------|:-------|:------------------------------| |
324 | `destination` | string | The directory into which the `files` will be copied.
| | 331 | `destination` | string | The directory into which the `files` will be copied.
| |
325 | `files` | list | A list of files to be copied. | | 332 | `files` | list | A list of files to be copied. | |
326 | 333 |
327 The copies will be created in `destination` and have the same file name | 334 The copies will be created in `destination` and have the same file name |
328 as the file they are copied from. Even if the `files` are from multiple | 335 as the file they are copied from. Even if the `files` are from multiple |
329 directories they will all be copied into the `destination` directory. | 336 directories they will all be copied into the `destination` directory. |
330 Each `destination` file has an implicit build dependency on the file it | 337 Each `destination` file has an implicit build dependency on the file it |
331 is copied from. | 338 is copied from. |
332 | 339 |
(...skipping 83 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
416 * Target platform | 423 * Target platform |
417 * V8 vs. JSC | 424 * V8 vs. JSC |
418 * Debug vs. Release | 425 * Debug vs. Release |
419 * Toolchain (VS version, gcc, version) | 426 * Toolchain (VS version, gcc, version) |
420 * Host platform | 427 * Host platform |
421 * L10N | 428 * L10N |
422 * Vendor | 429 * Vendor |
423 * Purify / Valgrind | 430 * Purify / Valgrind |
424 * Will everyone upgrade VS at once? | 431 * Will everyone upgrade VS at once? |
425 * What does a dylib dependency mean? | 432 * What does a dylib dependency mean? |
OLD | NEW |