aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMark Loeser <halcy0n@gentoo.org>2006-03-09 04:08:55 +0000
committerMark Loeser <halcy0n@gentoo.org>2006-03-09 04:08:55 +0000
commitcfbf02d976a56cf1bcc398127bcd4976bdcd313f (patch)
tree6ab0ec13f5a34b3868062bf0491addef3e6ea63d /keywording/text.xml
parentAdd profiles/ (diff)
downloaddevmanual-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/text.xml')
-rw-r--r--keywording/text.xml297
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>