Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 830088 - app-emulation/qemu: drop default USE=doc
Summary: app-emulation/qemu: drop default USE=doc
Status: RESOLVED FIXED
Alias: None
Product: Gentoo Linux
Classification: Unclassified
Component: Current packages (show other bugs)
Hardware: All Linux
: Normal normal (vote)
Assignee: John Helmert III
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-12-27 10:37 UTC by Manfred Knick
Modified: 2022-07-20 20:04 UTC (History)
6 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Manfred Knick 2021-12-27 10:37:37 UTC
AFAICS, Gentoo policy is *not* to pull in Documentation as default.
Setting global "doc" in /etc/portage/make.conf is discouraged as well.

Reproducible: Always
Comment 1 Manfred Knick 2021-12-27 10:39:57 UTC
Please, c.f. [ https://bugs.gentoo.org/802618#c11 ]
Comment 2 John Helmert III archtester Gentoo Infrastructure gentoo-dev Security 2021-12-27 17:34:56 UTC Comment hidden (obsolete)
Comment 3 Sam James archtester Gentoo Infrastructure gentoo-dev Security 2021-12-27 21:21:35 UTC
Note that it might well be to get man pages.
Comment 4 John Helmert III archtester Gentoo Infrastructure gentoo-dev Security 2021-12-28 05:30:23 UTC
It does seem to be required to get manpages. The size difference between USE=doc and not is ~14mb. This isn't really significant on most modern hardware, and Sphinx isn't really heavy, so I think this is an appropriate tradeoff to get manpages by default. So, if Sphinx or the size impact is really a problem for you, I'd just suggest turning off USE=doc.

I'll leave this open for a while in case anyone else has an opinion, though.
Comment 5 Ionen Wolkens gentoo-dev 2021-12-28 09:14:18 UTC
Optimal would be to provide a man page tarball in SRC_URI (used when USE=-doc) to satisfy both this and bug #770997 that wanted man pages by default, qemu doesn't update all that often and generating it shouldn't be much of a burden imo.

At one point there was consideration to make this a policy (man pages always available by default without USE, and if non-trivial deps then build them) but not all devs liked the added burden.
Comment 6 Ionen Wolkens gentoo-dev 2021-12-28 09:27:37 UTC
(In reply to Ionen Wolkens from comment #5)
> Optimal would be to provide a man page tarball in SRC_URI
On a side-note, /if/ going that route (I don't really mind either way personally), including the script used to generate the man page tarball in the tarball itself tend to be useful.
Comment 7 Marco Scardovi (scardracs) 2022-01-11 13:37:46 UTC
Personally, if possible, I'd suggest to treat manpages and docs as 2 different things and with 2 differents IUSE (eg: doc and man, I see man IUSE is used in other cases too [1]). Other than that, if not possible to follow my suggestion, I agree with what have been said before me: dropping a doc USE is not a good idea, because it contains manpages too.

[1] https://packages.gentoo.org/useflags/search?q=man
Comment 8 Manfred Knick 2022-01-11 14:15:13 UTC
(In reply to Sam James from comment #3)
> Note that it might well be to get man pages.
Sorry - caught by surprise: Filing this bug, 
I would never have expected this intermixture.

(In reply to Marco Scardovi (scardracs) from comment #7)
> ... treat manpages and docs as 2 different things ...
+ 1
Comment 9 Matthias Maier gentoo-dev 2022-01-11 15:04:51 UTC
The qemu build system uses sphinx internally to build docs and manpages and provides a single configuration option "docs" to enable or disable this build.

Because man pages are a very useful thing to have by default the use flag is enabled by default.

We would need to patch the build system in order to allow to build man pages independently from the rest of the html documentation. But honestly what do we gain by that?

This just creates a maintenance burden for very little gain.


If you really do not want to see the documentation installed, you can already either set USE=-doc, or use INSTALL_MASK="/usr/share/doc/qemu-*" to prevent any installation of documentation.
Comment 10 Manfred Knick 2022-01-11 17:03:32 UTC
(In reply to Matthias Maier from comment #9)

Perhaps you might like to note that "htop" displays
   "Add extra documentation (API, Javadoc, etc.)
   It is recommended to enable per package instead of globally
which - in my case - worked misleading.

> This just creates a maintenance burden for very little gain.
Thanks a lot for your explanation!
Comment 11 Larry the Git Cow gentoo-dev 2022-07-20 19:00:54 UTC
The bug has been referenced in the following commit(s):

https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=514d75e3d2f15b79934302e1015f2050da8868db

commit 514d75e3d2f15b79934302e1015f2050da8868db
Author:     Sam James <sam@gentoo.org>
AuthorDate: 2022-07-20 18:55:02 +0000
Commit:     Sam James <sam@gentoo.org>
CommitDate: 2022-07-20 18:58:51 +0000

    app-emulation/qemu: provide pre-generated man pages
    
    Bug: https://bugs.gentoo.org/830088
    Signed-off-by: Sam James <sam@gentoo.org>

 app-emulation/qemu/Manifest             |   1 +
 app-emulation/qemu/qemu-7.0.0-r3.ebuild | 944 ++++++++++++++++++++++++++++++++
 app-emulation/qemu/qemu-9999.ebuild     |  24 +-
 3 files changed, 968 insertions(+), 1 deletion(-)
Comment 12 John Helmert III archtester Gentoo Infrastructure gentoo-dev Security 2022-07-20 19:05:53 UTC
(In reply to Larry the Git Cow from comment #11)
> The bug has been referenced in the following commit(s):
> 
> https://gitweb.gentoo.org/repo/gentoo.git/commit/
> ?id=514d75e3d2f15b79934302e1015f2050da8868db
> 
> commit 514d75e3d2f15b79934302e1015f2050da8868db
> Author:     Sam James <sam@gentoo.org>
> AuthorDate: 2022-07-20 18:55:02 +0000
> Commit:     Sam James <sam@gentoo.org>
> CommitDate: 2022-07-20 18:58:51 +0000
> 
>     app-emulation/qemu: provide pre-generated man pages
>     
>     Bug: https://bugs.gentoo.org/830088
>     Signed-off-by: Sam James <sam@gentoo.org>
> 
>  app-emulation/qemu/Manifest             |   1 +
>  app-emulation/qemu/qemu-7.0.0-r3.ebuild | 944
> ++++++++++++++++++++++++++++++++
>  app-emulation/qemu/qemu-9999.ebuild     |  24 +-
>  3 files changed, 968 insertions(+), 1 deletion(-)

For anyone following along, this change ships QEMU with pregenerated docs by default, so we can avoid the annoying sphinx deps *and* get manpages by default.
Comment 13 Manfred Knick 2022-07-20 19:59:25 UTC
Respect
for this perfectly weighted balancing of interests!
Thanks a lot
Kind regards