[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Petteri Räty]

commit:     8576434dcc4712a5001ae498a7ec1dcb737b6333
Author:     Petteri Räty <betelgeuse <AT> gentoo <DOT> org>
AuthorDate: Tue Dec 13 20:11:28 2011 +0000
Commit:     Petteri Räty <betelgeuse <AT> gentoo <DOT> org>
CommitDate: Tue Dec 13 20:11:28 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=8576434d

Add note about changing eclass API

http://www.gentoo.org/proj/en/council/meeting-logs/20111108-summary.txt

---
 eclass-writing/text.xml |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index caefd7c..1914448 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -62,6 +62,13 @@ lot of trouble.
 </p>
 
 <p>
+When removing a function or changing the API of an eclass, make
+sure that it doesn't break any ebuilds in the tree, and post a
+notice to gentoo-dev at least 30 days in advance, preferably with
+a patch included.
+</p>
+
+<p>
 If there is an existing maintainer for an eclass (this is usually the case), you
 <b>must</b> talk to the maintainer before committing any changes.
 </p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     6b30f180594d6b6507aefc32505571bb420c579a
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jun  2 14:47:19 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:24 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6b30f180

eclass-writing: add documentation to the incorrect usage example.

Now that we have guidelines for documenting eclasses, the "Handling
incorrect usage of an eclass" section is under-documented. This commit
adds the minimum required documentation (eclass header) to that
example.

Gentoo-Bug: 373145

 eclass-writing/text.xml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 518cf2a..def2b89 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -382,7 +382,10 @@ for an eclass to invoke die from the global scope.  For example:
 # Distributed under the terms of the GNU General Public License v2
 # &#36;Id&#36;
 
-# Purpose: Demonstration of die upon invalid EAPI usage.
+# @ECLASS: eapi-die.eclass
+# @MAINTAINER:
+# Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
+# @BLURB: Calls die when used with an invalid EAPI.
 
 case ${EAPI:-0} in
   0) die "this eclass doesn't support EAPI 0" ;;

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     9b2cbaa0aa82b432293cf32f904197f4d7759e7e
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jun  2 14:42:34 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:18 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9b2cbaa0

eclass-writing: add documentation to the first existing example.

Now that we have guidelines for documenting eclasses, the "Simple
Common Functions Eclass Example" section is under-documented. This
commit adds the minimum required documentation (eclass and function
headers) to that example.

Gentoo-Bug: 373145

 eclass-writing/text.xml | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 488230d..518cf2a 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -251,18 +251,19 @@ a single function, <c>domacosapp</c>.
 # Distributed under the terms of the GNU General Public License v2
 # &#36;Id&#36;
 
-#
-# Original Author: Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
-# Purpose: install macos .app files to the relevant location.
-#
-# Bugs to osx@gentoo.org
-#
-
-# domacosapp: install a macos .app file. Usage is 'domacosapp file' or
-# 'domacosapp file newfile'.
+# @ECLASS: macosapp.eclass
+# @MAINTAINER:
+# Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
+# @BLURB: install macos .app files to the relevant location.
 
+# @FUNCTION: domacosapp
+# @USAGE: &lt;app-file&gt; [new-file]
+# @DESCRIPTION:
+# Install the given .app file into the appropriate location. If
+# [new-file] is given, it will be used as the new (installed) name of
+# the file. Otherwise &lt;app-file&gt; is installed as-is.
 domacosapp() {
-    [[ -z "${1}" ]] &amp;&amp; die "usage: domacosapp &lt;file&gt; &lt;new file&gt;"
+    [[ -z "${1}" ]] &amp;&amp; die "usage: domacosapp &lt;file&gt; [new file]"
     if use ppc-macos ; then
         insinto /Applications
         newins "$1" "${2:-${1}}" || die "Failed to install ${1}"

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     96238236a114e621cad58f6aa00580ec7f8345e0
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Sun Oct 30 00:33:15 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:45 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=96238236

eclass-writing: improve the eclass documentation sections #373145

Replace the eclass documentation text blobs from eclass-manpages with
tables. Add a section for eclass function variables.

Gentoo-Bug: https://bugs.gentoo.org/373145

 eclass-writing/text.xml | 471 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 418 insertions(+), 53 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 9329d88..1fe2ec1 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -125,24 +125,21 @@ adhere to the following process:</p>
 <body>
 
 <p>
-Eclasses are documented as any other bash project is, with code
-comments. We do however have a standard format for eclass, variable,
-and function headers. The <c>app-portage/eclass-manpages</c> package
-processes these headers to create documentation for the eclass. The
-result can be seen in our <uri link="::eclass-reference/">eclass
-reference</uri>, or by installing <c>app-portage/eclass-manpages</c>.
+Eclasses are documented with comment blocks that follow a special
+markup syntax. The comment blocks are separated by blank lines and
+each block documents an individual element of an eclass.
 </p>
+
 <p>
-The format for eclass, variable, and function headers are described
-below. Before committing your eclass, please ensure that the
-<c>eclass-to-manpage.sh</c> script (currently in <c>$FILESDIR</c> for
-<c>app-portage/eclass-manpages</c> in the <c>gentoo.git</c> repo) does
-not report any errors or serious warnings for your eclass.
+Documentation tags for various eclass elements are explained in their
+respective sections below. Common to all the tags that accept
+multiline freetext, the <c>@CODE</c> tag should be used when necessary
+to create unformatted code chunks (such as example code) by placing
+the tag at the beginning and the end.
 </p>
 </body>
 </section>
 
-
 <section>
 <title>Basic Eclass Format</title>
 <body>
@@ -157,26 +154,135 @@ underscores and dots. Eclasses are not intrinsically versioned.
 <p>
 Eclasses should start with the standard ebuild header, along with
 comments explaining the maintainer and purpose of the eclass, and any
-other relevant documentation. The format supported by
-<c>app-portage/eclass-manpages</c> is as follows:
+other relevant documentation. Eclass documentation block should be the
+first documentation block to appear in the eclass. The following table
+summarizes the available documentation tags:
 </p>
 
-<codesample lang="ebuild">
-# @ECLASS: foo.eclass
-# @MAINTAINER:
-# &lt;required; list of contacts, one per line&gt;
-# @AUTHOR:
-# &lt;optional; list of authors, one per line&gt;
-# @BUGREPORTS:
-# &lt;optional; description of how to report bugs;
-#  default: tell people to use bugs.gentoo.org&gt;
-# @VCSURL: &lt;optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@&gt;
-# @BLURB: &lt;required; short description&gt;
-# @DESCRIPTION:
-# &lt;optional; long description&gt;
-# @EXAMPLE:
-# &lt;optional; example usage&gt;
-</codesample>
+<table>
+<tr>
+  <th>tag</th>
+  <th>optional?</th>
+  <th>arguments</th>
+  <th>description</th>
+</tr>
+<tr>
+  <ti>
+    <c>@ECLASS:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Name of the eclass being documented.
+  </ti>
+  <ti>
+    Documents various information about the eclass. Must appear as the
+    first tag in the comment block.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@MAINTAINER:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    One or more name and email pairs.
+  </ti>
+  <ti>
+    List of maintainers for the eclass to be contacted. One line per
+    maintainer. Must start on a newline after the tag.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@AUTHOR:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    One or more name and email pairs.
+  </ti>
+  <ti>
+    List of authors for the eclass. One line per author. Must start on
+    a newline after the tag.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@BUGREPORTS:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    Describes how bugs related to this eclass should be reported.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@VCSURL:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    A URI string.
+  </ti>
+  <ti>
+    Points to the URL of the VCS that contains the eclass source.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@BLURB:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Single line freetext.
+  </ti>
+  <ti>
+    Contains a short description for the eclass. Must be on the same
+    line with the tag.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DESCRIPTION:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    Long description for the eclass.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@EXAMPLE:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    Examples that illustrate various uses of this eclass.
+  </ti>
+</tr>
+</table>
 
 </body>
 </section>
@@ -190,21 +296,95 @@ Top level variables may be defined as for ebuilds. If any USE flags are
 used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an
 eclass.
 </p>
+
 <p>
 You should document the meaning, usage, and default value of every
-variable in your eclass. The standard format supported by
-<c>app-portage/eclass-manpages</c> is,
+variable in your eclass. The tags available for documenting eclass
+variables are as follows:
 </p>
 
-<codesample lang="ebuild">
-# @ECLASS-VARIABLE: foo
-# [@DEFAULT_UNSET]
-# [@INTERNAL]
-# [@REQUIRED]
-# @DESCRIPTION:
-# &lt;required; blurb about this variable&gt;
-# foo=&quot;&lt;default value&gt;&quot;
-</codesample>
+<table>
+<tr>
+  <th>tag</th>
+  <th>optional?</th>
+  <th>arguments</th>
+  <th>description</th>
+</tr>
+<tr>
+  <ti nowrap="nowrap">
+    <c>@ECLASS-VARIABLE:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Name of the eclass variable to which the documentation applies.
+  </ti>
+  <ti>
+    This tag applies to eclass specific variables that affect the
+    default behavior of the eclass. Read-only variables, which are
+    exported by the eclass for developer use, are also documented with
+    this tag. Must appear as the first tag in the comment block.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DEFAULT_UNSET</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that this variable is unset by default if not set by the
+    developer.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@INTERNAL</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that the variable is internal to the eclass.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@REQUIRED</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that this variable must be set by the developer.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DESCRIPTION:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    Long description for the eclass variable.
+  </ti>
+</tr>
+</table>
 
 </body>
 </section>
@@ -217,22 +397,207 @@ variable in your eclass. The standard format supported by
 Eclasses may define functions. These functions will be visible to anything which
 inherits the eclass.
 </p>
+
 <p>
 You should document the purpose, arguments, usage, and return value of
-every function in your eclass. The standard format supported by
-<c>app-portage/eclass-manpages</c> is,
+every function in your eclass. The standard tags available for
+documentation are:
 </p>
 
-<codesample lang="ebuild">
-# @FUNCTION: foo
-# @USAGE: &lt;required arguments to foo&gt; [optional arguments to foo]
-# @RETURN: &lt;whatever foo returns&gt;
-# @MAINTAINER:
-# &lt;optional; list of contacts, one per line&gt;
-# [@INTERNAL]
-# @DESCRIPTION:
-# &lt;required if no @RETURN; blurb about this function&gt;
-</codesample>
+<table>
+<tr>
+  <th>tag</th>
+  <th>optional?</th>
+  <th>arguments</th>
+  <th>description</th>
+</tr>
+<tr>
+  <ti>
+    <c>@FUNCTION:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Name of the function to which the documentation block applies.
+  </ti>
+  <ti>
+    Documents information about an eclass function such as its calling
+    convention etc. Must appear as the first tag in the comment block.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@USAGE:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    List of required and optional arguments to the function.
+  </ti>
+  <ti>
+    List of arguments that the eclass function accepts, specified in
+    the following syntax: <c>&lt;</c>Required arguments<c>&gt;</c>
+    <c>[</c>Optional arguments<c>]</c>
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@RETURN:</c>
+  </ti>
+  <ti>
+    <b>*</b>
+  </ti>
+  <ti>
+    Return value of the function.
+  </ti>
+  <ti>
+    <p>Description for the value returned by the function.</p>
+    <p><b>*</b>: Not optional for functions that return a value.</p>
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@MAINTAINER:</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    List of contacts for the eclass function. One line per
+    maintainer. Must start on a newline after the tag.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@INTERNAL</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that the function is internal to the eclass and should
+    not be called from outside.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DESCRIPTION:</c>
+  </ti>
+  <ti>
+    <b>*</b>
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    <p>Long description for the eclass function.</p>
+    <p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p>
+  </ti>
+</tr>
+</table>
+
+</body>
+</section>
+<section>
+<title>Eclass Function Variables</title>
+<body>
+
+<p>
+Eclass functions may make use of variables just like any other bash
+function. Special function-specific variables should be documented
+using the following tags:
+</p>
+
+<table>
+<tr>
+  <th>tag</th>
+  <th>optional?</th>
+  <th>arguments</th>
+  <th>description</th>
+</tr>
+<tr>
+  <ti>
+    <c>@VARIABLE:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Name of the function-specific variable to which the documentation applies.
+  </ti>
+  <ti>
+    This tag applies to variables consumed by specific functions of
+    the eclass. They are in effect only when the specific function is
+    called.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DEFAULT_UNSET</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that this variable is unset by default if not set by the
+    developer.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@INTERNAL</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that the variable is internal to the eclass function.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@REQUIRED</c>
+  </ti>
+  <ti>
+    YES
+  </ti>
+  <ti>
+    <d/>
+  </ti>
+  <ti>
+    Indicates that this variable must be set by the developer.
+  </ti>
+</tr>
+<tr>
+  <ti>
+    <c>@DESCRIPTION:</c>
+  </ti>
+  <ti>
+    NO
+  </ti>
+  <ti>
+    Multiline freetext.
+  </ti>
+  <ti>
+    Long description for the function variable.
+  </ti>
+</tr>
+</table>
+
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     3fd0d856bf9e001b490f8af477a06033219823a7
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jun  2 15:02:07 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:28 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3fd0d856

eclass-writing: add documentation to the build system example.

Now that we have guidelines for documenting eclasses, the "Simple
Build System Eclass Example" section is under-documented. This commit
adds the minimum required documentation (eclass and function headers)
to that example.

Gentoo-Bug: 373145

 eclass-writing/text.xml | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index def2b89..9329d88 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -339,22 +339,41 @@ something like the following:
 # Distributed under the terms of the GNU General Public License v2
 # &#36;Id&#36;
 
-# Original Author: Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
-# Purpose: Demonstration of EXPORT_FUNCTIONS. Defines simple wrappers for the
-# (hypothetical) 'jmake' build system and a default src_compile.
+# @ECLASS: jmake.eclass
+# @MAINTAINER:
+# Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
+# @AUTHOR:
+# Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
+# @BLURB: Demonstrate a simple build system eclass.
+# @DESCRIPTION:
+# Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the
+# (hypothetical) jmake build system and a default src_compile.
 
 EXPORT_FUNCTIONS src_compile
 
 DEPEND="&gt;=sys-devel/jmake-2"
 
+# @FUNCTION: jmake-configure
+# @USAGE: [additional-args]
+# @DESCRIPTION:
+# Passes all arguments through to the appropriate &quot;jmake configure&quot;
+# command.
 jmake-configure() {
     jmake configure --prefix=/usr "$@"
 }
 
+# @FUNCTION: jmake-build
+# @USAGE: [additional-args]
+# @DESCRIPTION:
+# First builds all dependencies, and then passes through its arguments
+# to the appropriate &quot;jmake build&quot; command.
 jmake-build() {
     jmake dep &amp;&amp; jmake build "$@"
 }
 
+# @FUNCTION: jmake-src_compile
+# @DESCRIPTION:
+# Calls jmake-configure() and jmake-build() to compile a jmake project.
 jmake_src_compile() {
     jmake-configure || die "configure failed"
     jmake-build || die "build failed"

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jun  2 14:31:56 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:13 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=092cc15a

eclass-writing: add "Documenting Eclasses" section and examples.

There is no mention of the standard eclass documentation headers on
the eclass-writing page. This commit adds a new section titled
"Documenting Eclasses", and adds examples of the three main types of
headers for eclasses, functions, and variables.

Gentoo-Bug: 373145

 eclass-writing/text.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 74 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 1a115b1..488230d 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -121,6 +121,29 @@ adhere to the following process:</p>
 </section>
 
 <section>
+<title>Documenting Eclasses</title>
+<body>
+
+<p>
+Eclasses are documented as any other bash project is, with code
+comments. We do however have a standard format for eclass, variable,
+and function headers. The <c>app-portage/eclass-manpages</c> package
+processes these headers to create documentation for the eclass. The
+result can be seen in our <uri link="::eclass-reference/">eclass
+reference</uri>, or by installing <c>app-portage/eclass-manpages</c>.
+</p>
+<p>
+The format for eclass, variable, and function headers are described
+below. Before committing your eclass, please ensure that the
+<c>eclass-to-manpage.sh</c> script (currently in <c>$FILESDIR</c> for
+<c>app-portage/eclass-manpages</c> in the <c>gentoo.git</c> repo) does
+not report any errors or serious warnings for your eclass.
+</p>
+</body>
+</section>
+
+
+<section>
 <title>Basic Eclass Format</title>
 <body>
 
@@ -132,11 +155,29 @@ underscores and dots. Eclasses are not intrinsically versioned.
 </p>
 
 <p>
-Eclasses should start with the standard ebuild header, along with comments
-explaining the maintainer and purpose of the eclass, and any other relevant
-documentation.
+Eclasses should start with the standard ebuild header, along with
+comments explaining the maintainer and purpose of the eclass, and any
+other relevant documentation. The format supported by
+<c>app-portage/eclass-manpages</c> is as follows:
 </p>
 
+<codesample lang="ebuild">
+# @ECLASS: foo.eclass
+# @MAINTAINER:
+# &lt;required; list of contacts, one per line&gt;
+# @AUTHOR:
+# &lt;optional; list of authors, one per line&gt;
+# @BUGREPORTS:
+# &lt;optional; description of how to report bugs;
+#  default: tell people to use bugs.gentoo.org&gt;
+# @VCSURL: &lt;optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@&gt;
+# @BLURB: &lt;required; short description&gt;
+# @DESCRIPTION:
+# &lt;optional; long description&gt;
+# @EXAMPLE:
+# &lt;optional; example usage&gt;
+</codesample>
+
 </body>
 </section>
 
@@ -149,6 +190,21 @@ Top level variables may be defined as for ebuilds. If any USE flags are
 used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an
 eclass.
 </p>
+<p>
+You should document the meaning, usage, and default value of every
+variable in your eclass. The standard format supported by
+<c>app-portage/eclass-manpages</c> is,
+</p>
+
+<codesample lang="ebuild">
+# @ECLASS-VARIABLE: foo
+# [@DEFAULT_UNSET]
+# [@INTERNAL]
+# [@REQUIRED]
+# @DESCRIPTION:
+# &lt;required; blurb about this variable&gt;
+# foo=&quot;&lt;default value&gt;&quot;
+</codesample>
 
 </body>
 </section>
@@ -161,7 +217,22 @@ eclass.
 Eclasses may define functions. These functions will be visible to anything which
 inherits the eclass.
 </p>
+<p>
+You should document the purpose, arguments, usage, and return value of
+every function in your eclass. The standard format supported by
+<c>app-portage/eclass-manpages</c> is,
+</p>
 
+<codesample lang="ebuild">
+# @FUNCTION: foo
+# @USAGE: &lt;required arguments to foo&gt; [optional arguments to foo]
+# @RETURN: &lt;whatever foo returns&gt;
+# @MAINTAINER:
+# &lt;optional; list of contacts, one per line&gt;
+# [@INTERNAL]
+# @DESCRIPTION:
+# &lt;required if no @RETURN; blurb about this function&gt;
+</codesample>
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     4ece0aa606656792178aa576a5c2e82ed45fb048
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Aug  4 05:13:30 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Aug 30 15:49:22 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4ece0aa6

eclass-writing: Word review requirement more strongly

Make the review of eclass updates an explicit requirement rather than
strong suggestion.  Require them unconditionally, providing explicit
exception for per-package eclasses.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 eclass-writing/text.xml | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index ee7d5d0..011a3d5 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -53,12 +53,17 @@ does not require a new eclass will be suggested.
 </p>
 
 <p>
-Before updating <c>eutils</c> or a similar widely used eclass, it is best to email
-the gentoo-dev list. It may be that your proposed change is broken in a way you
-had not anticipated, or that there is an existing function which performs the
-same purpose, or that your function may be better off in its own eclass. If you
-don't email gentoo-dev first, and end up breaking something, expect to be in a
-lot of trouble.
+Before updating any eclass, email patches to the gentoo-dev list. It may be that
+your proposed change is broken in a way you had not anticipated, or that there
+is an existing function which performs the same purpose, or that your function
+may be better off in its own eclass. If you don't email gentoo-dev first,
+and end up breaking something, expect to be in a lot of trouble.
+</p>
+
+<p>
+The exceptions to this rule are per-package eclasses. For example,
+the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c>
+package, and thus does not typically require changes to be emailed for review.
 </p>
 
 <p>
@@ -73,11 +78,6 @@ If there is an existing maintainer for an eclass (this is usually the case), you
 <b>must</b> talk to the maintainer before committing any changes.
 </p>
 
-<p>
-It is not usually necessary to email the gentoo-dev list before making changes
-to a non-general eclass which you maintain. Use common sense here.
-</p>
-
 <warning>
 Committing a broken eclass can kill huge numbers of packages. Since
 <c>repoman</c> is not eclass-aware, be very sure you do proper testing.

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     56a559843cb4af1c10b1df1b2f3b7c8bfe95bcb5
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Thu Aug 29 05:54:34 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Aug 30 15:49:26 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=56a55984

eclass-writing: Remove 30-day review requirement

Remove the requirement of posting API changes for review 30 days prior
to committing.  It is a dead policy, and we currently perform such
changes with regular review periods.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 eclass-writing/text.xml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 011a3d5..e26dd00 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -67,10 +67,8 @@ package, and thus does not typically require changes to be emailed for review.
 </p>
 
 <p>
-When removing a function or changing the API of an eclass, make
-sure that it doesn't break any ebuilds in the tree, and post a
-notice to gentoo-dev at least 30 days in advance, preferably with
-a patch included.
+When removing a function or changing the API of an eclass, make sure that
+it doesn't break any ebuilds in the Gentoo repository.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     9f63cc9e468400cc0feb64c3bd45cedb525b0451
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Fri Sep  6 05:57:23 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Sep 20 22:51:10 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9f63cc9e

eclass-writing: Make even more explicit, per gentoo-dev

Change 'should' into 'must' for initial reviews.  Make it clear
that per-package eclass exception applies only to updates.

ML-Thread: https://archives.gentoo.org/gentoo-dev/message/122108eebce1c4da00a1838896b4b1c3

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 eclass-writing/text.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index e26dd00..1bc1768 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -46,9 +46,9 @@ Roughly speaking, there are three kinds of eclass:
 <body>
 
 <p>
-Before committing a new eclass to the tree, it should be emailed to the
-gentoo-dev mailing list with a justification and a proposed implementation. Do
-not skip this step <d/> sometimes a better implementation or an alternative which
+Before committing a new eclass to the tree, it must be emailed to the gentoo-dev
+mailing list with a justification and a proposed implementation. Do not skip
+this step <d/> sometimes a better implementation or an alternative which
 does not require a new eclass will be suggested.
 </p>
 
@@ -61,7 +61,7 @@ and end up breaking something, expect to be in a lot of trouble.
 </p>
 
 <p>
-The exceptions to this rule are per-package eclasses. For example,
+The exceptions to this rule are updates to per-package eclasses. For example,
 the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c>
 package, and thus does not typically require changes to be emailed for review.
 </p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     5a28f4c774671cc78517596ef77692dbce0e2704
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Sep 12 17:05:00 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Sep 12 17:59:17 2020 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5a28f4c7

eclass-writing: Update list of eclass examples.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index d5fcc8d..6598f9a 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -27,15 +27,16 @@ Roughly speaking, there are three kinds of eclass:
 <ul>
   <li>
     Those which provide common functions which are used by many ebuilds (for
-    example, <c>eutils</c>, <c>eapi7-ver</c>, <c>cvs</c>, <c>bash-completion</c>)
+    example, <c>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>,
+    <c>toolchain-funcs</c>
   </li>
   <li>
     Those which provide a basic build system for many similar packages (for
-    example, <c>vim-plugin</c>, <c>kde</c>)
+    example, <c>perl-module</c>, <c>vim-plugin</c>)
   </li>
   <li>
     Those which handle one or a small number of packages with complex build
-    systems (for example, <c>vim</c>, <c>toolchain</c>, <c>kernel-2</c>)
+    systems (for example, <c>kernel-2</c>, <c>toolchain</c>)
   </li>
 </ul>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Göktürk Yüksek]

commit:     f7cc34083e1b3447dde176963f98c1bf50b29f0b
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Tue Dec 29 02:40:34 2020 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Dec 29 22:07:30 2020 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f7cc3408

eclass-writing: prefer "phase functions" over "ebuild functions"

When the text specifically refers to phase functions, be more verbose
about it. Ebuilds can define other functions that are
internal. Eclasses also define functions. Using the term "phase
functions" should help clarify the ambiguity.

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/183

 eclass-writing/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 6598f9a..d0048b3 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -643,7 +643,7 @@ domacosapp() {
 <body>
 
 <p>
-An eclass may provide default implementations for any of the standard ebuild
+An eclass may provide default implementations for any of the ebuild phase
 functions (<c>src_unpack</c>, <c>pkg_postinst</c> etc). This can be done either as a
 simple function definition (which is not multiple eclass friendly) or using
 <c>EXPORT_FUNCTIONS</c>. Functions given to <c>EXPORT_FUNCTIONS</c> are implemented
@@ -651,7 +651,7 @@ as normal, but have their name prefixed with <c>${ECLASS}_</c>.
 </p>
 
 <important>
-Only 'standard' functions should be specified in <c>EXPORT_FUNCTIONS</c>.
+Only the ebuild phase functions may be specified in <c>EXPORT_FUNCTIONS</c>.
 </important>
 
 <note><c>EXPORT_FUNCTIONS</c> is a function, <e>not</e> a variable.</note>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     1916f42b99447c45e1f8e920dcdd025715a7c328
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 05:30:00 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:23 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1916f42b

eclass-writing: mention that checking (official) overlays may be useful

This is just a politeness/interesting thought which people may want to
consider, rather than a hard requirement.

For "official" overlays in particular, a Gentoo developer should be able
to give the responsible developer(s) a quick ping to ensure they're
aware if their overlay seems to be heavily using legacy functionality.

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 70f9fff..adf3671 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -70,7 +70,10 @@ package, and thus does not typically require changes to be emailed for review.
 
 <p>
 When removing a function or changing the API of an eclass, make sure that
-it doesn't break any ebuilds in the Gentoo repository.
+it doesn't break any ebuilds in the Gentoo repository. Optionally, you may wish
+to do a survey of some (official) overlays like <c>::guru</c>, <c>::musl</c>, or
+<c>::science</c> in order to better understand how it is currently used and
+<d/> where possible <d/> avoid breakage by pinging the maintainers directly.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     3d47a2bc63aec2ac36b63eae6b84905487f6ddd6
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:37:51 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:25 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3d47a2bc

eclass-writing: add new eclass doc tags for Eclass Variables

Adds:
* @PRE_INHERIT
* @USER_VARIABLE
* @OUTPUT_VARIABLE
* @INCLUDES_EPREFIX
* @DEPRECATED

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 87 ++++++++++++++++++++++++++++---------------------
 1 file changed, 50 insertions(+), 37 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index df02827..b7fd988 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -350,61 +350,74 @@ variables are as follows:
   </ti>
 </tr>
 <tr>
+  <ti><c>@PRE_INHERIT</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
-    <c>@DEFAULT_UNSET</c>
+    This tag describes whether the variable must be defined before
+    the eclass is inherited. This is important if any e.g. dependencies
+    are modified in global scope at the point of sourcing.
   </ti>
+</tr>
+<tr>
+  <ti><c>@USER_VARIABLE</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
-    YES
+    This tag describes whether the variable is unsuitable for use in ebuilds,
+    i.e. if it is solely for user consumption via e.g. make.conf or a similar
+    mechanism.
   </ti>
+</tr>
+<tr>
+  <ti><c>@OUTPUT_VARIABLE</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
-    <d/>
+    This tag indicates that the variable's value (which will be set by the
+    eclass) should be read within an ebuild.
   </ti>
+</tr>
+<tr>
+  <ti><c>@DEFAULT_UNSET</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
     developer.
   </ti>
 </tr>
 <tr>
+  <ti><c>@INCLUDES_EPREFIX</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
-    <c>@INTERNAL</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
-  </ti>
-  <ti>
-    Indicates that the variable is internal to the eclass.
+    Indicates that the variable is a path which has ${EPREFIX} prepended to it.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@REQUIRED</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
-  </ti>
-  <ti>
-    Indicates that this variable must be set by the developer.
-  </ti>
+  <ti><c>@INTERNAL</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
+  <ti>Indicates that the variable is internal to the eclass.</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@DESCRIPTION:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Multiline freetext.
-  </ti>
-  <ti>
-    Long description for the eclass variable.
-  </ti>
+  <ti><c>@REQUIRED</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
+  <ti>Indicates that this variable must be set by the developer.</ti>
+</tr>
+<tr>
+  <ti><c>@DEPRECATED</c></ti>
+  <ti>YES</ti>
+  <ti>Optionally, the name of any replacement variable.</ti>
+  <ti>Declares that this variable should no longer be used in ebuilds.</ti>
+</tr>
+<tr>
+  <ti><c>@DESCRIPTION:</c></ti>
+  <ti>NO</ti>
+  <ti>Multiline freetext.</ti>
+  <ti>Long description for the eclass variable.</ti>
 </tr>
 </table>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     b80285bdc37a51a2628bf4b7edd44717c15062cb
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:44:06 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:26 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b80285bd

eclass-writing: add new eclass doc tags for Eclass Functions

Adds:
* @INCLUDES_EPREFIX
* @DEPRECATED

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index b7fd988..5a1015f 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -508,20 +508,29 @@ documentation are:
   </ti>
 </tr>
 <tr>
+  <ti><c>@INCLUDES_EPREFIX</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
-    <c>@INTERNAL</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
+    Indicates whether the function returns a path with ${EPREFIX} prepended
+    to it.
   </ti>
+</tr>
+<tr>
+  <ti><c>@INTERNAL</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
     Indicates that the function is internal to the eclass and should
     not be called from outside.
   </ti>
 </tr>
+<tr>
+  <ti><c>@DEPRECATED</c></ti>
+  <ti>YES</ti>
+  <ti>Optionally, the name of a replacement function.</ti>
+  <ti>Declares that this function should no longer be used in ebuilds.</ti>
+</tr>
 <tr>
   <ti>
     <c>@DESCRIPTION:</c>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     bb1891eac5da63da15967397a1326cb680b5b0c6
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:16:06 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:23 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=bb1891ea

eclass-writing: mention that prefixing with the eclass name is "namespacing"

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index ccebfb6..6ac9f0d 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -658,10 +658,10 @@ domacosapp() {
 
 <p>
 An eclass may provide default implementations for any of the ebuild phase
-functions (<c>src_unpack</c>, <c>pkg_postinst</c> etc). This can be done either as a
+functions (<c>src_unpack</c>, <c>pkg_postinst</c>, etc). This can be done either as a
 simple function definition (which is not multiple eclass friendly) or using
 <c>EXPORT_FUNCTIONS</c>. Functions given to <c>EXPORT_FUNCTIONS</c> are implemented
-as normal, but have their name prefixed with <c>${ECLASS}_</c>.
+as normal, but have their name prefixed ("namespaced") with <c>${ECLASS}_</c>.
 </p>
 
 <important>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     3c482d5378acaa5e98d6b29f7b340527aa9daff7
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:22:04 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:24 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3c482d53

eclass-writing: adjust example 'inherit' slightly

We don't usually write 'inherit fnord.eclass' but 'inherit fnord'.

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 288008d..1483847 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -698,7 +698,7 @@ Then an ebuild could do this:
 </p>
 
 <codesample lang="ebuild">
-inherit fnord.eclass
+inherit fnord
 
 src_compile() {
 	do_pre_stuff || die

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     033a9827694d3a70af3df95971df0eee45ace9a5
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:23:20 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:25 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=033a9827

eclass-writing: add missing parenthesis

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 1483847..df02827 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -28,7 +28,7 @@ Roughly speaking, there are three kinds of eclass:
   <li>
     Those which provide common functions which are used by many ebuilds (for
     example, <c>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>,
-    <c>toolchain-funcs</c>
+    <c>toolchain-funcs</c>)
   </li>
   <li>
     Those which provide a basic build system for many similar packages (for

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     dbade96ef1200896733d0ec6842f7d82b0f645b3
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Mar 30 06:55:29 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:55:29 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dbade96e

eclass-writing: Remove full stop from table entries

::appendices/devbook-guide/#External Coding Style

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 86 ++++++++++++++++++++++++-------------------------
 1 file changed, 43 insertions(+), 43 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 094f939..cc703cc 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -201,7 +201,7 @@ summarizes the available documentation tags:
     NO
   </ti>
   <ti>
-    Name of the eclass being documented.
+    Name of the eclass being documented
   </ti>
   <ti>
     Documents various information about the eclass. Must appear as the
@@ -216,7 +216,7 @@ summarizes the available documentation tags:
     NO
   </ti>
   <ti>
-    One or more name and email pairs.
+    One or more name and email pairs
   </ti>
   <ti>
     List of maintainers for the eclass to be contacted. One line per
@@ -231,7 +231,7 @@ summarizes the available documentation tags:
     YES
   </ti>
   <ti>
-    One or more name and email pairs.
+    One or more name and email pairs
   </ti>
   <ti>
     List of authors for the eclass. One line per author. Must start on
@@ -246,10 +246,10 @@ summarizes the available documentation tags:
     YES
   </ti>
   <ti>
-    Multiline freetext.
+    Multiline freetext
   </ti>
   <ti>
-    Describes how bugs related to this eclass should be reported.
+    Describes how bugs related to this eclass should be reported
   </ti>
 </tr>
 <tr>
@@ -260,10 +260,10 @@ summarizes the available documentation tags:
     YES
   </ti>
   <ti>
-    A URI string.
+    A URI string
   </ti>
   <ti>
-    Points to the URL of the VCS that contains the eclass source.
+    Points to the URL of the VCS that contains the eclass source
   </ti>
 </tr>
 <tr>
@@ -274,7 +274,7 @@ summarizes the available documentation tags:
     NO
   </ti>
   <ti>
-    Single line freetext.
+    Single line freetext
   </ti>
   <ti>
     Contains a short description for the eclass. Must be on the same
@@ -289,10 +289,10 @@ summarizes the available documentation tags:
     YES
   </ti>
   <ti>
-    Multiline freetext.
+    Multiline freetext
   </ti>
   <ti>
-    Long description for the eclass.
+    Long description for the eclass
   </ti>
 </tr>
 <tr>
@@ -303,10 +303,10 @@ summarizes the available documentation tags:
     YES
   </ti>
   <ti>
-    Multiline freetext.
+    Multiline freetext
   </ti>
   <ti>
-    Examples that illustrate various uses of this eclass.
+    Examples that illustrate various uses of this eclass
   </ti>
 </tr>
 </table>
@@ -345,7 +345,7 @@ variables are as follows:
     NO
   </ti>
   <ti>
-    Name of the eclass variable to which the documentation applies.
+    Name of the eclass variable to which the documentation applies
   </ti>
   <ti>
     This tag applies to eclass specific variables that affect the
@@ -371,7 +371,7 @@ variables are as follows:
   <ti>
     This tag describes whether the variable is unsuitable for use in ebuilds,
     i.e. if it is solely for user consumption via e.g. make.conf or a similar
-    mechanism.
+    mechanism
   </ti>
 </tr>
 <tr>
@@ -380,7 +380,7 @@ variables are as follows:
   <ti><d/></ti>
   <ti>
     This tag indicates that the variable's value (which will be set by the
-    eclass) should be read within an ebuild.
+    eclass) should be read within an ebuild
   </ti>
 </tr>
 <tr>
@@ -389,7 +389,7 @@ variables are as follows:
   <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
-    developer.
+    developer
   </ti>
 </tr>
 <tr>
@@ -397,32 +397,32 @@ variables are as follows:
   <ti>YES</ti>
   <ti><d/></ti>
   <ti>
-    Indicates that the variable is a path which has ${EPREFIX} prepended to it.
+    Indicates that the variable is a path which has ${EPREFIX} prepended to it
   </ti>
 </tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
   <ti>YES</ti>
   <ti><d/></ti>
-  <ti>Indicates that the variable is internal to the eclass.</ti>
+  <ti>Indicates that the variable is internal to the eclass</ti>
 </tr>
 <tr>
   <ti><c>@REQUIRED</c></ti>
   <ti>YES</ti>
   <ti><d/></ti>
-  <ti>Indicates that this variable must be set by the developer.</ti>
+  <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
   <ti>YES</ti>
-  <ti>Optionally, the name of any replacement variable.</ti>
-  <ti>Declares that this variable should no longer be used in ebuilds.</ti>
+  <ti>Optionally, the name of any replacement variable</ti>
+  <ti>Declares that this variable should no longer be used in ebuilds</ti>
 </tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
   <ti>NO</ti>
-  <ti>Multiline freetext.</ti>
-  <ti>Long description for the eclass variable.</ti>
+  <ti>Multiline freetext</ti>
+  <ti>Long description for the eclass variable</ti>
 </tr>
 </table>
 
@@ -459,11 +459,11 @@ documentation are:
     NO
   </ti>
   <ti>
-    Name of the function to which the documentation block applies.
+    Name of the function to which the documentation block applies
   </ti>
   <ti>
     Documents information about an eclass function such as its calling
-    convention etc. Must appear as the first tag in the comment block.
+    convention etc. Must appear as the first tag in the comment block
   </ti>
 </tr>
 <tr>
@@ -474,7 +474,7 @@ documentation are:
     NO
   </ti>
   <ti>
-    List of required and optional arguments to the function.
+    List of required and optional arguments to the function
   </ti>
   <ti>
     List of arguments that the eclass function accepts, specified in
@@ -490,7 +490,7 @@ documentation are:
     <b>*</b>
   </ti>
   <ti>
-    Return value of the function.
+    Return value of the function
   </ti>
   <ti>
     <p>Description for the value returned by the function.</p>
@@ -505,7 +505,7 @@ documentation are:
     YES
   </ti>
   <ti>
-    Multiline freetext.
+    Multiline freetext
   </ti>
   <ti>
     List of contacts for the eclass function. One line per
@@ -518,7 +518,7 @@ documentation are:
   <ti><d/></ti>
   <ti>
     Indicates whether the function returns a path with ${EPREFIX} prepended
-    to it.
+    to it
   </ti>
 </tr>
 <tr>
@@ -527,14 +527,14 @@ documentation are:
   <ti><d/></ti>
   <ti>
     Indicates that the function is internal to the eclass and should
-    not be called from outside.
+    not be called from outside
   </ti>
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
   <ti>YES</ti>
-  <ti>Optionally, the name of a replacement function.</ti>
-  <ti>Declares that this function should no longer be used in ebuilds.</ti>
+  <ti>Optionally, the name of a replacement function</ti>
+  <ti>Declares that this function should no longer be used in ebuilds</ti>
 </tr>
 <tr>
   <ti>
@@ -544,7 +544,7 @@ documentation are:
     <b>*</b>
   </ti>
   <ti>
-    Multiline freetext.
+    Multiline freetext
   </ti>
   <ti>
     <p>Long description for the eclass function.</p>
@@ -576,7 +576,7 @@ using the following tags:
   <ti><c>@VARIABLE:</c></ti>
   <ti>NO</ti>
   <ti>
-    Name of the function-specific variable to which the documentation applies.
+    Name of the function-specific variable to which the documentation applies
   </ti>
   <ti>
     This tag applies to variables consumed by specific functions of
@@ -591,7 +591,7 @@ using the following tags:
    <ti>
      This tag describes whether the variable is unsuitable for use in ebuilds,
      i.e. if it is solely for user consumption via e.g. make.conf or a similar
-     mechanism.
+     mechanism
    </ti>
 </tr>
 <tr>
@@ -600,38 +600,38 @@ using the following tags:
   <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
-    developer.
+    developer
   </ti>
 </tr>
 <tr>
   <ti><c>@INCLUDES_EPREFIX</c></ti>
   <ti>YES</ti>
   <ti><d/></ti>
-  <ti>Indicates that the variable is a path which has ${EPREFIX} prepended.</ti>
+  <ti>Indicates that the variable is a path which has ${EPREFIX} prepended</ti>
 </tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
   <ti>YES</ti>
   <ti><d/></ti>
-  <ti>Indicates that the variable is internal to the eclass function.</ti>
+  <ti>Indicates that the variable is internal to the eclass function</ti>
 </tr>
 <tr>
   <ti><c>@REQUIRED</c></ti>
   <ti>YES</ti>
   <ti><d/></ti>
-  <ti>Indicates that this variable must be set by the developer.</ti>
+  <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
   <ti>YES</ti>
-  <ti>Optionally, the name of any replacement variable.</ti>
-  <ti>Declares that this variable should no longer be used in ebuilds.</ti>
+  <ti>Optionally, the name of any replacement variable</ti>
+  <ti>Declares that this variable should no longer be used in ebuilds</ti>
 </tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
   <ti>NO</ti>
-  <ti>Multiline freetext.</ti>
-  <ti>Long description for the function variable.</ti>
+  <ti>Multiline freetext</ti>
+  <ti>Long description for the function variable</ti>
 </tr>
 </table>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     97c28330bb6906f046337c4000e69ef52c52296f
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 05:37:37 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:23 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=97c28330

eclass-writing: mention etiquette with respect to metadata invalidation

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index adf3671..ccebfb6 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -90,6 +90,17 @@ Committing a broken eclass can kill huge numbers of packages. Since
 A simple way to verify syntax is <c>bash -n foo.eclass</c>.
 </p>
 
+<note>
+Given that updating an eclass will invalidate the cache of all consumer ebuilds,
+it is good etiquette to ping other developers in e.g. <c>#gentoo-dev</c>
+on IRC or informally determine if there are other similar changes (mainly
+documentation) which should be pushed at the same time in order to avoid
+unnecessary cache regeneration within a few hours or days of each other.
+
+The same applies to your own work <d/> please prepare all of your commits and
+batch push them at once where possible.
+</note>
+
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     ce22a0be5e11107c59d6f07fb508b5ff35cdf110
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:19:51 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:24 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ce22a0be

eclass-writing: mention pkgcheck usage for checking eclass docs

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 6ac9f0d..288008d 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -151,6 +151,14 @@ multiline freetext, the <c>@CODE</c> tag should be used when necessary
 to create unformatted code chunks (such as example code) by placing
 the tag at the beginning and the end.
 </p>
+
+<p>
+Note that <c>pkgcheck</c> can check for issues in eclass documentation.
+You could run e.g. <c>pkgcheck scan -s eclass</c> to check for issues
+in the tree or <c>pkgcheck scan --commits</c> to check for issues
+in your staged git commits.
+</p>
+
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     336d16aa5fe8c564a15760659e1670a0e98e58b3
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Mar 22 06:56:29 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:26 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=336d16aa

eclass-writing: add new eclass doc tags for Eclass Function Variables

Adds:
* @USER_VARIABLE
* @INCLUDES_EPREFIX
* @DEPRECATED

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 90 +++++++++++++++++++++----------------------------
 1 file changed, 39 insertions(+), 51 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 5a1015f..e8b1474 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -568,12 +568,8 @@ using the following tags:
   <th>description</th>
 </tr>
 <tr>
-  <ti>
-    <c>@VARIABLE:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
+  <ti><c>@VARIABLE:</c></ti>
+  <ti>NO</ti>
   <ti>
     Name of the function-specific variable to which the documentation applies.
   </ti>
@@ -584,61 +580,53 @@ using the following tags:
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@DEFAULT_UNSET</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
-  </ti>
+  <ti><c>@USER_VARIABLE</c></ti>
+   <ti>YES</ti>
+   <ti><d/></ti>
+   <ti>
+     This tag describes whether the variable is unsuitable for use in ebuilds,
+     i.e. if it is solely for user consumption via e.g. make.conf or a similar
+     mechanism.
+   </ti>
+</tr>
+<tr>
+  <ti><c>@DEFAULT_UNSET</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
     developer.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@INTERNAL</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
-  </ti>
-  <ti>
-    Indicates that the variable is internal to the eclass function.
-  </ti>
+  <ti><c>@INCLUDES_EPREFIX</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
+  <ti>Indicates that the variable is a path which has ${EPREFIX} prepended.</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@REQUIRED</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    <d/>
-  </ti>
-  <ti>
-    Indicates that this variable must be set by the developer.
-  </ti>
+  <ti><c>@INTERNAL</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
+  <ti>Indicates that the variable is internal to the eclass function.</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@DESCRIPTION:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Multiline freetext.
-  </ti>
-  <ti>
-    Long description for the function variable.
-  </ti>
+  <ti><c>@REQUIRED</c></ti>
+  <ti>YES</ti>
+  <ti><d/></ti>
+  <ti>Indicates that this variable must be set by the developer.</ti>
+</tr>
+<tr>
+  <ti><c>@DEPRECATED</c></ti>
+  <ti>YES</ti>
+  <ti>Optionally, the name of any replacement variable.</ti>
+  <ti>Declares that this variable should no longer be used in ebuilds.</ti>
+</tr>
+<tr>
+  <ti><c>@DESCRIPTION:</c></ti>
+  <ti>NO</ti>
+  <ti>Multiline freetext.</ti>
+  <ti>Long description for the function variable.</ti>
 </tr>
 </table>
 

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     b6e8ea5beb6d8995f953d63910065dc91a9089bf
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 28 01:54:47 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 06:53:27 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b6e8ea5b

eclass-writing: add note re deprecation of eclasses

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index e8b1474..094f939 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -130,6 +130,11 @@ adhere to the following process:</p>
   </li>
 </ol>
 
+<note>
+Before considering removal, please mark the eclass as <c># @DEPRECATED</c>
+to ensure consumers are warned if they are still using the eclass. Do this
+for a period before removing the eclass.
+</note>
 
 </body>
 </section>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     0b761177f88afc62cf5c040e8a5de49964451587
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 04:10:44 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr  7 17:28:16 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0b761177

eclass-writing: use BDEPEND for hypothetical jmake example

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index cc703cc..a1f65a2 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -751,7 +751,7 @@ something like the following:
 
 EXPORT_FUNCTIONS src_compile
 
-DEPEND="&gt;=sys-devel/jmake-2"
+BDEPEND="&gt;=sys-devel/jmake-2"
 
 # @FUNCTION: jmake-configure
 # @USAGE: [additional-args]

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     ba6a05c97b16d9030ea437be37ebefa62358f6a6
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Sep  1 18:02:10 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Sep  1 18:02:10 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ba6a05c9

eclass-writing: Fix dash

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index a1f65a2..84599cb 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -789,7 +789,7 @@ jmake_src_compile() {
 
 <p>
 Sometimes an eclass is used incorrectly by an ebuild and the eclass
-knows it is being used incorrectly- the common example is an
+knows it is being used incorrectly <d/> the common example is an
 eclass that only works with a specific set of EAPIs, but is being
 accessed inherited by an ebuild with a different EAPI.
 In those cases, used sparingly as a last resort, it is allowed

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     81542270c8ea07743b9d2b72ba410209919a4a6a
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Sep  2 15:20:43 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Sep  2 15:20:43 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=81542270

eclass-writing: Update example for EAPI conditional

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 84599cb..09b41d2 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -803,11 +803,12 @@ for an eclass to invoke die from the global scope.  For example:
 # @ECLASS: eapi-die.eclass
 # @MAINTAINER:
 # Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
+# @SUPPORTED_EAPIS: 7 8
 # @BLURB: Calls die when used with an invalid EAPI.
 
-case ${EAPI:-0} in
-	0) die "this eclass doesn't support EAPI 0" ;;
-	*) ;;
+case ${EAPI} in
+	7|8) ;;
+	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
 esac
 </codesample>
 </body>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     c2ddff702a72b8240915e8fb583a753670a1a553
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Sep  1 18:12:50 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Sep  4 10:35:12 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=c2ddff70

eclass-writing: Whitespace

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 184 ++++++++++++------------------------------------
 1 file changed, 46 insertions(+), 138 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 09b41d2..0c81bf6 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -194,120 +194,64 @@ summarizes the available documentation tags:
   <th>description</th>
 </tr>
 <tr>
-  <ti>
-    <c>@ECLASS:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Name of the eclass being documented
-  </ti>
+  <ti><c>@ECLASS:</c></ti>
+  <ti>NO</ti>
+  <ti>Name of the eclass being documented</ti>
   <ti>
     Documents various information about the eclass. Must appear as the
     first tag in the comment block.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@MAINTAINER:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    One or more name and email pairs
-  </ti>
+  <ti><c>@MAINTAINER:</c></ti>
+  <ti>NO</ti>
+  <ti>One or more name and email pairs</ti>
   <ti>
     List of maintainers for the eclass to be contacted. One line per
     maintainer. Must start on a newline after the tag.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@AUTHOR:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    One or more name and email pairs
-  </ti>
+  <ti><c>@AUTHOR:</c></ti>
+  <ti>YES</ti>
+  <ti>One or more name and email pairs</ti>
   <ti>
     List of authors for the eclass. One line per author. Must start on
     a newline after the tag.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@BUGREPORTS:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    Multiline freetext
-  </ti>
-  <ti>
-    Describes how bugs related to this eclass should be reported
-  </ti>
+  <ti><c>@BUGREPORTS:</c></ti>
+  <ti>YES</ti>
+  <ti>Multiline freetext</ti>
+  <ti>Describes how bugs related to this eclass should be reported</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@VCSURL:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    A URI string
-  </ti>
-  <ti>
-    Points to the URL of the VCS that contains the eclass source
-  </ti>
+  <ti><c>@VCSURL:</c></ti>
+  <ti>YES</ti>
+  <ti>A URI string</ti>
+  <ti>Points to the URL of the VCS that contains the eclass source</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@BLURB:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Single line freetext
-  </ti>
+  <ti><c>@BLURB:</c></ti>
+  <ti>NO</ti>
+  <ti>Single line freetext</ti>
   <ti>
     Contains a short description for the eclass. Must be on the same
     line with the tag.
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@DESCRIPTION:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    Multiline freetext
-  </ti>
-  <ti>
-    Long description for the eclass
-  </ti>
+  <ti><c>@DESCRIPTION:</c></ti>
+  <ti>YES</ti>
+  <ti>Multiline freetext</ti>
+  <ti>Long description for the eclass</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@EXAMPLE:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    Multiline freetext
-  </ti>
-  <ti>
-    Examples that illustrate various uses of this eclass
-  </ti>
+  <ti><c>@EXAMPLE:</c></ti>
+  <ti>YES</ti>
+  <ti>Multiline freetext</ti>
+  <ti>Examples that illustrate various uses of this eclass</ti>
 </tr>
 </table>
 
@@ -338,15 +282,9 @@ variables are as follows:
   <th>description</th>
 </tr>
 <tr>
-  <ti nowrap="nowrap">
-    <c>@ECLASS-VARIABLE:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Name of the eclass variable to which the documentation applies
-  </ti>
+  <ti nowrap="nowrap"><c>@ECLASS-VARIABLE:</c></ti>
+  <ti>NO</ti>
+  <ti>Name of the eclass variable to which the documentation applies</ti>
   <ti>
     This tag applies to eclass specific variables that affect the
     default behavior of the eclass. Read-only variables, which are
@@ -452,30 +390,18 @@ documentation are:
   <th>description</th>
 </tr>
 <tr>
-  <ti>
-    <c>@FUNCTION:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    Name of the function to which the documentation block applies
-  </ti>
+  <ti><c>@FUNCTION:</c></ti>
+  <ti>NO</ti>
+  <ti>Name of the function to which the documentation block applies</ti>
   <ti>
     Documents information about an eclass function such as its calling
     convention etc. Must appear as the first tag in the comment block
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@USAGE:</c>
-  </ti>
-  <ti>
-    NO
-  </ti>
-  <ti>
-    List of required and optional arguments to the function
-  </ti>
+  <ti><c>@USAGE:</c></ti>
+  <ti>NO</ti>
+  <ti>List of required and optional arguments to the function</ti>
   <ti>
     List of arguments that the eclass function accepts, specified in
     the following syntax: <c>&lt;</c>Required arguments<c>&gt;</c>
@@ -483,30 +409,18 @@ documentation are:
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@RETURN:</c>
-  </ti>
-  <ti>
-    <b>*</b>
-  </ti>
-  <ti>
-    Return value of the function
-  </ti>
+  <ti><c>@RETURN:</c></ti>
+  <ti><b>*</b></ti>
+  <ti>Return value of the function</ti>
   <ti>
     <p>Description for the value returned by the function.</p>
     <p><b>*</b>: Not optional for functions that return a value.</p>
   </ti>
 </tr>
 <tr>
-  <ti>
-    <c>@MAINTAINER:</c>
-  </ti>
-  <ti>
-    YES
-  </ti>
-  <ti>
-    Multiline freetext
-  </ti>
+  <ti><c>@MAINTAINER:</c></ti>
+  <ti>YES</ti>
+  <ti>Multiline freetext</ti>
   <ti>
     List of contacts for the eclass function. One line per
     maintainer. Must start on a newline after the tag.
@@ -537,15 +451,9 @@ documentation are:
   <ti>Declares that this function should no longer be used in ebuilds</ti>
 </tr>
 <tr>
-  <ti>
-    <c>@DESCRIPTION:</c>
-  </ti>
-  <ti>
-    <b>*</b>
-  </ti>
-  <ti>
-    Multiline freetext
-  </ti>
+  <ti><c>@DESCRIPTION:</c></ti>
+  <ti><b>*</b></ti>
+  <ti>Multiline freetext</ti>
   <ti>
     <p>Long description for the eclass function.</p>
     <p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     b691f696abfbc33a4e3f3bea2100ebc466c24e6b
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Sep  2 07:54:21 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Sep  4 10:35:13 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b691f696

eclass-writing: More documentation tags

@SUBSECTION, @SUPPORTED_EAPIS, @PROVIDES, and @DEPRECATED.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 0c81bf6..791a2ce 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -151,10 +151,11 @@ each block documents an individual element of an eclass.
 
 <p>
 Documentation tags for various eclass elements are explained in their
-respective sections below. Common to all the tags that accept
-multiline freetext, the <c>@CODE</c> tag should be used when necessary
-to create unformatted code chunks (such as example code) by placing
-the tag at the beginning and the end.
+respective sections below. Common to all the tags that accept multiline
+freetext, the <c>@CODE</c> tag should be used when necessary to create
+unformatted code chunks (such as example code) by placing the tag at the
+beginning and the end. The <c>@SUBSECTION</c> tag inserts a subsection
+heading; it is allowed only in the main <c>@DESCRIPTION</c>.
 </p>
 
 <p>
@@ -232,6 +233,21 @@ summarizes the available documentation tags:
   <ti>A URI string</ti>
   <ti>Points to the URL of the VCS that contains the eclass source</ti>
 </tr>
+<tr>
+  <ti nowrap="nowrap"><c>@SUPPORTED_EAPIS:</c></ti>
+  <ti>YES</ti>
+  <ti>Space-separated list of EAPIs</ti>
+  <ti>List of EAPIs supported by this eclass</ti>
+</tr>
+<tr>
+  <ti><c>@PROVIDES:</c></ti>
+  <ti>YES</ti>
+  <ti>Space-separated list of eclass names</ti>
+  <ti>
+    List of indirectly inherited eclasses whose functions and variables may be
+    used by an ebuild inheriting this eclass
+  </ti>
+</tr>
 <tr>
   <ti><c>@BLURB:</c></ti>
   <ti>NO</ti>
@@ -241,6 +257,12 @@ summarizes the available documentation tags:
     line with the tag.
   </ti>
 </tr>
+<tr>
+  <ti><c>@DEPRECATED:</c></ti>
+  <ti>YES</ti>
+  <ti>Replacement (or "none")</ti>
+  <ti>Declares that this eclass should no longer be used</ti>
+</tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
   <ti>YES</ti>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     cd392d0c6cd064ac3a1381111e678f4fe111afcc
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Sep  2 15:36:26 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Sep  4 10:37:13 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=cd392d0c

eclass-writing: @DEAD must be the first tag

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 791a2ce..db199f4 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -123,7 +123,9 @@ adhere to the following process:</p>
   </li>
   <li>
     Add a one line comment to the eclass, saying exactly <c># @DEAD</c> so that
-    the eclass-manpages package will not attempt to document it.
+    the eclass-manpages package will not attempt to document it. <c>@DEAD</c>
+    must be the first documentation tag in the eclass, i.e. it goes before
+    the <c>@ECLASS</c> tag.
   </li>
   <li>
     Wait for the 30-day period to pass, then remove the eclass from the tree.

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     6e206d3e065884f4675b041e069a3b05663fa1f7
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Tue Oct  5 04:37:49 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Oct 13 13:44:16 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6e206d3e

eclass-writing: mention CCing maintainers on eclass patches

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index db199f4..40ec0be 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -62,6 +62,12 @@ may be better off in its own eclass. If you don't email gentoo-dev first,
 and end up breaking something, expect to be in a lot of trouble.
 </p>
 
+<p>
+Note that you should also, when sending your patch, CC any maintainers of the
+eclass listed in the <c>@MAINTAINER</c> tag. You may want to contact them
+ahead of time and get their opinions too.
+</p>
+
 <p>
 The exceptions to this rule are updates to per-package eclasses. For example,
 the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Sam James]

commit:     760deadbbcf094a896e85827eaf3089b2cc0f2cc
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Thu Dec  9 05:00:15 2021 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Thu Dec  9 05:00:15 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=760deadb

eclass-writing: drop unnecessary '|| die'

newins is already fatal on errors.

Signed-off-by: Sam James <sam <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 40ec0be..2f316a3 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -605,7 +605,7 @@ domacosapp() {
 	[[ -z "${1}" ]] &amp;&amp; die "usage: domacosapp &lt;file&gt; [new file]"
 	if use ppc-macos ; then
 		insinto /Applications
-		newins "$1" "${2:-${1}}" || die "Failed to install ${1}"
+		newins "$1" "${2:-${1}}"
 	fi
 }
 </codesample>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Sam James]

commit:     47753e7ad55a22f24ebfab53a4bb6a03272b7f9f
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Wed Mar 16 13:17:34 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Wed Mar 16 14:46:08 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=47753e7a

eclass-writing: fix typo jmake-src_compile -> jmake_src_compile

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Closes: https://github.com/gentoo/devmanual/pull/277
Signed-off-by: Sam James <sam <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 41976c3..de6c0b2 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -708,7 +708,7 @@ jmake-build() {
 	jmake dep &amp;&amp; jmake build "$@"
 }
 
-# @FUNCTION: jmake-src_compile
+# @FUNCTION: jmake_src_compile
 # @DESCRIPTION:
 # Calls jmake-configure() and jmake-build() to compile a jmake project.
 jmake_src_compile() {

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Sam James]

commit:     59ae980db874417e300bd2b9ca57dffcaba12087
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Wed Mar 16 14:47:21 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Wed Mar 16 14:47:21 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=59ae980d

eclass-writing: tweak confusing typo

Signed-off-by: Sam James <sam <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index de6c0b2..5378184 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -728,7 +728,7 @@ jmake_src_compile() {
 Sometimes an eclass is used incorrectly by an ebuild and the eclass
 knows it is being used incorrectly <d/> the common example is an
 eclass that only works with a specific set of EAPIs, but is being
-accessed inherited by an ebuild with a different EAPI.
+accessed (inherited) by an ebuild with a different EAPI.
 In those cases, used sparingly as a last resort, it is allowed
 for an eclass to invoke die from the global scope.  For example:
 </p>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Sam James]

commit:     d26cb56cf88ca73b321ffa7f601d86ab682cc206
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Fri Mar 18 05:38:58 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Fri Mar 18 18:10:19 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d26cb56c

eclass-writing: Rework intro paragraph for jmake example

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Closes: https://github.com/gentoo/devmanual/pull/278
Signed-off-by: Sam James <sam <AT> gentoo.org>

 eclass-writing/text.xml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index f5bb88b..0e6ca99 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -667,9 +667,10 @@ src_compile() {
 <body>
 
 <p>
-A simple eclass which defines a number of functions and default <c>src_confgure</c> and
-<c>src_compile</c> for the (hypothetical) <c>jmake</c> build system might look
-something like the following:
+Here is an example of how a simple eclass for a hypothetical <c>jmake</c> build
+system might look. The eclass defines a few functions, along with default
+implementations for the <c>src_configure</c> and <c>src_compile</c> phase
+functions.
 </p>
 
 <codesample lang="ebuild">

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Sam James]

commit:     3214de4c965e8bc94c7f14f7f0d52c117df7a3cd
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Wed Mar 16 14:12:36 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Fri Mar 18 18:10:17 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3214de4c

eclass-writing: Add default src_configure to jmake example

The jmake sample eclass was written before EAPI 2 and thus predates
src_configure() where configuration and compilation where both handled
in src_compile().

Now it makes sense to have a separate jmake_src_configure() that is used
as the default src_configure().

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Signed-off-by: Sam James <sam <AT> gentoo.org>

 eclass-writing/text.xml | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 5378184..f5bb88b 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -667,7 +667,7 @@ src_compile() {
 <body>
 
 <p>
-A simple eclass which defines a number of functions and a default
+A simple eclass which defines a number of functions and default <c>src_confgure</c> and
 <c>src_compile</c> for the (hypothetical) <c>jmake</c> build system might look
 something like the following:
 </p>
@@ -684,9 +684,10 @@ something like the following:
 # @BLURB: Demonstrate a simple build system eclass.
 # @DESCRIPTION:
 # Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the
-# (hypothetical) jmake build system and a default src_compile.
+# (hypothetical) jmake build system along with default src_configure and
+# src_compile phase functions
 
-EXPORT_FUNCTIONS src_compile
+EXPORT_FUNCTIONS src_configure src_compile
 
 BDEPEND="&gt;=sys-devel/jmake-2"
 
@@ -699,6 +700,15 @@ jmake-configure() {
 	jmake configure --prefix=/usr "$@"
 }
 
+# @FUNCTION: jmake_src_configure
+# @USAGE: [additional-args]
+# @DESCRIPTION:
+# Calls jmake-configure() to configure a jmake project. Passes all arguments
+# through to the appropriate "jmake configure" command.
+jmake_src_configure() {
+	jmake-configure "$@" || die "configure failed"
+}
+
 # @FUNCTION: jmake-build
 # @USAGE: [additional-args]
 # @DESCRIPTION:
@@ -710,9 +720,8 @@ jmake-build() {
 
 # @FUNCTION: jmake_src_compile
 # @DESCRIPTION:
-# Calls jmake-configure() and jmake-build() to compile a jmake project.
+# Calls jmake-build() to compile a jmake project.
 jmake_src_compile() {
-	jmake-configure || die "configure failed"
 	jmake-build || die "build failed"
 }
 </codesample>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     3dfa91c478c62400e5849158679bb2e91db7d4da
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Fri Mar 18 19:54:32 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Mar 20 13:46:52 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3dfa91c4

eclass-writing: Use "required" instead of "not optional"

When figuring out if a documentation tag is required, the reader must
mentally handle "not optional" as "required". Simplify by changing the
"optional?" column to "required?".

Let us also stop shouting at the reader, so change "YES" and "NO" to
"Yes" and "No".

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 82 ++++++++++++++++++++++++-------------------------
 1 file changed, 41 insertions(+), 41 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 0e6ca99..795ccd0 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -197,13 +197,13 @@ summarizes the available documentation tags:
 <table>
 <tr>
   <th>tag</th>
-  <th>optional?</th>
+  <th>required?</th>
   <th>arguments</th>
   <th>description</th>
 </tr>
 <tr>
   <ti><c>@ECLASS:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Name of the eclass being documented</ti>
   <ti>
     Documents various information about the eclass. Must appear as the
@@ -212,7 +212,7 @@ summarizes the available documentation tags:
 </tr>
 <tr>
   <ti><c>@MAINTAINER:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>One or more name and email pairs</ti>
   <ti>
     List of maintainers for the eclass to be contacted. One line per
@@ -221,7 +221,7 @@ summarizes the available documentation tags:
 </tr>
 <tr>
   <ti><c>@AUTHOR:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>One or more name and email pairs</ti>
   <ti>
     List of authors for the eclass. One line per author. Must start on
@@ -230,25 +230,25 @@ summarizes the available documentation tags:
 </tr>
 <tr>
   <ti><c>@BUGREPORTS:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Multiline freetext</ti>
   <ti>Describes how bugs related to this eclass should be reported</ti>
 </tr>
 <tr>
   <ti><c>@VCSURL:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>A URI string</ti>
   <ti>Points to the URL of the VCS that contains the eclass source</ti>
 </tr>
 <tr>
   <ti nowrap="nowrap"><c>@SUPPORTED_EAPIS:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Space-separated list of EAPIs</ti>
   <ti>List of EAPIs supported by this eclass</ti>
 </tr>
 <tr>
   <ti><c>@PROVIDES:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Space-separated list of eclass names</ti>
   <ti>
     List of indirectly inherited eclasses whose functions and variables may be
@@ -257,7 +257,7 @@ summarizes the available documentation tags:
 </tr>
 <tr>
   <ti><c>@BLURB:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Single line freetext</ti>
   <ti>
     Contains a short description for the eclass. Must be on the same
@@ -266,19 +266,19 @@ summarizes the available documentation tags:
 </tr>
 <tr>
   <ti><c>@DEPRECATED:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Replacement (or "none")</ti>
   <ti>Declares that this eclass should no longer be used</ti>
 </tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Multiline freetext</ti>
   <ti>Long description for the eclass</ti>
 </tr>
 <tr>
   <ti><c>@EXAMPLE:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Multiline freetext</ti>
   <ti>Examples that illustrate various uses of this eclass</ti>
 </tr>
@@ -306,13 +306,13 @@ variables are as follows:
 <table>
 <tr>
   <th>tag</th>
-  <th>optional?</th>
+  <th>required?</th>
   <th>arguments</th>
   <th>description</th>
 </tr>
 <tr>
   <ti nowrap="nowrap"><c>@ECLASS-VARIABLE:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Name of the eclass variable to which the documentation applies</ti>
   <ti>
     This tag applies to eclass specific variables that affect the
@@ -323,7 +323,7 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@PRE_INHERIT</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     This tag describes whether the variable must be defined before
@@ -333,7 +333,7 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@USER_VARIABLE</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     This tag describes whether the variable is unsuitable for use in ebuilds,
@@ -343,7 +343,7 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@OUTPUT_VARIABLE</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     This tag indicates that the variable's value (which will be set by the
@@ -352,7 +352,7 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@DEFAULT_UNSET</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
@@ -361,7 +361,7 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     Indicates that the variable is a path which has ${EPREFIX} prepended to it
@@ -369,25 +369,25 @@ variables are as follows:
 </tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>Indicates that the variable is internal to the eclass</ti>
 </tr>
 <tr>
   <ti><c>@REQUIRED</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Optionally, the name of any replacement variable</ti>
   <ti>Declares that this variable should no longer be used in ebuilds</ti>
 </tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Multiline freetext</ti>
   <ti>Long description for the eclass variable</ti>
 </tr>
@@ -414,13 +414,13 @@ documentation are:
 <table>
 <tr>
   <th>tag</th>
-  <th>optional?</th>
+  <th>required?</th>
   <th>arguments</th>
   <th>description</th>
 </tr>
 <tr>
   <ti><c>@FUNCTION:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Name of the function to which the documentation block applies</ti>
   <ti>
     Documents information about an eclass function such as its calling
@@ -429,7 +429,7 @@ documentation are:
 </tr>
 <tr>
   <ti><c>@USAGE:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>List of required and optional arguments to the function</ti>
   <ti>
     List of arguments that the eclass function accepts, specified in
@@ -443,12 +443,12 @@ documentation are:
   <ti>Return value of the function</ti>
   <ti>
     <p>Description for the value returned by the function.</p>
-    <p><b>*</b>: Not optional for functions that return a value.</p>
+    <p><b>*</b>: Required for functions that return a value.</p>
   </ti>
 </tr>
 <tr>
   <ti><c>@MAINTAINER:</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Multiline freetext</ti>
   <ti>
     List of contacts for the eclass function. One line per
@@ -457,7 +457,7 @@ documentation are:
 </tr>
 <tr>
   <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     Indicates whether the function returns a path with ${EPREFIX} prepended
@@ -466,7 +466,7 @@ documentation are:
 </tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     Indicates that the function is internal to the eclass and should
@@ -475,7 +475,7 @@ documentation are:
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Optionally, the name of a replacement function</ti>
   <ti>Declares that this function should no longer be used in ebuilds</ti>
 </tr>
@@ -485,7 +485,7 @@ documentation are:
   <ti>Multiline freetext</ti>
   <ti>
     <p>Long description for the eclass function.</p>
-    <p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p>
+    <p><b>*:</b> Required if <c>RETURN:</c> is absent.</p>
   </ti>
 </tr>
 </table>
@@ -505,13 +505,13 @@ using the following tags:
 <table>
 <tr>
   <th>tag</th>
-  <th>optional?</th>
+  <th>required?</th>
   <th>arguments</th>
   <th>description</th>
 </tr>
 <tr>
   <ti><c>@VARIABLE:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>
     Name of the function-specific variable to which the documentation applies
   </ti>
@@ -523,7 +523,7 @@ using the following tags:
 </tr>
 <tr>
   <ti><c>@USER_VARIABLE</c></ti>
-   <ti>YES</ti>
+   <ti>No</ti>
    <ti><d/></ti>
    <ti>
      This tag describes whether the variable is unsuitable for use in ebuilds,
@@ -533,7 +533,7 @@ using the following tags:
 </tr>
 <tr>
   <ti><c>@DEFAULT_UNSET</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>
     Indicates that this variable is unset by default if not set by the
@@ -542,31 +542,31 @@ using the following tags:
 </tr>
 <tr>
   <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>Indicates that the variable is a path which has ${EPREFIX} prepended</ti>
 </tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>Indicates that the variable is internal to the eclass function</ti>
 </tr>
 <tr>
   <ti><c>@REQUIRED</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti><d/></ti>
   <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
   <ti><c>@DEPRECATED</c></ti>
-  <ti>YES</ti>
+  <ti>No</ti>
   <ti>Optionally, the name of any replacement variable</ti>
   <ti>Declares that this variable should no longer be used in ebuilds</ti>
 </tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
-  <ti>NO</ti>
+  <ti>Yes</ti>
   <ti>Multiline freetext</ti>
   <ti>Long description for the function variable</ti>
 </tr>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     108416f08c8e241b57c05ab4dbce6212eb2a6d87
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Mar 17 11:28:33 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Mar 23 14:06:36 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=108416f0

eclass-writing: @ECLASS-VARIABLE renamed to @ECLASS_VARIABLE

Bug: https://bugs.gentoo.org/835396
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 795ccd0..be57372 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -311,7 +311,7 @@ variables are as follows:
   <th>description</th>
 </tr>
 <tr>
-  <ti nowrap="nowrap"><c>@ECLASS-VARIABLE:</c></ti>
+  <ti nowrap="nowrap"><c>@ECLASS_VARIABLE:</c></ti>
   <ti>Yes</ti>
   <ti>Name of the eclass variable to which the documentation applies</ti>
   <ti>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     e45f656f8c5b18c258c14ff0da08ffc37f2c9c23
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Mar 26 16:14:58 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Mar 26 16:14:58 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e45f656f

eclass-writing: @DEPRECATED must be followed by a colon

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index be57372..f0f03c0 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -138,7 +138,7 @@ adhere to the following process:</p>
 </ol>
 
 <note>
-Before considering removal, please mark the eclass as <c># @DEPRECATED</c>
+Before considering removal, please mark the eclass as <c># @DEPRECATED:</c>
 to ensure consumers are warned if they are still using the eclass. Do this
 for a period before removing the eclass.
 </note>
@@ -380,7 +380,7 @@ variables are as follows:
   <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
-  <ti><c>@DEPRECATED</c></ti>
+  <ti><c>@DEPRECATED:</c></ti>
   <ti>No</ti>
   <ti>Optionally, the name of any replacement variable</ti>
   <ti>Declares that this variable should no longer be used in ebuilds</ti>
@@ -474,7 +474,7 @@ documentation are:
   </ti>
 </tr>
 <tr>
-  <ti><c>@DEPRECATED</c></ti>
+  <ti><c>@DEPRECATED:</c></ti>
   <ti>No</ti>
   <ti>Optionally, the name of a replacement function</ti>
   <ti>Declares that this function should no longer be used in ebuilds</ti>
@@ -559,7 +559,7 @@ using the following tags:
   <ti>Indicates that this variable must be set by the developer</ti>
 </tr>
 <tr>
-  <ti><c>@DEPRECATED</c></ti>
+  <ti><c>@DEPRECATED:</c></ti>
   <ti>No</ti>
   <ti>Optionally, the name of any replacement variable</ti>
   <ti>Declares that this variable should no longer be used in ebuilds</ti>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     be55691ed16c2ab4dd7c3d635fc2bd67ecd6b563
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Fri Apr 15 21:42:03 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Apr 24 12:51:53 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=be55691e

eclass-writing: doc inherit guards, EXPORT_FUNCTIONS warning

Add a section to explain what inherit guards are and their usage, and
add a "rule of thumb" to put EXPORT_FUNCTIONS at the end of eclasses for
max portability.

This turned into a larger re-ordering of the sections so the full jmake
example can showcase all the features discussed in the preceding
sections, like EAPI guard, inherit guard, and EXPORT_FUNCTIONS at the
very end.

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 156 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 122 insertions(+), 34 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index f0f03c0..22b973f 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -638,11 +638,11 @@ eclass-defined defaults <d/> for example, say we had <c>fnord.eclass</c>:
 </p>
 
 <codesample lang="ebuild">
-EXPORT_FUNCTIONS src_compile
-
 fnord_src_compile() {
 	do_stuff || die
 }
+
+EXPORT_FUNCTIONS src_compile
 </codesample>
 
 <p>
@@ -659,6 +659,115 @@ src_compile() {
 }
 </codesample>
 
+<p>
+Eclasses may inherit other eclasses to make use of their functionality, and
+historically there have been instances of eclasses calling
+<c>EXPORT_FUNCTIONS</c> and then inheriting another eclass. As inherited
+eclasses may also execute <c>EXPORT_FUNCTIONS</c>, it was not fully defined
+which defaults should take effect. The general recommendation is now that
+eclasses should not inherit other eclasses <e>after</e> calling
+<c>EXPORT_FUNCTIONS</c>.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Inherit guards</title>
+<body>
+
+<p>
+It is common practice to surround the main contents of an eclass with an
+"inherit guard". Much like header guards known from C, inherit guards help
+ensure that an eclass can be inherited multiple times and have its functions and
+variables defined only once. An inherit guard is only needed for an eclass that
+can be inherited more than once.
+</p>
+
+<p>
+A typical inherit guard looks as follows (for a hypothetical <c>foo.eclass</c>):
+</p>
+
+<codesample lang="ebuild">
+if [[ -z ${_FOO_ECLASS} ]]; then
+_FOO_ECLASS=1
+
+# Variables and functions go here
+
+fi
+</codesample>
+
+<p>
+When it comes to <c>EXPORT_FUNCTIONS</c> and inherit guards, the call to
+<c>EXPORT_FUNCTIONS</c> must be placed at the very end of the eclass
+<e>outside</e> any inherit guards, like this:
+</p>
+
+<codesample lang="ebuild">
+if [[ -z ${_FOO_ECLASS} ]]; then
+_FOO_ECLASS=1
+
+foo_src_compile() {
+	...
+}
+fi
+
+EXPORT_FUNCTIONS src_compile
+</codesample>
+
+<p>
+This helps to ensure that the last inherited eclass gets to define the default
+phase functions. Consider two eclasses <c>foo.eclass</c> and <c>bar.eclass</c>
+that define the same default phase function via <c>EXPORT_FUNCTIONS</c>. If an
+ebuild inherits both as <c>inherit foo bar</c>, then the default phases are
+defined by <c>bar.eclass</c>. If <c>foo.eclass</c> is then modified to inherit
+<c>bar</c> as well, then the ebuild's default functions could suddenly become
+those from <c>foo</c> if <c>EXPORT_FUNCTIONS</c> was placed inside the inherit
+guard.
+</p>
+
+<note>
+The rule of thumb here is: put the call (if any) to <c>EXPORT_FUNCTIONS</c> in
+the last line of an eclass, outside of any inherit guards.
+</note>
+
+<warning>
+Old eclasses may put <c>EXPORT_FUNCTIONS</c> in other places, even before
+<c>inherit</c>. They should <e>not</e> blindly be updated to follow the
+recommended pattern here, as it could result in significant breakage.
+</warning>
+
+</body>
+</section>
+
+<section>
+<title>Handling incorrect usage of an eclass</title>
+<body>
+
+<p>
+Sometimes an eclass is used incorrectly by an ebuild and the eclass
+knows it is being used incorrectly <d/> the common example is an
+eclass that only works with a specific set of EAPIs, but is being
+accessed (inherited) by an ebuild with a different EAPI.
+In those cases, used sparingly as a last resort, it is allowed
+for an eclass to invoke die from the global scope.  For example:
+</p>
+
+<codesample lang="ebuild">
+# Copyright 1999-2022 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: eapi-die.eclass
+# @MAINTAINER:
+# Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
+# @SUPPORTED_EAPIS: 7 8
+# @BLURB: Calls die when used with an invalid EAPI.
+
+case ${EAPI} in
+	7|8) ;;
+	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
+esac
+</codesample>
 </body>
 </section>
 
@@ -674,7 +783,7 @@ functions.
 </p>
 
 <codesample lang="ebuild">
-# Copyright 1999-2021 Gentoo Authors
+# Copyright 1999-2022 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: jmake.eclass
@@ -688,7 +797,13 @@ functions.
 # (hypothetical) jmake build system along with default src_configure and
 # src_compile phase functions
 
-EXPORT_FUNCTIONS src_configure src_compile
+case ${EAPI} in
+	7|8) ;;
+	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
+esac
+
+if [[ -z ${_JMAKE_ECLASS} ]]; then
+_JMAKE_ECLASS=1
 
 BDEPEND="&gt;=sys-devel/jmake-2"
 
@@ -725,40 +840,13 @@ jmake-build() {
 jmake_src_compile() {
 	jmake-build || die "build failed"
 }
+fi
+
+EXPORT_FUNCTIONS src_configure src_compile
 </codesample>
 
 </body>
 </section>
 
-<section>
-<title>Handling incorrect usage of an eclass</title>
-<body>
-
-<p>
-Sometimes an eclass is used incorrectly by an ebuild and the eclass
-knows it is being used incorrectly <d/> the common example is an
-eclass that only works with a specific set of EAPIs, but is being
-accessed (inherited) by an ebuild with a different EAPI.
-In those cases, used sparingly as a last resort, it is allowed
-for an eclass to invoke die from the global scope.  For example:
-</p>
-
-<codesample lang="ebuild">
-# Copyright 1999-2021 Gentoo Authors
-# Distributed under the terms of the GNU General Public License v2
-
-# @ECLASS: eapi-die.eclass
-# @MAINTAINER:
-# Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
-# @SUPPORTED_EAPIS: 7 8
-# @BLURB: Calls die when used with an invalid EAPI.
-
-case ${EAPI} in
-	7|8) ;;
-	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
-esac
-</codesample>
-</body>
-</section>
 </chapter>
 </guide>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     f219b1c2f633f5f3bc00b02d1237c3cc345f7f26
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Apr 26 08:18:43 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Apr 26 08:18:43 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f219b1c2

eclass-writing: Sentence ends should be followed by two spaces

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 22b973f..8c83dc2 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -172,6 +172,12 @@ in the tree or <c>pkgcheck scan --commits</c> to check for issues
 in your staged git commits.
 </p>
 
+<note>
+In eclass documentation, two spaces should be used after the end of each
+sentence (unless it is followed by a newline). This will help <c>groff</c>
+to properly break lines when generating eclass manpages.
+</note>
+
 </body>
 </section>
 
@@ -597,9 +603,9 @@ a single function, <c>domacosapp</c>.
 # @FUNCTION: domacosapp
 # @USAGE: &lt;app-file&gt; [new-file]
 # @DESCRIPTION:
-# Install the given .app file into the appropriate location. If
+# Install the given .app file into the appropriate location.  If
 # [new-file] is given, it will be used as the new (installed) name of
-# the file. Otherwise &lt;app-file&gt; is installed as-is.
+# the file.  Otherwise &lt;app-file&gt; is installed as-is.
 domacosapp() {
 	[[ -z "${1}" ]] &amp;&amp; die "usage: domacosapp &lt;file&gt; [new file]"
 	if use ppc-macos ; then

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     b99e3d57965f00401a37041564a029d96ec788b2
Author:     Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Sat Apr 30 11:32:28 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Apr 30 16:58:44 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b99e3d57

eclass-writing: minor edits to jmake example

Double space after full stop. Add full stop to sentence.

Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
[Wrap paragraph at column 72.]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 8c83dc2..9f5fbdf 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -801,7 +801,7 @@ functions.
 # @DESCRIPTION:
 # Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the
 # (hypothetical) jmake build system along with default src_configure and
-# src_compile phase functions
+# src_compile phase functions.
 
 case ${EAPI} in
 	7|8) ;;
@@ -825,8 +825,8 @@ jmake-configure() {
 # @FUNCTION: jmake_src_configure
 # @USAGE: [additional-args]
 # @DESCRIPTION:
-# Calls jmake-configure() to configure a jmake project. Passes all arguments
-# through to the appropriate "jmake configure" command.
+# Calls jmake-configure() to configure a jmake project.  Passes all
+# arguments through to the appropriate "jmake configure" command.
 jmake_src_configure() {
 	jmake-configure "$@" || die "configure failed"
 }

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     fb4c29d6e107495edb942dfca69ca7d36310a2ad
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat May 27 18:49:17 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat May 27 18:49:17 2023 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fb4c29d6

eclass-writing: Drop INCLUDES_EPREFIX documentation tag

This reflects its being dropped from eclass-to-manpage.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 23 -----------------------
 1 file changed, 23 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 7b2a3d2..ef58547 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -365,14 +365,6 @@ variables are as follows:
     developer
   </ti>
 </tr>
-<tr>
-  <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>No</ti>
-  <ti><d/></ti>
-  <ti>
-    Indicates that the variable is a path which has ${EPREFIX} prepended to it
-  </ti>
-</tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
   <ti>No</ti>
@@ -461,15 +453,6 @@ documentation are:
     maintainer. Must start on a newline after the tag.
   </ti>
 </tr>
-<tr>
-  <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>No</ti>
-  <ti><d/></ti>
-  <ti>
-    Indicates whether the function returns a path with ${EPREFIX} prepended
-    to it
-  </ti>
-</tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
   <ti>No</ti>
@@ -546,12 +529,6 @@ using the following tags:
     developer
   </ti>
 </tr>
-<tr>
-  <ti><c>@INCLUDES_EPREFIX</c></ti>
-  <ti>No</ti>
-  <ti><d/></ti>
-  <ti>Indicates that the variable is a path which has ${EPREFIX} prepended</ti>
-</tr>
 <tr>
   <ti><c>@INTERNAL</c></ti>
   <ti>No</ti>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     84304f7b8fa1706c6aa046cb84be4fa33c46d9f8
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Jun 30 09:24:14 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Aug 26 05:29:02 2023 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=84304f7b

eclass-writing: Use underscores for function names in the example

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index ef58547..2b3033e 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -795,34 +795,35 @@ BDEPEND="&gt;=sys-devel/jmake-2"
 # @DESCRIPTION:
 # Passes all arguments through to the appropriate "jmake configure"
 # command.
-jmake-configure() {
+jmake_configure() {
 	jmake configure --prefix=/usr "$@"
 }
 
 # @FUNCTION: jmake_src_configure
 # @USAGE: [additional-args]
 # @DESCRIPTION:
-# Calls jmake-configure() to configure a jmake project.  Passes all
+# Calls jmake_configure() to configure a jmake project.  Passes all
 # arguments through to the appropriate "jmake configure" command.
 jmake_src_configure() {
-	jmake-configure "$@" || die "configure failed"
+	jmake_configure "$@" || die "configure failed"
 }
 
-# @FUNCTION: jmake-build
+# @FUNCTION: jmake_build
 # @USAGE: [additional-args]
 # @DESCRIPTION:
 # First builds all dependencies, and then passes through its arguments
 # to the appropriate "jmake build" command.
-jmake-build() {
+jmake_build() {
 	jmake dep &amp;&amp; jmake build "$@"
 }
 
 # @FUNCTION: jmake_src_compile
 # @DESCRIPTION:
-# Calls jmake-build() to compile a jmake project.
+# Calls jmake_build() to compile a jmake project.
 jmake_src_compile() {
-	jmake-build || die "build failed"
+	jmake_build || die "build failed"
 }
+
 fi
 
 EXPORT_FUNCTIONS src_configure src_compile

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     e3e5476cab5c6a5a54032b621ef58059d4371c73
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 14 19:24:57 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Jan 14 19:24:57 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e3e5476c

eclass-writing: @USAGE is not required

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 2504c8c..23c7219 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -428,7 +428,7 @@ documentation are:
 </tr>
 <tr>
   <ti><c>@USAGE:</c></ti>
-  <ti>Yes</ti>
+  <ti>No</ti>
   <ti>List of required and optional arguments to the function</ti>
   <ti>
     List of arguments that the eclass function accepts, specified in

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     924469d9fa9cc1b84073e0cbcab6199cfb013730
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Apr 24 14:13:01 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr 24 14:13:01 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=924469d9

eclass-writing: Formatting fixes

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index cae3353..6575fcb 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -2,8 +2,8 @@
 <guide self="eclass-writing/">
 <chapter>
 <title>Eclass Writing Guide</title>
-
 <body>
+
 <p>
 This section provides a brief introduction to eclass authoring.
 </p>
@@ -102,7 +102,6 @@ it is good etiquette to ping other developers in e.g. <c>#gentoo-dev</c>
 on IRC or informally determine if there are other similar changes (mainly
 documentation) which should be pushed at the same time in order to avoid
 unnecessary cache regeneration within a few hours or days of each other.
-
 The same applies to your own work <d/> please prepare all of your commits and
 batch push them at once where possible.
 </note>
@@ -114,8 +113,10 @@ batch push them at once where possible.
 <title>Removing Eclasses</title>
 <body>
 
-<p>No longer used eclasses may be removed from the tree, but developers must
-adhere to the following process:</p>
+<p>
+No longer used eclasses may be removed from the tree, but developers must
+adhere to the following process:
+</p>
 
 <ol>
   <li>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     064e969676cf9ce8774a347e05ba35e025952afa
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Apr 24 14:09:50 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr 24 14:09:50 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=064e9696

Revert "eclass-writing: @DEAD must be the first tag"

eclass-to-manpages is now less strict about placement of the tag.

This reverts commit cd392d0c6cd064ac3a1381111e678f4fe111afcc.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 23c7219..2a6203f 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -129,9 +129,7 @@ adhere to the following process:</p>
   </li>
   <li>
     Add a one line comment to the eclass, saying exactly <c># @DEAD</c> so that
-    the eclass-manpages package will not attempt to document it. <c>@DEAD</c>
-    must be the first documentation tag in the eclass, i.e. it goes before
-    the <c>@ECLASS</c> tag.
+    the eclass-manpages package will not attempt to document it.
   </li>
   <li>
     Wait for the 30-day period to pass, then remove the eclass from the tree.

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     46eaf0892fe93c3d989f944dc6077fea44a5cee2
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Apr 24 14:12:21 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr 24 14:12:21 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=46eaf089

eclass-writing: Add @DEAD tag to table

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 2a6203f..cae3353 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -275,6 +275,15 @@ summarizes the available documentation tags:
   <ti>Replacement (or "none")</ti>
   <ti>Declares that this eclass should no longer be used</ti>
 </tr>
+<tr>
+  <ti><c>@DEAD</c></ti>
+  <ti>No</ti>
+  <ti><d/></ti>
+  <ti>
+    For an eclass that is slated for removal; prevents the eclass-manpages
+    package from documenting the eclass.
+  </ti>
+</tr>
 <tr>
   <ti><c>@DESCRIPTION:</c></ti>
   <ti>No</ti>

[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

[Ulrich Müller]

commit:     67a5bddbd0f99a6e82871738368d6f917ed7c017
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Apr 24 16:09:52 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr 24 16:09:52 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=67a5bddb

eclass-writing: Some updates from patch review

Suggested by mjo and sam.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 6575fcb..a8d373a 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -114,8 +114,8 @@ batch push them at once where possible.
 <body>
 
 <p>
-No longer used eclasses may be removed from the tree, but developers must
-adhere to the following process:
+Eclasses that are no longer in use may be removed from the tree, but developers
+must adhere to the following process:
 </p>
 
 <ol>
@@ -139,8 +139,8 @@ adhere to the following process:
 
 <note>
 Before considering removal, please mark the eclass as <c># @DEPRECATED:</c>
-to ensure consumers are warned if they are still using the eclass. Do this
-for a period before removing the eclass.
+to ensure consumers are warned if they are still using the eclass. Do this at
+least 30 days before removing the eclass.
 </note>
 
 </body>