SCons/Tool/ninja/ninja.xml

   1 <?xml version="1.0"?>
   2 <!--
   3  MIT License
   4
   5  Copyright The SCons Foundation
   6
   7  Permission is hereby granted, free of charge, to any person obtaining
   8  a copy of this software and associated documentation files (the
   9  "Software"), to deal in the Software without restriction, including
  10  without limitation the rights to use, copy, modify, merge, publish,
  11  distribute, sublicense, and/or sell copies of the Software, and to
  12  permit persons to whom the Software is furnished to do so, subject to
  13  the following conditions:
  14
  15  The above copyright notice and this permission notice shall be included
  16  in all copies or substantial portions of the Software.
  17
  18  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  19  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  20  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  21  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  22  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  23  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  24  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25
  26
  27 This file is processed by the bin/SConsDoc.py module.
  28 See its __doc__ string for a discussion of the format.
  29 -->
  30
  31 <!DOCTYPE sconsdoc [
  32         <!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
  33         %scons;
  34         <!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
  35         %builders-mod;
  36         <!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
  37         %functions-mod;
  38         <!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
  39         %tools-mod;
  40         <!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
  41         %variables-mod;
  42         ]>
  43
  44 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  45           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  46           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  47
  48     <tool name="ninja">
  49         <summary>
  50             <para>
  51                 Sets up the &b-link-Ninja; builder, which generates a &ninja; build file, and then optionally runs &ninja;.
  52             </para>
  53             <note>
  54                 <para>This is an experimental feature.
  55                     This functionality is subject to change and/or removal without a deprecation cycle.
  56                 </para>
  57             </note>
  58
  59         </summary>
  60         <sets>
  61             <item>NINJA_DISABLE_AUTO_RUN</item>
  62             <item>NINJA_ALIAS_NAME</item>
  63             <item>NINJA_DIR</item>
  64             <item>NINJA_COMPDB_EXPAND</item>
  65             <item>NINJA_ENV_VAR_CACHE</item>
  66             <item>NINJA_FILE_NAME</item>
  67             <item>NINJA_GENERATED_SOURCE_SUFFIXES</item>
  68             <item>NINJA_GENERATED_SOURCE_ALIAS_NAME</item>
  69             <item>NINJA_MSVC_DEPS_PREFIX</item>
  70             <item>NINJA_DEPFILE_PARSE_FORMAT</item>
  71             <item>NINJA_POOL</item>
  72             <item>NINJA_REGENERATE_DEPS</item>
  73             <item>NINJA_SYNTAX</item>
  74             <item>NINJA_FORCE_SCONS_BUILD</item>
  75             <item>_NINJA_REGENERATE_DEPS_FUNC</item>
  76 <!--            <item>__NINJA_NO</item>-->
  77             <item>IMPLICIT_COMMAND_DEPENDENCIES</item>
  78             <item>NINJA_SCONS_DAEMON_KEEP_ALIVE</item>
  79             <item>NINJA_SCONS_DAEMON_PORT</item>
  80             <item>NINJA_CMD_ARGS</item>
  81
  82             <!-- TODO: Document these -->
  83             <!-- <item>NINJA_RULES</item>-->
  84             <!-- <item>NINJA_POOLS</item>-->
  85             <!-- <item>NINJA</item>-->
  86             <!-- <item>GENERATING_NINJA</item>-->
  87             <!-- <item>NINJA_DIR</item>-->
  88
  89         </sets>
  90
  91         <uses>
  92             <item>AR</item>
  93             <item>ARCOM</item>
  94             <item>ARFLAGS</item>
  95             <item>CC</item>
  96             <item>CCCOM</item>
  97             <item>CCDEPFLAGS</item>
  98             <item>CCFLAGS</item>
  99             <item>CXX</item>
 100             <item>CXXCOM</item>
 101             <item>ESCAPE</item>
 102             <item>LINK</item>
 103             <item>LINKCOM</item>
 104             <item>PLATFORM</item>
 105             <item>RANLIB</item>
 106             <item>RANLIBCOM</item>
 107             <item>SHCCCOM</item>
 108             <item>SHCXXCOM</item>
 109             <item>SHLINK</item>
 110             <item>SHLINKCOM</item>
 111             <item>PROGSUFFIX</item>
 112             <item>PRINT_CMD_LINE_FUNC</item>
 113             <!--<item>TEMPFILE</item>-->
 114
 115             <!-- TODO: Document these -->
 116             <!-- <item>NINJA_MAX_JOBS</item> -->
 117             <!-- <item>NINJA_SKIP</item> -->
 118             <!-- <item>NINJA_CUSTOM_HANDLERS</item> -->
 119
 120         </uses>
 121     </tool>
 122
 123     <builder name="Ninja">
 124         <summary>
 125             <para>
 126                 A special builder which
 127                 adds a target to create a Ninja build file.
 128                 The builder does not require any source files to be specified.
 129             </para>
 130             <note>
 131                 <para>This is an experimental feature. To enable it you must use one of the following methods
 132                 </para>
 133
 134 <!--            NOTE DO NOT INDENT example_commands CONTENTS AS IT WILL ALTER THE FORMATTING-->
 135                 <example_commands>
 136 # On the command line
 137 --experimental=ninja
 138
 139 # Or in your SConstruct
 140 SetOption('experimental', 'ninja')
 141                 </example_commands>
 142
 143                 <para>This functionality is subject to change and/or removal without deprecation cycle.</para>
 144
 145                 <para>
 146                     To use this tool you need to install the &Python; &ninja; package,
 147                     as the tool by default depends on being able to do an
 148                     <systemitem>import</systemitem> of the package
 149 <!--                    (although see &cv-link-__NINJA_NO;).-->
 150                     This can be done via:
 151                     <example_commands>
 152 python -m pip install ninja
 153                     </example_commands>
 154                 </para>
 155
 156             </note>
 157
 158             <para>
 159                 If called with no arguments,
 160                 the builder will default to a target name of
 161                 <filename>ninja.build</filename>.
 162             </para>
 163             <para>
 164                 If called with a single positional argument,
 165                 &scons; will "deduce" the target name from that source
 166                 argument, giving it the same name, and then
 167                 ignore the source.
 168                 This is the usual way to call the builder if a
 169                 non-default target name is wanted.
 170             </para>
 171             <para>
 172                 If called with either the
 173                 <parameter>target=</parameter>
 174                 or <parameter>source=</parameter> keyword arguments,
 175                 the value of the argument is taken as the target name.
 176                 If called with both, the
 177                 <parameter>target=</parameter>
 178                 value is used and <parameter>source=</parameter> is ignored.
 179                 If called with multiple sources,
 180                 the source list will be ignored,
 181                 since there is no way to deduce what the intent was;
 182                 in this case the default target name will be used.
 183             </para>
 184             <para>
 185                 <emphasis>Available since &scons; 4.2.</emphasis>
 186             </para>
 187         </summary>
 188     </builder>
 189
 190
 191     <cvar name="NINJA_GENERATED_SOURCE_SUFFIXES">
 192         <summary>
 193             <para>
 194                 The list of source file suffixes which are generated by &SCons; build steps.
 195                 All source files which match these suffixes will be added to the _generated_sources alias in the output
 196                 &ninja; build file.
 197                 Then all other source files will be made to depend on this in the &ninja; build file, forcing the
 198                 generated sources to be built first.
 199             </para>
 200         </summary>
 201     </cvar>
 202
 203     <cvar name="NINJA_GENERATED_SOURCE_ALIAS_NAME">
 204         <summary>
 205             <para>
 206                 A string matching the name of a user defined alias which represents a list of all generated sources.
 207                 This will prevent the auto-detection of generated sources from &cv-NINJA_GENERATED_SOURCE_SUFFIXES;.
 208                 Then all other source files will be made to depend on this in the &ninja; build file, forcing the
 209                 generated sources to be built first.
 210             </para>
 211         </summary>
 212     </cvar>
 213
 214     <cvar name="NINJA_MSVC_DEPS_PREFIX">
 215         <summary>
 216             <para>
 217                 The <parameter>msvc_deps_prefix</parameter> string.
 218                 Propagates directly into the generated &ninja; build file.
 219                 From Ninja's docs:
 220                 <quote>defines the string which should be stripped from msvc's <option>/showIncludes</option> output</quote>
 221             </para>
 222         </summary>
 223     </cvar>
 224
 225     <cvar name="NINJA_DEPFILE_PARSE_FORMAT">
 226         <summary>
 227             <para>
 228                 Determines the type of format ninja should expect when parsing header
 229                 include depfiles. Can be <option>msvc</option>, <option>gcc</option>, or <option>clang</option>.
 230                 The <option>msvc</option> option corresponds to <option>/showIncludes</option> format, and
 231                 <option>gcc</option> or <option>clang</option> correspond to <option>-MMD -MF</option>.
 232             </para>
 233         </summary>
 234     </cvar>
 235
 236     <cvar name="NINJA_DIR">
 237         <summary>
 238             <para>
 239                 The <parameter>builddir</parameter> value.
 240                 Propagates directly into the generated &ninja; build file.
 241                 From Ninja's docs:
 242                 <quote>
 243                     A directory for some Ninja output files. ... (You can also store other build output in this
 244                     directory.)
 245                 </quote>
 246             The default value is <filename>.ninja</filename>.
 247             </para>
 248         </summary>
 249     </cvar>
 250
 251     <cvar name="NINJA_REGENERATE_DEPS">
 252         <summary>
 253             <para>
 254                 A generator function used to create a &ninja; depfile which
 255                 includes all the files which would require
 256                 &SCons; to be invoked if they change.
 257                 Or a list of said files.
 258             </para>
 259         </summary>
 260     </cvar>
 261
 262     <cvar name="NINJA_COMPDB_EXPAND">
 263         <summary>
 264             <para>
 265                 Boolean value to instruct &ninja; to expand the command line arguments normally put into
 266                 response files.
 267                 If true, prevents unexpanded lines in the compilation database like
 268                 <quote><literal>gcc @rsp_file</literal></quote> and instead yields expanded lines like
 269                 <quote><literal>gcc -c -o myfile.o myfile.c -Ia -DXYZ</literal></quote>.
 270             </para>
 271             <para>
 272                 Ninja's compdb tool added the <option>-x</option> flag in Ninja V1.9.0
 273             </para>
 274         </summary>
 275     </cvar>
 276
 277     <cvar name="NINJA_ENV_VAR_CACHE">
 278         <summary>
 279             <para>
 280                 A string that sets the environment for any environment variables that
 281                 differ between the OS environment and the &SCons; execution environment.
 282             </para>
 283
 284             <para>
 285                 It will be compatible with the default shell of the operating system.
 286             </para>
 287
 288             <para>
 289                 If not explicitly set, &SCons; will generate this dynamically from the
 290                 execution environment stored in the current &consenv;
 291                 (e.g. <literal>env['ENV']</literal>)
 292                 where those values differ from the existing shell..
 293             </para>
 294         </summary>
 295     </cvar>
 296
 297     <cvar name="NINJA_POOL">
 298         <summary>
 299             <para>
 300                 Set the <parameter>ninja_pool</parameter> for this or all targets in scope for this env var.
 301             </para>
 302         </summary>
 303     </cvar>
 304
 305     <cvar name="NINJA_DISABLE_AUTO_RUN">
 306         <summary>
 307             <para>
 308                 Boolean. Default: <constant>False</constant>.
 309                 If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file.
 310             </para>
 311
 312             <para>
 313                 If not explicitly set, this will be set to <constant>True</constant>
 314                 if <option>--disable_execute_ninja</option> or
 315                 <code>SetOption('disable_execute_ninja', True)</code> is seen.
 316             </para>
 317         </summary>
 318     </cvar>
 319
 320 <!-- Internal for now
 321     <cvar name="__NINJA_NO">
 322         <summary>
 323             <para>
 324                 Internal flag. Used to tell &SCons; whether or not to try to import the &Python; &ninja; module.
 325                 This is set to True when being called by Ninja?
 326             </para>
 327         </summary>
 328     </cvar>
 329 -->
 330
 331     <cvar name="NINJA_FILE_NAME">
 332         <summary>
 333             <para>
 334                 The filename for the generated Ninja build file.
 335                 The default is <filename>ninja.build</filename>.
 336             </para>
 337         </summary>
 338     </cvar>
 339
 340     <cvar name="NINJA_ALIAS_NAME">
 341         <summary>
 342             <para>
 343                 The name of the alias target which will cause &SCons; to create the &ninja; build file,
 344                 and then (optionally) run &ninja;.
 345                 The default value is <literal>generate-ninja</literal>.
 346             </para>
 347         </summary>
 348     </cvar>
 349
 350     <cvar name="NINJA_SYNTAX">
 351         <summary>
 352             <para>
 353                 The path to a custom <filename>ninja_syntax.py</filename> file which is used in generation.
 354                 The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that
 355                 installation if &cv-NINJA_SYNTAX; is not explicitly set.
 356             </para>
 357         </summary>
 358     </cvar>
 359
 360     <cvar name="NINJA_FORCE_SCONS_BUILD">
 361         <summary>
 362             <para>
 363                 If true, causes the build nodes to callback to scons instead of using
 364                 &ninja; to build them. This is intended to be passed to the environment on the builder invocation.
 365                 It is useful if you have a build node which does something which is not easily translated into &ninja;.
 366             </para>
 367         </summary>
 368     </cvar>
 369
 370     <cvar name="_NINJA_REGENERATE_DEPS_FUNC">
 371         <summary>
 372             <para>
 373                 Internal value used to specify the function to call with argument env to generate the list of files
 374                 which if changed would require the &ninja; build file to be regenerated.
 375             </para>
 376         </summary>
 377     </cvar>
 378
 379     <cvar name="NINJA_SCONS_DAEMON_KEEP_ALIVE">
 380         <summary>
 381             <para>
 382                 The number of seconds for the SCons deamon launched by ninja to stay alive.
 383                 (Default: 180000)
 384             </para>
 385         </summary>
 386     </cvar>
 387
 388     <cvar name="NINJA_SCONS_DAEMON_PORT">
 389         <summary>
 390             <para>
 391                 The TCP/IP port for the SCons daemon to listen on.
 392                 <emphasis>NOTE: You cannot use a port already being listened to on your build machine.</emphasis>
 393                 (Default: random number between 10000,60000)
 394             </para>
 395         </summary>
 396     </cvar>
 397
 398     <cvar name="NINJA_CMD_ARGS">
 399         <summary>
 400             <para>
 401                 A string which will pass arguments through SCons to the ninja command when scons executes ninja.
 402                 Has no effect if &cv-NINJA_DISABLE_AUTO_RUN; is set.
 403             </para>
 404             <para>
 405                 This value can also be passed on the command line:
 406             </para>
 407             <example_commands>
 408 scons NINJA_CMD_ARGS=-v
 409 or
 410 scons NINJA_CMD_ARGS="-v -j 3"
 411             </example_commands>
 412         </summary>
 413     </cvar>
 414
 415
 416 </sconsdoc>