-
Notifications
You must be signed in to change notification settings - Fork 418
zzz 500 annproc
This release includes the first cut of an annotation processor that can build a model from the picocli annotations at compile time rather than at runtime.
Use this if you’re interested in:
- Compile time error checking. Some combinations of annotations and attributes are invalid. The annotation processor will show compile time errors immediately, instead of runtime errors when you run your tests, resulting in shorter feedback cycles.
-
Graal native images. The annotation processor generates and updates Graal configuration files for reflection, resources and dynamic proxies under
META-INF/native-image/picocli-generated/$project
during compilation, to be included in the application jar. By embedding these configuration files, your jar is instantly Graal-enabled. In most cases no further configuration is needed when generating a native image.
Since Java 6, annotation processing is part of the standard javac
compiler, but many IDEs and build tools require something extra to enable annotation processing.
This page shows the steps to configure Eclipse and IntelliJ IDEA to enable annotation processing.
In Maven, the simplest is to specify the picocli-codegen
module on the classpath as a provided
dependency. This prevents it from being a transitive dependency included in the artifact the module produces.
<dependency>
<groupId>info.picocli</groupId>
<artifactId>picocli</artifactId>
<version>4.0.0-beta-1</version>
</dependency>
<dependency>
<groupId>info.picocli</groupId>
<artifactId>picocli-codegen</artifactId>
<version>4.0.0-beta-1</version>
<provided>true</provided>
</dependency>
This is simple but won’t let you configure any options to the processor. See Processor Options below.
Use the annotationProcessor
path in Gradle 4.6 and higher:
dependencies {
compile 'info.picocli:picocli:4.0.0-beta-1'
annotationProcessor 'info.picocli:picocli-codegen:4.0.0-beta-1'
}
For Gradle versions prior to 4.6, use compileOnly
, to prevent the picocli-codegen
jar from being a transitive dependency included in the artifact the module produces.
dependencies {
compile 'info.picocli:picocli:4.0.0-beta-1'
compileOnly 'info.picocli:picocli-codegen:4.0.0-beta-1'
}
The picocli annotation processor supports the options below.
-
project
- output subdirectory
The generated files are written to META-INF/native-image/picocli-generated/${project}
.
The project
option can be omitted, but it is a good idea to specify the project
option with a unique value for your project (e.g. $groupId/$artifactId
) if your jar may be shaded with other jars into an uberjar.
-
other.resource.patterns
- comma-separated list of regular expressions matching additional resources to include in the image -
other.resource.bundles
- comma-separated list of the base names of additional resource bundles to include in the image -
other.proxy.interfaces
- comma-separated list of the fully qualified class names of additional interfaces for which to generate proxy classes when building the image -
disable.proxy.config
- don’t generateproxy-config.json
-
disable.reflect.config
- don’t generatereflect-config.json
-
disable.resources.config
- don’t generateresources-config.json
To pass an annotation processor option with javac
, specify the -A
command line option:
javac -Aproject=org.myorg.myproject/myapp -cp ...
The -A
option lets you pass options to annotation processors. See the javac documentation for details.
To set an annotation processor option in Maven, you need to use the maven-compiler-plugin
and configure annotationProcessorPaths
and compilerArgs
sections.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin-version}</version>
<configuration>
<!-- minimum 1.6 -->
<source>${java-version}</source>
<target>${java-version}</target>
<annotationProcessorPaths>
<path>
<groupId>info.picocli</groupId>
<artifactId>picocli-codegen</artifactId>
<version>4.0.0-beta-1</version>
</path>
</annotationProcessorPaths>
<compilerArgs>
<arg>-Aproject=$groupId/$artifactId</arg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</build>
See https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html for details.
To set an annotation processor option in Graal, add these options to the options.compilerArgs
list in the compileJava
block.
compileJava {
// minimum 1.6
sourceCompatibility = ${java-version}
targetCompatibility = ${java-version}
options.compilerArgs += ["-Aproject=$group/$name"]
}
See the Gradle documentation for details.