Checking @Override compatibility between Java 1.5/1.6

[Tom Gibara]

This recent thread

http://groups.google.com/group/android-platform/browse_thread/thread/8b565af4a0ef82d8

highlighted the difficulties that have begun to arise from requiring Java 1.5 for platform builds. As I understand it, the main (possibly only?) thing that prevents Java 1.6 being used interchangeably with Java 1.5 is the incompatibility between they way they handle @Override annotations.

As one possible way of addressing this, I've put together a java Doclet that can identify when an @Override annotation is not compatible with Java 1.5. The source code, basic documentation and a simple test case are available here:

http://www.tomgibara.com/android/override-check

With perhaps some light modifications it could provide a useful way of ensuring that those building with 1.6 don't inadvertently break builds under 1.5 - though I'm ignorant of how this would actually work within the context of the build.

Tom.

[Chad Fawcett]

This is great, Tom, glad to see something come out of that thread so quickly!

I'm not yet as up to speed on the build process as I'd like, but I think the call to such a tool could be added (when building with 1.6) in build/core/definitions.mk in the "transform-java-to-classes.jar" definition or perhaps as a new definition in that file which would be called from java.mk right after the transform-java-to-classes call.

 -Chad

[Jean-Baptiste Queru]

I think it'd make sense to add them in the
transform-java-to-classes.jar definition indeed, either before or
after the javac invocation. Further refinement will focus on only
running it when building with 1.6.

For reference: http://android.git.kernel.org/?p=platform/build.git;a=blob;f=core/definitions.mk;h=9b3a03d91bf76946733d7ed24df26635bfe483cd;hb=refs/heads/master#l1229

JBQ

--
Jean-Baptiste M. "JBQ" Queru
Software Engineer, Android Open-Source Project, Google.

Questions sent directly to me that have no reason for being private
will likely get ignored or forwarded to a public forum with no further
warning.

[Tom Gibara]

I thought I'd hit a problem with running javadoc for this purpose, but I now have a modified version of this original doclet that seems to work: it correctly traps @Override annotations I've added to Android java source files that would otherwise choke the 1.5 javac compiler. But I have several questions about how to move towards having a worthwhile commit ('make' isn't my natural habitat - hopefully these aren't dumb questions):

1) This new little build tool is written is java and should have its own module (like droiddoc), but this introduces a circularity (the doclet is needed to compile the doclet) how should this best be handled?

2) What's the best way of checking the java version? I know there's an example at the top of build/code/main.mk, does a similar check need to be done on every invocation of transform-java-to-classes.jar ?

3) Running droiddoc depends on the availability of javadoc, but this is only run when building the SDK. Are there potential problems with introducing a dependency on javadoc in more situations?

4) If the @Override checking works as planned, does the java 6 version check become completely redundant?

Tom.

2009/9/18 Jean-Baptiste Queru <j...@android.com>

--
Tom Gibara
email: m...@tomgibara.com
web: http://www.tomgibara.com
blog: http://blog.tomgibara.com
twitter: tomgibara

[Chad Fawcett]

Hey Tom, 

Does your new version throw an error, or just print one out? I'm not a huge .mk guy either (or java for that matter), but here is how I was going to approach it:

* Pre-compile your doclet in 1.6 and add it it to prebuilt. (Possibly throwing in a src folder there just for future edits if you were ok with it).

* Update main.mk's java check. If it's 1.5, great, if it's 1.6 instead of crashing and burning, set a "RunOverrideCheck" type flag. 

* Update definitions.mk. I got as far as wrapping your doclet into the transform-java-to-classes definition so that it ran on the same sources, same classpath, etc. I was planning to update that to check the flag mentioned above and only run it on java 1.6 builds. If it only prints out ERROR/WARNING, then I'd wrap it in a script that will throw a true error to stop the build.

* Explicitly add -source 1.5 to the javac call that's also in that transform define, so any 1.5/1.6 issues that are caught properly by the compiler get caught.  

* I don't know if there's any reason to also add a -target 1.5, question for you real java people.

I can show you what I've got going in definitions.mk and the half-baked changes in main.mk and see if we can pull it all together if you'd like. 

 -Chad

[Chad Fawcett]

For question #4, I figure it only makes sense to call it on a 1.6 build, so leave in the java check so that we can keep the build time on 1.5 down a bit by skipping the doclet runs. (I also didn't know if you were using any 1.6 specific features), and only make that java version check once in main instead of on every transform-java-to-class call.

[Tom Gibara]

Hi Chad,

Almost anyone could do a better job than me, editing a make file, but fwiw, this is the line I introduced before the classes get compiled:

/usr/lib/jvm/java-6-sun/bin/javadoc -J-Xmx256m -docletpath OVERRIDE_CHECK -quiet -doclet OverrideCheck -private \ $(addprefix -classpath ,$(strip \ $(call normalize-path-list,$(PRIVATE_ALL_JAVA_LIBRARIES)))) \ \@$(dir $(PRIVATE_CLASS_INTERMEDIATES_DIR))/java-source-list-uniq

Does your new version throw an error, or just print one out?

It displays any errors and then returns false from its main method - this seems to have the desired effect of communicating an error back to the shell. I've just uploaded the amended version:

http://www.tomgibara.com/android/override-check

* Pre-compile your doclet in 1.6 and add it it to prebuilt. (Possibly throwing in a src folder there just for future edits if you were ok with it).

I tend to think of prebuilt components as a last resort, but given the circularity introduced by building the doclet (and given that it's so simple) this might be the most straightforward option. I regard OverrideCheck.java as being in the public domain, so the source code can be distributed or licenced in anyway that's useful.

* Explicitly add -source 1.5 to the javac call that's also in that transform define, so any 1.5/1.6 issues that are caught properly by the compiler get caught.  

* I don't know if there's any reason to also add a -target 1.5, question for you real java people.

Looking at javac.mk, you can see that -target 1.5 is specified, but not -source 1.5. I guess the 1.5 target is needed by some other tool, dex perhaps? And I suppose -source 1.5 hasn't been needed until now because it was the only supported compiler - I guess it should be added.

If you want to roll these changes into the ones you've already made, I'm fine with that - you seem to have a clearer sense of how to integrate it.

Tom.

2009/10/1 Chad Fawcett <chadf...@gmail.com>

[Chad Fawcett]

I've submitted changes incorporating the doclet into the build process and allowing java 1.6 here:

https://review.source.android.com/12074   (platform/build)

https://review.source.android.com/12075   (platform/prebuilt)

 -Chad

[Jean-Baptiste Queru]

I haven't had time to look at the changes (and honestly I'm not an
expert there, so I'll have to ask other people to have a look).

I want to say however that I really appreciate the effort that you've
been putting into this. I think it's a great step forward.

JBQ

[rockefeller]

I would like to suggest not to do this check if user types
"make clean" to clean output files.

On 10月2日, 上午11時43分, Chad Fawcett <c...@useless.net> wrote:
> I've submitted changes incorporating the doclet into the build process and
> allowing java 1.6 here:
>

> https://review.source.android.com/12074  (platform/build)https://review.source.android.com/12075  (platform/prebuilt)

> > 2009/10/1 Chad Fawcett <chadfawc...@gmail.com>

> >>>>http://android.git.kernel.org/?p=platform/build.git;a=blob;f=core/def...
>
> >>>> JBQ
>
> >>>> On Fri, Sep 18, 2009 at 2:58 PM, Chad Fawcett <chadfawc...@gmail.com>

> >>>> wrote:
> >>>> > This is great, Tom, glad to see something come out of that thread so
> >>>> > quickly!
> >>>> > I'm not yet as up to speed on the build process as I'd like, but I
> >>>> think the
> >>>> > call to such a tool could be added (when building with 1.6) in
> >>>> > build/core/definitions.mk in the "transform-java-to-classes.jar"
> >>>> definition
> >>>> > or perhaps as a new definition in that file which would be called from
> >>>> > java.mk right after the transform-java-to-classes call.
> >>>> >  -Chad
>
> >>>> > On Fri, Sep 18, 2009 at 5:29 PM, Tom Gibara <m...@tomgibara.com> wrote:
>
> >>>> >> This recent thread
>

> >>>>http://groups.google.com/group/android-platform/browse_thread/thread/...