| blob | 014d905e95c33adb7bf41345ca3391ea92495239 |
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="JAVAINCLUDES">
156 <summary>
157 <para>
158 Include path for Java header files
159 (such as <filename>jni.h</filename>).
160 </para>
161 </summary>
162 </cvar>
164 <cvar name="JAVAC">
165 <summary>
166 <para>
167 The Java compiler.
168 </para>
169 </summary>
170 </cvar>
172 <cvar name="JAVACCOM">
173 <summary>
174 <para>
175 The command line used to compile a directory tree containing
176 Java source files to
177 corresponding Java class files.
178 Any options specified in the &cv-link-JAVACFLAGS; construction variable
179 are included on this command line.
180 </para>
181 </summary>
182 </cvar>
184 <cvar name="JAVACCOMSTR">
185 <summary>
186 <para>
187 The string displayed when compiling
188 a directory tree of Java source files to
189 corresponding Java class files.
190 If this is not set, then &cv-link-JAVACCOM; (the command line) is displayed.
191 </para>
193 <example_commands>
194 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
195 </example_commands>
196 </summary>
197 </cvar>
199 <cvar name="JAVACFLAGS">
200 <summary>
201 <para>
202 General options that are passed to the Java compiler.
203 </para>
204 </summary>
205 </cvar>
207 <cvar name="JAVACLASSDIR">
208 <summary>
209 <para>
210 The directory in which Java class files may be found.
211 This is stripped from the beginning of any Java
212 <filename>.class</filename>
213 file names supplied to the &b-link-JavaH; builder.
214 </para>
215 </summary>
216 </cvar>
218 <cvar name="JAVACLASSPATH">
219 <summary>
220 <para>
221 Specifies the class search path for the JDK tools.
222 Can be specified as a string or Node object,
223 or as a list of strings or Node objects.
224 Class path entries may be directory names to search
225 for class files or packages, pathnames to archives
226 (<filename>.jar</filename> or <filename>.zip</filename>)
227 containing classes, or paths ending in a "base name wildcard"
228 character (<literal>*</literal>), which matches files
229 in that directory with a <filename>.jar</filename> suffix.
230 See the Java documentation for more details.
231 </para>
232 <para>
233 The value will be added to the JDK command lines
234 via the <option>-classpath</option> option,
235 which requires a system-specific search path separator.
236 This will be supplied by &SCons; as needed when it
237 constructs the command line if &cv-JAVACLASSPATH; is
238 provided in list form.
239 If &cv-JAVACLASSPATH; is a single string containing
240 search path separator characters
241 (<literal>:</literal> for POSIX systems or
242 <literal>;</literal> for Windows),
243 it will be split on the separator into a list of individual
244 paths for dependency scanning purposes.
245 It will not be modified for JDK command-line usage,
246 so such a string is inherently system-specific;
247 to supply the path in a system-independent manner,
248 give &cv-JAVACLASSPATH; as a list of paths instead.
249 </para>
250 <note>
251 <para>
252 &SCons; <emphasis role="bold">always</emphasis>
253 supplies a <option>-sourcepath</option>
254 when invoking the Java compiler &javac;,
255 regardless of the setting of &cv-link-JAVASOURCEPATH;,
256 as it passes the path(s) to the source(s) supplied
257 in the call to the &b-link-Java; builder via
258 <option>-sourcepath</option> .
259 From the documentation of the standard Java toolkit for &javac;:
260 <quote>If not compiling code for modules, if the
261 <option>--source-path</option> or <option>-sourcepath</option>
262 option is not specified, then the user class path is also
263 searched for source files.</quote>
264 Since <option>-sourcepath</option> is always supplied,
265 &javac; will not use the contents of the value of
266 &cv-JAVACLASSPATH; when searching for sources.
267 </para>
268 </note>
269 </summary>
270 </cvar>
272 <cvar name="JAVACLASSSUFFIX">
273 <summary>
274 <para>
275 The suffix for Java class files;
276 <filename>.class</filename>
277 by default.
278 </para>
279 </summary>
280 </cvar>
282 <cvar name="JAVASOURCEPATH">
283 <summary>
284 <para>
285 Specifies the list of directories that
286 will be searched for input (source)
287 <filename>.java</filename> files.
288 Can be specified as a string or Node object,
289 or as a list of strings or Node objects.
290 </para>
291 <para>
292 The value will be added to the JDK command lines
293 via the <option>-sourcepath</option> option,
294 which requires a system-specific search path separator,
295 This will be supplied by &SCons; as needed when it
296 constructs the command line if &cv-JAVASOURCEPATH; is
297 provided in list form.
298 If &cv-JAVASOURCEPATH; is a single string containing
299 search path separator characters
300 (<literal>:</literal> for POSIX systems or
301 <literal>;</literal> for Windows), it will not be modified,
302 and so is inherently system-specific;
303 to supply the path in a system-independent manner,
304 give &cv-JAVASOURCEPATH; as a list of paths instead.
305 </para>
306 <para>
307 Note that the specified directories are only added to
308 the command line via the <option>-sourcepath</option> option.
309 &SCons; does not currently search the
310 &cv-JAVASOURCEPATH; directories for dependent
311 <filename>.java</filename>
312 files.
313 </para>
314 </summary>
315 </cvar>
317 <cvar name="JAVASUFFIX">
318 <summary>
319 <para>
320 The suffix for Java files;
321 <filename>.java</filename>
322 by default.
323 </para>
324 </summary>
325 </cvar>
327 <cvar name="JAVAVERSION">
328 <summary>
329 <para>
330 Specifies the Java version being used by the &b-link-Java;
331 builder. Set this to specify the version of Java targeted
332 by the &javac; compiler.
333 This is sometimes necessary because
334 Java 1.5 changed the file names that are created
335 for nested anonymous inner classes,
336 which can cause a mismatch with the files
337 that &SCons; expects will be generated by the &javac; compiler.
338 Setting &cv-JAVAVERSION; to a version greater than
339 <literal>1.4</literal> makes &SCons; realize that a build
340 with such a compiler is actually up to date.
341 The default is <literal>1.4</literal>.
342 </para>
343 <para>
344 While this is <emphasis>not</emphasis> primarily intended for
345 selecting one version of the Java compiler vs. another,
346 it does have that effect on the Windows platform. A
347 more precise approach is to set &cv-link-JAVAC; (and related
348 &consvars; for related utilities) to the path to the specific
349 Java compiler you want, if that is not the default compiler.
350 On non-Windows platforms, the
351 <systemitem>alternatives</systemitem> system may provide a
352 way to adjust the default Java compiler without
353 having to specify explicit paths.
354 </para>
355 </summary>
356 </cvar>
358 </sconsdoc>