Référence des règles de grammaire gyp et utilisation des outils

 

Republié depuis : http://www.cnblogs.com/nanvann/p/3913880.html

Traduit de  https://code.google.com/p/gyp/wiki/GypLanguageSpecification

but et contexte

Google a utilisé de nombreux systèmes de création de projets indépendants de la plate-forme, tels que Scons et CMake . Ceux-ci ne peuvent pas répondre aux exigences en utilisation réelle. Lors du développement d'applications complexes, Xcode est plus adapté sur Mac et Visual Studio sur Windows est le meilleur choix.
gyp est un outil de génération de projet créé pour les projets Chromium, qui peut générer des fichiers de projet Visual Studio, Xcode et Makefile dépendant de la plate-forme à partir de configurations indépendantes de la plate-forme. De cette façon, nous n'avons pas besoin de passer plus de temps à gérer différentes configurations de projet pour chaque plate-forme et les dépendances entre les projets.

aperçu

Gyp a grosso modo les caractéristiques suivantes :

• Les fichiers de configuration se terminent par .gyp
• Chaque fichier .gyp décrit comment construire le projet

• Chaque fichier .gyp génère plusieurs fichiers de projet spécifiques à la plate-forme :

  • Sur Mac, le fichier .gyp génère le fichier de projet Xcode, qui contient comment construire le projet. Un fichier .gyp générera un .xcodeproj
  • Sous Windows, les fichiers .gyp génèrent des fichiers de projet Visual Studio. Un fichier .gyp génère un .sln et un .vcproj pour chaque cible
  • Sous Linux, le fichier .gyp génère le Makefile
• La syntaxe du fichier .gyp est le format de données Python (format Json)
• Le fichier .gypi peut être inclus par le fichier .gyp , ce qui est pratique pour les paramètres unifiés

• Les données de la configuration se présentent sous la forme de paires clé-valeur

conception détaillée

Directives de conception :

• Cohérence des mots clés : tous les mots clés sont identiques aux champs de configuration de projet du projet de plate-forme
• La plate-forme spécifique à laquelle appartient la configuration est indiquée par un préfixe. Par exemple : msvs_disabled_warnings,xcode_framework_dirs

goûter

{
  'target_defaults': {
    'defines': [
      'U_STATIC_IMPLEMENTATION',
      ['LOGFILE', 'foo.log',],
    ],
    'include_dirs': [
      '..',
    ],
  },
  'targets': [
    {
      'target_name': 'foo',
      'type': 'static_library',
      'sources': [
        'foo/src/foo.cc',
        'foo/src/foo_main.cc',
      ],
      'include_dirs': [
         'foo',
         'foo/include',
      ],
      'conditions': [
         [ 'OS==mac', { 'sources': [ 'platform_test_mac.mm' ] } ]
      ],
      'direct_dependent_settings': {
        'defines': [
          'UNIT_TEST',
        ],
        'include_dirs': [
          'foo',
          'foo/include',
        ],
      },
    },
  ],
} 

Élément structurel

Certaines cibles et règles de construction sont définies dans le fichier .gyp .

Les mots clés suivants peuvent être définis au niveau supérieur :

• conditions : définition de la condition. Voir *****conditions*****
• inclut : liste des fichiers .gypi inclus

  {
   'targets':[
   {
   'target_name': 'Thread',
   'type': 'executable',
   'includes': [
   '../common.gypi',
   './thread.gypi',
   ]
   ...
   }
   ],
  }
  

• target_defaults : la configuration de projet par défaut, la configuration de chaque projet (cibles) doit hériter de cette configuration
• cibles : liste des projets

  {
   'targets': [
   {
   'target_name': 'hello1',
   'product_extension': 'stuff',
   'type': 'executable',
   'sources': [
   'hello.c',
   ],
   },
   {
   'target_name': 'hello2',
   'target_extension': 'stuff',
   'type': 'executable',
   'sources': [
   'hello.c',
   ],
   }
   ]
  }
  

• variables : définit les paires clé-valeur, qui peuvent être <(varname)référencées ailleurs

  {
   'variables': {
   'pi': 'import math; print math.pi',
   'third_letters': "<(other_letters)HIJK",
   'letters_list': 'ABCD',
   'other_letters': '<(letters_list)EFG',
   'check_included': '<(included_variable)',
   'check_lists': [
   '<(included_variable)',
   '<(third_letters)',
   ],
   'check_int': 5,
   'check_str_int': '6',
   'check_list_int': [
   7,
   '8',
   9,
   ],
   'not_int_1': ' 10',
   'not_int_2': '11 ',
   'not_int_3': '012',
   'not_int_4': '13.0',
   'not_int_5': '+14',
   'negative_int': '-15',
   'zero_int': '0',
   },
   ...
  }
  

projet (cibles)

Un fichier .gyp définit un ensemble de règles pour la construction d'un projet. Les cibles peuvent également contenir includes, conditionset variables. Voici quelques-uns des champs propriétaires dans les cibles :

• target_name : spécifiez le nom de la cible définie
• type : le type de cible. Prise en charge de executable, et  . Parmi eux, les types sont également utiles et peuvent être utilisés comme types pour traiter des ressources, des documents et d'autres éléments spéciaux. Par exemple, sous Windows, existerait en tant que projet de type ensemble d'outilsstatic_libraryshared_librarynonenonenone
• product_extension : Spécifie l'extension de la cible cible générée, ne contient pas de '.'
• product_name : spécifiez le nom de fichier de la cible générée cible et product_extensionformez un nom de fichier complet
• dépendances : spécifiez les autres cibles dont dépend la cible

  {
   'targets': [
   {
   'target_name': 'a',
   'type': 'static_library',
   'dependencies': [
   'b/b.gyp:b',
   'c/c.gyp:*'
   ],
   'sources': [
   'a.c',
   ],
   },
   ],
  }
  

• Définit : définit les macros de prétraitement. Semblable à l'option -D ou /D dans la compilation de ligne de commande C/C++

  {
   'targets': [
   {
   'target_name': 'defines',
   'type': 'executable',
   'defines': [
   'FOO',
   'VALUE=1',
   'PAREN_VALUE=(1+2+3)',
   'HASH_VALUE="a#1"',
   ],
   'sources': [
   'defines.c',
   ],
   },
   ]
  }
  

• include_dirs : spécifie le répertoire dans lequel rechercher les fichiers d'inclusion. Semblable à l'option -I ou /I dans la compilation de ligne de commande C/C++

  {
   'targets': [
   {
   'target_name': 'includes',
   'type': 'executable',
   'dependencies': [
   'subdir/subdir_includes.gyp:subdir_includes',
   ],
   'cflags': [
   '-Ishadow1',
   ],
   'include_dirs': [
   '.',
   'inc1',
   'shadow2',
   'subdir/inc2',
   ],
   'sources': [
   'includes.c',
   ],
   },
   ],
  }
  

• sources : répertorie les fichiers de code du projet et certains fichiers liés au projet. sources!Les fichiers exclus peuvent être spécifiés dans la section
• configurations : un ensemble de configurations de construction définies pour les cibles. voir *****configurations*****
• link_settings : spécifiez la bibliothèque que la cible doit lier. executableEt shared_libraryle type de cible doit spécifier la bibliothèque de liens. Dans cette section, vous pouvez spécifier toutes les configurations pouvant être incluses dans la cible, à l'exception de configurations, target_nameet . typepeut être comparé all_dependent_settingavecdirect_dependent_setting
• direct_dependent_settings : spécifiez les paramètres cibles qui dépendent de cette cible. Dans cette section, vous pouvez spécifier toutes les configurations pouvant être incluses dans la cible, à l'exception de configurations, target_nameet . typepeut être comparé all_dependent_settingaveclink_settings
• all_dependent_settings :
• bibliothèques : spécifiez les bibliothèques dont dépend la cible, voirlink_settings>libraries

  ...
  'link_settings': {
   'libraries': [
   'libiconv.dylib',
   '<(ZLIB_DIR)contrib/minizip/libminizip.a',
   'libcurl.dylib',
   ],
  },
  ...
  

• actions : définit un ensemble d'actions de construction personnalisées pour les fichiers d'entrée. Voir *****actions*****
• copies : définit un ensemble d'actions de copie. voir *****copies*****
• règles: Voir *****règles (règles)*****
• conditions_cibles : similaire aux conditions, mais l'heure de début est postérieure aux conditions
• msvs_precompiled_header : spécifie le fichier d'en-tête précompilé. Uniquement pour Visual Studio
• msvs_precompiled_source : spécifie le fichier source précompilé. Uniquement pour Visual Studio
• msvs_prebuild : avant les événements de génération. Uniquement pour Visual Studio
• msvs_postbuild : événement de post-construction. Uniquement pour Visual Studio

  'msvs_postbuild': r'copy "$(OutDir)$(TargetName)" "C:\$(TargetName)"

• msvs_props : spécifie le fichier de page de propriétés (.vsprops) de la cible. Uniquement pour Visual Studio
• msvs_cygwin_shell : spécifie que l'action s'exécute sous cygwin. Uniquement pour Visual Studio
• msvs_cygwin_dirs : spécifiez le répertoire de cygwin. Uniquement pour Visual Studio
• xcode_config_file : dans xcode, spécifiez le fichier de configuration cible (.xcconfig). uniquement pour xcode
• xcode_framework_dirs : dans xcode, spécifiez le répertoire du framework. uniquement pour xcode

configurations

configurationsLes segments peuvent être dans targetset target_defaultssegments. configurationsImpossible de remplacer l'élément spécifié target_defaultspar .

Parfois, nous devons spécifier plusieurs configurations pour le projet, telles que Debug, Release. Le paragraphe suivant est la configuration générale sous Windows :

...
'configurations': {
 'Debug': {
 'msvs_settings': {
 'VCCLCompilerTool': {
 # 多线程调试 DLL (/MDd)
 'RuntimeLibrary': '3',
 # 不优化 /Od
 'Optimization': '0',
 # 用于“编辑并继续”的程序数据库 (/ZI)
 'DebugInformationFormat': '4',
 },
 'VCLinkerTool': {
 'GenerateDebugInformation': 'true',
 'GenerateMapFile': 'false',
 # 'SubSystem': '1',
 },
 },
 }, # Debug
 'Release': {
 'msvs_settings': {
 'VCCLCompilerTool': {
 # 多线程 DLL (/MD)
 'RuntimeLibrary': '2',
 # 完全优化 /Os
 'Optimization': '2',
 # 使用内部函数 /Oi
 'EnableIntrinsicFunctions': 'true',
 # 程序数据库 (/Zi)
 'DebugInformationFormat': '3',
 },
 'VCLinkerTool': {
 'GenerateDebugInformation': 'true',
 'GenerateMapFile': 'false',
 },
 },
 }, # Release
},
...

conditions

conditionset target_conditonspeut apparaître .gyp文件n'importe où. conditionsLes instructions .gypsont traitées dès que le fichier est chargé target_conditionset les instructions sont traitées une fois que toutes les dépendances ont été traitées. Après avoir chargé les données complètes et partielles, utilisez la fonction eval()
de Python pour traiter la chaîne de condition.

Actions

actionsFournit des fonctions pour le traitement personnalisé des entrées et sorties, chacune comportant les champs suivants :

• action_name : le nom de l'action, certaines plateformes peuvent ignorer ce champ
• entrées : informations d'entrée, utilisées comme build incrémentiel
• outputs : informations de sortie, utilisées comme build incrémentiel
• action : commande de construction
• message : le message affiché lors de la construction

Le système de construction comparera inputssi outputsles fichiers dans et ont été modifiés, et ne s'exécutera que s'ils ont été modifiés action.
Dans Xcode, il est implémenté via un script shell ; dans Visual Studio, une implémentation personnalisée de VCCustomBuildTool est incluse via FileConfiguration.

'sources': [
 # libraries.cc is generated by the js2c action below.
 '<(INTERMEDIATE_DIR)/libraries.cc',
],
'actions': [
 {
 'variables': {
 'core_library_files': [
 'src/runtime.js',
 'src/v8natives.js',
 'src/macros.py',
 ],
 },
 'action_name': 'js2c',
 'inputs': [
 'tools/js2c.py',
 '<@(core_library_files)',
 ],
 'outputs': [
 '<(INTERMEDIATE_DIR)/libraries.cc',
 '<(INTERMEDIATE_DIR)/libraries-empty.cc',
 ],
 'action': ['python', 'tools/js2c.py', '<@(outputs)', 'CORE', '<@(corelibrary_files)'],
 },
],

règles

rulesLa fonction de construction personnalisée est fournie, et chaque élément comporte les champs suivants :

• rule_name : le nom de la règle, certaines plateformes peuvent ignorer ce champ
• extension : Dans ce livre target, tous les fichiers source avec cette extension utilisent cette règle lors de la construction
• entrées : règles de construction dépendantes
• outputs : informations de sortie, utilisées comme build incrémentiel. RULE_INPUT_*Les variables suivantes sont accessibles
• action : commande de construction. RULE_INPUT_*Les variables suivantes sont accessibles
• message : Le message affiché lors de la construction. RULE_INPUT_*Les variables suivantes sont accessibles

Cette variable est accessible dans outputs, actionet message:

• RULE_INPUT_PATH : le chemin complet de l'entrée actuelle
• RULE_INPUT_DIRNAME : répertoire d'entrée actuel
• RULE_INPUT_NAME : le nom de l'entrée actuelle
• RULE_INPUT_ROOT : l'entrée actuelle supprime l'extension
• RULE_INPUT_EXT : l'extension de l'entrée actuelle

{
  'targets': [
    {
      'target_name': 'program',
      'type': 'executable',
      'msvs_cygwin_shell': 0,
      'sources': [
        'main.c',
        'prog1.in',
        'prog2.in',
      ],
      'rules': [
        {
          'rule_name': 'make_sources',
          'extension': 'in',
          'inputs': [
            'make-sources.py',
          ],
          'outputs': [
            '<(INTERMEDIATE_DIR)/<(RULE_INPUT_ROOT).c',
            '<(INTERMEDIATE_DIR)/<(RULE_INPUT_ROOT).h',
          ],
          'action': [
            'python', '<(_inputs)', '<(RULE_INPUT_NAME)', '<@(_outputs)',
          ],
          'process_outputs_as_sources': 1,
        },
      ],
    },
  ],
}

rulesa quelques similitudes avec actions.

copie

copiesFournit une fonction de copie de fichier simple, chaque élément a les champs suivants :

• destination : le dossier de destination de la copie
• fichiers : liste des fichiers à copier

copiesdestinationUn fichier portant le même nom sera créé.

{
  'targets': [
    {
      'target_name': 'copies1',
      'type': 'none',
      'copies': [
        {
          'destination': 'copies-out',
          'files': [
            'file1',
          ],
        },
      ],
    },
    {
      'target_name': 'copies2',
      'type': 'none',
      'copies': [
        {
          'destination': '<(PRODUCT_DIR)/copies-out',
          'files': [
            'file2',
          ],
        },
      ],
    },
    # 拷贝目录
    {
      'target_name': 'copies3',
      'type': 'none',
      'copies': [
        {
          'destination': '<(PRODUCT_DIR)/copies-out',
          'files': [
            'directory/',
          ],
        },
      ],
    },
  ],
}

Dénomination du fichier de code

Les règles de nommage des fichiers dépendant de la plate-forme sont *_win.{ext}, et . Par exemple:*_mac.{ext}*_linux.{ext}*_posix.{ext}

• _win : foo_win.cpp
• _mac : foo_mac.cpp,foo_mac.mm
• _linux : foo_linux.cpp
• _posix : foo_posix.cpp

code source gyp

Pour certains endroits non répertoriés et controversés dans la documentation, le plus fiable est de regarder gyple code source et les exemples. gypLe code de test est très détaillé et peut être utilisé comme référence pour apprendre des exemples.

Utiliser l'IDE pour déboguer le projet Makefile généré

Le débogage sous Linux utilise généralement gdb, mais il n'est pas facile de s'y mettre directement si vous ne le connaissez pas. QtCreator est recommandé ici Bien sûr, Netbeans et Eclipse CDT sont également disponibles, mais ce n'est pas aussi pratique et efficace que QtCreator.

configuration commune  common.gypi

 {
  'includes': [
    'env.gypi'  
  ],
  'include_dirs': [
    '.',
  ],
  'configurations': {
    'Debug': {
      'defines': [
        'DEBUG',
      ],
    },
    'Release': {
      'defines': [
        'NDEBUG',
      ],
    },
  }, # configurations
  'conditions': [
    ['OS=="win"', {
      'defines': [
        'WIN32',
        'UNICODE',
        '_UNICODE',
        'OS_WIN',
      ],
      'msbuild_configuration_attributes': {
        'IntermediateDirectory': '$(OutDir)__BuildTemp\\$(ProjectName)\\',
      },
      'msbuild_toolset': {
        #'PlatformToolset': 'v100'
      }, # msbuild_toolset
      'msvs_settings': {
        'VCCLCompilerTool': {
          'WarningLevel': '3',
          'DisableSpecificWarnings': ['4251','4996'],
          'WarnAsError': 'true',
        },
        'VCLinkerTool': {
          'AdditionalDependencies': [
            'kernel32.lib',
            'user32.lib',
          ],
          'AdditionalLibraryDirectories': [],
        },
      }, # msvs_settings
      'configurations': {
        'Debug': {
          'msvs_settings': {
            'VCCLCompilerTool': {
              # 多线程调试 DLL (/MDd)
              'RuntimeLibrary': '3',
              # 不优化 /Od
              'Optimization': '0',
              # 用于“编辑并继续”的程序数据库 (/ZI)
              'DebugInformationFormat': '4',
            },
            'VCLinkerTool': {
              'GenerateDebugInformation': 'true',
              'GenerateMapFile': 'false',
              # 'SubSystem': '1',
            },
          }, # msvs_settings
        }, # Debug
        'Release': {
          'msvs_settings': {
            'VCCLCompilerTool': {
              # 多线程 DLL (/MD)
              'RuntimeLibrary': '2',
              # 完全优化 /Os
              'Optimization': '2',
              # 使用内部函数 /Oi
              'EnableIntrinsicFunctions': 'true',
              # 程序数据库 (/Zi)
              'DebugInformationFormat': '3',
            },
            'VCLinkerTool': {
              'GenerateDebugInformation': 'true',
              'GenerateMapFile': 'false',
            },
          }, # msvs_settings
        }, # Release
      }, # configurations
    }], # Windows
    ['OS=="mac"', {
      'make_global_settings': [
        ['CC', '/usr/bin/clang'],
        ['CXX', '/usr/bin/clang++'],
       ],
      
      'defines': [
        'OS_POSIX',
        'OS_MACOSX',
      ],
      'xcode_settings': {
        'ALWAYS_SEARCH_USER_PATHS': 'NO',
        #'i386', 'x86_64'
        'ARCHS': [ 'x86_64' ],
        'MACOSX_DEPLOYMENT_TARGET': '10.6',
        'CC': 'clang',
        'GCC_VERSION': 'com.apple.compilers.llvm.clang.1_0',
        'CLANG_CXX_LANGUAGE_STANDARD': 'c++0x',
        # libstdc++, c++11, libc++
        'CLANG_CXX_LIBRARY': 'libstdc++',
        'GCC_ENABLE_OBJC_GC': 'unsupported',
        #'LIBRARY_SEARCH_PATHS': [],
        'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
        'GCC_SYMBOLS_PRIVATE_EXTERN': 'NO',
        'DEBUG_INFORMATION_FORMAT': 'dwarf-with-dsym',
        #'DEPLOYMENT_POSTPROCESSING': 'YES',
        'OTHER_CFLAGS': [
          '-fno-eliminate-unused-debug-symbols',
          '-mmacosx-version-min=10.6',
          # compile use oc++
          '-x objective-c++',
        ],
        'WARNING_CFLAGS': ['-Wno-deprecated-declarations'],
        'WARNING_CFLAGS!': ['-Wall', '-Wextra',],
        'WARNING_CXXFLAGS': ['-Wstrict-aliasing', '-Wno-deprecated',],
      }, # xcode_settings
      'link_settings': {
        'libraries': [
          '$(SDKROOT)/System/Library/Frameworks/Foundation.framework',
        ],
      },
      'libraries': [],
      'mac_framework_dirs': [],
      'configurations': {
        'Debug': {
          'xcode_settings': {
            'GCC_DEBUGGING_SYMBOLS': 'full',
            'STRIP_INSTALLED_PRODUCT': 'YES',
            'GCC_OPTIMIZATION_LEVEL': '0',
            'OTHER_CFLAGS': ['-g',],
            'OTHER_CXXFLAGS': ['-g',],
          }, # xcode_settings
        }, # Debug
        'Release': {
          'xcode_settings': {
            'GCC_OPTIMIZATION_LEVEL': 's',
          }, # xcode_settings
        }, # Release
      }, # configurations
    }], # Mac
    ['OS=="linux"', {
      'defines': [
        'OS_POSIX',
        'OS_LINUX',
      ],
      'cflags': [
        # Support 64-bit shared libs (also works fine for 32-bit).
        '-fPIC',
        '-std=c++11',
        '-fstrict-aliasing',
        '-Wall',
        '-Wextra',
        '-Wshadow',
        '-Wconversion',
        #'-Wpadded',
        '-Wstrict-aliasing=2',
        '-Wstrict-overflow=4',
      ],
      'ldflags': [],
      'configurations': {
        'Debug': {
          'cflags': [
            '-g',
            '-C',
          ],
        },
        'Release': {
          'cflags': [
            '-O2',
          ],
        },
      }, # configurations
    }], # Linux
  ], # conditions
}

ligne de commande gyp

• --depth: Problèmes d'historique de chrome, doivent être réglés sur.
• --generator-out: Définir le dossier de sortie du projet généré
• --f: Définir le type de projet généré, s'il n'est pas défini, le type de projet généré sera déterminé en fonction de la plateforme. Les valeurs disponibles sont : msvs, xcode,make

• --G: Définissez les autres paramètres d'indicateur générés, cette valeur est liée à la plate-forme spécifique.

  • msvs_version : spécifie la version du projet Visual Studio généré. Si elle n'est pas définie, le projet sera généré en fonction de la dernière version de Visual Studio installée sur le système. Les valeurs disponibles sont 2005, 2005e, 2008, 2008e, 2010, , 2010e, 2012, 2012e, 2013. 2013ePar exemple: --Gmsvs_version=2010
• --toplevel-dir: Définissez le répertoire racine du code source, la valeur par défaut prendra --depthla valeur spécifiée
• -D: Passez des variables à .gyp, qui peuvent être <(varname)lues de cette façon. Par exemple:-Dbuildtype=share_library

• --no-circular-check:

L'écriture de la documentation de l'API est une chose très pénible, et je continuerai à l'ajouter à l'avenir.