xpybuild.targets.java¶

Contains targets for building and documenting Java applications.

The main target in this module is xpybuild.targets.java.Jar.

The directory containing the JDK is identified by the option java.home.

SignJars¶

class xpybuild.targets.java.SignJars(output, jars, keystore, alias=None, storepass=None, manifestDefaults=None)[source]¶

Bases: xpybuild.basetarget.BaseTarget

Copy jars into a target directory and sign them with the supplied keystore, optionally also updating their manifests.

Additional command line arguments can be passed to signjars using the option jarsigner.options (default []).

Parameters

output – The output directory in which to put the signed jars
jars – The list (or PathSet) of input jars to copy and sign
keystore – The path to the keystore
alias – The alias for the keystore (optional)
storepass – The password for the store file (optional)
manifestDefaults – a dictionary of manifest entries to add to the existing manifest.mf file of each jar before signing. Entries in this dictionary will be ignored if the same entry is found in the original manifest.mf file already.

Javac¶

class xpybuild.targets.java.Javac(output, compile, classpath, options=None)[source]¶

Bases: xpybuild.basetarget.BaseTarget

Compile Java classes to a directory (without creating a .jar).

Example usage:

Javac('${OUTPUT_DIR}/myclasses/', 
        # FindPaths walks a directory tree, supporting complex ant-style globbing patterns for include/exclude
        compile=[
                FindPaths('./src/', excludes=['**/VersionConstants.java']), 
                '${BUILD_WORK_DIR}/filtered-java-src/VersionConstants.java',
        ],

        # DirBasedPathSet statically lists dependent paths under a directory
        classpath=[DirBasedPathSet('${MY_DEPENDENT_LIBRARY_DIR}/', 'mydep-api.jar', 'mydep-core.jar')],
)

The following options can be set with Javac(...).option(key, value) or xpybuild.propertysupport.setGlobalOption() to customize the compilation process:

javac.warningsAsErrors: bool Make the build fail if any warnings are detected.

javac.debug = False Include debug information (line numbers) in the compiled .class files.

javac.encoding = "ASCII" The character encoding for .java source files.

javac.source = "" The .java source compliance level.

javac.target = "" The .class compliance level.

javac.options = [] A list of extra options to pass to javac.

javac.logs = "${BUILD_WORK_DIR}/javac_logs" The directory in which errors/warnings from javac will be written.

javac.outputHandlerFactory = JavacProcessOutputHandler The class used to parse and handle error/warning messages.

Parameters

output – output dir for class files
compile – PathSet (or list) of things to compile
classpath – PathSet (or list) of things to be on the classpath
options – [DEPRECATED - use .option() instead]

Jar¶

class xpybuild.targets.java.Jar(jar, compile, classpath, manifest, options=None, package=None, preserveManifestFormatting=False)[source]¶

Bases: xpybuild.basetarget.BaseTarget

Create a jar, first compiling some Java classes, then packing it all up as a .jar.

Example usage:

Javac('${OUTPUT_DIR}/myapp.jar', 
        # FindPaths walks a directory tree, supporting complex ant-style globbing patterns for include/exclude
        compile=[
                FindPaths('./src/', excludes=['**/VersionConstants.java']), 
                '${BUILD_WORK_DIR}/filtered-java-src/VersionConstants.java',
        ],

        # DirBasedPathSet statically lists dependent paths under a directory
        classpath=[DirBasedPathSet('${MY_DEPENDENT_LIBRARY_DIR}/', 'mydep-api.jar', 'mydep-core.jar')],

        # Specify Jar-specific key/values for the MANIFEST.MF (in addition to any set globally via options)
        manifest={'Implementation-Title':'My Amazing Java Application'}, 

        package=FindPaths('resources/', includes='**/*.properties'),
)

setGlobalOption('jar.manifest.defaults', {'Implementation-Version': '${APP_VERSION}', 'Implementation-Vendor': 'My Company'})

In addition to the options listed on the Javac target, the following options can be set when creating a Jar, using Jar(...).option(key, value) or xpybuild.propertysupport.setGlobalOption():

jar.manifest.defaults = {} Default key/value pairs (e.g. version number) to include in the MANIFEST.MF of every jar.

jar.manifest.classpathAppend = [] Add additional classpath entries to the MANIFEST.MF which are needed at runtime but not during compilation.

jar.options = [] A list of extra options to pass to jar.

Parameters

jar – path to jar to create.
compile – PathSet (or list) of things to compile.
classpath – PathSet (or list) of things to be on the classpath; destination mapping indicates how they will appear in the manifest.
manifest –
Typically a map of MANIFEST.MF entries (can be empty) such as:
```
manifest={'Implementation-Title':'My Amazing Java Application'}, 
```
Alternative, specify a string to get the manifest from a file, or None to disable manifest generation and just produce a normal zip.
options – (deprecated - use .option() instead).
package – PathSet (or list) of other files to include in the jar; destination mapping indicates where they will appear in the jar.
preserveManifestFormatting – an advanced option that prevents the jar tool from reformatting the specified manifest file to comply with Java conventions (also prevents manifest merging if jar already exists).

Javadoc¶

class xpybuild.targets.java.Javadoc(destdir, source, classpath, options)[source]¶

Bases: xpybuild.basetarget.BaseTarget

Creates Javadoc from a set of input files.

The following options can be set with Javadoc(...).option(key, value) to customize the documentation process:

javadoc.title = "Documentation" The title.

javac.ignoreSourceFilesFromClasspath = False By default, Javadoc will parse any source .java files present in the classpath in case they contain comments that should be inherited by the source files being documented. If these files contain errors (such as missing optional dependencies) it will cause Javadoc to fail. This option prevents the classpath from being searched for source files (by setting -sourcepath to a non-existent directoryu), which avoids errors and may also speed up the Javadoc generation.

javac.access = "public" Identifies which members and classes to include.

Parameters

destdir – directory to create docs in
source – a set of files to build from
classpath – a list of jars needed for the classpath
options – [DEPRECATED - use .option() instead]