SCons/Tool/compilation_db.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright 2020 MongoDB Inc.
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12         <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  13         %scons;
  14         <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  15         %builders-mod;
  16         <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  17         %functions-mod;
  18         <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  19         %tools-mod;
  20         <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  21         %variables-mod;
  22         ]>
  23
  24 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  25           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  26           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  27
  28     <tool name="compilation_db">
  29         <summary>
  30             <para>
  31                 Sets up &b-link-CompilationDatabase; builder which generates a clang tooling compatible compilation database.
  32             </para>
  33         </summary>
  34         <sets>
  35             <item>COMPILATIONDB_COMSTR</item>
  36 <!--
  37             <item>__COMPILATIONDB_UACTION</item>
  38             <item>__COMPILATIONDB_UOUTPUT</item>
  39             <item>__COMPILATIONDB_USOURCE</item>
  40             <item>__COMPILATIONDB_ENV</item>
  41 -->
  42             <item>COMPILATIONDB_USE_ABSPATH</item>
  43             <item>COMPILATIONDB_PATH_FILTER</item>
  44         </sets>
  45     </tool>
  46
  47     <builder name="CompilationDatabase">
  48         <summary>
  49             <para>
  50                 &b-CompilationDatabase; is a special builder which
  51                 adds a target to create a JSON formatted
  52                 compilation database compatible with
  53                 <systemitem>clang</systemitem> tooling
  54                 (see the
  55                 <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">LLVM specification</ulink>).
  56                 This database is suitable for consumption by various
  57                 tools and editors who can use it to obtain build and
  58                 dependency information which otherwise would be
  59                 internal to &SCons;.
  60                 The builder does not require any source files to be specified,
  61                 rather it arranges to emit information about all
  62                 of the C, C++ and assembler source/output pairs
  63                 identified in the build that are not excluded by the
  64                 optional filter &cv-link-COMPILATIONDB_PATH_FILTER;.
  65                 The target is subject to the usual &SCons; target
  66                 selection rules.
  67             </para>
  68             <para>
  69                 If called with no arguments,
  70                 the builder will default to a target name of
  71                 <filename>compile_commands.json</filename>.
  72             </para>
  73             <para>
  74                 If called with a single positional argument,
  75                 &scons; will "deduce" the target name from that source
  76                 argument, giving it the same name, and then
  77                 ignore the source.
  78                 This is the usual way to call the builder if a
  79                 non-default target name is wanted.
  80             </para>
  81             <para>
  82                 If called with either the <parameter>target=</parameter>
  83                 or <parameter>source=</parameter> keyword arguments,
  84                 the value of the argument is taken as the target name.
  85                 If called with both, the <parameter>target=</parameter>
  86                 value is used and <parameter>source=</parameter> is ignored.
  87                 If called with multiple sources,
  88                 the source list will be ignored,
  89                 since there is no way to deduce what the intent was;
  90                 in this case the default target name will be used.
  91             </para>
  92             <note>
  93               <para>
  94                 You must load the &t-compilation_db; tool prior to specifying
  95                 any part of your build or some source/output
  96                 files will not show up in the compilation database.
  97               </para>
  98             </note>
  99             <para>
 100                 <emphasis>Available since &scons; 4.0.</emphasis>
 101             </para>
 102         </summary>
 103     </builder>
 104
 105     <cvar name="COMPILATIONDB_COMSTR">
 106         <summary>
 107             <para>
 108                 The string displayed when the &b-link-CompilationDatabase;
 109                 builder's action is run.
 110             </para>
 111         </summary>
 112     </cvar>
 113
 114     <cvar name="COMPILATIONDB_USE_ABSPATH">
 115         <summary>
 116             <para>
 117                 A boolean flag to instruct &b-link-CompilationDatabase;
 118                 whether to write the <literal>file</literal> and
 119                 <literal>output</literal> members
 120                 in the compilation database using absolute or relative paths.
 121             </para>
 122             <para>
 123                 The default value is False (use relative paths)
 124             </para>
 125         </summary>
 126     </cvar>
 127
 128     <cvar name="COMPILATIONDB_PATH_FILTER">
 129         <summary>
 130             <para>
 131                 A string which instructs &b-link-CompilationDatabase; to
 132                 only include entries where the <literal>output</literal> member
 133                 matches the pattern in the filter string using fnmatch, which
 134                 uses glob style wildcards.
 135
 136             </para>
 137             <para>
 138                 The default value is an empty string '', which disables filtering.
 139             </para>
 140         </summary>
 141     </cvar>
 142 <!--  Internal env vars for use by CompilationDatabase builder/pseudobuilder only   -->
 143 <!--    <cvar name="__COMPILATIONDB_UACTION">-->
 144 <!--        <summary>-->
 145 <!--            <para>-->
 146 <!--                This variable stores the action for building a target.-->
 147 <!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
 148 <!--            </para>-->
 149 <!--        </summary>-->
 150 <!--    </cvar>-->
 151 <!--    <cvar name="__COMPILATIONDB_UOUTPUT">-->
 152 <!--        <summary>-->
 153 <!--            <para>-->
 154 <!--                This variable stores the action for building a target.-->
 155 <!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
 156 <!--            </para>-->
 157 <!--        </summary>-->
 158 <!--    </cvar>-->
 159 <!--    <cvar name="__COMPILATIONDB_USOURCE">-->
 160 <!--        <summary>-->
 161 <!--            <para>-->
 162 <!--                This variable stores the action for building a target.-->
 163 <!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
 164 <!--            </para>-->
 165 <!--        </summary>-->
 166 <!--    </cvar>-->
 167 <!--    <cvar name="__COMPILATIONDB_ENV">-->
 168 <!--        <summary>-->
 169 <!--            <para>-->
 170 <!--                This variable stores the action for building a target.-->
 171 <!--                It's intended for internal usage by &b-link-CompilationDatabase; only.-->
 172 <!--            </para>-->
 173 <!--        </summary>-->
 174 <!--    </cvar>-->
 175
 176
 177 </sconsdoc>