Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 669848 - Ebuild writing style guide GLEP is needed
Summary: Ebuild writing style guide GLEP is needed
Status: RESOLVED NEEDINFO
Alias: None
Product: Documentation
Classification: Unclassified
Component: New GLEP submissions (show other bugs)
Hardware: All All
: Normal enhancement
Assignee: GLEP Editors
URL: https://github.com/gentoo/gentoo/pull...
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2018-10-28 11:53 UTC by Eugene Bright
Modified: 2018-10-29 10:52 UTC (History)
0 users

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 Eugene Bright 2018-10-28 11:53:54 UTC
Currently maintainers are prone to prohibit any ebuild formatting changes.
Eclass inheritance and IUSE definition are done in one line by convention.
I personally stand against using long lines in ebuilds. PEP8 should be a good point to start new GLEP.

My points in defence of multi-line IUSE:
 - more readable
 - easy flag sorting (vim's ":!sort" is enough)
 - clear `git diff` in case of flag addition/deletion

The same is applicable for inheriting eclasses if only one class is inherited per line.

Link to the precedent.
https://github.com/gentoo/gentoo/pull/10192#discussion_r227992990

Reproducible: Always

Steps to Reproduce:
1. Send a new ebuild formatted in PEP8 manner
Actual Results:  
Ebuild is not accepted by maintainer.

Expected Results:  
Ebuild is accepted by maintainer.
Comment 1 Ulrich Müller gentoo-dev 2018-10-28 17:14:20 UTC
<GLEP editor>
We don't assign GLEP numbers unless there is a first draft. So please follow the workflow as outlined in GLEP 1:
https://www.gentoo.org/glep/glep-0001.html#glep-work-flow
</GLEP editor>

(Also, the devmanual already addresses line length and whitespace. I doubt that a separate GLEP would be the best format a style guide.)
Comment 2 Eugene Bright 2018-10-28 17:26:27 UTC
Devmanual should be enough. I just can't find related style guides in it.
Could you give me a hint?
Comment 3 Ulrich Müller gentoo-dev 2018-10-28 17:54:29 UTC
https://devmanual.gentoo.org/ebuild-writing/file-format/index.html#indenting-and-whitespace

There are also some tacit conventions, like having single lines for things like KEYWORDS, IUSE, and inherit, in order to facilitate grep across the tree. I don't think we've any formal writeup for those, but everyone seems to follow them.
Comment 4 Eugene Bright 2018-10-29 08:59:58 UTC
Thank you very much.
Relying on grep doesn't look a good justification for prohibiting multi-line IUSE. The assumption that IUSE is defined in one line is generally wrong. Moreover writing long lines contradicts with manual recommendations as it's really *possible* to make them readable and short.
Why not to use specialized tools like equery for probing for USE flags?
Comment 5 Ulrich Müller gentoo-dev 2018-10-29 10:52:15 UTC
As I said, this is currently not an item for the GLEP editors, but should be discussed on the mailing lists.

(My personal opinion is that there will be zero chance for changing that long established convention. Feel free to try, though.)

$ find /var/db/repos/gentoo -name '*.ebuild' -exec grep '^KEYWORDS=".*"' '{}' + | wc -l
31840
$ find /var/db/repos/gentoo -name '*.ebuild' -exec grep '^KEYWORDS="[^"]*$' '{}' + | wc -l
1