<?xml version="1.0"?>
<!--
SPDX-License-Identifier: MIT
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module
-->

<!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 call back 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 daemon 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>
