Basics

If you're not doing anything out of the ordinary, using saker.java.compile() won't have any surprises. Simply specify one or more source directories, class path, and you're good to go:

saker.java.compile(src)
saker.java.compile([
	src,
	src_2
])
saker.java.compile(
	SourceDirectories: src,
	ClassPath: lib/my_library.jar
)

You can pass other compilation results, and wildcards as the class path as well:

$base = saker.java.compile(src/base)
saker.java.compile(
	SourceDirectories: src/core,
	ClassPath: [
		lib/*.jar,
		$base
	]
)

The above will result in two Java compilation passes to be done. One for the directory src/base, and one for src/core. The core pass will have the JAR files in the lib directory and the classes from the base pass on its classpath.

Compilation output

The results of the compilation is placed in the build directory. It will be at the location {build-dir}/saker.java.compile/{compilation-id}. You may notice the following subdirectories:

• bin: This contains the compiled class files. It may also include resources that were generated by annotation processors with the CLASS_OUTPUT location.
• gen: Contains source files that were generated by annotation processors. If you're not using processors, it will be empty.
• nativeh: Contains native headers that were generated for the compiled source files. If a Java class contains native declarations, and you set the GenerateNativeHeaders parameter to true, the task will generate native header files that can be used to develop native libraries against.
• res: Generic output location for annotation processors to write resources to. If an annotation processor decides to write a resource to an output location with unrecognized name, the resources will be written here. The actual output directory for the resources are res/{location-name}.

You can retrieve these paths from the output object of the task invocations:

$javac = saker.java.compile(src)
$javac[ClassDirectory]		# bin
$javac[SourceGenDirectory]	# gen
$javac[HeaderDirectory]		# nativeh
$javac[ResourceDirectory]	# res

Compilation identifier

You may have noted the {compilation-id} part in the Compilation output section. This is an identifier that uniquely identifies a Java compilation pass during a build execution. You can specify it using the Identifier task parameter. If you don't, it will be automatically generated based on the names of the input source directories.

There may not be two different compilation tasks with the same identifier executed during a single build execution, and the runtime will throw an exception if it detects such scenario.