From 84b9b5c2aea408b9e490b352885891bb3875714d Mon Sep 17 00:00:00 2001 From: Daniel Robbins Date: Sun, 29 Sep 2019 14:50:18 -0700 Subject: man/ebuild.5: Improvements to the ebuild(5) man page The following patch contains several formatting improvements, as well as extended information about KEYWORDS that is easier to understand. The original description started describing Gentoo policy on KEYWORDS without actually explaining what they are and how they work. I have also added missing documentation for the ARCH variable as this was sort of shoe-horned in to the KEYWORDS documentation, and tried to make it clearer what is a technical requirement of Portage the software and what are Gentoo-specific arch team requirements. Bug: https://bugs.gentoo.org/695870 Signed-off-by: Zac Medico --- man/ebuild.5 | 160 +++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 116 insertions(+), 44 deletions(-) diff --git a/man/ebuild.5 b/man/ebuild.5 index b002f3889..e955907f7 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -17,9 +17,10 @@ calculating relationships between packages. Please note that if the atom has not already been emerged, then the latest version available is matched. .TP .B Atom Bases -The base atom is just a full category/packagename. +The base atom is just a full category/packagename. Another name for a full +category/packagename is a \fI"catpkg"\fR. You will find this shorthand\-name +used frequently in Gentoo. Here are some base atoms, a.k.a \fI"catpkgs"\fR: -Examples: .nf .I sys\-apps/sed .I sys\-libs/zlib @@ -31,7 +32,7 @@ It is nice to be more specific and say that only certain versions of atoms are acceptable. Note that versions must be combined with a prefix (see below). Hence you may add a version number as a postfix to the base. -Examples: +\fBExamples\fR: .nf sys\-apps/sed\fI\-4.0.5\fR sys\-libs/zlib\fI\-1.1.4\-r1\fR @@ -51,7 +52,7 @@ Sometimes you want to be able to depend on general versions rather than specifying exact versions all the time. Hence we provide standard boolean operators: -Examples: +\fBExamples\fR: .nf \fI>\fRmedia\-libs/libgd\-1.6 \fI>=\fRmedia\-libs/libgd\-1.6 @@ -71,7 +72,7 @@ means match any revision of the base version specified. So in the example below, we would match versions '1.0.2a', '1.0.2a\-r1', '1.0.2a\-r2', etc... -Example: +\fBExample\fR: .nf \fI~\fRnet\-libs/libnet\-1.0.2a .fi @@ -79,7 +80,7 @@ Example: .I ! means block packages from being installed at the same time. -Example: +\fBExample\fR: .nf \fI!\fRapp\-text/dos2unix .fi @@ -90,7 +91,7 @@ and explicitly disallow them from being temporarily installed simultaneously during a series of upgrades. This syntax is supported beginning with \fBEAPI 2\fR. -Example: +\fBExample\fR: .nf \fI!!\fR $P=='xfree\-4.2.1' +\fBExample\fR: +.nf + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base/xorg\-server\-1.20.5\fR' +.fi .TP .B PN Contains the name of the script without the version number. -xfree\-4.2.1\-r2.ebuild \-\-> $PN=='xfree' +\fBExample\fR: +.nf + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base/xorg\-server\fR' +.fi .TP .B PV Contains the version number without the revision. -xfree\-4.2.1\-r2.ebuild \-\-> $PV=='4.2.1' +\fBExample\fR: +.nf + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fI1.20.5\fR' +.fi .TP .B PR Contains the revision number or 'r0' if no revision number exists. -xfree\-4.2.1\-r2.ebuild \-\-> $PR=='r2' +\fBExample\fR: +.nf + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIr2\fR' +.fi .TP .B PVR Contains the version number with the revision (if non-zero). +\fBExample\fR: .nf -xfree\-4.2.1.ebuild \-\-> $PVR=='4.2.1' -xfree\-4.2.1\-r2.ebuild \-\-> $PVR=='4.2.1\-r2' + x11\-base/xorg\-server\-1.20.5 \-\-> '\fI1.20.5\fR' + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fI1.20.5\-r2\fR' .fi .TP .B PF Contains the full package name \fBPN\fR\-\fBPVR\fR +\fBExamples\fR: .nf -xfree\-4.2.1.ebuild \-\-> $PF=='xfree\-4.2.1' -xfree\-4.2.1\-r2.ebuild \-\-> $PF=='xfree\-4.2.1\-r2' + x11\-base/xorg\-server\-1.20.5 \-\-> '\fIxorg\-server\-1.20.5\fR' + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIxorg\-server\-1.20.5\-r2\fR' .fi .TP .B CATEGORY Contains the package category name. + +\fBExample\fR: +.nf + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base\fR' +.fi .TP .B A Contains all source files required for the package. This variable must @@ -543,17 +571,61 @@ file name, should be separated by whitespace. Should contain a list of URIs for the sources main sites and other further package dependent information. .TP -.B KEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa] -Should contain appropriate list of arches that the ebuild is know to -work/not work. By default if you do not know if an ebuild runs under -a particular arch simply omit that KEYWORD. If the ebuild will not -work on that arch include it as \-ppc for example. If the ebuild is -being submitted for inclusion, it must have ~arch set for architectures -where it has been PROVEN TO WORK. (Packages KEYWORDed this way may be -unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command -line, or in \fBmake.conf\fR(5)) For an authoritative list please review -/var/db/repos/gentoo/profiles/arch.list. Please keep this list in -alphabetical order. +.B KEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa,...] +.P + +KEYWORDS works in conjunction with ACCEPT_KEYWORDS (see \fBmake.conf\fR(5)) +to implement a system of creating sets of different types of packages +which can then be masked or unmasked en masse. In the Gentoo Linux +project, they are used by the Gentoo arch teams to define what ebuilds +are included in a particular CPU architecture's set of stable and unstable +unmasked packages. + +Here's how they work. For purposes of explanation, let's assume you have +a stable x86\-64bit system, typically referred to as "amd64". +ARCH would be defined as "amd64". If you were using the stable build of +Gentoo Linux, then ACCEPT_KEYWORDS would be set to "amd64" via profiles. +Any ebuild that then has +"amd64" in KEYWORDS will be unmasked by default. + +On an "unstable" +amd64 system, ACCEPT_KEYWORDS will be set to "amd64 ~amd64", with the +tilde denoting "unstable." Then, if an ebuild has \fIeither\fR +"amd64" or "~amd64" in KEYWORDS, it will be keyword unmasked by default on +that system. Similarly, if an ebuild is known to not be compatible +with a particular architecture, the "\-" prefix ( i.e. "\-amd64") setting +can be specified to mask it only on that arch. +.P +If you are developing ebuilds for Gentoo Linux, there are certain +policies regarding KEYWORDS that you are expected to follow in order +to align with Gentoo's arch team workflow. The most important +policies are listed below: +.RS +.IP \(bu 2 +If you do not know if an ebuild runs under a particular arch, then do not +specify it in KEYWORDS. +It will then be masked by default on that architecture. +.IP \(bu +If the ebuild is known not to work on an arch, disable that arch in KEYWORDS. +This would be done by specifying "\-ppc", for example. This will ensure that +it is explicitly keyword\-masked for that architecture. +.IP \(bu +When submitting an ebuild to Gentoo Linux, it is the project policy to only +have "~arch" set in KEYWORDS +for the architecture for which it has been successfully tested, and no more. +As the ebuild receives more testing, Gentoo arch teams will gradually expand +the KEYWORDS settings to "bump" the package to unstable, and possibly stable. + +It is possible to customize the behavior of ACCEPT_KEYWORDS and KEYWORDS on +a per\-package basis using package.accept_keywords and package.keywords files +in profiles. See \fBportage\fR(5) for more information on using these files. +.RE +.P +Note that while other Gentoo\-based projects +have KEYWORDS and ACCEPT_KEYWORDS, they likely will not have exactly +the same policies regarding their use. Therefore, it is necessary that you +research their specific policies and how they differ from Gentoo. +.RE .TP .B SLOT This sets the SLOT for packages that may need to have multiple versions -- cgit v1.2.3