Suggestions to improve the JAVA guidelines

[Orcan Ogetbil]

Hi, 
As I promised overholt on IRC, I wanted to share my views about the Fedora Java packaging guidelines from a non-Java-coder point of view.

JAVA GUIDELINES:

- "JNI-using JAR files"
This link is broken. It can be fixed easily.

- BuildRequires:  jpackage-utils
Why do we need this? I understand Requires:  jpackage-utils for directory ownership etc, but the BR is not necessary for most packages (at least all the ones I saw so far). I think this should *not* be required.

- In certain cases, we can build applications GCJ-natively (producing .so files). But these won't work with any JVM. What should be the packager's primary preference? GCJ-native or OpenJDK? The first one runs faster, but the second one has larger coverage.

For instance, tuxguitar (that I packaged) provides GNU Makefiles (that use GCJ) for this. Are the resulting .so files going to be the same as the ones built by aot-compile-rpm? (More about AOT later)

This case has confused me a lot in the past.

- Some explanation in the beginning about what GCJ can do and what openjdk can do; and some information about byte-code vs. machine-code will be very useful.

- BuildRequires: java-devel [>= specific_version]
How will the packager get to know the "specific_version"? For openjdk this is 1:1.6.0 , but for GCJ this is 1.5.0 . Are there other numbers that we need to know? Can't we put the numbers for all the cases in the guidelines?

- The Specfile Templates for ant and maven contradict with what was written in the BuildRequires and Requires section.

- the abbreviation "SNPG" should be defined in the first possible place, not in the third iteration (both for ant and maven).

- "Will this preserve the line ending as the this page says it must?"
This would be an artistic ending if we were writing a novel. But I think a guideline shouldn't end with open questions :)

GCJ GUIDELINES:

- It would be nice if there was a definition of GCJ-AOT bits. What do they do? Why do we like them? What does gij do? etc

- "Note: For Fedora versions < 8, no JDK was available other than GCJ so java packages with executable code MUST have the GCJ AOT bits."

This notice can be removed safely.

- The occurences of 
   %attr(-,root,root)
should be removed.

- GCJ AOT bits SHOULD be built and included in packages.
This needs to be more explicit. ie. 's@in packages@in all Java packages@'. I also think that this sentence should go to JAVA GUIDELINES so people click on the link for "GCJ Guidelines". The way that "GCJ Guidelines" link is put there, doesn't give an impression that it should be visited for any possible Java package.

These are all issues I encountered. If I remember more I will post them here. I thought a review on the guidelines from a Java-ignorant person would help other Java-ignorant people in the future. Thanks for reading :)

-oget

[Orcan Ogetbil]

Apparently Conrad forgot to send his reply to the mailing list. With his permission I'm quoting the message he sent to me:

--- On Wed, 11/19/08, Conrad Meyer wrote:
> > Hi,
> > As I promised overholt on IRC, I wanted to share my
>
> views about the Fedora
> > Java packaging guidelines from a non-Java-coder point
>
> of view.
> > JAVA GUIDELINES:
> > "JNI-using JAR files"
> >
> > This link is broken. It can be fixed easily.
> > BuildRequires:  jpackage-utils
> >
> > Why do we need this? I understand Requires:
>
> jpackage-utils for directory
> > ownership etc, but the BR is not necessary for most
>
> packages (at least all
> > the ones I saw so far). I think this should *not* be
>
> required.
>
> rpm -ql jpackage-utils | grep /usr/bin
>
> A lot of these are useful.

Yes, I agree. But can't we leave the BR out for those packages which don't use these tools?
> > In certain cases, we can build applications
>
> GCJ-natively (producing .so
> > files). But these won't work with any JVM. What
>
> should be the packager's
> > primary preference? GCJ-native or OpenJDK? The first
>
> one runs faster, but
> > the second one has larger coverage.
>
> We prefer both, but only require .class files (compiled by
> either GCJ or 
> OpenJDK).
> > For instance, tuxguitar (that I packaged) provides GNU
>
> Makefiles (that use
> > GCJ) for this. Are the resulting .so files going to be
>
> the same as the ones
> > built by aot-compile-rpm? (More about AOT later)
> >
> > This case has confused me a lot in the past.
>
> I think we require you to ship .class files as well if
> it's a java project.

Let's make this clear: .jar files are nothing but containers of .class files and a manifest file, right? When you say we require .class files, does that imply that we require them either standalone or inside some .jar file? If yes, these statements should go to the guidelines.

Also, I'd be glad if someone answers my question above?
> > Some explanation in the beginning about what GCJ can
>
> do and what openjdk
> > can do; and some information about byte-code vs.
>
> machine-code will be very
> > useful.
> > BuildRequires: java-devel [>= specific_version]
> >
> > How will the packager get to know the
>
> "specific_version"? For openjdk this
> > is 1:1.6.0 , but for GCJ this is 1.5.0 . Are there
>
> other numbers that we
> > need to know? Can't we put the numbers for all the
>
> cases in the guidelines?
>
> Just those, I think. Adding them somewhere couldn't
> hurt.
> > The Specfile Templates for ant and maven contradict
>
> with what was written
> > in the BuildRequires and Requires section.
>
> How?

In the "BuildRequires and Requires section", it states that we need to put explicit versions for R:java and BR:java-devel. Yet in the templates no explicit versions were used or indicated.
> > the abbreviation "SNPG" should be defined
>
> in the first possible place,
> > not in the third iteration (both for ant and maven).
>
> It's commonly used by other
> non-normal-packaging-guidelines documentation, but 
> this confused me at first as well.
> > "Will this preserve the line ending as the this
>
> page says it must?"
> > This would be an artistic ending if we were writing a
>
> novel. But I think a
> > guideline shouldn't end with open questions :)
> >
> > GCJ GUIDELINES:
> > It would be nice if there was a definition of
>
> GCJ-AOT bits. What do they
> > do? Why do we like them? What does gij do? etc
> > "Note: For Fedora versions < 8, no JDK was
>
> available other than GCJ so
> > java packages with executable code MUST have the GCJ
>
> AOT bits."
> > This notice can be removed safely.
>
> When this was written F-7 wasn't yet EOL, I think.
> Agreed.
> > The occurences of
> >  %attr(-,root,root)
> >
> > should be removed.
> > GCJ AOT bits SHOULD be built and included in
>
> packages.
> > This needs to be more explicit. ie. 's@in
>
> packages@in all Java packages@'.
>
> Eh, it's in the GCJ/Java guidelines page, not anything
> for all packages.

I am not saying "all packages". I say "all Java packages". I have to say that being explicit clears an important amount of confusion in most cases I encounter in life.
> > I also think that this sentence should go to JAVA
>
> GUIDELINES so people
> > click on the link for "GCJ Guidelines". The
>
> way that "GCJ Guidelines" link
> > is put there, doesn't give an impression that it
>
> should be visited for any
> > possible Java package.
>
> Makes sense.
> > These are all issues I encountered. If I remember more
>
> I will post them
> > here. I thought a review on the guidelines from a
>
> Java-ignorant person
> > would help other Java-ignorant people in the future.
>
> Thanks for reading :)
> > -oget
>
> I agree with most of your criticisms and would welcome
> these changes. I think 
> the wiki page is locked though.
> Regards,

Cheers,

-oget

[Victor Vasilyev]

Orcan,

Orcan Ogetbil wrote:
> Let's make this clear: .jar files are nothing but containers of .class files and a manifest file, right?

A JAR file can have a bit more functions than providing a simplest ZIP 
archive of .class files and a manifest file.
But, globally you are right, JAR is container for resources intended to 
be used by Java program(s).
Complete info about it in the JAR File Specification  [1] .

IMHO Ideally, a JAR file in the target software package (i.e. in the 
binary RPM) should be the same as the JAR file that is originally 
provided by its Java software project.
Of course, it is true only if there are no intentions to change original 
behavior of the Java applications that are based on that JAR file.

BTW Such viewpoint gives me idea that repackaging of JARs via 
brp-java-repack-jars is not good for pure Java software at all.
Note, it doesn't meet a requirement declared in the message [2] :
"... a jar ... needs to be repacked if (a) it is destined for 
/usr/share/ ..."

[1] http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html
[2] 
https://www.redhat.com/archives/fedora-devel-java-list/2008-September/msg000...

Cheers,
Victor Vasilyev

[Victor Vasilyev]

Hi,

It seems one interesting question about Java guidelines has no answer yet...

Orcan Ogetbil wrote:
> Conrad Meyer wrote:
> > Orcan Ogetbil wrote:
> > > JAVA GUIDELINES:
> > > BuildRequires: jpackage-utils
> > >
> > > Why do we need this? I understand Requires: jpackage-utils for 
> > > directory ownership etc, but the BR is not necessary for most 
> > > packages (at least all the ones I saw so far). I think this should 
> > > *not* be required.
> >
> > rpm -ql jpackage-utils | grep /usr/bin
> > A lot of these are useful.
>
> Yes, I agree. But can't we leave the BR out for those packages which don't use these tools?

AFAIK minimization of dependencies between components is an important 
development target of any system.
Establishing of the superfluous dependencies is not a good development 
approach even if we'll add a dependency on a component that is very 
useful in all other cases.

The jemmy package [1] is an example where dependencies on the 
jpackage-utils are redundant.

Are there any valuable reasons for establishing dependencies on the 
jpackage-utils if such facilities are not used in a package/subpackage?

[1] https://bugzilla.redhat.com/show_bug.cgi?id=514699

Thanks in advance,
Victor

[Andrew Overholt]

* Victor Vasilyev  [2009-07-30 19:33]:
> Orcan Ogetbil wrote:
> > Conrad Meyer wrote:
> > > Orcan Ogetbil wrote:
> > > > JAVA GUIDELINES:
> > > > BuildRequires: jpackage-utils
> > > >
> > > > Why do we need this? I understand Requires: jpackage-utils for  
> > > > directory ownership etc, but the BR is not necessary for most  
> > > > packages (at least all the ones I saw so far). I think this should  
> > > > *not* be required.
> > >
> > > rpm -ql jpackage-utils | grep /usr/bin
> > > A lot of these are useful.
> >
> > Yes, I agree. But can't we leave the BR out for those packages which don't use these tools?
> > [...]
>
> Are there any valuable reasons for establishing dependencies on the  
> jpackage-utils if such facilities are not used in a package/subpackage?

The BR on jpackage-utils could probably be made optional.

Andrew

[Victor Vasilyev]

Hi Andrew,

Andrew Overholt wrote:
> Victor Vasilyev  [2009-07-30 19:33]:
> > Are there any valuable reasons for establishing dependencies on the 
> > jpackage-utils if such facilities are not used in a package/subpackage?
>
> The BR on jpackage-utils could probably be made optional.

Why only BR?
For example, my package jemmy doesn't use the jpackage-utils facilities 
in the run time too.

Moreover, I don't see any reasons to have the run time dependencies on 
jpackage-utils for both javadoc and manual subpackages.
At least concerning javadoc subpackages the OpenJDK (i.e java-devel 
package) must have complete set of tools to create javadoc, otherwise it 
is a bug JDK, isn't it?

---
Victor

[Andrew Overholt]

* Victor Vasilyev  [2009-07-31 11:11]:
> Hi Andrew,
>
> Andrew Overholt wrote:
> > Victor Vasilyev  [2009-07-30 19:33]:
> > > Are there any valuable reasons for establishing dependencies on the  
> > > jpackage-utils if such facilities are not used in a 
> > > package/subpackage?
> >
> > The BR on jpackage-utils could probably be made optional.
>
> Why only BR?

Doesn't jpackage-utils own /usr/share/java which you're using in your
jemmy package?

Andrew

[Mat Booth]

On Fri, Jul 31, 2009 at 4:23 PM, Andrew Overholt wrote:
> Victor Vasilyev  [2009-07-31 11:11]:
> > Hi Andrew,
> >
> > Andrew Overholt wrote:
> > > Victor Vasilyev  [2009-07-30 19:33]:
> > > > Are there any valuable reasons for establishing dependencies on the
> > > > jpackage-utils if such facilities are not used in a
> > > > package/subpackage?
> > >
> > > The BR on jpackage-utils could probably be made optional.
> >
> > Why only BR?
>
> Doesn't jpackage-utils own /usr/share/java which you're using in your
> jemmy package?
>
> Andrew

It also owns ${_javadocdir}, which is where you should be installing javadocs.

[Victor Vasilyev]

Mat, Andrew,

Thanks for the clarifications.

I've understood that the jpackage-utils package has got a lot of 
functions and facilities,
and it is not just a container for the utility scripts.

From this moment, I'll use the jpackage-utils as described without any 
doubts  :-)

---
Victor

Booth wrote:
> On Fri, Jul 31, 2009 at 4:23 PM, Andrew Overholt wrote:
> > Victor Vasilyev  [2009-07-31 11:11]:
> > > Hi Andrew,
> > >
> > > Andrew Overholt wrote:
> > > > Victor Vasilyev  [2009-07-30 19:33]:
> > > > > Are there any valuable reasons for establishing dependencies on the
> > > > > jpackage-utils if such facilities are not used in a
> > > > > package/subpackage?
> > > >
> > > > The BR on jpackage-utils could probably be made optional.
> > >
> > > Why only BR?
> >
> > Doesn't jpackage-utils own /usr/share/java which you're using in your
> > jemmy package?
> >
> > Andrew
>
> It also owns ${_javadocdir}, which is where you should be installing javadocs.

[Andrew Overholt]

Hi,

Sorry no one responded earlier.  I'm in the process of trying to get all
of these questions/comments into the Talk page [1] of the guidelines
[2].

On Wed, 2008-11-19 at 00:36 -0800, Orcan Ogetbil wrote:
> As I promised overholt on IRC, I wanted to share my views about the
> Fedora Java packaging guidelines from a non-Java-coder point of view.

Thanks!
> In certain cases, we can build applications GCJ-natively
>
> (producing .so files). But these won't work with any JVM.

The .so files will only be used by gij but the corresponding .class
files will be the same and will be used by other JVMs.
> What should be the packager's primary preference? GCJ-native or
> OpenJDK? The first one runs faster, but the second one has larger
> coverage.

Many people said they want to keep GCJ AOT bits for F11 so I guess that
will continue to be the preference.
> For instance, tuxguitar (that I packaged) provides GNU Makefiles (that
> use GCJ) for this. Are the resulting .so files going to be the same as
> the ones built by aot-compile-rpm? (More about AOT later)

I don't know what tuxguitar is doing, but this small explanation from a
non-GCJ expert may help:

- gcj can compile java code in one of two ways:

1) .java source directly to C++-style .so files
2) java bytecode (.class files) to special GCJ-only .so files

- in case 2) above, the package will ship *both* the .class files
(usually in a .jar) *and* the GCJ .so files.  The GCJ .so files will
*only* be read by gij -- the GCJ java bytecode interpreter -- and not by
other JVMs.  Since GCJ is an ahead-of-time (AOT) compiler and has no
just-in-time (JIT) compiler like HotSpot, using these pre-compiled .so
files is faster than purely interpreting the java bytecode.  The
presence of the AOT .so files (sometimes referred to as "GCJ AOT bits")
is inconsequential to JVMs other than gij/gcj.

I hope this helps.  Like I said, I'm trying to capture outstanding
issues with the guidelines on the talk page in the hopes that we can
drive this to some fixes.

Andrew

[1]
https://fedoraproject.org/w/index.php?title=Packaging_talk:Java

[2]
http://fedoraproject.org/wiki/Packaging/Java