Javadoc subpackage generator

[mizdebsk]

Long time ago we tried to introduce experimental generator of javadoc subpackages (see 26ebe8d701f53159f10194b43e51891fa1864eda) aimed at reducing boilerplate code in spec files, but it wasn't successful for different reasons.

Since then we added several missing bits that can make it easier to implement such feature:

• installation is automated with %mvn_install
• %files are automated with .mfiles-javadoc
• %mvn_build and %mvn_install know when javadocs were skipped and can disable javadoc subpackage generation,
• %license macro - the same license can be reused for javadocs, it was not possible with %doc used for licenses

Therefore lets reconsider adding this feature.

[msimacek]

%license macro - the same license can be reused for javadocs, it was not possible with %doc used for licenses

Do you have any idea how to do that? I don't see any way how to programatically access filelists. I though I could redefine %license macro to capture the licenses in some global variable, but RPM doesn't allow that (ironically, this can be done for %doc, but not for %license).

[mizdebsk]

This should do the trick:

%files javadoc -f .mfiles-javadoc
%{_licensedir}/*

[mizdebsk]

Or even better (will work even when there are no license files installed):

%install
install -d -m 755 %{buildroot}%{_licensedir}

%files javadoc -f .mfiles-javadoc
%{_licensedir}
%exclude %dir %{_licensedir}

[msimacek]

That works, thanks. It should also have %license on %{_licensedir} in order to have RPMFILE_LICENSE flag set. There are some limitations of this approach:

• It includes the license files in the directory of the declaring package, not it's own, thus breaking the convention, that license files are installed in %{_licensedir}/$rpm_name. On the other hand, this will save space, as the file will be installed only once if both javadoc and decalring package is installed.
• It will include license files from all subpackages, so there may be duplicates
• It is order dependent - it will only include license files from subpackages that were declared before the javadoc subpackage. We'll need to emphasise this in the documentation.

[msimacek]

Solution with a macro that the user explicitly uses:

• the macro for generating the subpackage

  %generate_javadoc_package() \
  %package javadoc \
  Summary:        Javadoc for %{?scl:%{pkg_name}}%{!?scl:%{name}} \
  %description javadoc \
  API documentation for %{?scl:%{pkg_name}}%{!?scl:%{name}}. \
  %files javadoc -f .mfiles-javadoc \
  %%license %{_licensedir} \
  %exclude %dir %{_licensedir}

• installing the license dir for the case that there are no licenses would be done within body of %mvn_install

Fully automatic "solution" (user doesn't specify anything):

• disclaimer: I think this is a big hack and should not be implemented. I merely want to show that it's possible
• generation of javadoc must be registered by %mvn_build and %mvn_install -J
  • for %mvn_install, it's easy: %{?-J*:%global __javadoc_built 1}
  • for %mvn_build this would be more problematic, because we need to cature -j/--skip-javadoc. Rpm uses getopt for parsing, which cannot be made to process long options. It can, at least, be made to ignore them by making the optstring qwertyuiopasdfghjklzxcvbnm-. But to be able to get --skip-javadoc we'd need to parse it with lua. Then it would register %global __javadoc_built 1 like in %mvn_install
• It would need to detect, that the user already specified javadoc package manually, to avoid making a duplicate. This is the first hack that I don't like, but it works:

  %package(n) \
  %{expand: %%global __has_package_%{lua: print(string.gsub(rpm.expand("%{1}"), '[-+]', '_'))} 1} \
  %%package %**

• And now the biggest hack, to actually invoke the generation. There's no easy way to input top-level code without the user specifying anything. The only way I found is to redefine something which is always there (in fedora compliant specfiles):

  %changelog \
  %if (0%{?__javadoc_built:1} && 0%{!?__has_package_javadoc:1} && 0%{!?_without_javadoc:1}) \
  %generate_javadoc_package \
  %endif \
  %%changelog

[mizdebsk]

The first option (explicit macro invocation) seems fine to me. It has clear migration path and is safer than the other proposal.

Perhaps it could be improved a bit to make the macro more flexible:

• add option to skip auto-licenses - user would need to list them explicitly after macro invocation
• respect _without_javadoc - generate empty javadoc pkg

Also I would avoid word "Javadoc" in summary/description - it causes rpmlint warning.