[Soc-coordination] Jigsaw - Report 2

Sat Jun 18 10:29:49 UTC 2011

Status report Jigsaw num. 2 for GSoC 2011
-----------------------------------------

My internship is now finished, this means that I will be able to work on
my GSoC project a lot more than the previous weeks. I hope to make some
good progress in the next days.

This last 2 weeks, I was still studying how Jigsaw works. Even if there
is no progress on the Jigsaw packaging I have done some packages that
will help later.

I've spend a lot of time trying to package JT Harness[1] and JTReg[2].
I've successfully built JT Harness using CDBS but I've finally rewritten
the package using only debhelper and javahelper[3]. Javahelper was
really useful to build JAR files, move them to the right directory, put
the Javadoc in the right place as well as the examples. The Debian
directory of JT Harness can be found on the Java team SVN.

    svn co
svn+ssh://${SVN_USER}@svn.debian.org/svn/pkg-java/trunk/libjtharness-java

The source package of jtharness build 2 binary packages:
libjtharness-java and libjtharness-java-doc. You can see that by looking
at the "control" file in the "debian" directory. There are some
interesting files in this package, let's take a look at them.

First of all, some of the source files needed to be patched for the
package to build. So to accomplish this, there is a couple of patches in
"debian/patches":

    * dependencies.diff, used to locate JAR files in "/usr/share/java",
    * and,
    * rxtx.diff, done by Tom Marble used to change some imports from
    * "javax.comm" to "gnu.io".

To generate these patches, I've used the "edit-patch" command which is a
really awesome tool. This command uses a temporary shell where we can
edit files we want to patch. When the job is done, CTRL + D terminates
the temporary shell and the patch is generated.

There are 4 interesting files which are used to build the binary
packages and put the files in the right directories. These files are:

    * rules,
    * libjtharness-java-doc.install,
    * libjtharness-java.jlibs, and,
    * libjtharness-java-doc.javadoc.

Of course "rules" is the most important one. This file tells us how
packages are built. A good thing is that "rules" is quite simple in the
jtharness case.

    #!/usr/bin/make -f

    JAVA_HOME = /usr/lib/jvm/default-java

    override_dh_auto_build:
        ant -f build/build.xml

    %:
        dh $@ --with javahelper

We just tell where Java is and to use javahelper (--with javahelper).
Overriding "dh_auto_build" is interesting because since the JT Harness
uses Ant as build system we need to give to Ant where the "build.xml"
file is. By default Ant is searching it in the current directory but in
jtharness the file is in the "build" directory. Since the Ant build file
is correctly written, the build generates JAR files, Javadoc and
examples code. And "libjtharness-java*" files are here to put the
generated things in the right places.
The job of "libjtharness-java.jlibs" is to tell where to find the JAR
libraries. In this case, the intesresting JAR files were "javatest.jar"
and "jt-junit.jar". So in the .jlibs file we just give where those files
are after being built.
The job of "libjtharness-java-doc.javadoc" is to tell where the Javadoc
is and where to put it. So there is only one line that says the
generated Javadoc is in "jar-build/javadoc" and put it in
"/usr/share/doc/libjtharness-java/api".
And finally, "libjtharness-java-doc.install" is used to move the
examples. The syntax is same as "libjtharness-java-doc.javadoc".

The JT Harness package can be found in Sid[4] now thanks to Sylvestre
Ledru[5] who uploaded it for me. So the ITP bug[6] that I created is now
closed.

Building the package for jtreg is quite similar. In fact, it probably
easier but I'm still facing a problem. jtharness is just a library,
jtreg does have main classes and generate some binaries. The difficulty
here is to generate the man pages for the 2 generated binaries: jtdiff
and jtreg. These 2 files are shell scripts which just use "jtreg.jar"
with the correct parameters.

I tried several tools to generate the man pages of each script. Sadly, I
can't find a way that does not causes any problems.
My first choice was to use help2man[7]. This tool looked like to be
perfect for the job. But I couldn't find how to launch the scripts
correctly. The scripts needs "jtreg.jar" but they also need
"javatest.jar" from the libjtharness-java package. The classpath cannot
be set correctly due how the scripts are written. So to use help2man
I'll probably have to patch and completely rewrite "jtdiff.sh" and
"jtreg.sh" in the sources.
My second choice was to use txt2man[8]. During the build of jtreg there
is a "usage.txt" file which is generated and which can be used as a man
page. txt2man can take this text file and output a man page based on the
text. I thought it was working but when building the package, lintian
threw some warnings about syntax errors in the man pages.

    W: jtreg: manpage-has-bad-whatis-entry
usr/share/man/man1/jtdiff.1.gz
    W: jtreg: manpage-has-errors-from-man usr/share/man/man1/jtdiff.1.gz
292: warning [p 4, 3.3i]: cannot adjust line

Finally, few days ago I decided to try rst2man[9]. This tool looks cool
and easy to use. But the text that I have to convert into a man page is
not a reStructured text so it cannot without patching the "usage.txt"
file for example. I was going to do it but there is no such file in the
sources of jtreg. Actually this file is generated during the build but
the text had to come from somewhere. And it was from two properties
files in the source code.
I'm still looking for a good solution to generate the man pages. If
someone has any idea just let me know ;-)

The debian packaging of jtreg is not in the Java team SVN yet because of
the man pages problem. I opened an ITP bug[10] so people know that
someone is working on jtreg.

My goal for the next two weeks is to finish the jtreg package,
understand how "jpkg" (which is supposed to create Debian packages)
works in Jigsaw and write more examples using the modular JVM.

[1] http://jtharness.java.net/
[2] http://openjdk.java.net/jtreg/
[3] http://pkg-java.alioth.debian.org/docs/tutorial.html
[4] http://packages.debian.org/unstable/main/libjtharness-java
[5]
http://qa.debian.org/developer.php?login=sylvestre@debian.org&comaint=yes
[6] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=628857
[7] http://www.gnu.org/software/help2man/
[8] http://mvertes.free.fr/
[9] http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt
[10] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=629577
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/soc-coordination/attachments/20110618/feab8c95/attachment-0001.pgp>