nmake Java Build Support

:JAVA: Assertion Operator

:JAVA: - Java source dependency operator

Description

The :JAVA: operator has the format:

:JAVA: files-or-directories

Java files to be built are specified by the right hand side arguments. There must be at least one right hand side argument. Each right hand side argument specifies a pathname and may be one of the following types:

file

Pathname of a .java source file. Shell pathname expansion patterns such as *.java work as expected. This is typically, but not necessarily, a relative pathname.

directory

Pathname of a directory. This is equivalent to specifying the relative pathnames of all .java files which exist in the tree rooted at the specified directory. Shell pathname expansion is not supported for directories.

The :JAVA: operator uses dependencies among .java and .class files to insure that build steps run in the proper order, and that only necessary build steps get run. These dependencies are automatically derived from Java source files; furthermore, complex requirements of Java builds, such as dependency cycles and implicit targets, are correctly handled. However, to speed the development cycle this version of :JAVA: does not by default automatically update the dependencies themselves each time a build is run. If javadeps=1 or no $(LOCALJAVADEPS) file exists in the viewpath the dependencies are automatically updated from source, otherwise the dependencies in $(LOCALJAVADEPS)are used. The user is responsible for updating the dependencies whenever Java source is changed in a way that modifies the dependencies among .java and .class files.

In order to speed up dependency maintenance, this version of :JAVA: updates dependencies incrementally if possible. This means that only source files whose modification time is changed since the last run are rescanned for dependencies. Dependency information for other files is reused from the last run.

Since commonly used Java compilers have a high startup overhead, :JAVA: provides an optional feature (enabled by default) which reduces the number of Java compiler invocations by batching calls to the compiler. That is, instead of compiling Java files one by one as is normally the case in nmake based builds, :JAVA: arranges for Java compilations to be queued, and only runs the compiler when the queue length exceeds a threshold. This approach can dramatically reduce build times. The MAXJAVAC variable provides user control over this feature.

Several user-settable nmake variables influence the behavior of the :JAVA: operator. The following variables specify the locations of files and commands used:

CLASSPATH

Java class search path, as used by $(JAVAC). Within a Makefile, .SOURCE.class is preferred.

JAVAC

Java compiler. Defaults to javac.

JAVACFLAGS

Java compiler flags.

JAVACLASSDEST

Specify the destination directory for .class files. This sets the $(JAVAC) -d option.

JDEPS

Java source dependency scanner. This is an external tool used to extract dependency information from Java source files. Defaults to an external scanner which is known to produce dependency information in a format usable by nmake.

JDEPSDIR

Pathname of directory where javadeps package may be found. Defaults to a directory called ``javadeps'' located in the same directory as the nmake installation root directory.

JDEPS.JAR

Location of jdeps jar file. This file is required in order to run $(JDEPS), and defaults appropriately to properly run the external scanner.

LOCALJAVADEPS

Location of file containing Java dependencies. Defaults to localjavadeps. This file is generated automatically by $(JDEPS).

SYNCONFIG

Specify syntax configuration file for $(JDEPS).

The following variables provide fine control over the behavior of the :JAVA: operator:

MAXJAVAC

Specify maximum number of .java files to be compiled in a single call to javac.

javadeps

If javadeps=1, force regeneration of Java file dependencies.

The following special atoms are used:

.SOURCE.class

Specifies option for javac -classpath command line option. Note that the meaning of this option changed between JDK1.1 and JDK1.2. One consequence is that the system library class.zip must be included in the .SOURCE.class atom for JDK1.1, but not for JDK1.2. See http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/migration.html#clspath for details.

.SOURCE.java

Directories to search for Java files.

Example of use

Given a directory structure:

    java/
        Makefile
        com/
            lucent/
                stc/
                    pkg1/
                        a.java
                        b.java
                    pkg2/
                        c.java
                        d.java
                        e.java
    class/            
        com/
            lucent/
                stc/
                    pkg1/
                    pkg2/

and contents of Makefile:

JAVACLASSDEST=../class
.SOURCE.class:/opt/exp/java/lib/classes.zip

:JAVA: com/lucent/stc/pkg1 com/lucent/stc/pkg2
  

Then if the current directory is the directory containing Makefile, running nmake builds the dependencies and compiles all Java source files in packages 1 and 2:

nmake
+ /home/gms/wrk/nmake/java/phase2/pkg/jdeps /home/gms/wrk/nmake/java/phase2/pkg/jdeps.jar -C JAVACLASSES -d ../class -n --vpath= --silent -s /home/gms/wrk/nmake/java/phase2/pkg/synconfig -o localjavadeps --classpath=../class:/opt/exp/java/lib/classes.zip com/lucent/stc/pkg1/B.java com/lucent/stc/pkg1/A.java com/lucent/stc/pkg2/C.java com/lucent/stc/pkg2/E.java com/lucent/stc/pkg2/D.java
+ /opt/exp/bin/javac -O -d ../class -classpath .:../class:/opt/exp/java/lib/classes.zip com/lucent/stc/pkg2/D.java com/lucent/stc/pkg1/B.java com/lucent/stc/pkg2/C.java com/lucent/stc/pkg2/E.java com/lucent/stc/pkg1/A.java

In this case, the following :JAVA: assertion has the same effect:

:JAVA: com

To force dependency regeneration in addition to updating the .class files, run

nmake javadeps=1

Note that the Makefile is in the top level Java source directory, and controls all the Java sources in the source tree.