RFR: JDK-8310061: Note if implicit annotation processing is being used

[Joseph D. Darcy]

On 6/16/2023 12:20 PM, Alex Buckley wrote:
> On 6/16/2023 11:48 AM, Joe Darcy wrote:
>> On Thu, 15 Jun 2023 18:16:57 GMT, Joe Darcy <darcy at openjdk.org> wrote:
>>
>>> Emit a note warning of the possibility of changing the implicit 
>>> running of annotation processors in a future release.
>>
>> The goal of the change in this PR is to emit a message to users who 
>> may be unknowingly relying on default implicit annotation processing 
>> that the long-standing default may be changing in a future release. 
>> The message is a Note rather than a Warning to avoid running afoul of 
>> build setups using configurations like "-Xlint:all -Werror".
>
> I looked at the man page -- 
> https://download.java.net/java/early_access/jdk21/docs/specs/man/javac.html#how-annotation-processing-works 
> -- to learn about javac's default search path for processors.
>
> (`-proc:full` isn't mentioned, but maybe it's coming soon?)


Getting -proc:full in the man page is being addressed under JDK-8308456.


>
> The title of this mail is about "implicit annotation processing", that 
> is, the fact that annotation processing is enabled by default ... but 
> the focus of the new message is about a different kind of default, 
> namely the default search path for locating annotation processors. I 
> read:
>
>   One or more annotation processors found under the default policy of
>   searching the class path or module path for processors.
>
> as saying:
>
>   Let's try to be more specific about where javac should search for
>   processors -- look at --processor-path or --processor-module-path
>
> (The man page doesn't mention searching the module path for 
> processors. It only searches the "user class path".)


My mistake; I verified the implementation does not look for annotation 
processors on the --module-path, just on --processor-module-path. I'll 
update the note accordingly.


>
>
> Consider this text, which sidesteps "implicit" in favor of 
> "enabled"/"disabled" to align with how the man page starts: "Unless 
> annotation processing is disabled with the -proc:none option ..."
>
>   Annotation processing is enabled, and one or more annotation
>   processors were found. [Maybe -processorpath was specified, maybe it
>   wasn't, but either way, something was found.]


To give more context around the situations where the note appears and 
the motivation behind it. Using a command line like

     $ javac --class-path JarFileWithAnnotationProcessor.java Foo.java

will look for and find the annotation processor inside 
JarFileWithAnnotationProcessor and run it per the process outlined in 
the man page, etc. There are no strictly annotation processing related 
configuration options in this situation; these are the sort of implicit 
cases where the warning note will be reported under this PR.

In contrast, none of these other command lines would generate a note:

     $ javac --processor-path JarFileWithAnnotationProcessor.java Foo.java
     $ javac --class-path     JarFileWithAnnotationProcessor.java 
-processor NameOfProcessorInJarFile Foo.java
     $ javac --class-path     JarFileWithAnnotationProcessor.java 
-proc:full                          Foo.java

     $ javac --class-path JarFileWithAnnotationProcessor.java 
-Xlint:-options Foo.java
     $ javac --class-path JarFileWithAnnotationProcessor.java 
-Xlint:none     Foo.java

The first three have explicit annotation processor related configuration 
optoins, hence opting-in to annotation processing, and the last two 
explicitly disable warnings related to option handling.

Thanks,

-Joe


>
>   They will be called [the word from the man page] in this compilation,
>   but a future release of javac may choose to disable annotation
>   processing by default. It will then be necessary to enable annotation
>   processing with `-proc:only` or `-proc:full`.
>
>   Use -Xlint:-options to suppress this message.
>
> Alex