Installing docs and examples

[Alan Somers]

My FreeBSD port reviewer (Garrett Cooper) requested that the ports
optionally not install examples and documentation. In the cases of
lutok and kyua-cli (I haven't checked the others), there doesn't seem
to be any easy way to do this with the make command. It seems like
the best solution would be to modify the autotools scripts to add
"--disable-examples" and "--disable-docs" arguments to the configure
script. Does this sound like a good idea? I'm not very good with
autotools, but if I can get it working, would you merge my changes?
-Alan

[Julio Merino]

Just for the record, this issue is being discussed in its
corresponding bug tracker entry:

http://code.google.com/p/lutok/issues/detail?id=4

[Giorgos Keramidas]

Why don't we want the docs installed by FreeBSD ports? So that the
ports machinery can do the installation itself, using MAN= or similar
options in the port Makefile?

I'm mostly interested to find out why we don't want the docs, because
other ports *do* install their documentation. For example mail/mutt
installs the manual of mutt, and the manpages of mutt, and so on.

[Julio Merino]

On Mon, Apr 29, 2013 at 4:29 AM, Giorgos Keramidas
<kera...@ceid.upatras.gr> wrote:
> Why don't we want the docs installed by FreeBSD ports? So that the
> ports machinery can do the installation itself, using MAN= or similar
> options in the port Makefile?
>
> I'm mostly interested to find out why we don't want the docs, because
> other ports *do* install their documentation. For example mail/mutt
> installs the manual of mutt, and the manpages of mutt, and so on.

My uninformed understanding is that ports want to provide "just" an
option to not install docs and examples... possibly to save some space
and, particularly, to cut down build times.

If I have to guess even further, I'd say that such options were
originally provided _only_ in packages where building the docs
required some heavyweight tools (gtkdoc, jade, ...) and/or where
building the examples required some additional dependencies. Having an
option to not install these results in less dependencies, and
therefore in a faster build. As a result of this, some other packagers
adopted the options even when it made no sense to do so in their own
packages -- i.e. where the docs and examples required no additional
dependencies. Or that's what I've seen happen in pkgsrc.

This is also similar to how some Linux distributions split the
documentation into -doc packages, but only when the docs are "huge" or
have a weird license.

Based on this, my take on the request is: in the case of Kyua, none of
the above are true. Neither the documentation nor the examples
require additional dependencies; therefore, cutting them out of the
build provides no advantage. Providing an option to disable their
build is just boilerplate in configure and the Makefiles for the only
benefit of ports. Even more: ports, as part of its infrastructure,
should have a way to _not_ install these files if the packager wants
to do so, without requiring the addition of unnecessary hacks to the
upstream packages.

For example, in pkgsrc this is as easy as issuing "rm -rf
${DESTDIR}${PREFIX}/path/to/unwanted/stuff" right after the
installation, so that the files don't end up in the binary package. Or
in Fedora, you'd specify %{_docdir}/.../ in a different -doc
subpackage to keep them outside of the main binary package. None of
these require changes to configure nor the Makefiles. It should be
possible to do the same thing in ports.

--
Julio Merino / @jmmv

[Garrett Cooper]

The existing infrastructure still installs to ${DESTDIR}${LOCALBASE} though, so there isn't anything preventing the files from being installed..

> For example, in pkgsrc this is as easy as issuing "rm -rf
> ${DESTDIR}${PREFIX}/path/to/unwanted/stuff" right after the
> installation, so that the files don't end up in the binary package. Or
> in Fedora, you'd specify %{_docdir}/.../ in a different -doc
> subpackage to keep them outside of the main binary package. None of
> these require changes to configure nor the Makefiles. It should be
> possible to do the same thing in ports.

Correct. The plist comment method and ports Makefile pattern matching for filtering out docs and examples wasn't employed, so the ports attached to the PR still need to be polished up...

Thanks!
-Garrett

[aso...@gmail.com]

Have you looked at my revised ports, Garrett? I think I got all of
the docs and examples filtered out. I reattached them to the PRs.

>
>
> --
> You received this message because you are subscribed to the Google Groups "kyua-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kyua-discuss...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Garrett Cooper]

Please see the attached comment on the lutok PR. I'm not positive as to whether or not the filtering is actually working properly if DOCS/EXAMPLES are enabled.
Thanks,
-Garrett