--- a/man/ebuild.5 +++ a/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,15 +72,15 @@ 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~\fRnet\-libs/libnet\-1.0.2a .fi .TP .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). -xfree\-4.2.1.ebuild \-\-> $PVR=='4.2.1' +\fBExample\fR: .nf -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 -xfree\-4.2.1.ebuild \-\-> $PF=='xfree\-4.2.1' +\fBExamples\fR: .nf -xfree\-4.2.1\-r2.ebuild \-\-> $PF=='xfree\-4.2.1\-r2' + x11\-base/xorg\-server\-1.20.5 \-\-> '\fIx11\-base/xorg\-server\-1.20.5\fR' + x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base/xorg\-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 @@ -521,17 +549,59 @@ 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: +.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. +.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 @@ -1425,7 +1495,7 @@ file and the file is installed as \fI[new filename]\fR. Beginning with \fBEAPI 5\fR, standard input is read when the first parameter is \- (a hyphen). -.SH "EXAMPLES" +.SH "Examples" .DS .nf # Copyright 1999\-2013 Gentoo Foundation