javaw¶

Java support

Javac is one of the few compilers that behaves very badly:

it outputs files where it wants to (-d is only for the package root)
it recompiles files silently behind your back
it outputs an undefined amount of files (inner classes)

Remember that the compilation can be performed using Jython[1] rather than regular Python. Instead of running one of the following commands:

./waf configure
python waf configure

You would have to run:

java -jar /path/to/jython.jar waf configure

[1] http://www.jython.org/

Usage¶

Load the “java” tool.

def configure(conf):: conf.load(‘java’)

Java tools will be autodetected and eventually, if present, the quite standard JAVA_HOME environment variable will be used. The also standard CLASSPATH variable is used for library searching.

In configuration phase checks can be done on the system environment, for example to check if a class is known in the classpath:

conf.check_java_class('java.io.FileOutputStream')

or if the system supports JNI applications building:

conf.check_jni_headers()

The java tool supports compiling java code, creating jar files and creating javadoc documentation. This can be either done separately or together in a single definition. For example to manage them separately:

bld(features  = 'javac',
        srcdir    = 'src',
        compat    = '1.7',
        use       = 'animals',
        name      = 'cats-src',
)

bld(features  = 'jar',
        basedir   = '.',
        destfile  = '../cats.jar',
        name      = 'cats',
        use       = 'cats-src'
)

Or together by defining all the needed attributes:

bld(features   = 'javac jar javadoc',
        srcdir     = 'src/',  # folder containing the sources to compile
        outdir     = 'src',   # folder where to output the classes (in the build directory)
        compat     = '1.6',   # java compatibility version number
        classpath  = ['.', '..'],

        # jar
        basedir    = 'src', # folder containing the classes and other files to package (must match outdir)
        destfile   = 'foo.jar', # do not put the destfile in the folder of the java classes!
        use        = 'NNN',
        jaropts    = ['-C', 'default/src/', '.'], # can be used to give files
        manifest   = 'src/Manifest.mf', # Manifest file to include

        # javadoc
        javadoc_package = ['com.meow' , 'com.meow.truc.bar', 'com.meow.truc.foo'],
        javadoc_output  = 'javadoc',
)

External jar dependencies can be mapped to a standard waf “use” dependency by setting an environment variable with a CLASSPATH prefix in the configuration, for example:

conf.env.CLASSPATH_NNN = ['aaaa.jar', 'bbbb.jar']

and then NNN can be freely used in rules as:

use        = 'NNN',

In the java tool the dependencies via use are not transitive by default, as this necessity depends on the code. To enable recursive dependency scanning use on a specific rule:

recurse_use = True

Or build-wise by setting RECURSE_JAVA:

bld.env.RECURSE_JAVA = True

Unit tests can be integrated in the waf unit test environment using the javatest extra.

waflib.Tools.javaw.conf(f)¶

Decorator: attach new configuration functions to waflib.Build.BuildContext and waflib.Configure.ConfigurationContext. The methods bound will accept a parameter named ‘mandatory’ to disable the configuration errors:

def configure(conf):
        conf.find_program('abc', mandatory=False)

Parameters: f (function) – method to bind

waflib.Tools.javaw.feature(*k)¶

Decorator that registers a task generator method that will be executed when the object attribute feature contains the corresponding key(s):

from waflib.TaskGen import feature
@feature('myfeature')
def myfunction(self):
        print('that is my feature!')
def build(bld):
        bld(features='myfeature')

Parameters: k (list of string) – feature names

waflib.Tools.javaw.before_method(*k)[source]¶

Decorator that registera task generator method which will be executed before the functions of given name(s):

from waflib.TaskGen import feature, before
@feature('myfeature')
@before_method('fun2')
def fun1(self):
        print('feature 1!')
@feature('myfeature')
def fun2(self):
        print('feature 2!')
def build(bld):
        bld(features='myfeature')

Parameters: k (list of string) – method names

waflib.Tools.javaw.after_method(*k)[source]¶

Decorator that registers a task generator method which will be executed after the functions of given name(s):

from waflib.TaskGen import feature, after
@feature('myfeature')
@after_method('fun2')
def fun1(self):
        print('feature 1!')
@feature('myfeature')
def fun2(self):
        print('feature 2!')
def build(bld):
        bld(features='myfeature')

Parameters: k (list of string) – method names

waflib.Tools.javaw.taskgen_method(func)¶

Decorator that registers method as a task generator method. The function must accept a task generator as first parameter:

from waflib.TaskGen import taskgen_method
@taskgen_method
def mymethod(self):
        pass

Parameters: func (function) – task generator method to add
Return type: function

waflib.Tools.javaw.apply_java(self)[source]¶

Task generator method

Create a javac task for compiling .java files. There can be only one javac task by task generator.

Feature: javac

waflib.Tools.javaw.java_use_rec(self, name, **kw)[source]¶

Task generator method

Processes recursively the use attribute for each referred java compilation

waflib.Tools.javaw.use_javac_files(self)[source]¶

Task generator method

Processes the use attribute referring to other java compilations

Feature: javac

waflib.Tools.javaw.set_classpath(self)[source]¶

Task generator method

Sets the CLASSPATH value on the javac task previously created.

Feature: javac

waflib.Tools.javaw.jar_files(self)[source]¶

Task generator method

Creates a jar task (one maximum per task generator)

Feature: jar

waflib.Tools.javaw.use_jar_files(self)[source]¶

Task generator method

Processes the use attribute to set the build order on the tasks created by another task generator.

Feature: jar

class waflib.Tools.javaw.JTask(*k, **kw)[source]¶

Base class for java and jar tasks; provides functionality to run long commands

split_argfile(cmd)[source]¶

Splits a list of process commands into the executable part and its list of arguments

Returns: a tuple containing the executable first and then the rest of arguments
Return type: tuple

hasrun¶

generator¶

env¶: waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs¶: List of input nodes, which represent the files used by the task instance

outputs¶: List of output nodes, which represent the files created by the task instance

dep_nodes¶: List of additional nodes to depend on

run_after¶: Set of tasks that must be executed before this one

class waflib.Tools.javaw.jar_create(*k, **kw)[source]¶

Creates a jar file

color = 'GREEN'¶: Color for the console display, see waflib.Logs.colors_lst

runnable_status()[source]¶: Wait for dependent tasks to be executed, then read the files to update the list of inputs.

hasrun¶

generator¶

env¶: waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs¶: List of input nodes, which represent the files used by the task instance

outputs¶: List of output nodes, which represent the files created by the task instance

dep_nodes¶: List of additional nodes to depend on

run_after¶: Set of tasks that must be executed before this one

hcode = b'${JAR} ${JARCREATE} ${TGT} ${JAROPTS}'¶: String representing an additional hash for the class representation

orig_run_str = '${JAR} ${JARCREATE} ${TGT} ${JAROPTS}'¶

vars = ['JAR', 'JARCREATE', 'JAROPTS']¶: ConfigSet variables that should trigger a rebuild (class attribute used for waflib.Task.Task.sig_vars())

class waflib.Tools.javaw.javac(*k, **kw)[source]¶

Compiles java files

color = 'BLUE'¶: Color for the console display, see waflib.Logs.colors_lst

vars = ['CLASSPATH', 'JAVAC', 'JAVACFLAGS', 'OUTDIR']¶: The javac task will be executed again if the variables CLASSPATH, JAVACFLAGS, JAVAC or OUTDIR change.

uid()[source]¶: Identify java tasks by input&output folder

runnable_status()[source]¶: Waits for dependent tasks to be complete, then read the file system to find the input nodes.

post_run()[source]¶: List class files created

hasrun¶

generator¶

env¶: waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs¶: List of input nodes, which represent the files used by the task instance

outputs¶: List of output nodes, which represent the files created by the task instance

dep_nodes¶: List of additional nodes to depend on

run_after¶: Set of tasks that must be executed before this one

hcode = b'${JAVAC} -classpath ${CLASSPATH} -d ${OUTDIR} ${JAVACFLAGS} ${SRC}'¶: String representing an additional hash for the class representation

orig_run_str = '${JAVAC} -classpath ${CLASSPATH} -d ${OUTDIR} ${JAVACFLAGS} ${SRC}'¶

waflib.Tools.javaw.create_javadoc(self)[source]¶

Task generator method

Creates a javadoc task (feature ‘javadoc’)

Feature: javadoc

class waflib.Tools.javaw.javadoc(*k, **kw)[source]¶

Builds java documentation

color = 'BLUE'¶: Color for the console display, see waflib.Logs.colors_lst

post_run()[source]¶: Update the cache files (executed by threads). Override in subclasses.

hasrun¶

generator¶

env¶: waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs¶: List of input nodes, which represent the files used by the task instance

outputs¶: List of output nodes, which represent the files created by the task instance

dep_nodes¶: List of additional nodes to depend on

run_after¶: Set of tasks that must be executed before this one

hcode = b'\tdef run(self):\n\t\tenv = self.env\n\t\tbld = self.generator.bld\n\t\twd = bld.bldnode\n\n\t\t#add src node + bld node (for generated java code)\n\t\tsrcpath = self.generator.path.abspath() + os.sep + self.generator.srcdir\n\t\tsrcpath += os.pathsep\n\t\tsrcpath += self.generator.path.get_bld().abspath() + os.sep + self.generator.srcdir\n\n\t\tclasspath = env.CLASSPATH\n\t\tclasspath += os.pathsep\n\t\tclasspath += os.pathsep.join(self.classpath)\n\t\tclasspath = "".join(classpath)\n\n\t\tself.last_cmd = lst = []\n\t\tlst.extend(Utils.to_list(env.JAVADOC))\n\t\tlst.extend([\'-d\', self.generator.javadoc_output.abspath()])\n\t\tlst.extend([\'-sourcepath\', srcpath])\n\t\tlst.extend([\'-classpath\', classpath])\n\t\tlst.extend([\'-subpackages\'])\n\t\tlst.extend(self.generator.javadoc_package)\n\t\tlst = [x for x in lst if x]\n\n\t\tself.generator.bld.cmd_and_log(lst, cwd=wd, env=env.env or None, quiet=0)\n'¶: String representing an additional hash for the class representation

waflib.Tools.javaw.configure(self)[source]¶: Detects the javac, java and jar programs

waflib.Tools.javaw.check_java_class(self, classname, with_classpath=None)[source]¶

Configuration Method bound to waflib.Configure.ConfigurationContext

Checks if the specified java class exists

Parameters

classname (string) – class to check, like java.util.HashMap
with_classpath (string) – additional classpath to give

waflib.Tools.javaw.check_jni_headers(conf)[source]¶

Configuration Method bound to waflib.Configure.ConfigurationContext

Checks for jni headers and libraries. On success the conf.env variables xxx_JAVA are added for use in C/C++ targets:

def options(opt):
        opt.load('compiler_c')

def configure(conf):
        conf.load('compiler_c java')
        conf.check_jni_headers()

def build(bld):
        bld.shlib(source='a.c', target='app', use='JAVA')

Features defined in this module:

javaw¶

Usage¶

Table of Contents

Previous topic

Next topic

This Page