[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 1827baaac60d39987c44a791fde73b186c19844f Author: Sam James gentoo org> AuthorDate: Sat Jan 22 23:41:34 2022 + Commit: Sam James gentoo org> CommitDate: Sat Jan 22 23:43:45 2022 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1827baaa ebuild-writing/common-mistakes: .diff -> .patch We usually use .patch nowadays so reflect that in the docs. Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 4e26462..63c44d3 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -607,7 +607,7 @@ The best way to generate it would be: -$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild ~/some-package-0.2.0.diff +$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild ~/some-package-0.2.0.patch
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 7ce5e147a7ef3b776cb3910c0c21b999f7e2839b Author: Sam James gentoo org> AuthorDate: Sun Aug 1 02:50:13 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Dec 22 15:36:22 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7ce5e147 ebuild-writing/common-mistakes: add calling external tools without die Suggested-by: Joonas Niilola gentoo.org> Signed-off-by: Sam James gentoo.org> [Internal cross reference fixed] Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 13 + 1 file changed, 13 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index e0cdd12..4e26462 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -13,6 +13,19 @@ writing ebuilds. Common Ebuild Writing Mistakes + +Unguarded external calls + + + +Calls to external tools should be guarded with || die (or use +assert) in almost all cases to allow failure to be detected. +See . + + + + + Invalid use of static use-flag
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: bd11b6fbeaeb84ce87177e0524b712a61e5a08de Author: Sam James gentoo org> AuthorDate: Fri Sep 17 03:35:56 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Sep 17 09:09:23 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=bd11b6fb ebuild-writing/common-mistakes: fix formatting of DESCRIPTION/HOMEPAGE note Reported-by: Ulrich Müller gentoo.org> Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index cd37eb8..e0cdd12 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -416,7 +416,9 @@ SLOT="0" Make sure the DESCRIPTION is not overly long. Good descriptions will describe the main function of the package in a sentence. + + Please check if the HOMEPAGE variable is right and leads users to the right page if they want to find out more about the package. If no homepage for the package is available, set the HOMEPAGE variable to
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 719a4484b8c02dd2d69872c08b76a7cd850ffcff Author: Ulrich Müller gentoo org> AuthorDate: Sat Aug 14 09:53:42 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Sat Aug 14 09:53:42 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=719a4484 ebuild-writing/common-mistakes: Rewrap a long line Fixes: 947a4714250dfb5d614bce6ef3689b655f235234 Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 10 +- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index a179ef7..cd37eb8 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -385,11 +385,11 @@ Make sure when you bump a version, the stable KEYWORDS are all marked as -Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. a -dependency may have become mandatory but the USE flag remains in IUSE and -*DEPEND. Similarly, eclasses often become redundant due to changes in the ebuild, -or new EAPIs, e.g. eutils.eclass should be obsolete in modern EAPIs. -Remember to prune these. +Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. +a dependency may have become mandatory but the USE flag remains in IUSE and +*DEPEND. Similarly, eclasses often become redundant due to changes in the +ebuild, or new EAPIs, e.g. eutils.eclass should be obsolete in modern +EAPIs. Remember to prune these.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 947a4714250dfb5d614bce6ef3689b655f235234 Author: Sam James gentoo org> AuthorDate: Sun Aug 1 02:43:16 2021 + Commit: Sam James gentoo org> CommitDate: Sun Aug 1 02:43:16 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=947a4714 ebuild-writing/common-mistakes: rewrap paragraph Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 7 --- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index e46a36c..a179ef7 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -386,9 +386,10 @@ Make sure when you bump a version, the stable KEYWORDS are all marked as Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. a -dependency may have become mandatory but the USE flag remains in IUSE and *DEPEND. -Similarly, eclasses often become redundant due to changes in the ebuild, or new EAPIs, -e.g. eutils.eclass should be obsolete in modern EAPIs. Remember to prune these. +dependency may have become mandatory but the USE flag remains in IUSE and +*DEPEND. Similarly, eclasses often become redundant due to changes in the ebuild, +or new EAPIs, e.g. eutils.eclass should be obsolete in modern EAPIs. +Remember to prune these.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: cb01338bb42175efee3af2aeca1055c544b33140
Author: Sam James gentoo org>
AuthorDate: Sat Apr 10 01:41:53 2021 +
Commit: Sam James gentoo org>
CommitDate: Sun Aug 1 02:38:39 2021 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=cb01338b
ebuild-writing/common-mistakes: add 'Calling pkg-config directly'
Quite a lot of ebuilds do this. We should instead use the tc-getPKG_CONFIG
helper from toolchain-funcs.eclass which respects ${PKG_CONFIG} - useful
for e.g. cross-compiling.
Signed-off-by: Sam James gentoo.org>
ebuild-writing/common-mistakes/text.xml | 23 ++-
1 file changed, 22 insertions(+), 1 deletion(-)
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index 1969efe..cc87d74 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -505,8 +505,29 @@ the ebuild's quality and ease review.
-
+
+Calling pkg-config directly
+
+
+
+You should not call pkg-config directly in ebuilds because this is
+problematic for e.g. cross-compiling. The correct helper respects
+${PKG_CONFIG}. Instead, use tc-getPKG_CONFIG from
+toolchain-funcs.eclass, e.g.
+
+
+
+sed -i -e "s:-lncurses:$($(tc-getPKG_CONFIG) --libs ncurses):" || die
+
+
+
+Don't then forget to add virtual/pkgconfig to BDEPEND!
+
+
+
+
+
Common Ebuild Submission Mistakes
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 2c6c0026d80b3d6c34bc1c70a12debfa7dfdc30f Author: Sam James gentoo org> AuthorDate: Sat Apr 10 01:58:38 2021 + Commit: Sam James gentoo org> CommitDate: Sun Aug 1 02:38:37 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2c6c0026 ebuild-writing/common-mistakes: mention HTTPS for HOMEPAGE Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 23935be..ce4bc95 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -405,7 +405,8 @@ right page if they want to find out more about the package. And make sure the DESCRIPTION is not overly long. Good descriptions will describe the main function of the package in a sentence. If no homepage for the package is available, set the HOMEPAGE variable to -https://wiki.gentoo.org/wiki/No_homepage. +https://wiki.gentoo.org/wiki/No_homepage. Please also strive to test +HTTPS support for the site used in HOMEPAGE.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 3a00a5fc63342e1a2a5e01ce2db232e5d21f2c3f Author: Sam James gentoo org> AuthorDate: Sat Apr 10 02:16:27 2021 + Commit: Sam James gentoo org> CommitDate: Sun Aug 1 02:38:38 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3a00a5fc ebuild-writing/common-mistakes: mention leftover USE flags, inherits Suggested-by: Joonas Niilola gentoo.org> (inherits) Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 13 + 1 file changed, 13 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index ce4bc95..1969efe 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -378,6 +378,19 @@ Make sure when you bump a version, the stable KEYWORDS are all marked as ~. + + + +Unused flags and eclass inherits + + + +Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. a +dependency may have become mandatory but the USE flag remains in IUSE and *DEPEND. +Similarly, eclasses often become redundant due to changes in the ebuild, or new EAPIs, +e.g. eutils.eclass should be obsolete in modern EAPIs. Remember to prune these. + +
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: b27290e15d077e852be76bdf4e9627c9a84653a9 Author: Sam James gentoo org> AuthorDate: Sat Apr 10 01:57:35 2021 + Commit: Sam James gentoo org> CommitDate: Sun Aug 1 02:38:37 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b27290e1 ebuild-writing/common-mistakes: mention using latest EAPI Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 14 ++ 1 file changed, 14 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 2313c50..23935be 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -477,6 +477,20 @@ at least when the ebuild hits the stable branch. + + +Not using latest EAPI + + + +Often, user-submitted ebuilds do not use the latest EAPI and may even +be several versions behind. EAPIs bring new helper functions and improved +methods for completing common tasks. It's recommended that submitted ebuilds +use the latest EAPI possible (subject to eclass constraints) to improve +the ebuild's quality and ease review. + + +
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 8efea8b918e6b9f12d8612ed4c9bb498fcdbd33a Author: Sam James gentoo org> AuthorDate: Fri Jun 18 05:03:31 2021 + Commit: Sam James gentoo org> CommitDate: Sun Aug 1 02:38:39 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8efea8b9 ebuild-writing/common-mistakes: reformat 'DESCRIPTION and HOMEPAGE' Closes: https://github.com/gentoo/devmanual/pull/223 Signed-off-by: Sam James gentoo.org> ebuild-writing/common-mistakes/text.xml | 9 + 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index cc87d74..e46a36c 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -413,11 +413,12 @@ SLOT="0" +Make sure the DESCRIPTION is not overly long. Good descriptions will +describe the main function of the package in a sentence. + Please check if the HOMEPAGE variable is right and leads users to the -right page if they want to find out more about the package. And make sure -the DESCRIPTION is not overly long. Good descriptions will describe -the main function of the package in a sentence. If no homepage for the package -is available, set the HOMEPAGE variable to +right page if they want to find out more about the package. If no homepage for +the package is available, set the HOMEPAGE variable to https://wiki.gentoo.org/wiki/No_homepage. Please also strive to test HTTPS support for the site used in HOMEPAGE.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: aa2dd537f393f9c90b4bdef06f1478d0a09d8635 Author: Ulrich Müller gentoo org> AuthorDate: Tue Mar 30 18:17:02 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:17:02 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=aa2dd537 ebuild-writing/common-mistakes: Fix Gentoo Bugzilla URL Warning on previous git push: remote: WARNING: invalid Gentoo Bugzilla URL: https://bugs.gentoo.org/show_bug.cgi?id=werror Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 8afe2a5..2313c50 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -121,8 +121,8 @@ ebuild level are preferred. "-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. -See https://bugs.gentoo.org/show_bug.cgi?id=werror;>bug 260867 -for more information and real-life examples/fixes in the Gentoo tree. +See https://bugs.gentoo.org/260867;>bug 260867 for more +information and real-life examples/fixes in the Gentoo tree. Rationale
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: f72795c60b475cc36501ed03b7b3a03c38bcf851 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:50:27 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:56 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f72795c6 ebuild-writing/common-mistakes: mention "the compiler", not only GCC Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 15 --- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 6f33248..9455688 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -176,13 +176,14 @@ Always check that it's really gone in the build log. Specific -Werror=... flags -GCC can turn any specific warning into an error. A specific -Werror flag would -be "-Werror=implicit-function-declaration" for example and will only affect -warnings about implicit function declarations. It's mostly safe to leave these -untouched, cause they are pinned to this issue and should not cause random -build time breakage. Also, we can expect that upstream did this on purpose to -avoid known runtime errors and not just for testing their builds. However you -should check the specified warnings yourself or ask other developers if unsure. +The compiler (e.g. GCC) can turn any specific warning into an error. A +specific -Werror flag would be "-Werror=implicit-function-declaration" for +example and will only affect warnings about implicit function declarations. It's +mostly safe to leave these untouched, cause they are pinned to this issue and +should not cause random build time breakage. Also, we can expect that upstream +did this on purpose to avoid known runtime errors and not just for testing their +builds. However, you should check the specified warnings yourself or ask other +developers if unsure. Exceptions
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: fd90736ea1141e95c63a9634d424aa843454ca45
Author: Sam James gentoo org>
AuthorDate: Sun Mar 21 02:31:00 2021 +
Commit: Ulrich Müller gentoo org>
CommitDate: Tue Mar 30 18:14:52 2021 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fd90736e
ebuild-writing/common-mistakes: give more information on invalid ${ROOT} usage
Bug: https://bugs.gentoo.org/775191
Signed-off-by: Sam James gentoo.org>
[Add bug number to link text.]
Signed-off-by: Ulrich Müller gentoo.org>
ebuild-writing/common-mistakes/text.xml | 7 +--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index d77b143..c92813f 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -31,8 +31,11 @@ this.
The usage of ROOT is only designed to influence the way the package is
installed (ie. into ROOT) building and compiling should not depend
-on ROOT. As a consequence of this the usage of ROOT in
-src_* functions is not allowed.
+on ROOT. As a consequence of this, the usage of ROOT in
+src_* functions is not allowed. pkgcheck can now detect some
+such cases via its MisplacedVariable check.
+See https://bugs.gentoo.org/775191;>bug 775191 for more
+information.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 05a0ec105e50d6f67a02020bac969474ec6a3ef3 Author: Sam James gentoo org> AuthorDate: Mon Mar 29 23:06:16 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:57 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=05a0ec10 ebuild-writing/common-mistakes: adjust XML style for build systems list Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 35 +++-- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 05380bf..7b47c2c 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -83,21 +83,26 @@ There are several ways to fix non-verbose build logs depending on the build syst - For cmake-based build systems, it should be sufficient that - the ebuild calls cmake_src_compile which picks up the cmake.eclass - variable 'CMAKE_VERBOSE=1' by default. If you call emake directly for - whatever reason, you can do 'emake VERBOSE=1' (note that - cmake_src_compile takes arguments as well which are passed to make). - - For autotools based build systems you can pass - '--disable-silent-rules' to econf, or use EAPI 5 where that argument is - passed automatically. 'emake V=1' should also work. - - For custom Makefiles, you often have to write a patch. Try to get - upstream to include an option like 'V=1' to enable full verbosity. - - Note that when building Go manually outside of the eclass, you - will need GOFLAGS="-x". + +For cmake-based build systems, it should be sufficient that the +ebuild calls cmake_src_compile which picks up the cmake.eclass variable +CMAKE_VERBOSE=1 by default. If you call emake directly for whatever +reason, you can do emake VERBOSE=1 (note that 'cmake_src_compile' +takes arguments as well which are passed to make). + + +For autotools based build systems you can pass +'--disable-silent-rules' to econf, or use EAPI 5 where that argument is +passed automatically. emake V=1 should also work. + + +For custom Makefiles, you often have to write a patch. Try to get +upstream to include an option like 'V=1' to enable full verbosity. + + +Note that when building Go manually outside of the eclass, you +will need GOFLAGS="-x". + In case you encounter an affected package which uses a build system not
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 7e6a5e6ae276413702c4dc93245e724944c1ab52 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:45:11 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:55 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7e6a5e6a ebuild-writing/common-mistakes: linkify bug reference for non-verbose builds Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 8 +--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 0dc7b5b..481eadb 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -101,9 +101,11 @@ There are several ways to fix non-verbose build logs depending on the build syst In case you encounter an affected package which uses a build system not -controllable by Portage or eclasses you should file a bug (preferably with a patch) -and make it block the tracker bug #429308. Solutions above ebuild level are -preferred. +controllable by Portage or eclasses, you should file a bug (preferably with +a patch) and make it block the tracker +https://bugs.gentoo.org/429308;>bug 429308. Solutions above +ebuild level are preferred. +
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 196e48b1418b58a2d32efd21cec47af1b6bd8f1c Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:34:53 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:52 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=196e48b1 ebuild-writing/common-mistakes: convert 'build log not verbose' to list Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 28 ++-- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index c92813f..9ff6608 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -81,22 +81,22 @@ someone reports a bug for your package, the build log must always be verbose. There are several ways to fix non-verbose build logs depending on the build system: - -For cmake based build systems it should be sufficient that the ebuild calls -cmake-utils_src_compile which picks up the cmake-utils.eclass variable 'CMAKE_VERBOSE=1' -by default. If you call emake directly for whatever reason, you can do 'emake VERBOSE=1' -(note that cmake-utils_src_compile takes arguments as well which are passed to make). - - -For autotools based build systems you can pass '--disable-silent-rules' to econf, -or use EAPI 5 where that argument is passed automatically. 'emake V=1' should also work. - + + For cmake based build systems it should be sufficient that + the ebuild calls cmake-utils_src_compile which picks up the cmake-utils.eclass + variable 'CMAKE_VERBOSE=1' by default. If you call emake directly for + whatever reason, you can do 'emake VERBOSE=1' (note that + cmake-utils_src_compile takes arguments as well which are passed to make). + + For autotools based build systems you can pass + '--disable-silent-rules' to econf, or use EAPI 5 where that argument is + passed automatically. 'emake V=1' should also work. + + For custom Makefiles you often have to write a patch. Try to get + upstream to include an option like 'V=1' to enable full verbosity. + - -For custom Makefiles you often have to write a patch. Try to get upstream to include an -option like 'V=1' to enable full verbosity. - In case you encounter an affected package which uses a build system not controllable by Portage or eclasses you should file a bug (preferably with a patch) and make it block the tracker bug #429308. Solutions above ebuild level are
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 63d617e00118af7bf23814fa324dce4bc9ed2e95 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:37:56 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:53 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=63d617e0 ebuild-writing/common-mistakes: mention manual Go compiles (verbose builds) Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index fba6bac..2d8695f 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -95,6 +95,9 @@ There are several ways to fix non-verbose build logs depending on the build syst For custom Makefiles you often have to write a patch. Try to get upstream to include an option like 'V=1' to enable full verbosity. + + Note that when building Go manually outside of the eclass, you + will need GOFLAGS="-x". In case you encounter an affected package which uses a build system not
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 225b6e2260e0e34523cb793de23cee8d78023764 Author: Sam James gentoo org> AuthorDate: Tue Mar 30 09:52:44 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:57 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=225b6e22 ebuild-writing/common-mistakes: modernise autotools/econf advice on verbose log Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 7 --- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 7b47c2c..8afe2a5 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -91,9 +91,10 @@ There are several ways to fix non-verbose build logs depending on the build syst takes arguments as well which are passed to make). -For autotools based build systems you can pass -'--disable-silent-rules' to econf, or use EAPI 5 where that argument is -passed automatically. emake V=1 should also work. +For autotools based build systems, econf automatically +passes '--disable-silent-rules' to ./configure. If necessary, +emake V=1 should also work. Note that V=1 is not a universal +parameter so may not always work. For custom Makefiles, you often have to write a patch. Try to get
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: d922c8c08a951c2a5f4c057cf6e1174d0a12f5a9 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:36:43 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:56 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d922c8c0 ebuild-writing/common-mistakes: slight grammar fixes/phrasing changes Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 16 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 9455688..05380bf 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -93,7 +93,7 @@ There are several ways to fix non-verbose build logs depending on the build syst '--disable-silent-rules' to econf, or use EAPI 5 where that argument is passed automatically. 'emake V=1' should also work. - For custom Makefiles you often have to write a patch. Try to get + For custom Makefiles, you often have to write a patch. Try to get upstream to include an option like 'V=1' to enable full verbosity. Note that when building Go manually outside of the eclass, you @@ -127,8 +127,8 @@ without purpose, e.g.: -new warnings on version bumps of GCC/glibc which the developer was not aware -of at the point of coding +new warnings on version bumps of GCC/glibc of which the developer was not +aware at the point of coding some autoconf checks will fail badly @@ -147,9 +147,9 @@ without purpose, e.g.: -Turning off "-Werror" we will still see the warnings, but there is no reason -that they cause compile failure. Also note that Portage already emits QA -notices about gcc warnings that can cause runtime breakage. +By turning off "-Werror", we will still see the warnings, but there is no reason +that they cause compile failure. Note that Portage already emits QA +notices about GCC warnings that can cause runtime breakage. How to fix @@ -179,8 +179,8 @@ Always check that it's really gone in the build log. The compiler (e.g. GCC) can turn any specific warning into an error. A specific -Werror flag would be "-Werror=implicit-function-declaration" for example and will only affect warnings about implicit function declarations. It's -mostly safe to leave these untouched, cause they are pinned to this issue and -should not cause random build time breakage. Also, we can expect that upstream +mostly safe to leave these untouched, because they are pinned to this issue and +should not cause random build-time breakage. Also, we can expect that upstream did this on purpose to avoid known runtime errors and not just for testing their builds. However, you should check the specified warnings yourself or ask other developers if unsure.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 7b3a50bdcef9968c1c894ab8ce55f0436d576327 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:48:36 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:55 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7b3a50bd ebuild-writing/common-mistakes: s/GLIBC/glibc/ Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 481eadb..6f33248 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -127,8 +127,8 @@ without purpose, e.g.: -new warnings on version bumps of GCC/GLIBC the developer was not aware of -at the point of coding +new warnings on version bumps of GCC/glibc which the developer was not aware +of at the point of coding some autoconf checks will fail badly
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 0ba65e82f048d69ee2d9e72131a245c63acdc133 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:39:51 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:54 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0ba65e82 ebuild-writing/common-mistakes: add -Werror tracker link Bug: https://bugs.gentoo.org/show_bug.cgi?id=werror Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 2d8695f..3bbda05 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -113,6 +113,8 @@ preferred. "-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +See https://bugs.gentoo.org/show_bug.cgi?id=werror;>bug 260867 +for more information and real-life examples/fixes in the Gentoo tree. Rationale
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 51452b8d8f452053086e03c1bf35061cc6c1caa9 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:43:05 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:54 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=51452b8d ebuild-writing/common-mistakes: build-log -> build log Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 3bbda05..0dc7b5b 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -120,7 +120,7 @@ for more information and real-life examples/fixes in the Gentoo tree. Rationale This flag is not recommended for releases and should always be disabled when -encountered in build-logs, because there are numerous cases where this breaks +encountered in build logs, because there are numerous cases where this breaks without purpose, e.g.:
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: eb65d74e2ad8428672c7e4d944beaa483a1df6d1 Author: Sam James gentoo org> AuthorDate: Sun Mar 21 02:36:03 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 18:14:53 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=eb65d74e ebuild-writing/common-mistakes: s/cmake-utils/cmake/ Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 9ff6608..fba6bac 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -83,11 +83,11 @@ There are several ways to fix non-verbose build logs depending on the build syst - For cmake based build systems it should be sufficient that - the ebuild calls cmake-utils_src_compile which picks up the cmake-utils.eclass + For cmake-based build systems, it should be sufficient that + the ebuild calls cmake_src_compile which picks up the cmake.eclass variable 'CMAKE_VERBOSE=1' by default. If you call emake directly for whatever reason, you can do 'emake VERBOSE=1' (note that - cmake-utils_src_compile takes arguments as well which are passed to make). + cmake_src_compile takes arguments as well which are passed to make). For autotools based build systems you can pass '--disable-silent-rules' to econf, or use EAPI 5 where that argument is
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 2d6f348dda36f01bb240e06b38c5a894e6dce7aa Author: Sam James gentoo org> AuthorDate: Sun Mar 21 04:36:02 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 16:00:53 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2d6f348d ebuild-writing/common-mistakes: mention pkgcheck Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 91eca66..b178209 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -409,8 +409,9 @@ the guidelines to use TABS rather than spaces. So please use tabs! -I'm often guilty of this. Remember to run repoman over your ebuilds so it can -tell you if there is trailing whitespace at the end of lines or on empty lines. +I'm often guilty of this. Remember to run repoman or pkgcheck +over your ebuilds so it can tell you if there is trailing whitespace at the end +of lines or on empty lines.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 74c5a670a8e25b07893ee7533e69259cbe806e6d Author: Sam James gentoo org> AuthorDate: Tue Mar 30 09:56:41 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 16:00:55 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=74c5a670 ebuild-writing/common-mistakes: fix 1st->3rd person per style Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index b178209..d77b143 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -409,9 +409,8 @@ the guidelines to use TABS rather than spaces. So please use tabs! -I'm often guilty of this. Remember to run repoman or pkgcheck -over your ebuilds so it can tell you if there is trailing whitespace at the end -of lines or on empty lines. +Remember to run repoman or pkgcheck over your ebuilds so it can +tell you if there is trailing whitespace at the end of lines or on empty lines.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: b487288add4b6a7ecc8a9674fe8e500ab7d8306a Author: Sam James gentoo org> AuthorDate: Sat Mar 20 15:21:57 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Mon Mar 29 20:41:39 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b487288a ebuild-writing/common-mistakes: extend 'DEPEND is incomplete' Emphasise that the tips/information applies to all dependency classes. Signed-off-by: Sam James gentoo.org> Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 7 ++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index dcdc969..91eca66 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -284,6 +284,11 @@ part. DEPEND is incomplete + +The tips in this section apply to all dependency classes, not just +DEPEND. + + This is another very common error. The ebuild submitter submits an ebuild that "just works" without checking if the dependencies are correct. Here are @@ -317,7 +322,7 @@ some tips on how to find the correct dependencies. programs, etc. Usually the build process requires some dependencies such as intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those -are clearly stated. +are clearly stated, usually in BDEPEND.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 557f3dbd124b34928e4e11d8e51d8822e281f240 Author: Ulrich Müller gentoo org> AuthorDate: Sun Mar 21 06:02:20 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Sun Mar 21 06:06:13 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=557f3dbd ebuild-writing/common-mistakes: Reformat paragraphs in the -Werror section No change of wording. Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 44 - 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 0d3d441..dcdc969 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -19,7 +19,8 @@ writing ebuilds. The static use-flag should only be used to make a binary use static linking instead of dynamic linking. It should not be used to make a library -install static libraries. Instead, the static-libs use-flag is used for this. +install static libraries. Instead, the static-libs use-flag is used for +this. @@ -104,32 +105,41 @@ preferred. -Werror compiler flag not removed -"-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +"-Werror" is a flag which turns all warnings into errors and thus will abort +compiling if any warning is encountered. Rationale -This flag is not recommended for releases and should always be disabled when encountered in build-logs, because there are numerous cases where this breaks without purpose, e.g.: +This flag is not recommended for releases and should always be disabled when +encountered in build-logs, because there are numerous cases where this breaks +without purpose, e.g.: -new warnings on version bumps of GCC/GLIBC the developer was not aware of at the point of coding +new warnings on version bumps of GCC/GLIBC the developer was not aware of +at the point of coding some autoconf checks will fail badly -libraries adding deprecated API warnings although that API is still working/supported +libraries adding deprecated API warnings although that API is still +working/supported -on less known architectures we may get different/more warnings than on common ones +on less known architectures we may get different/more warnings than on +common ones -random breakage depending on what distro/architecture/library version/kernel/userland the developer was testing "-Werror" on +random breakage depending on what distro/architecture/library +version/kernel/userland the developer was testing "-Werror" on -Turning off "-Werror" we will still see the warnings, but there is no reason that they cause compile failure. Also note that Portage already emits QA notices about gcc warnings that can cause runtime breakage. +Turning off "-Werror" we will still see the warnings, but there is no reason +that they cause compile failure. Also note that Portage already emits QA +notices about gcc warnings that can cause runtime breakage. How to fix @@ -138,10 +148,16 @@ To fix the affected build system you should try the following methods: -remove the compiler flag from the build system, e.g. Makefile.am or configure.ac or even provide a switch (for autotools based build systems that could be "--disable-werror", which is good for sending a patch upstream) +remove the compiler flag from the build system, e.g. Makefile.am or +configure.ac or even provide a switch (for autotools based build +systems that could be "--disable-werror", which is good for sending a patch +upstream) -use append-flags -Wno-error (needs flag-o-matic.eclass); for this to work the environment flags have to be respected and placed after build system flags; this method is not preferred as it will disable all "-Werror=specific-warning" flags as well, see next section +use append-flags -Wno-error (needs flag-o-matic.eclass); for this +to work the environment flags have to be respected and placed after build +system flags; this method is not preferred as it will disable all +"-Werror=specific-warning" flags as well, see next section @@ -150,7 +166,13 @@ Always check that it's really gone in the build log. Specific -Werror=... flags -GCC can turn any specific warning into an error. A specific -Werror flag would be "-Werror=implicit-function-declaration" for example and will only affect warnings about implicit function declarations. It's mostly safe to leave these untouched, cause they are pinned to this issue and should not cause random build time breakage. Also, we can expect that upstream did this on purpose to avoid known runtime errors and not just for testing their builds. However you should check the specified warnings yourself or ask other developers if
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 36b6a8d9cfd1f44a76b4b117f2dfee45a552c8d5 Author: Ulrich Müller gentoo org> AuthorDate: Mon Feb 1 09:25:54 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Mon Feb 1 09:35:09 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=36b6a8d9 ebuild-writing/common-mistakes: Drop note on Header/Id line This is no longer a common mistake. Exactly the same note is still present in ebuild-writing/file-format. Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 7 --- 1 file changed, 7 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 67be337..85c0e3f 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -184,13 +184,6 @@ The first two lines must look like this: # Distributed under the terms of the GNU General Public License v2 - -The header previously included a third line with a CVS Id -or Header keyword. That line was abolished after conversion -to Git by https://bugs.gentoo.org/611234;>decision of the Gentoo -Council on 28 February 2017 and must not be added any more. - -
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/, ebuild-maintenance/maintenance-tasks/, ...
commit: cb01d9ebc777517fce784dde4f8cdbf78d91b5bf Author: Ulrich Müller gentoo org> AuthorDate: Tue Jan 21 10:34:07 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Jan 23 07:48:05 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=cb01d9eb ebuild-maintenance/new-ebuild: New chapter. Split off from ebuild-maintenance/maintenance-tasks. Signed-off-by: Ulrich Müller gentoo.org> ebuild-maintenance/maintenance-tasks/text.xml | 123 - ebuild-maintenance/new-ebuild/text.xml| 126 ++ ebuild-maintenance/text.xml | 1 + ebuild-writing/common-mistakes/text.xml | 3 +- 4 files changed, 128 insertions(+), 125 deletions(-) diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml index b5b7359..972b7b3 100644 --- a/ebuild-maintenance/maintenance-tasks/text.xml +++ b/ebuild-maintenance/maintenance-tasks/text.xml @@ -11,129 +11,6 @@ developers may not be familiar with. - -Adding a new ebuild - - -What (not) to put in the Gentoo repository - - - -Before writing a new ebuild, check -https://bugs.gentoo.org/;>bugs.gentoo.org -to see if an ebuild has already been written for the package, but has not yet -been added to the Gentoo repository. Go to https://bugs.gentoo.org/;>bugs.gentoo.org, choose query and select -Advanced Search; as product select Gentoo Linux, as component select -ebuilds. In the search field put the name of the ebuild and as status -select all possible fields, then submit the query. For you lazy people, click -https://bugs.gentoo.org/query.cgi?format=advancedproduct=Gentoo%20Linuxcomponent=New%20Ebuildsbug_Status=UNCONFIRMEDbug_status=CONFIRMEDbug_status=IN_PROGRESSbug_status=RESOLVEDbug_status=VERIFIED;>here. - - - -In general, the Gentoo repository should only be used for storing -.ebuild files, as well as any relatively small companion -files, such as patches or sample configuration files. These types of -files should be placed in the mycat/mypkg/files directory -to keep the main mycat/mypkg directory uncluttered. -Exceptions to this rule are for larger patch files (we recommend this -for patches above 20KB) which should be distributed as tarballs via the -Gentoo -mirror system so that people do not waste excessive amounts of -bandwidth and hard drive space. Also, you should not add binary -(non-ASCII) files to the git tree. Also, speaking of merging changes, -any patches you add to Portage should generally not be -compressed. This will allow git to merge changes and correctly inform -developers of conflicts. - - - -Remember, the packages that you commit must be ready out of the -box for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -https://www.debian.org/distrib/packages;>Debian or -https://src.fedoraproject.org/projects/rpms/*;>Fedora for some -examples. - - - -When committing to git, all developers should use repoman commit -instead of git commit to submit their ebuilds. Before committing, -please run repoman full to make sure you didn't forget something. - - - - - - -Initial Architecture Keywords - - -When adding a new ebuild, you should only include KEYWORDS for -architectures on which you have actually tested the ebuild, confirming -that it works as it should and that USE flags are properly -honoured in the resulting package which would be installed. If -possible, you should give the actual library or application thorough -testing as well, since you would be responsible for any breakages for -your architecture(s). Minimal testing such as checking that the -application starts up without any errors should always be performed. - - - -If you are adding a user-submitted ebuild, do not assume that the -submitter has done testing on various architectures: often, KEYWORDS -are cloned across packages or generated from documentation in the -source packages, which does not signify that the package does indeed -work on those architectures. - - - - - - -The files Directory - - - -As noted earlier, under each package subdirectory is -a files/ directory. Any patches, configuration files, or -other ancillary files your package might require should be added to -this directory; any files bigger than 20KB-or-so should go to the -mirrors to lower the amount of (unneeded) files our users have to -download. You may want to consider naming patches you create yourself -just to get your package to build with a version-specific name, such -as mypkg-1.0-gentoo.diff, or more -simply, 1.0-gentoo.diff. Also note that the -gentoo extension informs people that this patch was created -by us, the Gentoo Linux developers, rather than
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/, function-reference/install-functions/, ...
commit: 18bf92b7ef4b09b58add33d4ce40a965c05b2f49
Author: Ulrich Müller gentoo org>
AuthorDate: Wed Dec 4 17:08:48 2019 +
Commit: Ulrich Müller gentoo org>
CommitDate: Sun Dec 8 11:32:04 2019 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=18bf92b7
Element is not supported.
Replace by paragraph break, or drop.
Signed-off-by: Ulrich Müller gentoo.org>
appendices/contributing/devbook-guide/text.xml | 4 +++-
ebuild-writing/common-mistakes/text.xml | 20 ++--
ebuild-writing/eapi/text.xml | 4 ++--
ebuild-writing/functions/src_prepare/epatch/text.xml | 8 ++--
function-reference/install-functions/text.xml| 2 +-
5 files changed, 22 insertions(+), 16 deletions(-)
diff --git a/appendices/contributing/devbook-guide/text.xml
b/appendices/contributing/devbook-guide/text.xml
index d1225d6..5aa5525 100644
--- a/appendices/contributing/devbook-guide/text.xml
+++ b/appendices/contributing/devbook-guide/text.xml
@@ -71,7 +71,9 @@ document and specifies its DTD. The !--
Header -- line
will be automatically modified by the CVS server and helps to track revisions.
Next, there's a guide tag -- the entire guide document is
enclosed within a guide /guide pair.
-
+
+
+
The lang attribute should be used to specify the language code of your
document. It is used to format the date and insert strings like "Note",
"Content", etc. in the specified language. The default is English.
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index 026e1d9..dbf6eee 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -242,22 +242,22 @@ part.
-Always include the CATEGORY.
+Always include the CATEGORY.
For example, use =x11-libs/gtk+-2 and not =gtk+-2.
-Do not put an asterisk (*) for = dependencies.
+Do not put an asterisk (*) for = dependencies.
For example, it should be =x11-libs/gtk+-2 rather than
=x11-libs/gtk+-2*.
GTK specific. Always use =x11-libs/gtk+-1.2* for GTK+1 apps.
-Never depend on a meta package.
+Never depend on a meta package.
So don't depend on gnome-base/gnome, always depend on the specific
libraries like libgnome.
-One dependency per line.
+One dependency per line.
Don't put multiple dependency on the same line. It makes it ugly to read
and hard to follow.
@@ -277,29 +277,29 @@ some tips on how to find the correct dependencies.
-Look in configure.in or configure.ac
+Look in configure.in or configure.ac.
Look for checks for packages in here. Things to look out for are pkg-config
checks or AM_* functions that check for a specific version.
-Look at included .spec files
+Look at included .spec files.
A good indication of dependencies is to look at the included .spec files
for relevant deps. However, do not trust them to be the definitive complete
-list of dependencies
+list of dependencies.
-Look at the application/library website
+Look at the application/library website.
Check the application website for possible dependencies that they suggest
are needed.
-Read the README and INSTALL for the package
+Read the README and INSTALL for the package.
They usually also contain useful information about building and installing
packages.
Remember non-binary dependencies such as pkg-config, doc generation
-programs, etc.
+programs, etc.
Usually the build process requires some dependencies such as intltool,
libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those
are clearly stated.
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
index 84db3cb..3f9590d 100644
--- a/ebuild-writing/eapi/text.xml
+++ b/ebuild-writing/eapi/text.xml
@@ -1110,8 +1110,8 @@ src_install() {
New function dostrip
The dostrip helper has been added with
EAPI=7.
- This function controls whether or not to strip a
binary.
- dostrip -x [file] will exclude a binary from
being stripped.
+ This function controls whether or not to strip a binary.
+ dostrip -x [file] will exclude a binary from
being stripped.
Conversely, when combined with RESTRICT=strip,
dostrip [file] selects a binary
file to be stripped.
diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml
b/ebuild-writing/functions/src_prepare/epatch/text.xml
index 0bd0938..59987fc 100644
--- a/ebuild-writing/functions/src_prepare/epatch/text.xml
+++ b/ebuild-writing/functions/src_prepare/epatch/text.xml
@@ -9,11 +9,15 @@ The canonical way of applying patches in ebuilds is to
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/, ebuild-maintenance/maintenance-tasks/
commit: 07452705c2b149c0510d64c72dc9e474bd0f8363 Author: Ulrich Müller gentoo org> AuthorDate: Mon Jun 17 19:51:59 2019 + Commit: Ulrich Müller gentoo org> CommitDate: Mon Jun 17 19:51:59 2019 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=07452705 Avoid absolute (and outdated) /usr/portage path. Signed-off-by: Ulrich Müller gentoo.org> ebuild-maintenance/maintenance-tasks/text.xml | 9 - ebuild-writing/common-mistakes/text.xml | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml index a434fb5..06634b8 100644 --- a/ebuild-maintenance/maintenance-tasks/text.xml +++ b/ebuild-maintenance/maintenance-tasks/text.xml @@ -34,11 +34,10 @@ select all possible fields, then submit the query. For you lazy people, click In general, the Gentoo repository should only be used for storing .ebuild files, as well as any relatively small companion files, such as patches or sample configuration files. These types of -files should be placed in the -/usr/portage/mycat/mypkg/files directory to keep the main -mycat/mypkg directory uncluttered. Exceptions to this -rule are for larger patch files (we recommend this for patches above -20KB) which should be distributed as tarballs via the +files should be placed in the mycat/mypkg/files directory +to keep the main mycat/mypkg directory uncluttered. +Exceptions to this rule are for larger patch files (we recommend this +for patches above 20KB) which should be distributed as tarballs via the Gentoo mirror system so that people do not waste excessive amounts of bandwidth and hard drive space. Also, you should not add binary diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 2842531..869676e 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -300,14 +300,14 @@ Another common mistake users make when submitting ebuilds is supplying an invalid license. For example, GPL is not a valid license. You need to specify GPL-1 or GPL-2. Same with LGPL. Make sure the license you use in the LICENSE field is something that exists in -/usr/portage/licenses. As a tip, check the COPYING +the licenses directory. As a tip, check the COPYING in a source tarball for the license. If a package does not specify it uses GPL-1 or GPL-2, it is very likely it uses GPL-2. If the license for the package you submit is unique and not in -/usr/portage/licenses/, then you must submit the new license in a +licenses/, then you must submit the new license in a separate file.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 4ab265a32b85e372328c11f16911e845197c18ee Author: Göktürk Yüksek gentoo org> AuthorDate: Wed Jan 25 05:29:50 2017 + Commit: Göktürk Yüksek gentoo org> CommitDate: Wed Jan 25 05:29:50 2017 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4ab265a3 ebuild-writing/common-mistakes: update the ebuild header copyright ebuild-writing/common-mistakes/text.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index bc98089..e3ee42d 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -159,7 +159,7 @@ The first three lines must look like this: -# Copyright 1999-2016 Gentoo Foundation +# Copyright 1999-2017 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 # Id
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: b76359b3dad438a347e97b1a57c4be3011efceae Author: Jonas Stein jonasstein de> AuthorDate: Mon Jan 23 21:47:09 2017 + Commit: Göktürk Yüksek gentoo org> CommitDate: Wed Jan 25 05:29:42 2017 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b76359b3 ebuild-writing/common-mistakes: improve the text with links * add link to skel.ebuild header * add link to No_homepage Major changes to the text have been made by the committer. ebuild-writing/common-mistakes/text.xml | 11 +++ 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index e9bcf5c..bc98089 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -148,9 +148,10 @@ Removing "-Werror" from configure.ac can cause breakage in very rare cases where -When you submit your ebuilds, the header should be exactly the same as -the one in /usr/portage/skel.ebuild. Most importantly, do not -modify it in any way and make sure that the Id line is intact. +When you submit your ebuilds, the header must be exactly the same as +the one in +https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.ebuild;> +skel.ebuild. @@ -345,7 +346,9 @@ SLOT="0" Please check if the HOMEPAGE variable is right and leads users to the right page if they want to find out more about the package. And make sure the DESCRIPTION is not overly long. Good descriptions will describe the main -function of the package in a sentence. +function of the package in a sentence. Set HOMEPAGE to +No_homepage wiki page, +if there is none.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 1ad3d23d6d061b3bfe5849804a1efbe0aaa1e5cd Author: Jonas Stein jonasstein de> AuthorDate: Sat Jan 21 12:03:27 2017 + Commit: Göktürk Yüksek gentoo org> CommitDate: Sat Jan 21 19:21:03 2017 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1ad3d23d ebuild-writing/common-mistakes: shortened to facts and made it more objective The user who reads this does not need 3x please. Well sorted and readable attachments are good for everyone. Gentoo-devs, bug reporter, proxy-maintainer, packagers from other distributions looking for solutions... ebuild-writing/common-mistakes/text.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 1a2ef85..e9bcf5c 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -440,8 +440,8 @@ link="::ebuild-maintenance#adding-a-new-ebuild">Adding new Ebuild tutorial -Please please please do not attach ebuilds as tarballs. Attach patches -separately as well so we can easily examine them. +Please do not attach ebuilds or patches as tarballs. It avoids extra +operations when reviewing.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 3607b7a4e355a2421321f2dfccc24f40f1d0d48e
Author: Ulrich Müller gentoo org>
AuthorDate: Fri Oct 28 17:13:30 2016 +
Commit: Ulrich Müller gentoo org>
CommitDate: Fri Oct 28 17:13:30 2016 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3607b7a4
Whitespace fixes.
ebuild-writing/common-mistakes/text.xml | 16
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index 8293bc8..1a2ef85 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -237,7 +237,7 @@ part.
One dependency per line.
-Don't put multiple dependency on the same line. It makes it ugly to read
+Don't put multiple dependency on the same line. It makes it ugly to read
and hard to follow.
@@ -293,17 +293,17 @@ some tips on how to find the correct dependencies.
Another common mistake users make when submitting ebuilds is supplying an
-invalid license. For example, GPL is not a valid license. You need to
-specify GPL-1 or GPL-2. Same with LGPL. Make sure the
-license you use in the LICENSE field is something that exists in
-/usr/portage/licenses. As a tip, check the COPYING
+invalid license. For example, GPL is not a valid license. You need to
+specify GPL-1 or GPL-2. Same with LGPL. Make sure the
+license you use in the LICENSE field is something that exists in
+/usr/portage/licenses. As a tip, check the COPYING
in a source tarball for the license. If a package does not specify it
uses GPL-1 or GPL-2, it is very likely it uses GPL-2.
If the license for the package you submit is unique and not in
-/usr/portage/licenses/, then you must submit the new license in a
+/usr/portage/licenses/, then you must submit the new license in a
separate file.
@@ -377,8 +377,8 @@ tell you if there is trailing whitespace at the end of
lines or on empty lines.
-If S=${WORKDIR}/${P}, then you should not add it to your ebuild. This
is
-implied already, you should only add it if it is something other than
+If S=${WORKDIR}/${P}, then you should not add it to your ebuild. This is
+implied already, you should only add it if it is something other than
${WORKDIR}/${P}.
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/, ebuild-writing/functions/src_prepare/epatch/, ...
commit: 3d3e03c8f83de3b9fde8589c995d0f70c641556b
Author: Ulrich Müller gentoo org>
AuthorDate: Sat Apr 2 08:38:08 2016 +
Commit: Ulrich Müller gentoo org>
CommitDate: Sat Apr 2 08:38:08 2016 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3d3e03c8
Update years in example ebuild and eclass headers.
Also escape any VCS keywords that could potentially be expanded.
ebuild-writing/common-mistakes/text.xml | 2 +-
ebuild-writing/eapi/text.xml | 12 ++--
ebuild-writing/file-format/text.xml | 9 +
ebuild-writing/functions/src_prepare/epatch/text.xml | 4 ++--
.../functions/src_unpack/rpm-sources/text.xml| 4 ++--
ebuild-writing/misc-files/patches/text.xml | 4 ++--
ebuild-writing/using-eclasses/text.xml | 4 ++--
eclass-writing/text.xml | 12 ++--
quickstart/text.xml | 20 ++--
9 files changed, 36 insertions(+), 35 deletions(-)
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index 1716e5d..8293bc8 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -158,7 +158,7 @@ The first three lines must look like this:
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# Id
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
index 239f6f3..8045b28 100644
--- a/ebuild-writing/eapi/text.xml
+++ b/ebuild-writing/eapi/text.xml
@@ -42,9 +42,9 @@ Most developers prefer to set the EAPI version without
quotes. However, the PMS
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
-# $Id$
+# Id
EAPI=5
inherit eutils
@@ -120,9 +120,9 @@ src_compile() {
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
-# $Id$
+# Id
EAPI=1
@@ -515,9 +515,9 @@ DEPEND="
Example:
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
-# $Id$
+# Id
EAPI=4
inherit linux-info
diff --git a/ebuild-writing/file-format/text.xml
b/ebuild-writing/file-format/text.xml
index 74a623e..e74fd15 100644
--- a/ebuild-writing/file-format/text.xml
+++ b/ebuild-writing/file-format/text.xml
@@ -138,14 +138,15 @@ is to use as the version (or as the last
version component).
All ebuilds committed to the tree should have a three line header immediately
at
the start indicating copyright. This must be an exact copy of the contents of
-$(portageq get_repo_path / gentoo)/header.txt. Ensure that the
$Id$ line is not
-modified manually will be expanded on staging box. See .
+$(portageq get_repo_path / gentoo)/header.txt. Ensure that the
+Id line is not modified manually will be expanded
+on staging box. See .
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
-# $Id$
+# Id
diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml
b/ebuild-writing/functions/src_prepare/epatch/text.xml
index 2401bdc..a8d5f04 100644
--- a/ebuild-writing/functions/src_prepare/epatch/text.xml
+++ b/ebuild-writing/functions/src_prepare/epatch/text.xml
@@ -69,8 +69,8 @@ Remember to add the patch to SRC_URI.
Git Keyword Expansion Lines and Patches
-If your patch includes any changes to Git $Id$
-(or $Date$) lines, it cannot be
+If your patch includes any changes to Git Id
+(or Date) lines, it cannot be
distributed under files/, since Git will clobber the patch when
keywords are expanded on the staging box. In these situations, either remove
this hunk of the patch
manually, or mirror the file. See .
diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
index 0ff0def..0046e20 100644
--- a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
+++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
@@ -52,9 +52,9 @@ patches. The filename should be
suse-fetchmail-6.2.5.54.1.ebuild.
-# Copyright 1999-2015 Gentoo Foundation
+# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
-# $Id$
+# Id
inherit eutils versionator rpm
diff --git a/ebuild-writing/misc-files/patches/text.xml
b/ebuild-writing/misc-files/patches/text.xml
index cd85244..4bb8375 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -107,8 +107,8 @@
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: 8801a95310ec5e7d553a0a8285612a8a7cbee144 Author: Gokturk Yuksek binghamton edu> AuthorDate: Thu Feb 4 00:57:32 2016 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Feb 5 12:58:19 2016 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8801a953 general-concepts/tree: replace the mention of ChangeLog #558642 Package updates do not require changing of the ChangeLog file. Package updates by users that do not mention what has changed is still considered a common mistake however. Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=558642 Signed-off-by: Gokturk Yuksek binghamton.edu> ebuild-writing/common-mistakes/text.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 1718d55..1716e5d 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -468,7 +468,7 @@ of the application, if any exists. -Package updates without changing the ChangeLog +Package updates without explaining what has changed
[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
commit: a4ada1b4f1e37f189a38d4d5bc06a2c3503e77c9
Author: W. Trevor King wking AT tremily DOT us
AuthorDate: Sun Sep 14 18:31:38 2014 +
Commit: Markos Chandras hwoarang AT gentoo DOT org
CommitDate: Sun Sep 14 21:22:55 2014 +
URL:
http://sources.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=a4ada1b4
ebuild-writing/common-mistakes: Mention the 'doc' USE flag
When reminding folks to install the docs, also remind them that they
should be using the 'doc' USE flag for serious docs. This USE flag is
the standard way to enable/disable doc installation, and we don't want
ebuilds blindly pulling in doc depenencies regardless of how it's set.
Use some of Ulrich Müller's wording [1].
[1]: https://bugs.gentoo.org/show_bug.cgi?id=522800#c3
Thanks-to: Ulrich Müller ulm AT gentoo.org
---
ebuild-writing/common-mistakes/text.xml | 12 ++--
1 file changed, 10 insertions(+), 2 deletions(-)
diff --git a/ebuild-writing/common-mistakes/text.xml
b/ebuild-writing/common-mistakes/text.xml
index db851a2..ff906fd 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -391,11 +391,19 @@ implied already, you should only add it if it is
something other than
body
p
-If your package has documentation, make sure you install it using cdodoc/c
-or in path/usr/share/doc/${PF}/path. Remember to check for errors when
+If your package has documentation, make sure you install it using cdodoc/c
+or in path/usr/share/doc/${PF}/path. Remember to check for errors when
running cdodoc/c/cdoins/c.
/p
+p
+If the package documentation is large or requires additional
+dependencies to build, you should make it optional with the cdoc/c
+USE flag. If the documentation is small and does not require
+additional dependencies (e.g. cREADME/c files), install it
+unconditionally.
+/p
+
/body
/subsection
