1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<?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>
|
