| blob | 6f48356e405f55ee2e277672566c9434c12c87ed |
1 <?xml version="1.0"?>
2 <!--
3 SPDX-License-Identifier: MIT
5 Copyright The SCons Foundation
7 This file is processed by the bin/SConsDoc.py module.
8 See its __doc__ string for a discussion of the format.
9 -->
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 ]>
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">
28 <tool name="javac">
29 <summary>
30 <para>
31 Sets construction variables for the &javac; compiler.
32 </para>
33 </summary>
34 <sets>
35 <item>JAVAC</item>
36 <item>JAVACFLAGS</item>
37 <item>JAVACCOM</item>
38 <item>JAVACLASSSUFFIX</item>
39 <item>JAVAINCLUDES</item>
40 <item>JAVASUFFIX</item>
41 <item>JAVABOOTCLASSPATH</item>
42 <item>JAVACLASSPATH</item>
43 <item>JAVASOURCEPATH</item>
44 </sets>
45 <uses>
46 <item>JAVACCOMSTR</item>
47 </uses>
48 </tool>
50 <builder name="Java">
51 <summary>
52 <para>
53 Builds one or more Java class files.
54 The sources may be any combination of explicit
55 <filename>.java</filename>
56 files,
57 or directory trees which will be scanned
58 for <filename>.java</filename> files.
59 </para>
61 <para>
62 SCons will parse each source <filename>.java</filename> file
63 to find the classes
64 (including inner classes)
65 defined within that file,
66 and from that figure out the
67 target <filename>.class</filename> files that will be created.
68 The class files will be placed underneath
69 the specified target directory.
70 </para>
72 <para>
73 SCons will also search each Java file
74 for the Java package name,
75 which it assumes can be found on a line
76 beginning with the string
77 <literal>package</literal>
78 in the first column;
79 the resulting <filename>.class</filename> files
80 will be placed in a directory reflecting
81 the specified package name.
82 For example,
83 the file
84 <filename>Foo.java</filename>
85 defining a single public
86 <classname>Foo</classname>
87 class and
88 containing a package name of
89 <classname>sub.dir</classname>
90 will generate a corresponding
91 <filename>sub/dir/Foo.class</filename>
92 class file.
93 </para>
95 <para>
96 Examples:
97 </para>
99 <example_commands>
100 env.Java(target='classes', source='src')
101 env.Java(target='classes', source=['src1', 'src2'])
102 env.Java(target='classes', source=['File1.java', 'File2.java'])
103 </example_commands>
105 <para>
106 Java source files can use the native encoding for the underlying OS.
107 Since SCons compiles in simple ASCII mode by default,
108 the compiler will generate warnings about unmappable characters,
109 which may lead to errors as the file is processed further.
110 In this case, the user must specify the
111 <literal>LANG</literal>
112 environment variable to tell the compiler what encoding is used.
113 For portibility, it's best if the encoding is hard-coded
114 so that the compile will work if it is done on a system
115 with a different encoding.
116 </para>
118 <example_commands>
119 env = Environment()
120 env['ENV']['LANG'] = 'en_GB.UTF-8'
121 </example_commands>
122 </summary>
123 </builder>
125 <cvar name="JAVABOOTCLASSPATH">
126 <summary>
127 <para>
128 Specifies the location of the bootstrap class files.
129 Can be specified as a string or Node object,
130 or as a list of strings or Node objects.
131 </para>
132 <para>
133 The value will be added to the JDK command lines
134 via the <option>-bootclasspath</option> option,
135 which requires a system-specific search path separator.
136 This will be supplied by &SCons; as needed when it
137 constructs the command line if &cv-JAVABOOTCLASSPATH; is
138 provided in list form.
139 If &cv-JAVABOOTCLASSPATH; is a single string containing
140 search path separator characters
141 (<literal>:</literal> for POSIX systems or
142 <literal>;</literal> for Windows), it will not be modified;
143 and so is inherently system-specific;
144 to supply the path in a system-independent manner,
145 give &cv-JAVABOOTCLASSPATH; as a list of paths instead.
146 </para>
147 <note>
148 <para>
149 Can only be used when compiling for releases prior to JDK 9.
150 </para>
151 </note>
152 </summary>
153 </cvar>
155 <cvar name="JAVAPROCESSORPATH">
156 <summary>
157 <para>
158 Specifies the location of the annotation processor class files.
159 Can be specified as a string or Node object,
160 or as a list of strings or Node objects.
161 </para>
162 <para>
163 The value will be added to the JDK command lines
164 via the <option>-processorpath</option> option,
165 which requires a system-specific search path separator.
166 This will be supplied by &SCons; as needed when it
167 constructs the command line if &cv-JAVAPROCESSORPATH; is
168 provided in list form.
169 If &cv-JAVAPROCESSORPATH; is a single string containing
170 search path separator characters
171 (<literal>:</literal> for POSIX systems or
172 <literal>;</literal> for Windows), it will not be modified;
173 and so is inherently system-specific;
174 to supply the path in a system-independent manner,
175 give &cv-JAVAPROCESSORPATH; as a list of paths instead.
176 </para>
177 <para>
178 <emphasis>New in version 4.5.0</emphasis>
179 </para>
180 </summary>
181 </cvar>
183 <cvar name="JAVAINCLUDES">
184 <summary>
185 <para>
186 Include path for Java header files
187 (such as <filename>jni.h</filename>).
188 </para>
189 </summary>
190 </cvar>
192 <cvar name="JAVAC">
193 <summary>
194 <para>
195 The Java compiler.
196 </para>
197 </summary>
198 </cvar>
200 <cvar name="JAVACCOM">
201 <summary>
202 <para>
203 The command line used to compile a directory tree containing
204 Java source files to
205 corresponding Java class files.
206 Any options specified in the &cv-link-JAVACFLAGS; construction variable
207 are included on this command line.
208 </para>
209 </summary>
210 </cvar>
212 <cvar name="JAVACCOMSTR">
213 <summary>
214 <para>
215 The string displayed when compiling
216 a directory tree of Java source files to
217 corresponding Java class files.
218 If this is not set, then &cv-link-JAVACCOM; (the command line) is displayed.
219 </para>
221 <example_commands>
222 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
223 </example_commands>
224 </summary>
225 </cvar>
227 <cvar name="JAVACFLAGS">
228 <summary>
229 <para>
230 General options that are passed to the Java compiler.
231 </para>
232 </summary>
233 </cvar>
235 <cvar name="JAVACLASSDIR">
236 <summary>
237 <para>
238 The directory in which Java class files may be found.
239 This is stripped from the beginning of any Java
240 <filename>.class</filename>
241 file names supplied to the &b-link-JavaH; builder.
242 </para>
243 </summary>
244 </cvar>
246 <cvar name="JAVACLASSPATH">
247 <summary>
248 <para>
249 Specifies the class search path for the JDK tools.
250 Can be specified as a string or Node object,
251 or as a list of strings or Node objects.
252 Class path entries may be directory names to search
253 for class files or packages, pathnames to archives
254 (<filename>.jar</filename> or <filename>.zip</filename>)
255 containing classes, or paths ending in a "base name wildcard"
256 character (<literal>*</literal>), which matches files
257 in that directory with a <filename>.jar</filename> suffix.
258 See the Java documentation for more details.
259 </para>
260 <para>
261 The value will be added to the JDK command lines
262 via the <option>-classpath</option> option,
263 which requires a system-specific search path separator.
264 This will be supplied by &SCons; as needed when it
265 constructs the command line if &cv-JAVACLASSPATH; is
266 provided in list form.
267 If &cv-JAVACLASSPATH; is a single string containing
268 search path separator characters
269 (<literal>:</literal> for POSIX systems or
270 <literal>;</literal> for Windows),
271 it will be split on the separator into a list of individual
272 paths for dependency scanning purposes.
273 It will not be modified for JDK command-line usage,
274 so such a string is inherently system-specific;
275 to supply the path in a system-independent manner,
276 give &cv-JAVACLASSPATH; as a list of paths instead.
277 </para>
278 <note>
279 <para>
280 &SCons; <emphasis role="bold">always</emphasis>
281 supplies a <option>-sourcepath</option>
282 when invoking the Java compiler &javac;,
283 regardless of the setting of &cv-link-JAVASOURCEPATH;,
284 as it passes the path(s) to the source(s) supplied
285 in the call to the &b-link-Java; builder via
286 <option>-sourcepath</option> .
287 From the documentation of the standard Java toolkit for &javac;:
288 <quote>If not compiling code for modules, if the
289 <option>--source-path</option> or <option>-sourcepath</option>
290 option is not specified, then the user class path is also
291 searched for source files.</quote>
292 Since <option>-sourcepath</option> is always supplied,
293 &javac; will not use the contents of the value of
294 &cv-JAVACLASSPATH; when searching for sources.
295 </para>
296 </note>
297 </summary>
298 </cvar>
300 <cvar name="JAVACLASSSUFFIX">
301 <summary>
302 <para>
303 The suffix for Java class files;
304 <filename>.class</filename>
305 by default.
306 </para>
307 </summary>
308 </cvar>
310 <cvar name="JAVASOURCEPATH">
311 <summary>
312 <para>
313 Specifies the list of directories that
314 will be searched for input (source)
315 <filename>.java</filename> files.
316 Can be specified as a string or Node object,
317 or as a list of strings or Node objects.
318 </para>
319 <para>
320 The value will be added to the JDK command lines
321 via the <option>-sourcepath</option> option,
322 which requires a system-specific search path separator,
323 This will be supplied by &SCons; as needed when it
324 constructs the command line if &cv-JAVASOURCEPATH; is
325 provided in list form.
326 If &cv-JAVASOURCEPATH; is a single string containing
327 search path separator characters
328 (<literal>:</literal> for POSIX systems or
329 <literal>;</literal> for Windows), it will not be modified,
330 and so is inherently system-specific;
331 to supply the path in a system-independent manner,
332 give &cv-JAVASOURCEPATH; as a list of paths instead.
333 </para>
334 <para>
335 Note that the specified directories are only added to
336 the command line via the <option>-sourcepath</option> option.
337 &SCons; does not currently search the
338 &cv-JAVASOURCEPATH; directories for dependent
339 <filename>.java</filename>
340 files.
341 </para>
342 </summary>
343 </cvar>
345 <cvar name="JAVASUFFIX">
346 <summary>
347 <para>
348 The suffix for Java files;
349 <filename>.java</filename>
350 by default.
351 </para>
352 </summary>
353 </cvar>
355 <cvar name="JAVAVERSION">
356 <summary>
357 <para>
358 Specifies the Java version being used by the &b-link-Java;
359 builder. Set this to specify the version of Java targeted
360 by the &javac; compiler.
361 This is sometimes necessary because
362 Java 1.5 changed the file names that are created
363 for nested anonymous inner classes,
364 which can cause a mismatch with the files
365 that &SCons; expects will be generated by the &javac; compiler.
366 Setting &cv-JAVAVERSION; to a version greater than
367 <literal>1.4</literal> makes &SCons; realize that a build
368 with such a compiler is actually up to date.
369 The default is <literal>1.4</literal>.
370 </para>
371 <para>
372 While this is <emphasis>not</emphasis> primarily intended for
373 selecting one version of the Java compiler vs. another,
374 it does have that effect on the Windows platform. A
375 more precise approach is to set &cv-link-JAVAC; (and related
376 &consvars; for related utilities) to the path to the specific
377 Java compiler you want, if that is not the default compiler.
378 On non-Windows platforms, the
379 <systemitem>alternatives</systemitem> system may provide a
380 way to adjust the default Java compiler without
381 having to specify explicit paths.
382 </para>
383 </summary>
384 </cvar>
386 </sconsdoc>