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