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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<!--
Copyright 2001 Steven Knight
-- >
<para>
The &scons; utility builds software (or other files)
by determining which component pieces must be rebuilt
and executing the necessary commands to rebuild them.
</para>
<para>
By default, &scons; searches for a file named &SConstruct;,
&Sconstruct; or &sconstruct (in that order) in the current directory
and reads its configuration from the first file found. An alternate
file name may be specified via the <option>-f</option> option. If
the specified file is not in the local directory, &scons; will
internally change its working directory (chdir) to the directory
containing the file.
</para>
<para>
The configuration file specifies the files to be built, and
(optionally) the rules to build those files. Reasonable default
rules exist for building common software components (executable
programs, object files, libraries), so that for simple software
projects, only the target and input files need be specified.
<!--
See
.IR scconsfile (5)
for information about the contents of
&scons;
configuration files.
-- >
</para>
<para>
&scons; can scan known input files automatically for dependency
information (for example, <literal>#include</literal> statements
in C or C++ files) and will rebuild dependent files appropriately
whenever any "included" input file changes. &scons; supports the
ability to define new scanners for unknown input file types.
</para>
<para>
&scons; is normally executed in a top-level directory containing a
&SConstruct; file, specifying the target or targets to be built as
command-line arguments. The command
</para>
<screen>
scons .
</screen>
<para>
will build all target files in or below the current directory
( <filename>.</filename>).
</para>
<screen>
scons /
</screen>
<para>
will build all target files in or below the root directory (i.e.,
all files). Specific targets may be supplied:
</para>
<screen>
scons foo bar
</screen>
<para>
Targets may be omitted from the command line,
in which case the targets specified
in the configuration file(s) as
<function>Default</function>
targets will be built:
</para>
<screen>
scons
</screen>
<para>
Specifying "cleanup" targets in configuration files is not
necessary. The <option>-c</option> flag removes all files
necessary to build the specified target:
</para>
<screen>
# removes all target files
scons -c .
# removes all target files under the specified subdirectories
scons -c build export
</screen>
<para>
A subset of a hierarchical tree may be built by:
</para>
<orderedlist>
<listitem>
<para>
remaining at the top-level directory (where the &SConstruct;
file lives) and specifying the subdirectory as the target to be
built:
</para>
<screen>
scons src/subdir
</screen>
</listitem>
<listitem>
<para>
changing directory and invoking sccons with the
<option>-u</option> option, which traverses up the directory
hierarchy until it finds the &SConstruct; file, and then builds
targets relatively to the current subdirectory:
</para>
<screen>
cd src/subdir
scons -u .
</screen>
</listitem>
</orderedlist>
<para>
&scons; supports building multiple targets in parallel via a
<option>-j</option> option that takes, as its argument, the number
of simultaneous tasks that may be spawned:
</para>
<screen>
# build four targets in parallel
&scons; -j 4
</screen>
<para>
Values of variables to be passed to the configuration file(s)
may be specified on the command line:
</para>
<screen>
&scons; debug=1 .
</screen>
<para>
These variables can be used in the configuration file(s) to modify
the build in any way.
</para>
<para>
&scons; can maintain a cache of target (derived) files that can
be shared between multiple builds. When caching is enabled in a
configuration file, any target files built by &scons; will be copied
to the cache. If an up-to-date target file is found in the cache, it
will be retrieved from the cache instead of being rebuilt locally.
Caching behavior may be disabled and controlled in other ways by the
<option>--cache-force</option>, <option>--cache-disable</option>,
and <option>--cache-show</option> command-line options. The
<option>--random</option> is useful whenever multiple builds may be
trying to update the cache simultaneously.
</para>
|
