Re: How to get html, man into .destdir

[Roland Illig <roland.illig%gmx.de@localhost>]

Am 04.07.2022 um 11:09 schrieb Mayuresh:
> I have built a new package wip/ltsmin. It is commited, with some TODOs.
>
> I find that adding --docdir to configure args, automatically included
> certain documentation into /usr/share/doc
>
> The package also contains man pages and html documentation. But defining
> --mandir and --htmldir is not automatically installing these documents
> under .destdir.
>
> What is the right way to include man pages and/or html documentation in a
> pkgsrc package?

The package uses autoconf and automake, and up until now, some package
maintainers do not understand how they are intended to work together.
LTSmin seems to be such a case.

Its top-level Makefile.am says:
> if DX_COND_doc
> if HAVE_ASCIIDOC
> if HAVE_XMLTO
> SUBDIRS += doc

So in order to install this part of the documentation, you are supposed
to have Doxygen, AsciiDoc and xmlto installed. On the other hand, the
package already provides the pregenerated manual pages in its
distribution, making AsciiDoc and xmlto unnecessary for just installing
the package.

Even more strangely, doc/Makefile.am says:
> if HAVE_ASCIIDOC

As the directory 'doc' only gets processed if the 3 above variables are
set to true, checking again in doc/Makefile.am is redundant.

The top-level Makefile.in says:
> @DX_COND_doc_TRUE@@HAVE_ASCIIDOC_TRUE@@HAVE_XMLTO_TRUE@ \
>   am__append_1 = doc

I remembered that there was a variable for setting the make environment
at installation time, so I ran:
> $ bmake help topic=install_env

My first, rather brutal idea was to add this line to the pkgsrc Makefile:
> INSTALL_ENV+= am__append_1=doc

This would have the benefit of leaving HAVE_ASCIIDOC and HAVE_XMLTO
undefined, thereby preventing the documentation from being regenerated.

Then I remembered that instead of running gmake manually, there is a
list of directories used at installation time:
> $ bmake help topic=install_dirs

There's no documentation on that variable, but looking in
mk/install/install.mk revealed the following snippet:
> .if !target(do-install)
> do-install:
> .  for _dir_ in ${INSTALL_DIRS}
>         ${RUN} ${_ULIMIT_CMD}                                           \
>         cd ${WRKSRC} && cd ${_dir_} &&                                  \
>         ${PKGSRC_SETENV} ${INSTALL_ENV} ${MAKE_ENV}                     \
>                 ${MAKE_PROGRAM} ${MAKE_FLAGS} ${INSTALL_MAKE_FLAGS}     \
>                         -f ${MAKE_FILE} ${INSTALL_TARGET}
> .  endfor
> .endif

This code handles all the pkgsrc magic about setting up the right
environment, the PATH for the pkgsrc tools, and much more, making the
shortest and simplest possible solution:
> INSTALL_DIRS= . doc

Even though there is no help page for this variable, it is officially
supported, and it is also described in the pkgsrc guide:
https://www.netbsd.org/docs/pkgsrc/pkgsrc.html#build.install

Roland