From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/java.in | 657 ------------------------------------------------------- 1 file changed, 657 deletions(-) delete mode 100644 doc/user/java.in (limited to 'doc/user/java.in') diff --git a/doc/user/java.in b/doc/user/java.in deleted file mode 100644 index 5744055..0000000 --- a/doc/user/java.in +++ /dev/null @@ -1,657 +0,0 @@ - - - - - So far, we've been using examples of - building C and C++ programs - to demonstrate the features of &SCons;. - &SCons; also supports building Java programs, - but Java builds are handled slightly differently, - which reflects the ways in which - the Java compiler and tools - build programs differently than - other languages' tool chains. - - - -
- Building Java Class Files: the &b-Java; Builder - - - - The basic activity when programming in Java, - of course, is to take one or more .java files - containing Java source code - and to call the Java compiler - to turn them into one or more - .class files. - In &SCons;, you do this - by giving the &b-link-Java; Builder - a target directory in which - to put the .class files, - and a source directory that contains - the .java files: - - - - - - Java('classes', 'src') - - - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - - - - If the src directory contains - three .java source files, - then running &SCons; might look like this: - - - - - scons -Q - - - - - &SCons; will actually search the src - directory tree for all of the .java files. - The Java compiler will then create the - necessary class files in the classes subdirectory, - based on the class names found in the .java files. - - - -
- -
- How &SCons; Handles Java Dependencies - - - - In addition to searching the source directory for - .java files, - &SCons; actually runs the .java files - through a stripped-down Java parser that figures out - what classes are defined. - In other words, &SCons; knows, - without you having to tell it, - what .class files - will be produced by the &javac; call. - So our one-liner example from the preceding section: - - - - - - Java('classes', 'src') - - - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - public class AdditionalClass1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example2 - { - class Inner2 { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - } - - - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - public class AdditionalClass3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - - - - Will not only tell you reliably - that the .class files - in the classes subdirectory - are up-to-date: - - - - - scons -Q - scons -Q classes - - - - - But it will also remove all of the generated - .class files, - even for inner classes, - without you having to specify them manually. - For example, if our - Example1.java - and - Example3.java - files both define additional classes, - and the class defined in Example2.java - has an inner class, - running scons -c - will clean up all of those .class files - as well: - - - - - scons -Q - scons -Q -c classes - - - - - To ensure correct handling of .class - dependencies in all cases, you need to tell &SCons; which Java - version is being used. This is needed because Java 1.5 changed - the .class file names for nested anonymous - inner classes. Use the JAVAVERSION construction - variable to specify the version in use. With Java 1.6, the - one-liner example can then be defined like this: - - - - - Java('classes', 'src', JAVAVERSION='1.6') - - - - See JAVAVERSION in the man page for more information. - - -
- -
- Building Java Archive (<filename>.jar</filename>) Files: the &b-Jar; Builder - - - - After building the class files, - it's common to collect them into - a Java archive (.jar) file, - which you do by calling the &b-link-Jar; Builder method. - If you want to just collect all of the - class files within a subdirectory, - you can just specify that subdirectory - as the &b-Jar; source: - - - - - - Java(target = 'classes', source = 'src') - Jar(target = 'test.jar', source = 'classes') - - - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - - - - &SCons; will then pass that directory - to the &jar; command, - which will collect all of the underlying - .class files: - - - - - scons -Q - - - - - If you want to keep all of the - .class files - for multiple programs in one location, - and only archive some of them in - each .jar file, - you can pass the &b-Jar; builder a - list of files as its source. - It's extremely simple to create multiple - .jar files this way, - using the lists of target class files created - by calls to the &b-link-Java; builder - as sources to the various &b-Jar; calls: - - - - - - prog1_class_files = Java(target = 'classes', source = 'prog1') - prog2_class_files = Java(target = 'classes', source = 'prog2') - Jar(target = 'prog1.jar', source = prog1_class_files) - Jar(target = 'prog2.jar', source = prog2_class_files) - - - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - public class Example4 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - - - - This will then create - prog1.jar - and prog2.jar - next to the subdirectories - that contain their .java files: - - - - - scons -Q - - -
- -
- Building C Header and Stub Files: the &b-JavaH; Builder - - - - You can generate C header and source files - for implementing native methods, - by using the &b-link-JavaH; Builder. - There are several ways of using the &JavaH; Builder. - One typical invocation might look like: - - - - - - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = 'native', source = classes) - - - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - - - - - - The source is a list of class files generated by the - call to the &b-link-Java; Builder, - and the target is the output directory in - which we want the C header files placed. - The target - gets converted into the - when &SCons; runs &javah;: - - - - - scons -Q - - - - - In this case, - the call to &javah; - will generate the header files - native/pkg_sub_Example1.h, - native/pkg_sub_Example2.h - and - native/pkg_sub_Example3.h. - Notice that &SCons; remembered that the class - files were generated with a target directory of - classes, - and that it then specified that target directory - as the option - to the call to &javah;. - - - - - - Although it's more convenient to use - the list of class files returned by - the &b-Java; Builder - as the source of a call to the &b-JavaH; Builder, - you can - specify the list of class files - by hand, if you prefer. - If you do, - you need to set the - &cv-link-JAVACLASSDIR; construction variable - when calling &b-JavaH;: - - - - - - Java(target = 'classes', source = 'src/pkg/sub') - class_file_list = ['classes/pkg/sub/Example1.class', - 'classes/pkg/sub/Example2.class', - 'classes/pkg/sub/Example3.class'] - JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes') - - - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - - - - - - The &cv-JAVACLASSDIR; value then - gets converted into the - when &SCons; runs &javah;: - - - - - scons -Q - - - - - Lastly, if you don't want a separate header file - generated for each source file, - you can specify an explicit File Node - as the target of the &b-JavaH; Builder: - - - - - - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = File('native.h'), source = classes) - - - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - - - - - - Because &SCons; assumes by default - that the target of the &b-JavaH; builder is a directory, - you need to use the &File; function - to make sure that &SCons; doesn't - create a directory named native.h. - When a file is used, though, - &SCons; correctly converts the file name - into the &javah; option: - - - - - scons -Q - - -
- -
- Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder - - - - You can generate Remote Method Invocation stubs - by using the &b-link-RMIC; Builder. - The source is a list of directories, - typically returned by a call to the &b-link-Java; Builder, - and the target is an output directory - where the _Stub.class - and _Skel.class files will - be placed: - - - - - - classes = Java(target = 'classes', source = 'src/pkg/sub') - RMIC(target = 'outdir', source = classes) - - - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - - - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - - - - - - As it did with the &b-link-JavaH; Builder, - &SCons; remembers the class directory - and passes it as the option - to &rmic;: - - - - - scons -Q - - - - - This example would generate the files - outdir/pkg/sub/Example1_Skel.class, - outdir/pkg/sub/Example1_Stub.class, - outdir/pkg/sub/Example2_Skel.class and - outdir/pkg/sub/Example2_Stub.class. - - - -
-- cgit v1.2.3