scons_gd/scons/SCons/Tool/compilation_db.xml

<?xml version="1.0"?>
<!--
__COPYRIGHT__

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="compilation_db">
        <summary>
            <para>
                Sets up &b-link-CompilationDatabase; builder which generates a clang tooling compatible compilation database.
            </para>
        </summary>
        <sets>
            <item>COMPILATIONDB_COMSTR</item>
<!--
            <item>__COMPILATIONDB_UACTION</item>
            <item>__COMPILATIONDB_UOUTPUT</item>
            <item>__COMPILATIONDB_USOURCE</item>
            <item>__COMPILATIONDB_ENV</item>
-->
            <item>COMPILATIONDB_USE_ABSPATH</item>
            <item>COMPILATIONDB_PATH_FILTER</item>
        </sets>
    </tool>

    <builder name="CompilationDatabase">
        <summary>
            <para>
                &b-CompilationDatabase; is a special builder which
                adds a target to create a JSON formatted
                compilation database compatible with
                <systemitem>clang</systemitem> tooling
                (see the
                <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">LLVM specification</ulink>).
                This database is suitable for consumption by various
                tools and editors who can use it to obtain build and
                dependency information which otherwise would be
                internal to &SCons;.
                The builder does not require any source files to be specified,
                rather it arranges to emit information about all
                of the C, C++ and assembler source/output pairs
                identified in the build that are not excluded by the
                optional filter &cv-link-COMPILATIONDB_PATH_FILTER;.
                The target is subject to the usual &SCons; target
                selection rules.
            </para>
            <para>
                If called with no arguments,
                the builder will default to a target name of
                <filename>compile_commands.json</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>
            <note>
              <para>
                You must load the &t-compilation_db; tool prior to specifying
                any part of your build or some source/output
                files will not show up in the compilation database.
              </para>
            </note>
            <para>
                <emphasis>Available since &scons; 4.0.</emphasis>
            </para>
        </summary>
    </builder>

    <cvar name="COMPILATIONDB_COMSTR">
        <summary>
            <para>
                The string displayed when the &b-link-CompilationDatabase;
                builder's action is run.
            </para>
        </summary>
    </cvar>

    <cvar name="COMPILATIONDB_USE_ABSPATH">
        <summary>
            <para>
                A boolean flag to instruct &b-link-CompilationDatabase;
                whether to write the <literal>file</literal> and
                <literal>output</literal> members
                in the compilation database using absolute or relative paths.
            </para>
            <para>
                The default value is False (use relative paths)
            </para>
        </summary>
    </cvar>

    <cvar name="COMPILATIONDB_PATH_FILTER">
        <summary>
            <para>
                A string which instructs &b-link-CompilationDatabase; to
                only include entries where the <literal>output</literal> member
                matches the pattern in the filter string using fnmatch, which
                uses glob style wildcards.

            </para>
            <para>
                The default value is an empty string '', which disables filtering.
            </para>
        </summary>
    </cvar>
<!--  Internal env vars for use by CompilationDatabase builder/pseudobuilder only   -->
<!--    <cvar name="__COMPILATIONDB_UACTION">-->
<!--        <summary>-->
<!--            <para>-->
<!--                This variable stores the action for building a target.-->
<!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
<!--            </para>-->
<!--        </summary>-->
<!--    </cvar>-->
<!--    <cvar name="__COMPILATIONDB_UOUTPUT">-->
<!--        <summary>-->
<!--            <para>-->
<!--                This variable stores the action for building a target.-->
<!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
<!--            </para>-->
<!--        </summary>-->
<!--    </cvar>-->
<!--    <cvar name="__COMPILATIONDB_USOURCE">-->
<!--        <summary>-->
<!--            <para>-->
<!--                This variable stores the action for building a target.-->
<!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
<!--            </para>-->
<!--        </summary>-->
<!--    </cvar>-->
<!--    <cvar name="__COMPILATIONDB_ENV">-->
<!--        <summary>-->
<!--            <para>-->
<!--                This variable stores the action for building a target.-->
<!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
<!--            </para>-->
<!--        </summary>-->
<!--    </cvar>-->


</sconsdoc>