mirror of
https://github.com/Relintai/scons_gd.git
synced 2025-02-04 16:16:00 +01:00
417 lines
15 KiB
XML
417 lines
15 KiB
XML
|
<?xml version="1.0"?>
|
||
|
|
<!--
|
||
|
|
MIT License
|
||
|
|
|
||
|
|
Copyright The SCons Foundation
|
||
|
|
|
||
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
||
|
|
a copy of this software and associated documentation files (the
|
||
|
|
"Software"), to deal in the Software without restriction, including
|
||
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
||
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
||
|
|
permit persons to whom the Software is furnished to do so, subject to
|
||
|
|
the following conditions:
|
||
|
|
|
||
|
|
The above copyright notice and this permission notice shall be included
|
||
|
|
in all copies or substantial portions of the Software.
|
||
|
|
|
||
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
|
||
|
|
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
|
||
|
|
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||
|
|
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||
|
|
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||
|
|
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||
|
|
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||
|
|
|
||
|
|
|
||
|
|
This file is processed by the bin/SConsDoc.py module.
|
||
|
|
See its __doc__ string for a discussion of the format.
|
||
|
|
-->
|
||
|
|
|
||
|
|
<!DOCTYPE sconsdoc [
|
||
|
|
<!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
|
||
|
|
%scons;
|
||
|
|
<!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
|
||
|
|
%builders-mod;
|
||
|
|
<!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
|
||
|
|
%functions-mod;
|
||
|
|
<!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
|
||
|
|
%tools-mod;
|
||
|
|
<!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
|
||
|
|
%variables-mod;
|
||
|
|
]>
|
||
|
|
|
||
|
|
<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
|
||
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
|
|
xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
|
||
|
|
|
||
|
|
<tool name="ninja">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Sets up the &b-link-Ninja; builder, which generates a &ninja; build file, and then optionally runs &ninja;.
|
||
|
|
</para>
|
||
|
|
<note>
|
||
|
|
<para>This is an experimental feature.
|
||
|
|
This functionality is subject to change and/or removal without a deprecation cycle.
|
||
|
|
</para>
|
||
|
|
</note>
|
||
|
|
|
||
|
|
</summary>
|
||
|
|
<sets>
|
||
|
|
<item>NINJA_DISABLE_AUTO_RUN</item>
|
||
|
|
<item>NINJA_ALIAS_NAME</item>
|
||
|
|
<item>NINJA_DIR</item>
|
||
|
|
<item>NINJA_COMPDB_EXPAND</item>
|
||
|
|
<item>NINJA_ENV_VAR_CACHE</item>
|
||
|
|
<item>NINJA_FILE_NAME</item>
|
||
|
|
<item>NINJA_GENERATED_SOURCE_SUFFIXES</item>
|
||
|
|
<item>NINJA_GENERATED_SOURCE_ALIAS_NAME</item>
|
||
|
|
<item>NINJA_MSVC_DEPS_PREFIX</item>
|
||
|
|
<item>NINJA_DEPFILE_PARSE_FORMAT</item>
|
||
|
|
<item>NINJA_POOL</item>
|
||
|
|
<item>NINJA_REGENERATE_DEPS</item>
|
||
|
|
<item>NINJA_SYNTAX</item>
|
||
|
|
<item>NINJA_FORCE_SCONS_BUILD</item>
|
||
|
|
<item>_NINJA_REGENERATE_DEPS_FUNC</item>
|
||
|
|
<!-- <item>__NINJA_NO</item>-->
|
||
|
|
<item>IMPLICIT_COMMAND_DEPENDENCIES</item>
|
||
|
|
<item>NINJA_SCONS_DAEMON_KEEP_ALIVE</item>
|
||
|
|
<item>NINJA_SCONS_DAEMON_PORT</item>
|
||
|
|
<item>NINJA_CMD_ARGS</item>
|
||
|
|
|
||
|
|
<!-- TODO: Document these -->
|
||
|
|
<!-- <item>NINJA_RULES</item>-->
|
||
|
|
<!-- <item>NINJA_POOLS</item>-->
|
||
|
|
<!-- <item>NINJA</item>-->
|
||
|
|
<!-- <item>GENERATING_NINJA</item>-->
|
||
|
|
<!-- <item>NINJA_DIR</item>-->
|
||
|
|
|
||
|
|
</sets>
|
||
|
|
|
||
|
|
<uses>
|
||
|
|
<item>AR</item>
|
||
|
|
<item>ARCOM</item>
|
||
|
|
<item>ARFLAGS</item>
|
||
|
|
<item>CC</item>
|
||
|
|
<item>CCCOM</item>
|
||
|
|
<item>CCDEPFLAGS</item>
|
||
|
|
<item>CCFLAGS</item>
|
||
|
|
<item>CXX</item>
|
||
|
|
<item>CXXCOM</item>
|
||
|
|
<item>ESCAPE</item>
|
||
|
|
<item>LINK</item>
|
||
|
|
<item>LINKCOM</item>
|
||
|
|
<item>PLATFORM</item>
|
||
|
|
<item>RANLIB</item>
|
||
|
|
<item>RANLIBCOM</item>
|
||
|
|
<item>SHCCCOM</item>
|
||
|
|
<item>SHCXXCOM</item>
|
||
|
|
<item>SHLINK</item>
|
||
|
|
<item>SHLINKCOM</item>
|
||
|
|
<item>PROGSUFFIX</item>
|
||
|
|
<item>PRINT_CMD_LINE_FUNC</item>
|
||
|
|
<!--<item>TEMPFILE</item>-->
|
||
|
|
|
||
|
|
<!-- TODO: Document these -->
|
||
|
|
<!-- <item>NINJA_MAX_JOBS</item> -->
|
||
|
|
<!-- <item>NINJA_SKIP</item> -->
|
||
|
|
<!-- <item>NINJA_CUSTOM_HANDLERS</item> -->
|
||
|
|
|
||
|
|
</uses>
|
||
|
|
</tool>
|
||
|
|
|
||
|
|
<builder name="Ninja">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
A special builder which
|
||
|
|
adds a target to create a Ninja build file.
|
||
|
|
The builder does not require any source files to be specified.
|
||
|
|
</para>
|
||
|
|
<note>
|
||
|
|
<para>This is an experimental feature. To enable it you must use one of the following methods
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<!-- NOTE DO NOT INDENT example_commands CONTENTS AS IT WILL ALTER THE FORMATTING-->
|
||
|
|
<example_commands>
|
||
|
|
# On the command line
|
||
|
|
--experimental=ninja
|
||
|
|
|
||
|
|
# Or in your SConstruct
|
||
|
|
SetOption('experimental', 'ninja')
|
||
|
|
</example_commands>
|
||
|
|
|
||
|
|
<para>This functionality is subject to change and/or removal without deprecation cycle.</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To use this tool you need to install the &Python; &ninja; package,
|
||
|
|
as the tool by default depends on being able to do an
|
||
|
|
<systemitem>import</systemitem> of the package
|
||
|
|
<!-- (although see &cv-link-__NINJA_NO;).-->
|
||
|
|
This can be done via:
|
||
|
|
<example_commands>
|
||
|
|
python -m pip install ninja
|
||
|
|
</example_commands>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</note>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If called with no arguments,
|
||
|
|
the builder will default to a target name of
|
||
|
|
<filename>ninja.build</filename>.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If called with a single positional argument,
|
||
|
|
&scons; will "deduce" the target name from that source
|
||
|
|
argument, giving it the same name, and then
|
||
|
|
ignore the source.
|
||
|
|
This is the usual way to call the builder if a
|
||
|
|
non-default target name is wanted.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If called with either the
|
||
|
|
<parameter>target=</parameter>
|
||
|
|
or <parameter>source=</parameter> keyword arguments,
|
||
|
|
the value of the argument is taken as the target name.
|
||
|
|
If called with both, the
|
||
|
|
<parameter>target=</parameter>
|
||
|
|
value is used and <parameter>source=</parameter> is ignored.
|
||
|
|
If called with multiple sources,
|
||
|
|
the source list will be ignored,
|
||
|
|
since there is no way to deduce what the intent was;
|
||
|
|
in this case the default target name will be used.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<emphasis>Available since &scons; 4.2.</emphasis>
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</builder>
|
||
|
|
|
||
|
|
|
||
|
|
<cvar name="NINJA_GENERATED_SOURCE_SUFFIXES">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The list of source file suffixes which are generated by &SCons; build steps.
|
||
|
|
All source files which match these suffixes will be added to the _generated_sources alias in the output
|
||
|
|
&ninja; build file.
|
||
|
|
Then all other source files will be made to depend on this in the &ninja; build file, forcing the
|
||
|
|
generated sources to be built first.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_GENERATED_SOURCE_ALIAS_NAME">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
A string matching the name of a user defined alias which represents a list of all generated sources.
|
||
|
|
This will prevent the auto-detection of generated sources from &cv-NINJA_GENERATED_SOURCE_SUFFIXES;.
|
||
|
|
Then all other source files will be made to depend on this in the &ninja; build file, forcing the
|
||
|
|
generated sources to be built first.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_MSVC_DEPS_PREFIX">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The <parameter>msvc_deps_prefix</parameter> string.
|
||
|
|
Propagates directly into the generated &ninja; build file.
|
||
|
|
From Ninja's docs:
|
||
|
|
<quote>defines the string which should be stripped from msvc's <option>/showIncludes</option> output</quote>
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_DEPFILE_PARSE_FORMAT">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Determines the type of format ninja should expect when parsing header
|
||
|
|
include depfiles. Can be <option>msvc</option>, <option>gcc</option>, or <option>clang</option>.
|
||
|
|
The <option>msvc</option> option corresponds to <option>/showIncludes</option> format, and
|
||
|
|
<option>gcc</option> or <option>clang</option> correspond to <option>-MMD -MF</option>.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_DIR">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The <parameter>builddir</parameter> value.
|
||
|
|
Propagates directly into the generated &ninja; build file.
|
||
|
|
From Ninja's docs:
|
||
|
|
<quote>
|
||
|
|
A directory for some Ninja output files. ... (You can also store other build output in this
|
||
|
|
directory.)
|
||
|
|
</quote>
|
||
|
|
The default value is <filename>.ninja</filename>.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_REGENERATE_DEPS">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
A generator function used to create a &ninja; depfile which
|
||
|
|
includes all the files which would require
|
||
|
|
&SCons; to be invoked if they change.
|
||
|
|
Or a list of said files.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_COMPDB_EXPAND">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Boolean value to instruct &ninja; to expand the command line arguments normally put into
|
||
|
|
response files.
|
||
|
|
If true, prevents unexpanded lines in the compilation database like
|
||
|
|
<quote><literal>gcc @rsp_file</literal></quote> and instead yields expanded lines like
|
||
|
|
<quote><literal>gcc -c -o myfile.o myfile.c -Ia -DXYZ</literal></quote>.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Ninja's compdb tool added the <option>-x</option> flag in Ninja V1.9.0
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_ENV_VAR_CACHE">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
A string that sets the environment for any environment variables that
|
||
|
|
differ between the OS environment and the &SCons; execution environment.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
It will be compatible with the default shell of the operating system.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If not explicitly set, &SCons; will generate this dynamically from the
|
||
|
|
execution environment stored in the current &consenv;
|
||
|
|
(e.g. <literal>env['ENV']</literal>)
|
||
|
|
where those values differ from the existing shell..
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_POOL">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Set the <parameter>ninja_pool</parameter> for this or all targets in scope for this env var.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_DISABLE_AUTO_RUN">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Boolean. Default: <constant>False</constant>.
|
||
|
|
If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If not explicitly set, this will be set to <constant>True</constant>
|
||
|
|
if <option>--disable_execute_ninja</option> or
|
||
|
|
<code>SetOption('disable_execute_ninja', True)</code> is seen.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<!-- Internal for now
|
||
|
|
<cvar name="__NINJA_NO">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Internal flag. Used to tell &SCons; whether or not to try to import the &Python; &ninja; module.
|
||
|
|
This is set to True when being called by Ninja?
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
-->
|
||
|
|
|
||
|
|
<cvar name="NINJA_FILE_NAME">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The filename for the generated Ninja build file.
|
||
|
|
The default is <filename>ninja.build</filename>.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_ALIAS_NAME">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The name of the alias target which will cause &SCons; to create the &ninja; build file,
|
||
|
|
and then (optionally) run &ninja;.
|
||
|
|
The default value is <literal>generate-ninja</literal>.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_SYNTAX">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The path to a custom <filename>ninja_syntax.py</filename> file which is used in generation.
|
||
|
|
The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that
|
||
|
|
installation if &cv-NINJA_SYNTAX; is not explicitly set.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_FORCE_SCONS_BUILD">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
If true, causes the build nodes to callback to scons instead of using
|
||
|
|
&ninja; to build them. This is intended to be passed to the environment on the builder invocation.
|
||
|
|
It is useful if you have a build node which does something which is not easily translated into &ninja;.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="_NINJA_REGENERATE_DEPS_FUNC">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
Internal value used to specify the function to call with argument env to generate the list of files
|
||
|
|
which if changed would require the &ninja; build file to be regenerated.
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_SCONS_DAEMON_KEEP_ALIVE">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The number of seconds for the SCons deamon launched by ninja to stay alive.
|
||
|
|
(Default: 180000)
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_SCONS_DAEMON_PORT">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
The TCP/IP port for the SCons daemon to listen on.
|
||
|
|
<emphasis>NOTE: You cannot use a port already being listened to on your build machine.</emphasis>
|
||
|
|
(Default: random number between 10000,60000)
|
||
|
|
</para>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
<cvar name="NINJA_CMD_ARGS">
|
||
|
|
<summary>
|
||
|
|
<para>
|
||
|
|
A string which will pass arguments through SCons to the ninja command when scons executes ninja.
|
||
|
|
Has no effect if &cv-NINJA_DISABLE_AUTO_RUN; is set.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
This value can also be passed on the command line:
|
||
|
|
</para>
|
||
|
|
<example_commands>
|
||
|
|
scons NINJA_CMD_ARGS=-v
|
||
|
|
or
|
||
|
|
scons NINJA_CMD_ARGS="-v -j 3"
|
||
|
|
</example_commands>
|
||
|
|
</summary>
|
||
|
|
</cvar>
|
||
|
|
|
||
|
|
|
||
|
|
</sconsdoc>
|