Nov 3, 2011

Automatic javadoc subpackage generation

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

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


%files javadoc
%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.



Post a Comment