binding.gyp参数说明书/文档/指南（GYP Input Format Reference）

Posted 岬淢箫声

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了binding.gyp参数说明书/文档/指南（GYP Input Format Reference）相关的知识，希望对你有一定的参考价值。

接着上篇文章继续写。上一篇文章介绍了binding.gyp的基本写法，但不够全面，特别对于条件编译和变量的说明太少。接下来将重点描述相关细节。

Primitive Types

The following primitive types are found within input files:

  • String values, which may be represented by enclosing them in 'single quotes' or "double quotes". By convention, single quotes are used.

  • Integer values, which are represented in decimal without any special decoration. Integers are fairly rare in input files, but have a few applications in boolean contexts, where the convention is to represent true values with 1 and false with 0.

  • Lists, which are represented as a sequence of items separated by commas (,) within square brackets ([ and ]). A list may contain any other primitive types, including other lists. Generally, each item of a list must be of the same type as all other items in the list, but in some cases (such as within conditions sections), the list structure is more tightly specified. A trailing comma is permitted.

    This example list contains three string values.

    [ 'Generate', 'Your', 'Projects', ]

  • Dictionaries, which map keys to values. All keys are strings. Values may be of any other primitive type, including other dictionaries. A dictionary is enclosed within curly braces ( and ). Keys precede values, separated by a colon (:). Successive dictionary entries are separated by commas (,). A trailing comma is permitted. It is an error for keys to be duplicated within a single dictionary as written in an input file, although keys may replace other keys during merging.

    This example dictionary maps each of three keys to different values.

    
  'inputs': ['version.c.in'],
  'outputs': ['version.c'],
  'process_outputs_as_sources': 1,

Overall Structure

A GYP input file is organized as structured data. At the root scope of each .gyp or .gypi (include) file is a dictionary. The keys and values of this dictionary, along with any descendants contained within the values, provide the data contained within the file. This data is given meaning by interpreting specific key names and their associated values in specific ways (see Settings Keys).

Comments (#)

Within an input file, a comment is introduced by a pound sign (#) not within a string. Any text following the pound sign, up until the end of the line, is treated as a comment.

Example


  'school_supplies': [
    'Marble composition book',
    'Sharp #2 pencil',
    'Safety scissors',  # You still shouldn't run with these
  ],

In this example, the # in 'Sharp #2 pencil' is not taken as introducing a comment because it occurs within a string, but the text after 'Safety scissors' is treated as a comment having no impact on the data within the file.

Merging

Merge Basics (=, ?, +)

Many operations on GYP input files occurs by merging dictionary and list items together. During merge operations, it is important to recognize the distinction between source and destination values. Items from the source value are merged into the destination, which leaves the source unchanged and the destination modified by the source. A dictionary may only be merged into another dictionary, and a list may only be merged into another list.

  • When merging a dictionary, for each key in the source:
    • If the key does not exist in the destination dictionary, insert it and copy the associated value directly.
    • If the key does exist:
      • If the associated value is a dictionary, perform the dictionary merging procedure using the source's and destination's value dictionaries.
      • If the associated value is a list, perform the list merging procedure using the source's and destination's value lists.
      • If the associated value is a string or integer, the destination value is replaced by the source value.
  • When merging a list, merge according to the suffix appended to the key name, if the list is a value within a dictionary.
    • If the key ends with an equals sign (=), the policy is for the source list to completely replace the destination list if it exists. Mnemonic: = for assignment.
    • If the key ends with a question mark (?), the policy is for the source list to be set as the destination list only if the key is not already present in the destination. Mnemonic: ? for conditional assignment.
    • If the key ends with a plus sign (+), the policy is for the source list contents to be prepended to the destination list.Mnemonic: + for addition or concatenation.
    • If the list key is undecorated, the policy is for the source list contents to be appended to the destination list. This is the default list merge policy.

Example

Source dictionary:


  'include_dirs+': [
    'shared_stuff/public',
  ],
  'link_settings': 
    'libraries': [
      '-lshared_stuff',
    ],
  ,
  'test': 1,

Destination dictionary:


  'target_name': 'hello',
  'sources': [
    'kitty.cc',
  ],
  'include_dirs': [
    'headers',
  ],
  'link_settings': 
    'libraries': [
      '-lm',
    ],
    'library_dirs': [
      '/usr/lib',
    ],
  ,
  'test': 0,

Merged dictionary:


  'target_name': 'hello',
  'sources': [
    'kitty.cc',
  ],
  'include_dirs': [
    'shared_stuff/public',  # Merged, list item prepended due to include_dirs+
    'headers',
  ],
  'link_settings': 
    'libraries': [
      '-lm',
      '-lshared_stuff',  # Merged, list item appended
    ],
    'library_dirs': [
      '/usr/lib',
    ],
  ,
  'test': 1,  # Merged, int value replaced

Pathname Relativization

In a .gyp or .gypi file, many string values are treated as pathnames relative to the file in which they are defined.

String values associated with the following keys, or contained within lists associated with the following keys, are treated as pathnames:

  • destination
  • files
  • include_dirs
  • inputs
  • libraries
  • outputs
  • sources
  • mac_bundle_resources
  • mac_framework_dirs
  • msvs_cygwin_dirs
  • msvs_props

Additionally, string values associated with keys ending in the following suffixes, or contained within lists associated with keys ending in the following suffixes, are treated as pathnames:

  • _dir
  • _dirs
  • _file
  • _files
  • _path
  • _paths

However, any string value beginning with any of these characters is excluded from pathname relativization:

  • / for identifying absolute paths.
  • $ for introducing build system variable expansions.
  • - to support specifying such items as -llib, meaning “library lib in the library search path.”
  • <, >, and ! for GYP expansions.

When merging such relative pathnames, they are adjusted so that they can remain valid relative pathnames, despite being relative to a new home.

Example

Source dictionary from ../build/common.gypi:


  'include_dirs': ['include'],  # Treated as relative to ../build
  'libraries': ['-lz'],  # Not treated as a pathname, begins with a dash
  'defines': ['NDEBUG'],  # defines does not contain pathnames

Target dictionary, from base.gyp:


  'sources': ['string_util.cc'],

Merged dictionary:


  'sources': ['string_util.cc'],
  'include_dirs': ['../build/include'],
  'libraries': ['-lz'],
  'defines': ['NDEBUG'],

Because of pathname relativization, after the merge is complete, all of the pathnames in the merged dictionary are valid relative to the directory containing base.gyp.

List Singletons

Some list items are treated as singletons, and the list merge process will enforce special rules when merging them. At present, any string item in a list that does not begin with a dash (-) is treated as a singleton, although this is subject to change.When appending or prepending a singleton to a list, if the item is already in the list, only the earlier instance is retained in the merged list.

Example

Source dictionary:


  'defines': [
    'EXPERIMENT=1',
    'NDEBUG',
  ],

Destination dictionary:


  'defines': [
    'NDEBUG',
    'USE_THREADS',
  ],

Merged dictionary:


  'defines': [
    'NDEBUG',
    'USE_THREADS',
    'EXPERIMENT=1',  # Note that NDEBUG is not appended after this.
  ],

Including Other Files

If the -I (--include) argument was used to invoke GYP, any files specified will be implicitly merged into the root dictionary of all .gyp files.

An includes section may be placed anywhere within a .gyp or .gypi (include) file. includes sections contain lists of other files to include. They are processed sequentially and merged into the enclosing dictionary at the point that the includessection was found. includes sections at the root of a .gyp file dictionary are merged after any -I includes from the command line.

includes sections are processed immediately after a file is loaded, even before variable and conditional processing, so it is not possible to include a file based on a variable reference. While it would be useful to be able to include files based on variable expansions, it is most likely more useful to allow included files access to variables set by the files that included them.

An includes section may, however, be placed within a conditional section. The included file itself will be loaded unconditionally, but its dictionary will be discarded if the associated condition is not true.

Variables and Conditionals

Variables

There are three main types of variables within GYP.

  • Predefined variables. By convention, these are named with CAPITAL_LETTERS. Predefined variables are set automatically by GYP. They may be overridden, but it is not advisable to do so. See Predefined Variables for a list of variables that GYP provides.
  • User-defined variables. Within any dictionary, a key named variables can be provided, containing a mapping between variable names (keys) and their contents (values), which may be strings, integers, or lists of strings. By convention, user-defined variables are named with lowercase_letters.
  • Automatic variables. Within any dictionary, any key with a string value has a corresponding automatic variable whose name is the same as the key name with an underscore (_) prefixed. For example, if your dictionary contains type: 'static_library', an automatic variable named _type will be provided, and its value will be a string, 'static_library'.

Variables are inherited from enclosing scopes.

Providing Default Values for Variables (%)

Within a variables section, keys named with percent sign (%) suffixes mean that the variable should be set only if it is undefined at the time it is processed. This can be used to provide defaults for variables that would otherwise be undefined, so that they may reliably be used in variable expansion or conditional processing.

Predefined Variables

Each GYP generator module provides defaults for the following variables:

  • OS: The name of the operating system that the generator produces output for. Common values for values for OS are:

    • 'linux'
    • 'mac'
    • 'win'

    But other values may be encountered and this list should not be considered exhaustive. The gypd (debug) generator module does not provide a predefined value for OS. When invoking GYP with the gypd module, if a value for OS is needed, it must be provided on the command line, such as gyp -f gypd -DOS=mac.

    GYP generators also provide defaults for these variables. They may be expressed in terms of variables used by the build system that they generate for, often in $(VARIABLE) format. For example, the GYP PRODUCT_DIR variable maps to the Xcode BUILT_PRODUCTS_DIR variable, so PRODUCT_DIR is defined by the Xcode generator as $(BUILT_PRODUCTS_DIR).

  • EXECUTABLE_PREFIX: A prefix, if any, applied to executable names. Usually this will be an empty string.

  • EXECUTABLE_SUFFIX: A suffix, if any, applied to executable names. On Windows, this will be .exe, elsewhere, it will usually be an empty string.

  • INTERMEDIATE_DIR: A directory that can be used to place intermediate build results in. INTERMEDIATE_DIR is only guaranteed to be accessible within a single target (See targets). This variable is most useful within the context of rules and actions (See rules, See actions). Compare with SHARED_INTERMEDIATE_DIR.

  • PRODUCT_DIR: The directory in which the primary output of each target, such as executables and libraries, is placed.

  • RULE_INPUT_ROOT: The base name for the input file (e.g. "foo"). See Rules.

  • RULE_INPUT_EXT: The file extension for the input file (e.g. ".cc"). See Rules.

  • RULE_INPUT_NAME: Full name of the input file (e.g. "foo.cc"). See Rules.

  • RULE_INPUT_PATH: Full path to the input file (e.g. "/bar/foo.cc"). See Rules.

  • SHARED_INTERMEDIATE_DIR: A directory that can be used to place intermediate build results in, and have them be accessible to other targets. Unlike INTERMEDIATE_DIR, each target in a project, possibly spanning multiple .gyp files, shares the same SHARED_INTERMEDIATE_DIR.

The following additional predefined variables may be available under certain circumstances:

  • DEPTH. When GYP is invoked with a --depth argument, when processing any .gyp file, DEPTH will be a relative path from the .gyp file to the directory specified by the --depth argument.

User-Defined Variables

A user-defined variable may be defined in terms of other variables, but not other variables that have definitions provided in the same scope.

Variable Expansions (<, >, <@, >@)

GYP provides two forms of variable expansions, “early” or “pre” expansions, and “late,” “post,” or “target” expansions. They have similar syntax, differing only in the character used to introduce them.

  • Early expansions are introduced by a less-than (<) character. Mnemonic: the arrow points to the left, earlier on a timeline.
  • Late expansions are introduced by a less-than (>) character. Mnemonic: the arrow points to the right, later on a timeline.

The difference the two phases of expansion is described in Early and Late Phases.

These characters were chosen based upon the requirement that they not conflict with the variable format used natively by build systems. While the dollar sign ($) is the most natural fit for variable expansions, its use was ruled out because most build systems already use that character for their own variable expansions. Using different characters means that no escaping mechanism was needed to differentiate between GYP variables and build system variables, and writing build system variables into GYP files is not cumbersome.

Variables may contain lists or strings, and variable expansions may occur in list or string context. There are variant forms of variable expansions that may be used to determine how each type of variable is to be expanded in each context.

  • When a variable is referenced by <(VAR) or >(VAR):
    • If VAR is a string, the variable reference within the string is replaced by variable's string value.
    • If VAR is a list, the variable reference within the string is replaced by a string containing the concatenation of all of the variable’s list items. Generally, the items are joined with spaces between each, but the specific behavior is generator-specific. The precise encoding used by any generator should be one that would allow each list item to be treated as a separate argument when used as program arguments on the system that the generator produces output for.
  • When a variable is referenced by <@(VAR) or >@(VAR):
    • The expansion must occur in list context.
    • The list item must be '<@(VAR)' or '>@(VAR)' exactly.
    • If VAR is a list, each of its elements are inserted into the list in which expansion is taking place, replacing the list item containing the variable reference.
    • If VAR is a string, the string is converted to a list which is inserted into the list in which expansion is taking place as above. The conversion into a list is generator-specific, but generally, spaces in the string are taken as separators between list items. The specific method of converting the string to a list should be the inverse of the encoding method used to expand list variables in string context, above.

GYP treats references to undefined variables as errors.

Command Expansions (<!, <!@)

Command expansions function similarly to variable expansions, but instead of resolving variable references, they cause GYP to execute a command at generation time and use the command’s output as the replacement. Command expansions are introduced by a less than and exclamation mark (<!).

In a command expansion, the entire string contained within the parentheses is passed to the system’s shell. The command’s output is assigned to a string value that may subsequently be expanded in list context in the same way as variable expansions if an 以上是关于binding.gyp参数说明书/文档/指南（GYP Input Format Reference）的主要内容，如果未能解决你的问题，请参考以下文章

如何在 binding.gyp node-gyp 中为 node.js 扩展添加对静态库的依赖

构建时的 node-gyp 链接库依赖项

Nodejs 使用 addons 调用c++ 初体验

在Linux 环境 运行 node-gyp configure 出错了，在线求助

使用 node-gyp 预定义变量 PRODUCT_DIR

STM32模拟IIC与IIC四种实现数字光强采集模块GY30（标准库与HAL库）