README
gulp-javac
Compile java source and create jars from gulp.
Notice: Source is being migrated to a new repository and is temporarily unavailable.
Install
$ npm install --save-dev gulp-javac
Usage
javac = require('gulp-javac');
gulp.task('example', function() {
return gulp.src('./src/**/*.java')
.pipe(javac('example.jar')
.addLibraries('./lib/**/*.jar')
.addLibraries('./external/**/*.jar'))
.pipe(gulp.dest('out'));
});
API
javac.javac([options])
Returns: Duplex Stream (<java source files>
---> <class files>
)
Compiles source into a set of .class files. Input files are expected to be java source files; directories are ignored. Produces a stream of generated files.
options
debuggingInformation
Type: string
or string[]
Default: ['lines', 'source']
Sets the debugging information output to the class files. Valid values are
'lines'
, 'source'
, and 'vars'
. Set this to 'none'
, null
(or something
false-y) to not include any debugging information. Set this to '*'
to include
all debugging information.
javaVersion
Type: string
Default: System default
Sets the Java language version to use. Example: '1.7'
failOnWarning
Type: boolean
Default: false
Set to true
for compilation to fail on compiler warnings.
noWarnings
Type: boolean
Default: false
Set to true
to not output compiler warnings.
javacToolPath
Type: string
Default: javac on $PATH
Path to the javac compiler. If javac
isn't on your $PATH, set this to the path.
verbose
Type: boolean
Default: false
Set to true
to include verbose javac output.
javacCompilerFlags
Type: string[]
Default: []
Flags to pass to the underlying javac runner. See the -J
flag in man javac
.
traceEnabled
Type: boolean
Default: undefined
(Uses module settings)
Sets tracing for this particular step. This overrides the module-level setting.
addLibraries(...sources)
Returns: javac object
Adds libraries to the classpath for compilation against. This returns the javac object that it was called on so that calls can be chained.
sources
Required
Type: string
or string[]
or readable stream of vinyl files
Libraries to add. If this is a string
or string[]
it is treated as a
glob spec and all files are added. Otherwise all files on the stream are
added. The following are all equivalent:
javac().addLibraries('./a/**/*').addLibraries('./b/**/*');
javac().addLibraries('./a/**/*', './b/**/*');
javac().addLibraries(['./a/**/*', './b/**/*']);
javac().addLibraries(gulp.src('./a/**/*'), gulp.src('./b/**/*'));
javac().addLibraries(gulp.src(['./a/**/*', './b/**/*']));
javac.jar(jarName, [options])
Returns: Duplex Stream (<class files>
---> <jar file>
)
Builds a jar file from provided sources. Expects a stream of jar contents and will use relative paths for jar contents. Produces a stream with just the resulting jar.
Note: The jar command will not repackage other jars. If other jars are included in the sources, those jars will be embedded within the created jar, which probably isn't what you want. If you want to repackage jars, you can try the following recipe:
const merge = require('merge-stream');
merge(
gulp.src('./src/**/*.java')
.pipe(javac.javac()
.addLibraries('./lib/**/*.jar')),
gulp.src('./lib/**/*.jar')
.pipe(javac.unjar()))
.pipe(jar('example.jar'));
This is likely to fail if there are collisions. In this case you'll probably have to use other tools, like Jar Jar Links or ProGuard.
jarName
Required Base name of the jar file to create.
options
omitManifest
Type: boolean
Default: false
Use true
to direct the jar tool to not create a manifest.
entryPoint
Type: string
Default: undefined
Set this to the full class name of the class to use when running the jar from the command line.
jarToolPath
Type: string
Default: jar on $PATH
Path to the jar tool. If jar
isn't on your $PATH, set this to the path.
verbose
Type: boolean
Default: false
Set to true
to include verbose jar output.
traceEnabled
Type: boolean
Default: undefined
(Uses module settings)
Sets tracing for this particular step. This overrides the module-level setting.
jarCompilerFlags
Type: string[]
Default: []
Flags to pass to the underlying jar runner. See the -J
flag in man jar
.
javac.unjar([options])
Returns: Duplex Stream (<jar files>
---> <jar contents>
)
Extracts files from a jar. Expects a stream of jar files. Produces a stream
of the jar contents. By default this will only include .class
files, but
can be expanded to all files by using the includeAllFiles
option.
options
jarToolPath
Type: string
Default: jar on $PATH
Path to the jar tool. If jar
isn't on your $PATH, set this to the path.
includeAllFiles
Type: boolean
Default: false
Set to true
to include all jar contents. Otherwise only .class
files will
be included.
verbose
Type: boolean
Default: false
Set to true
to include verbose jar output.
traceEnabled
Type: boolean
Default: undefined
(Uses module settings)
Sets tracing for this particular step. This overrides the module-level setting.
javac(jarName, [options])
Returns: Duplex Stream (<java source files>
---> <jar file>
)
Convenience function for running both javac.javac(...) and javac.jar(...). These are equivalent:
// Options.
let javacOptions = {...},
jarOptions = {...},
jarName = '...';
let mergedOptions = require('underscore')
.extend({}, javacOptions, jarOptions);
// Manual method:
gulp.src(...)
.pipe(javac.javac(mergedOptions).addLibraries(...))
.pipe(javac.jar(jarName, mergedOptions));
// Merged method:
gulp.src(...)
.pipe(javac(jarName, mergedOptions).addLibraries(...));
The only overlapping options are verbose
and traceEnabled
. jarName
is
passed to jar()
and options
is passed to both javac
and jar
. The
addLibraries()
method is passed to javac
, but the return object is this
stream to allow chaining.
trace
Type: boolean
Default: false
Module-level flag for tracing. Set to true
to enable trace output. This is useful
when trying to diagnose a problem with compilation, or when developing the library.
This can be enabled per-run by passing a --gulp-javac.trace
flag to gulp
.
License
The MIT License (MIT)
Copyright (c) 2016 Paul Hounshell paul.hounshell@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.