From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id A4FBC13800E for ; Thu, 26 Jul 2012 19:05:58 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id B8A03E07DD; Thu, 26 Jul 2012 19:05:50 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 768EFE07DD for ; Thu, 26 Jul 2012 19:05:50 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id ACB7B1B412F for ; Thu, 26 Jul 2012 19:05:49 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id 6D45BE543E for ; Thu, 26 Jul 2012 19:05:48 +0000 (UTC) From: "Ulrich Mueller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Mueller" Message-ID: <1343329862.d99d0fe7c4fef5b541604020642255de291e4dbd.ulm@gentoo> Subject: [gentoo-commits] proj/pms:master commit in: / X-VCS-Repository: proj/pms X-VCS-Files: ebuild-vars.tex X-VCS-Directories: / X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Mueller X-VCS-Revision: d99d0fe7c4fef5b541604020642255de291e4dbd X-VCS-Branch: master Date: Thu, 26 Jul 2012 19:05:48 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: f6f31154-2cf1-4f29-b3b5-808d591b7a02 X-Archives-Hash: 4224bbeedda68c8033760d38e261943c commit: d99d0fe7c4fef5b541604020642255de291e4dbd Author: Ulrich Müller gentoo org> AuthorDate: Fri Jul 20 21:12:24 2012 +0000 Commit: Ulrich Mueller gentoo org> CommitDate: Thu Jul 26 19:11:02 2012 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=commit;h=d99d0fe7 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 | 92 +++++++++++++++++++++++++++--------------------------- 1 files changed, 46 insertions(+), 46 deletions(-) diff --git a/ebuild-vars.tex b/ebuild-vars.tex index 29b9dfa..1dadc35 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -4,6 +4,10 @@ \note This section describes variables that may or must be defined by ebuilds. For variables that are passed from the package manager to the ebuild, see section~\ref{sec:ebuild-env-vars}. +If any of these variables are set to invalid values, or if any of the mandatory variables are +undefined, the package manager's behaviour is undefined; ideally, an error in one ebuild should not +prevent operations upon other ebuilds or packages. + \section{Metadata invariance} \label{sec:metadata-invariance} @@ -23,10 +27,32 @@ 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 +\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. +\end{description} + +\section{Optional Ebuild-defined Variables} + +Ebuilds may define any of the following variables: + +\begin{description} +\item[EAPI] The EAPI. See below. +\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. @@ -34,26 +60,24 @@ All ebuilds must define at least the following variables: \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. +\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} -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 @@ -69,30 +93,6 @@ operations upon other ebuilds or packages. \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[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}. -\end{description} - \begin{centertable}{EAPIs supporting various ebuild-defined variables} \label{tab:optional-vars-table} \begin{tabular}{ l l l }