Nov 3, 2011

Automatic javadoc subpackage generation

Posted by Stanislav Ochotnicky at 4:53 PM / Labels: , , , , / 0 comments
Do you hate repeating the same thing over and over again? I know I do...
Java packaging guidelines state that we have to include javadocs with all java packages. This means we have to repeat following code in almost all packages (except pom and resource projects): 
...
%package        javadoc
Summary:        API documentation for %{name}
Group:          Documentation
Requires:       jpackage-utils

%description    javadoc
%{summary}.
...

%install
...
# javadoc
install -d -m 755 %{buildroot}%{_javadocdir}/%{name}
cp -pr target/site/apidocs/* %{buildroot}%{_javadocdir}/%{name}

...

%files javadoc
%doc LICENSE
%doc %{_javadocdir}/%{name}
...
The code is practically the same in all packages so why not automate this? Well there were two main reasons why this wasn't done before:
  • Copying of files needs to be done during install phase
  • If package contains license, javadoc has to have it too
We solved both of these in a fairly reasonable way. Resulting macro help looks like this: 
# %create_javadoc_subpackage can be used to completely create
# javadoc subpackage for java projects.
# !!! Needs to be used at the end of %install section
# There are these variables that change its behaviour:
#
# %__javadoc_license - set if the license is in non-standard place to
#                prevent Requires on main package
# %__apidocs_dir - set custom path to directory with javadocs
#                (defaults to target/site/apidocs)
# %__javadoc_skip_requires - if defined javadoc subpackage will not
#                require main package under any circumstances (useful
#                if upstream doesn't provide separate license file)
#
Is it understandable enough? If you need to generate javadocs, just make them build and then add %create_javadoc_subpackage macro call at the end of %install section. Normally you shouldn't have to change anything. We search in a few standard places for licenses. More specifically we look for LICENSE* COPYING* doc/LICENSE* doc/COPYING* license*. Do you have more ideas where to look? It's easy to add. If we don't find license we automatically add requires on main package and assume you put license in there. If upstream doesn't provide separate license file you can do %global __javadoc_skip_requires t and we will ignore licensing completely.
I'd like this added to our packaging guidelines so we can start using it. My testing shows it works fairly well. I'd love to improve it so you could place it anywhere in the spec, not just %install section, but rpm macros are...complicated.
*Note*: For gory details head over to our git repository. For now it's in separate feature branch.

Share/Save/Bookmark
Oct 17, 2011

Understood and agreed with

Posted by Stanislav Ochotnicky at 12:25 AM / Labels: , , , , / 1 comments
Dear OSS/Fedora/whatever reader. Stop right here.

Oh nothing's going to change my love for you
I wanna spend my life with you
So we make love on the grass under the moon
No one call tell, damned if I do
Forever journey on golden avenues
I drift in your eyes since I love you
I got that beat in my veins for only rule
Love is to share, mine is for you

Share/Save/Bookmark
Sep 12, 2011

Making packaging Maven projects easier

Posted by Stanislav Ochotnicky at 6:47 PM / Labels: , , / 0 comments
There are two recent changes to our Java guidelines in Fedora and use of Maven when packaging that I'd like to mention today

Maven dependency mapping macros

Thing I haven't blogged about yet but it's pretty important: We have new macros for maven depmaps in Fedora. In the past when you wanted to map certain groupId:artifactId to a file in _javadir, you had to include snippet like this in your spec: 
%add_to_maven_depmap com.google.guava guava 05 JPP guava
%add_to_maven_depmap com.google.collections google-collections 05 JPP guava
This tells our maven that com:google:guava:guava and com.google.collections:google-collections can be found in one of the repositories as JPP/guava.jar. It meant you had to know the groupId:artifactId and other information, plus it was extremely easy to make a mistake here causing all sorts of trouble. Current code doing the same thing: 
%add_maven_depmap JPP-guava.pom guava.jar -a "com.google.collections:google-collections"
We parse the pom file and get groupId:artifactId from it, plus we do additional sanity checks such as:
  • naming of pom and jar file have to be consistent
  • jar file has to exist if packaging type is not pom
If you need additional mappings you can easily add them. There are few other options for this new macro useful in certain situations.

Maven test deps skipping

Long story short: When you use -Dmaven.test.skip=true in Fedora packages you no longer need to patch those test dependencies out of pom.xml.

We've had Apache Maven in Fedora for quite some time and packaging using Maven has been getting easier over time due to small tweaks to our packaging macros and guidelines changes. However there has been one problem that's been bugging all Java packagers and was especially confusing for those starting to package software built with Maven. The problem is that Maven creates a tree of dependencies before it starts building the project, but it includes test dependencies even when tests are being skipped.

Skipping tests is sometimes necessary due to problems with koji, or dependencies and up until now we had to either patch those tests dependencies from pom.xml or use custom dependency mappings (ugly concept in itself).

Last week I decided it's about time someone did something about this, so I dug in the Maven code and created a solution (more of a hack really) that is already included in Fedora. If you want the gory details, you can read the patch itself (I advise against it). I'll try to make the patch work properly so that it can be included in mainstream code.

I can just hope that packagers will find these changes helpful, but general feedback has been positive.

Share/Save/Bookmark
Subscribe to: Posts (Atom)