diff options
| author |   Mark Loeser <halcy0n@gentoo.org> | 2006-03-09 04:08:55 +0000 |
|---|---|---|
| committer | Mark Loeser <halcy0n@gentoo.org> | 2006-03-09 04:08:55 +0000 |
| commit | cfbf02d976a56cf1bcc398127bcd4976bdcd313f (patch) | |
| tree | 6ab0ec13f5a34b3868062bf0491addef3e6ea63d /keywording | |
| parent | Add profiles/ (diff) | |
| download | devmanual-cfbf02d976a56cf1bcc398127bcd4976bdcd313f.tar.gz devmanual-cfbf02d976a56cf1bcc398127bcd4976bdcd313f.tar.bz2 devmanual-cfbf02d976a56cf1bcc398127bcd4976bdcd313f.zip | |
Add the keywording page
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@17 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'keywording')
| -rw-r--r-- | keywording/text.xml | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/keywording/text.xml b/keywording/text.xml new file mode 100644 index 0000000..a7effc3 --- /dev/null +++ b/keywording/text.xml @@ -0,0 +1,297 @@ +<?xml version="1.0"?> +<guide self="keywording/"> +<chapter> +<title>Keywording</title> +<body> + +<note> +<e>Terminology</e>: The term 'package' refers to an entire directory, for example +<c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific version. The terms +'ebuild' or 'package version' are used when this meaning is intended. This +distinction is important. +</note> + +<p> +Every ebuild should specify a <c>KEYWORDS</c> variable. This variable is used to +indicate the suitability and stability of both the package and the ebuild on +each given arch (<c>sparc</c>, <c>ppc</c>, <c>x86-obsd</c>, ...). +</p> + +<note> +The term 'arch' is used in this sense for historical reasons. As a result +of <uri link="http://www.gentoo.org/proj/en/glep/glep-0022.html">GLEP 22</uri> +and the various non-Linux ports, this is no longer a particularly +accurate term. +</note> + +<p> +A sample <c>KEYWORDS</c> entry might look like: +</p> + +<codesample lang="ebuild"> +KEYWORDS="x86 sparc mips ~ppc ~ppc-macos -ia64" +</codesample> + +<p> +The different levels of keyword are: +</p> + +<table> + <tr> + <th>Keyword</th> + <th>Meaning</th> + </tr> + <tr> + <ti> + <c>arch</c> (<c>x86</c>, <c>ppc-macos</c>) + </ti> + <ti> + Both the package version <e>and</e> the ebuild are widely tested, known to work + and not have any serious issues on the indicated platform. + </ti> + </tr> + <tr> + <ti> + <c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>) + </ti> + <ti> + The package version and the ebuild are believed to work and do not have any + known serious bugs, but more testing is required before the package version + is considered suitable for <c>arch</c>. + </ti> + </tr> + <tr> + <ti> + No keyword + </ti> + <ti> + If a package has no keyword for a given arch, it means it is not known + whether the package will work, or that insufficient testing has occurred for + <c>~arch</c>. + </ti> + </tr> + <tr> + <ti> + <c>-arch</c> (<c>-x86</c>, <c>-ppc-macos</c>) + </ti> + <ti> + The package version will not work on the arch. This could be caused by badly + written code (for example, non-64-bit or endian clean code), relying upon + particular hardware (for example, a BIOS querying tool would not work on + non-BIOS architectures) or binary only packages. + </ti> + </tr> +</table> + +<p> +The <c>-*</c> keyword is special. It is used to indicate package versions which are +not worth trying to test on unlisted archs. For example, a binary-only package +which is only supported upstream on <c>x86</c> and <c>ppc</c> might use: +</p> + +<codesample lang="ebuild"> +KEYWORDS="-* x86 ppc" +</codesample> + +<p> +This is different in implication from <c>"x86 ppc"</c> <d /> the former implies that +it will not work on other archs, whereas the latter implies that it has not been +tested. +</p> + +<p> +Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds. +</p> + +<section> +<title>Equal Visibility Requirement</title> +<body> + +<p> +An ebuild <b>must not</b> depend upon any package that is of a lower keyword level +than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>, and +<c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked stable on +<c>x86</c> unless <c>bar-1.2</c> is also stabilised. +</p> + +<p> +You may assume that if a user accepts <c>~arch</c> for a given arch then they also +accept <c>arch</c>. +</p> + +<p> +For optional dependencies, all <e>possible</e> dependencies must satisfy the above. +Note that certain <c>USE</c> flags can be forcibly disabled on a per-profile basis +<d /> talk to the arch teams if you require this. For either-or dependencies, <e>at +least one</e> of the options must be of equal or better visibility than the +package in question. +</p> + +</body> +</section> + +<section> +<title>Hard Masks</title> +<body> + +<p> +The <c>package.mask</c> file can be used to 'hard mask' individual or groups of +ebuilds. This should be used for testing ebuilds or beta releases of software, +and may also be used if a package has serious compatibility problems. Packages +which are not hard masked must <b>not</b> have a dependency upon hard masked +packages. +</p> + +<p> +The only time it is acceptable for a user to see the <c>Possibly a DEPEND +problem</c> error message is if they have manually changed visibility levels for a +package (for example, through <c>/etc/portage/</c>) and have missed a dependency. +<b>You should never commit a change which could cause this error to appear on a +user system</b>. +</p> + +</body> +</section> + +<section> +<title>Keywording New Packages</title> +<body> + +<important> +New packages should be marked as <c>~arch</c> only upon +architectures for which the committing developer has tested. +</important> + +<p> +Do <b>not</b> assume that your package works on all architectures. Do <b>not</b> +assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d /> chances are +they just copied from somewhere else. Do <b>not</b> assume that upstream's +'supported architectures' list is correct. Do <b>not</b> assume that because your +code is written in Perl / Python / Java / whatever that it will run on other +archs (there is at least one case of a <c>vim</c> script which only worked on +<c>x86</c>). +</p> + +<p> +Note that most (non-x86) archs expect you to be on the arch team and bugzilla +alias if you are committing packages with keywords for that arch, and may have +additional requirements of which you should be aware (on <c>mips</c>, for example, +there are multiple ABIs and byte orders to consider <d /> a package working on your +<c>o32</c> box may not work on <c>o64</c> or <c>n32</c>). Contact the individual arch +teams for details. +</p> + +<p> +Do <b>not</b> commit straight to <c>arch</c>. +</p> + +</body> +</section> + +<section> +<title>Keywording on Upgrades</title> +<body> + +<p> +When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c>, and leave +any existing <c>~arch</c> keywords intact. This must be done even if you <e>think</e> +you're just making a trivial fix <d /> there have been several examples of the +stable tree getting broken this way. +</p> + +<p> +Sometimes you may need to remove a keyword because of new unresolved +dependencies. If you do this, you <b>must</b> file a bug notifying the relevant +arch teams. +</p> + +<p> +This also applies to revision bumps, not just to upstream version changes. +</p> + +</body> +</section> + +<section> +<title>Moving from <c>~arch</c> to <c>arch</c></title> +<body> + +<p> +Moving a package from <c>~arch</c> to <c>arch</c> is done only by the relevant arch teams. +If you have access to non-x86 hardware but are not on the arch teams, you may wish +to make individual arrangements <d /> the arch teams are happy for help, so long as +they know what is going on. Please note that <c>x86</c> is now no longer an exception +and stabilisation must be done through the <c>x86</c> arch team unless you have +individual arrangements <d /> see +<uri link="http://www.gentoo.org/proj/en/glep/glep-0040.html">GLEP 40</uri> +for further details. +</p> + +<p> +For a package to move to stable, the following guidelines must be met: +</p> + +<ul> + <li> + The package has spent a reasonable amount of time in <c>~arch</c> first. Thirty + days is the usual figure, although this is clearly only a guideline. For + critical packages, a much longer duration is expected. For small packages + which have only minor changes between versions, a shorter period is sometimes + appropriate. + </li> + <li> + The package must not have any non-<c>arch</c> dependencies. + </li> + <li> + The package must not have any severe outstanding bugs or issues. + </li> + <li> + The package must be widely tested. + </li> + <li> + If the package is a library, it should be known not to break any package which + depends upon it. + </li> +</ul> + +<p> +For security fixes, the "reasonable amount of time" guideline may be relaxed. +See the <uri link="http://www.gentoo.org/security/en/vulnerability-policy.xml"> +Vulnerability Treatment Policy</uri> +</p> + +</body> +</section> + +<section> +<title>Removing Package Versions</title> +<body> + +<p> +When removing ebuild, ensure that you do not remove the most recent version at +any given keyword level on any profile. The aim here is: +</p> + +<ul> + <li> + Never to force a downgrade. (Exception: occasionally you really do want to + force a downgrade, for example if the newly committed <c>foo-1.3</c> turns out + to be badly broken and that making everyone downgrade to <c>foo-1.2</c> is the + better option. This is rare.) + </li> + <li> + Do not break any existing dependencies. + </li> +</ul> + +<p> +If you would like a particular package version moved to stable on certain archs +so that you can tidy up, file a bug. +</p> + +</body> +</section> + +</body> +</chapter> +</guide> |