saker.java.compiler Documentation TaskDoc JavaDoc Packages
Compiles Java sources. Use the SourceDirectories parameter to specify the directories containing the .java sources to compile.
Summary
Parameters
AddExportsSpecifies the additional module export definitions when compiling for Java 9 or later.
AllowTargetReleaseMismatchSets if mismatching TargetVersion, SourceVersion and --release values are allowed to be used.
AnnotationProcessorOptionsSpecifies the global key-value options that should be passed to all annotation processors.
AnnotationProcessorsSpecifies the annotation processors that should be used during compilation.
BootClassPathInput boot class path for the compilation.
BuildIncrementalSpecifies if incremental Java compilation should be used or not.
ClassPathInput class path for the compilation.
CompilerOptionsSpecifies one or more option specifications that are merged into the compilation options of the Java compilation if applicable.
DebugInfoSpecifies the debugging informations to be included in the generated class files.
GenerateNativeHeadersSpecifies whether or not native headers should be generated for the compiled source files.
IdentifierThe Identifier of the Java compilation.
LanguageServes only as a qualifier for CompilerOptions merging.
ModuleMainClassSpecifies a Java class binary name that should be injected in the generated module-info.class file.
ModulePathInput module path for the compilation.
ModuleVersionSpecifies a version string that should be injected in the generated module-info.class file.
ParallelProcessingSpecifies if the compiler task may run the annotation processors in a parallel manner.
ParameterNamesSpecifies whether or not the parameter names of methods and constructors should be included in the generated class files.
ParametersSpecifies the command line parameters that should be passed to javac.
PatchEnablePreviewSets if the --enable-preview requirement on the generated class files should be patched.
ProcessorInputLocationsSpecifies a read-only input location for annotation processors.
SDKsSpecifies the SDKs (Software Development Kits) used by the compilation task.
SourceDirectoriesInput source directories for the compilation.
SourceVersionSpecifies the accepted source version.
SuppressWarningsSpecifies the warning types which should be suppressed by the compiler task.
TargetVersionSpecifies the target version of the class files.
Parameters
Specifies the additional module export definitions when compiling for Java 9 or later. Specifying this option will add the appropriate --add-exports options to the Java compiler backend. The option accepts string values in the format of module/package=other-module(,other-module)*. If the target module is omitted, ALL-UNNAMED is used.
Sets if mismatching TargetVersion, SourceVersion and --release values are allowed to be used. WARNING: Using this flag may cause your class files to be binary incompatible with the platform you intend to run it on. This flag uses undocumented javac API to trick it into generating bytecode for different versions than it's used to. Using this may cause crashes in your application in unexpected ways. WARNING: The specified TargetVersion shouldn't be greater than the --release version. Compilation may result in error if you target a more recent release than the specified --release. WARNING: Other general incompatibility errors may occurr if you intend to use bytecode instructions on older Java releases where they don't exist. By setting this to true, the compile task will directly set the specified TargetVersion, SourceVersion and --release parameter values as they are specified as inputs. No compatibility validation will be performed for these. This generally can be used to generate bytecode for older releases while sometimes using newer language features. This is a completely undocumented and unreliable feature of this build task and we don't recommend using it without thorough testing or in general.
Specifies the global key-value options that should be passed to all annotation processors. All the entries in this map will be added without modification to the options which are used for the processors.
Specifies the annotation processors that should be used during compilation. Annotation processors are plugins into the compilation. They can examine the compiled source code and generate various sources, classes, and resources based on that. Annotation processors can be constructed by other tasks in the build system. See saker.java.processor() or the use-case documentation for your processor of interest. Global options can be specified for the processors using AnnotationProcessorOptions. Input locations can be specified using ProcessorInputLocations.
Input boot class path for the compilation. The class files in the specified class path will used as the boot class path during Java compilation. The value may be paths to JARs or class directories, wildcards to specify multiple one easily, outputs of previous compilations, paths based on SDKs, or class paths from other tasks. Class paths of compilation outputs will be transitive added. Any Class-Path or similar attributes in JAR file manifests are ignored.
Specifies if incremental Java compilation should be used or not. The default value is true. Setting this to false will cause the task to use legacy compilation, and will call the javac backend with the least modification to the input parameters as possible. Using it will result in the compile Parameters being passed directly to the backend, and annotation processors will be called by the javac backed instead of the task implementation. This option should only be used when there are issues with the incremental Java compilation implementation. If you ever need to turn this feature off, make sure to file an issue about your use-case as this is considered to be a bug in the incremental compiler. Issues at: https://github.com/sakerbuild/saker.java.compiler/issues
Input class path for the compilation. The class files in the specified class path will be added to the available classes during Java compilation. The value may be paths to JARs or class directories, wildcards to specify multiple one easily, outputs of previous compilations, paths based on SDKs, or class paths from other tasks. Class paths of compilation outputs will be transitive added. Any Class-Path or similar attributes in JAR file manifests are ignored.
Specifies one or more option specifications that are merged into the compilation options of the Java compilation if applicable. The parameter can be used to indirectly specify various compilation arguments independent of the actual task invocation. This is generally useful when common options need to be specified to multiple Java compilations. When the compilation arguments are determined, each option specification will be merged into the used arguments if applicable. An option is considered to be applicable for merging if all of the Identifier parts are contained in the compilation task identifier, and the Language qualifier argument can be matched. In case of option conflicts, the task will throw an appropriate exception.
Specifies the debugging informations to be included in the generated class files. The default is all. May specify empty collection to signal no information to be included. Corresponds to the -parameters command line option for javac.
Specifies whether or not native headers should be generated for the compiled source files. When set to true, the task will create C language bindings for any native declarations in the files. The created header files can be included by C/C++ and other language compilers if appropriate. Use the HeaderDirectory field of the task output to get a path to the generated headers.
The Identifier of the Java compilation. Each Java compilation task has an identifier that uniquely identifies it during a build execution. The identifer is used to determine the output directory of the compilation. It is also used to merge the appropriate options specified in CompilerOptions parameter. An identifier constists of dash separated parts of character sequences of a-z, A-Z, 0-9, _, ., (), [], @. An option specification in the CompilerOptions can be merged if the compilation identifier contains all parts of the option Identifier. The default value is automatically generated based on the SourceDirectories argument. Auto-generated identifiers are not subject to option merging.
Serves only as a qualifier for CompilerOptions merging. Specifying this argument doesn't have any effect on the Java source compilation. The default value is Java. When CompilerOptions are merged, the languages are checked for compatibility. If the specified compiler option declares a different language than this one, then its options won't be merged into the compilation task.
Specifies a Java class binary name that should be injected in the generated module-info.class file. When the compilation targets Java 9 or later, and uses modules (module-info.java), specifying this option will cause the compiler task to inject the main class attribute in the generated module-info.class class file. The task will not verify if the specified class exists or not.
Input module path for the compilation. The specified JARs and class directories will be used as the module path durin Java compilation. The value may be paths to JARs or class directories, wildcards to specify multiple one easily, outputs of previous compilations, paths based on SDKs, or module paths from other tasks. Module paths of compilation outputs will be transitive added. This option only has relevance if the compilation is done for JDK9 or later.
Specifies a version string that should be injected in the generated module-info.class file. When the compilation targets Java 9 or later, and uses modules (module-info.java), specifying this option will cause the compiler task to inject the version attribute in the generated module-info.class class file. The task will not check if the specified version is syntactically correct.
Specifies if the compiler task may run the annotation processors in a parallel manner. The default value is true. Running annotation processors in parallel may result in performance increase, as they can generate their classes and resources without waiting on each other. In general, parallel processing shouldn't distrupt the operation of annotation processors, however, if developers notice any unexpected processor outputs, they may check if turning parallel processing off helps. When parallel processing is on, the result of the Processor.process() function is ignored by the compiler.
Specifies whether or not the parameter names of methods and constructors should be included in the generated class files. If so, the parameter names will be available through the Reflection APIs. The default is true. Corresponds to the -parameters command line option for javac.
Specifies the command line parameters that should be passed to javac. The specified parameters will be passed to the Java compiler backend with minimal modifications by the compiler task. The -processorpath and -processor parameters are ignored. Use the annotation processor options for the compiler task. The -source and -target parameters are ignored. Use SourceVersion and TargetVersion parameters for the compiler task. The -sourcepath parameter is ignored. Use SourceDirectories parameter to specify source inputs. The -cp, -classpath, --class-path parameters are merged with the ClassPath parameter. Developers should use the ClassPath parameter instead of these options. The -p and --module-path are merged with the ModulePath option. Developers should use ModulePath instead. The -bootclasspath and --boot-class-path parameters are merged with BootClassPath. Developers should use BootClassPath instead. The -A parameters are stripped and merged with the AnnotationProcessorOptions option.
Sets if the --enable-preview requirement on the generated class files should be patched. If this flag is set to true, then the compile task will modify the minor version of the class files from 0xFFFF to 0x0000. As a result of this, they can be run using javac without specifying the --enable-preview flag for it. Note that this feature may break on future versions of Java.
Specifies a read-only input location for annotation processors. The value is a string-path map which contains the names of locations and the directory paths from where processors can read resources from. The processors can use the Filer API to read resources, by passing StandardLocation.locationFor(name) as the location argument.
Specifies the SDKs (Software Development Kits) used by the compilation task. SDKs represent development kits that are available in the build environment and to the task. For Java compilation, they can be used to resolve class and module paths against, or to specify a different JDK to use for compilation. SDKs are referenced by simple string names in a case-insensitive way. The "Java" SDK is used by the compilation task to determine which JDK to use. If a different JDK is specified than the one the build is running on, then the task will spawn a new Java process that it delegates the compilation to. (i.e. forks a compiler process) The saker.java.sdk() task can be used to find JDKs with a specific version during build.
Aliases:
SourceDirectory
Input source directories for the compilation. It is used to specify which files should be compiled. It can accept a single path to the source directory containing .java files.
Specifies the accepted source version. The compiled Java sources should comply to the specified source version number. The value can be a positive integer representing the Java major release number, or in the format of RELEASE_<num>.
Specifies the warning types which should be suppressed by the compiler task.
Specifies the target version of the class files. The generated class files will be used to target the Java VM with the specified version. The value can be a positive integer representing the Java major release number, or in the format of RELEASE_<num>.