[gentoo-pms] Why do we have mandatory ebuild variables?

[gentoo-pms] Why do we have mandatory ebuild variables?

[Ulrich Mueller]

PMS says that seven variables (DESCRIPTION, HOMEPAGE, SRC_URI,
LICENSE, SLOT, KEYWORDS, IUSE) are mandatory in ebuilds. In bug 425848
and in #gentoo-portage the question arose why this is needed.
For example, many live ebuilds don't define SRC_URI or KEYWORDS, and
package managers seem to have no problem with it. (?)

Virtuals could profit if they wouldn't have to define variables like
HOMEPAGE, SRC_URI, and LICENSE that are meaningless for them.

Could we loosen this requirement for the variables that are allowed to
be empty (i.e. all except DESCRIPTION and SLOT), or would this cause
any trouble with package managers? For EAPI 5, or retroactively?

Ulrich

[gentoo-pms] Re: Why do we have mandatory ebuild variables?

[Ulrich Mueller]

>>>>> On Sun, 15 Jul 2012, Ulrich Mueller wrote:

> Could we loosen this requirement for the variables that are allowed to
> be empty (i.e. all except DESCRIPTION and SLOT), or would this cause
> any trouble with package managers? For EAPI 5, or retroactively?

No objections here, and only positive replies in gentoo-dev.
A patch is included below.

Ulrich


From 8505dd0cf7afd639e48bfe696148e6f820a853e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Fri, 20 Jul 2012 23:12:24 +0200
Subject: [PATCH] Some ebuild-defined variables are optional.

Move HOMEPAGE, SRC_URI, LICENSE, KEYWORDS, and IUSE from the mandatory
to the optional variables list. Sort variables in canonical order.
---
 ebuild-vars.tex |  100 +++++++++++++++++++++++++++---------------------------
 1 files changed, 50 insertions(+), 50 deletions(-)

diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 29b9dfa..ea4962b 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -23,76 +23,76 @@ All ebuilds must define at least the following variables:
 \begin{description}
 \item[DESCRIPTION] A short human-readable description of the package's purpose. May be defined by an
     eclass. Must not be empty.
-\item[HOMEPAGE] The URI or URIs for a package's homepage, including protocols. May be defined by an
-    eclass. See section~\ref{sec:dependencies} for full syntax.
-\item[IUSE] The \t{USE} flags used by the ebuild. Any eclass that works with \t{USE} flags
-    must also set \t{IUSE}, listing only the variables used by that eclass. The package manager is
-    responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on
-    which values must be listed this variable.
-
-    \featurelabel{iuse-defaults} In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting
-    \t{IUSE} defaults, any use flag name in \t{IUSE} may be prefixed by at most one of a plus or a
-    minus sign. If such a prefix is present, the package manager may use it as a suggestion as to
-    the default value of the use flag if no other configuration overrides it.
-\item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a
-    valid keyword name, as per section~\ref{sec:keyword-names}. May include \t{-*}, which
-    indicates that the package will only work on explicitly listed archs. May include \t{-arch},
-    which indicates that the package will not work on the specified arch. May be empty, which
-    indicates uncertain functionality on any architecture. May be defined in an eclass.
-\item[LICENSE] The package's license. Each text token must correspond to a tree ``licenses/'' entry
-    (see section~\ref{sec:licenses-dir}). See section~\ref{sec:dependencies} for full syntax.
-    May be defined by an eclass. \label{ebuild-var-LICENSE}
 \item[SLOT] The package's slot. Must be a valid slot name, as per section~\ref{sec:slot-names}. May
     be defined by an eclass. Must not be empty.
-\item[SRC\_URI] A list of source URIs for the package. Valid protocols are \t{http://},
-    \t{https://}, \t{ftp://} and \t{mirror://} (see section~\ref{sec:thirdpartymirrors} for mirror
-    behaviour). Fetch restricted packages may include URL parts consisting of just a filename.
-    May be defined by an eclass. See section~\ref{sec:dependencies} for full syntax.
 \end{description}
 
 If any of these variables are undefined, or if any of these variables are set to invalid values,
 the package manager's behaviour is undefined; ideally, an error in one ebuild should not prevent
 operations upon other ebuilds or packages.
 
-\begin{centertable}{EAPIs supporting \t{IUSE} defaults} \label{tab:iuse-defaults-table}
-    \begin{tabular}{ l l }
-        \toprule
-        \multicolumn{1}{c}{\textbf{EAPI}} &
-        \multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\
-        \midrule
-    \t{0} & No \\
-    \t{1} & Yes \\
-    \t{2} & Yes \\
-    \t{3} & Yes \\
-    \t{4} & Yes \\
-    \bottomrule
-    \end{tabular}
-\end{centertable}
-
 \section{Optional Ebuild-defined Variables}
 
 Ebuilds may define any of the following variables:
 
 \begin{description}
-\item[DEPEND] See section~\ref{sec:dependencies}.
 \item[EAPI] The EAPI. See below.
-\item[PDEPEND] See section~\ref{sec:dependencies}.
-\item[RDEPEND] See section~\ref{sec:dependencies}. For some EAPIs, \t{RDEPEND} has special behaviour
-    for its value if unset and when used with an eclass. See section~\ref{sec:rdepend-depend} for
-    details.
-\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}
-    for value meanings and section~\ref{sec:dependencies} for full syntax.
-\item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See
-    section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full
-    syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support,
-    ebuilds must not rely upon the package manager recognising or understanding this variable in
-    any way.
+\item[HOMEPAGE] The URI or URIs for a package's homepage, including protocols.
+    See section~\ref{sec:dependencies} for full syntax.
+\item[SRC\_URI] A list of source URIs for the package. Valid protocols are \t{http://},
+    \t{https://}, \t{ftp://} and \t{mirror://} (see section~\ref{sec:thirdpartymirrors} for mirror
+    behaviour). Fetch restricted packages may include URL parts consisting of just a filename.
+    See section~\ref{sec:dependencies} for full syntax.
+\item[LICENSE] The package's license. Each text token must correspond to a tree ``licenses/'' entry
+    (see section~\ref{sec:licenses-dir}). See section~\ref{sec:dependencies} for full syntax.
+    \label{ebuild-var-LICENSE}
+\item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a valid
+    keyword name, as per section~\ref{sec:keyword-names}. May include \t{-*}, which indicates that
+    the package will only work on explicitly listed archs. May include \t{-arch}, which indicates
+    that the package will not work on the specified arch. May be empty, which indicates uncertain
+    functionality on any architecture.
+\item[IUSE] The \t{USE} flags used by the ebuild. Any eclass that works with \t{USE} flags must
+    also set \t{IUSE}, listing only the variables used by that eclass. The package manager is
+    responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on
+    which values must be listed this variable.
+
+    \featurelabel{iuse-defaults} In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting
+    \t{IUSE} defaults, any use flag name in \t{IUSE} may be prefixed by at most one of a plus or a
+    minus sign. If such a prefix is present, the package manager may use it as a suggestion as to
+    the default value of the use flag if no other configuration overrides it.
 \item[REQUIRED\_USE] \featurelabel{required-use} Zero or more assertions that must be met by the
     configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use}
     for description and section~\ref{sec:dependencies} for full syntax. Only in EAPIs listed in
     table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED\_USE}.
+\item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package.
+    See section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full
+    syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support,
+    ebuilds must not rely upon the package manager recognising or understanding this variable in
+    any way.
+\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}
+    for value meanings and section~\ref{sec:dependencies} for full syntax.
+\item[DEPEND] See section~\ref{sec:dependencies}.
+\item[RDEPEND] See section~\ref{sec:dependencies}. For some EAPIs, \t{RDEPEND} has special behaviour
+    for its value if unset and when used with an eclass. See section~\ref{sec:rdepend-depend} for
+    details.
+\item[PDEPEND] See section~\ref{sec:dependencies}.
 \end{description}
 
+\begin{centertable}{EAPIs supporting \t{IUSE} defaults} \label{tab:iuse-defaults-table}
+    \begin{tabular}{ l l }
+        \toprule
+        \multicolumn{1}{c}{\textbf{EAPI}} &
+        \multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\
+        \midrule
+    \t{0} & No \\
+    \t{1} & Yes \\
+    \t{2} & Yes \\
+    \t{3} & Yes \\
+    \t{4} & Yes \\
+    \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \begin{centertable}{EAPIs supporting various ebuild-defined variables}
 \label{tab:optional-vars-table}
     \begin{tabular}{ l l l }
-- 
1.7.8.6