<author title="Author"><mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail></author> 

<author title="Author"><mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail></author> 

<author title="Author/Editor"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> 

<author title="Author/Editor"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> 

<author title="Editor"><mail link="seemant@gentoo.org">Seemant Kulleen</mail></author> 

<author title="Editor"><mail link="seemant@gentoo.org">Seemant Kulleen</mail></author> 

<abstract>

<abstract>

This guide is meant to be the authoritative written reference for Gentoo Linux development policy.

This guide is meant to be the authoritative written reference for Gentoo Linux development policy.

It will be updated periodically to reflect new developer procedures.

It will be updated periodically to reflect new developer procedures.

</abstract>

</abstract>

<chapter>

<chapter>

<title>General guidelines</title>

<title>General guidelines</title>

settings.</li>

settings.</li>

<li>Don't be afraid to consult our on-line documentation and ebuilds written

<li>Don't be afraid to consult our on-line documentation and ebuilds written

</ul>

</ul>

</body>

</body>

</section>

</section>

</chapter>

</chapter>

<chapter>

<chapter>

<title>Ebuild policy</title>

<title>Ebuild policy</title>

<section>

<section>

the literal package name. <c>#</c> represents any non-zero positive

the literal package name. <c>#</c> represents any non-zero positive

integer.</note>

integer.</note>

lowercase letters, the digits 0-9, and any number of single hyphen (<c>-</c>)

lowercase letters, the digits 0-9, and any number of single hyphen (<c>-</c>)

characters. Examples: <c>util-linux</c>, <c>sysklogd</c>, <c>glibc</c>. We have

characters. Examples: <c>util-linux</c>, <c>sysklogd</c>, <c>glibc</c>. We have

some packages in Portage that don't follow these rules, but <i>your</i>

some packages in Portage that don't follow these rules, but <i>your</i>

normally be same as the version on the main source tarball. The version is

normally be same as the version on the main source tarball. The version is

normally made up of two or three (or more) numbers separated by periods, such

normally made up of two or three (or more) numbers separated by periods, such

as <c>1.2</c> or <c>4.5.2</c>, and may have a single letter immediately

as <c>1.2</c> or <c>4.5.2</c>, and may have a single letter immediately

following the last digit, e.g., <c>1.4b</c> or <c>2.6h</c>. The package version

following the last digit, e.g., <c>1.4b</c> or <c>2.6h</c>. The package version

is joined to the package name with a hyphen. Examples: <c>foo-1.0</c>,

is joined to the package name with a hyphen. Examples: <c>foo-1.0</c>,

<table>

<table>

</table>

</table>

integer, e.g., <c>linux-2.4.0_pre10</c>. Assuming identical version parts, the

integer, e.g., <c>linux-2.4.0_pre10</c>. Assuming identical version parts, the

suffixes are ordered as follows (lower means older): <c>_alpha</c> &lt;

suffixes are ordered as follows (lower means older): <c>_alpha</c> &lt;

<c>_beta</c> &lt; <c>_pre</c> &lt; <c>_rc</c> &lt; (no suffix) &lt;

<c>_beta</c> &lt; <c>_pre</c> &lt; <c>_rc</c> &lt; (no suffix) &lt;

larger integer will be considered most recent. Example: <c>foo-1.0_alpha4</c>

larger integer will be considered most recent. Example: <c>foo-1.0_alpha4</c>

number (<c>{-r#}</c>). This section, like the suffix, is also optional.

number (<c>{-r#}</c>). This section, like the suffix, is also optional.

is used to inform people that a new and improved Gentoo Linux revision of a

is used to inform people that a new and improved Gentoo Linux revision of a

particular package is available. Initial releases of ebuilds must have no

particular package is available. Initial releases of ebuilds must have no

revision number, e.g. <c>package-4.5.3</c> and are considered by Portage to

revision number, e.g. <c>package-4.5.3</c> and are considered by Portage to

have a revision number of zero. This means that counting goes as follows:

have a revision number of zero. This means that counting goes as follows:

</body>

</body>

</section>

</section>

<section>

<section>

<title>Versioning and revision bumps</title>

<title>Versioning and revision bumps</title>

<body>

<body>

when the ebuild has changed to the point where users would want to upgrade.

when the ebuild has changed to the point where users would want to upgrade.

Typically, this is the case when fixes are made to an ebuild that affect the

Typically, this is the case when fixes are made to an ebuild that affect the

resultant installed files, but the ebuild uses the same source tarball as the

resultant installed files, but the ebuild uses the same source tarball as the

those for whom it worked perfectly would see no benefit in installing a new

those for whom it worked perfectly would see no benefit in installing a new

revision, and those who experienced the problem do not have the package

revision, and those who experienced the problem do not have the package

installed (since compilation failed) and thus have no need for the new revision

installed (since compilation failed) and thus have no need for the new revision

<path>ChangeLog</path> file in the ebuild directory. Failing to do so is

<path>ChangeLog</path> file in the ebuild directory. Failing to do so is

considered to be in very poor taste and may result in disciplinary

considered to be in very poor taste and may result in disciplinary

</body> 

</body> 

</section> 

</section> 

<section>

<section>

<title>Virtuals</title>

<title>Virtuals</title>

<body>

<body>

packages, it is possible to have a particular category/package name map to

packages, it is possible to have a particular category/package name map to

another. Here's an example of how to use virtual packages. Let's say you create

another. Here's an example of how to use virtual packages. Let's say you create

a new cron package called <c>foocron</c>. Gentoo Linux is currently set up so

a new cron package called <c>foocron</c>. Gentoo Linux is currently set up so

<c>virtual/cron</c> package. This allows ebuilds to ensure that there is some

<c>virtual/cron</c> package. This allows ebuilds to ensure that there is some

kind of cron available while allowing users the flexibility to install the cron

kind of cron available while allowing users the flexibility to install the cron

package that they prefer. To plug your <path>foocron-1.0.ebuild</path> into

package that they prefer. To plug your <path>foocron-1.0.ebuild</path> into

<pre>

<pre>

PROVIDE="virtual/cron"

PROVIDE="virtual/cron"

</pre>

</pre>

will be registered. If you didn't have any cron package installed before, this

will be registered. If you didn't have any cron package installed before, this

would mean that any package <e>depending</e> on <c>virtual/cron</c> would have

would mean that any package <e>depending</e> on <c>virtual/cron</c> would have

that dependency fully satisfied. Note that it is possible to specify a

that dependency fully satisfied. Note that it is possible to specify a

<c>PROVIDE</c> value for any type of package -- it need not begin with

<c>PROVIDE</c> value for any type of package -- it need not begin with

<c>virtual/</c>. However, you <e>should</e> use the <c>virtual/</c> category

<c>virtual/</c>. However, you <e>should</e> use the <c>virtual/</c> category

unless you are using the <c>PROVIDE</c> functionality to handle packages that

unless you are using the <c>PROVIDE</c> functionality to handle packages that

What would happen if there were no installed package that provided

What would happen if there were no installed package that provided

<c>virtual/cron</c>? How would Portage choose the "correct" cron to install to

<c>virtual/cron</c>? How would Portage choose the "correct" cron to install to

satisfy the <c>virtual/cron</c> dependency? Portage takes care of this

satisfy the <c>virtual/cron</c> dependency? Portage takes care of this

<path>virtuals</path> which is stored in the profile directory

<path>virtuals</path> which is stored in the profile directory

<path>/etc/make.profile</path>. If you take a look at your

<path>/etc/make.profile</path>. If you take a look at your

<path>virtuals</path> file, you'll find that the contents look something like

<path>virtuals</path> file, you'll find that the contents look something like

<pre caption="Sample virtuals file">

<pre caption="Sample virtuals file">

virtual/lpr             net-print/cups

virtual/lpr             net-print/cups

virtual/mta             net-mail/ssmtp

virtual/mta             net-mail/ssmtp

</pre>

</pre>

<c>virtual/lpr</c> and no <c>virtual/lpr</c> is installed and no

<c>virtual/lpr</c> and no <c>virtual/lpr</c> is installed and no

<c>virtual/lpr</c> package is available in the Portage tree, then

<c>virtual/lpr</c> package is available in the Portage tree, then

<c>net-print/cups</c> should be installed to satisfy this dependency.

<c>net-print/cups</c> should be installed to satisfy this dependency.

<c>net-print/cups</c> contains a line that reads <c>PROVIDE="virtual/lpr"</c>

<c>net-print/cups</c> contains a line that reads <c>PROVIDE="virtual/lpr"</c>

package, you would obviously want to ensure that all programs that depend upon

package, you would obviously want to ensure that all programs that depend upon

<c>virtual/cron</c> are able to work correctly with it. And if you were to add

<c>virtual/cron</c> are able to work correctly with it. And if you were to add

a package named <c>foobarosity</c> that depended on <c>virtual/cron</c>, you

a package named <c>foobarosity</c> that depended on <c>virtual/cron</c>, you

should likewise ensure that all packages that provide <c>virtual/cron</c> will

should likewise ensure that all packages that provide <c>virtual/cron</c> will

</body>

</body>

</section>

</section>

<section>

<section>

<title>CVS sources policy</title>

<title>CVS sources policy</title>

<body>

<body>

development tree. The first and traditional way is to create a "CVS snapshot"

development tree. The first and traditional way is to create a "CVS snapshot"

ebuild by creating your own tarball snapshot of the upstream CVS tree,

ebuild by creating your own tarball snapshot of the upstream CVS tree,

mirroring the sources on our official distfile repository, and writing an

mirroring the sources on our official distfile repository, and writing an

ebuild to specifically use this tarball snapshot. These types of CVS ebuilds

ebuild to specifically use this tarball snapshot. These types of CVS ebuilds

creating a CVS-based ebuild is to use <path>cvs.eclass</path> to create a

creating a CVS-based ebuild is to use <path>cvs.eclass</path> to create a

"live" CVS ebuild. Such an ebuild will dynamically grab the latest development

"live" CVS ebuild. Such an ebuild will dynamically grab the latest development

sources from a CVS repository at "fetch" time, ensuring that the sources are as

sources from a CVS repository at "fetch" time, ensuring that the sources are as

up-to-date as possible. These types of CVS ebuilds will be referred to as

up-to-date as possible. These types of CVS ebuilds will be referred to as

ebuilds.  Note that there are strict rules relating to the addition of such

ebuilds.  Note that there are strict rules relating to the addition of such

are needed for proper operation of a software package, or if the cvs version of

are needed for proper operation of a software package, or if the cvs version of

a particular software package is known to or has been proven to simply "work

a particular software package is known to or has been proven to simply "work

convenience of developers and should always be masked with a <c>~[arch]</c>

convenience of developers and should always be masked with a <c>~[arch]</c>

keyword. It is impossible to guarantee the reliability of a "live"

keyword. It is impossible to guarantee the reliability of a "live"

<path>cvs.eclass</path> ebuild since the upstream cvs tree may change at any

<path>cvs.eclass</path> ebuild since the upstream cvs tree may change at any

developer are responsible for ensuring that the ebuild works correctly</b>.

developer are responsible for ensuring that the ebuild works correctly</b>.

This is particularly difficult to do with "live" cvs ebuilds for obvious

This is particularly difficult to do with "live" cvs ebuilds for obvious

fixed or removed from the Portage tree. If they are "live" ebuilds, they may be

fixed or removed from the Portage tree. If they are "live" ebuilds, they may be

<c>~[arch]</c> keyword masked for their lifetime (this special exception is

<c>~[arch]</c> keyword masked for their lifetime (this special exception is

for them. It should have a <c>~[arch]</c> keyword so that other users don't

for them. It should have a <c>~[arch]</c> keyword so that other users don't

them but other users will be protected from merging them accidentally.

them but other users will be protected from merging them accidentally.

Again, this only applies to situations where a user or users

Again, this only applies to situations where a user or users

specifically request a "live" <path>cvs.eclass</path> CVS ebuild. Snapshot

specifically request a "live" <path>cvs.eclass</path> CVS ebuild. Snapshot

ebuilds should only be added to the Portage tree with the intention that they

ebuilds should only be added to the Portage tree with the intention that they

are stable and provide better functionality than the normal release versions

are stable and provide better functionality than the normal release versions

follows: <path>foo-x.y_preYYYYMMDD.ebuild</path>.  <c>foo</c> is the package

follows: <path>foo-x.y_preYYYYMMDD.ebuild</path>.  <c>foo</c> is the package

name, <c>x.y</c> is the version number of the <e>upcoming</e> release,

name, <c>x.y</c> is the version number of the <e>upcoming</e> release,

<c>_pre</c> is a literal string, and <c>YYYYMMDD</c> is a timestamp of the day

<c>_pre</c> is a literal string, and <c>YYYYMMDD</c> is a timestamp of the day

snapshots of <e>already-released</e> CVS sources, use the format

snapshots of <e>already-released</e> CVS sources, use the format

<path>foo-x.y_pYYYYMMDD.ebuild</path> (notice the <c>_p</c> for "patchlevel.")

<path>foo-x.y_pYYYYMMDD.ebuild</path> (notice the <c>_p</c> for "patchlevel.")

This will ensure that your CVS ebuild will be considered <e>newer</e> than the

This will ensure that your CVS ebuild will be considered <e>newer</e> than the

package name ends with <c>-cvs</c>. In the future, a <c>_cvs</c> version suffix

package name ends with <c>-cvs</c>. In the future, a <c>_cvs</c> version suffix

</body>

</body>

</section>

</section>

<section>

<section>

<title>User-submitted ebuilds</title>

<title>User-submitted ebuilds</title>

<body>

<body>

well-tested and audited before being committed to CVS. <b>If a user-submitted

well-tested and audited before being committed to CVS. <b>If a user-submitted

ebuild has problems, you will be held accountable.</b> By committing it to CVS,

ebuild has problems, you will be held accountable.</b> By committing it to CVS,

<p>Make sure that the user-submitted ebuild doesn't contain custom headers like this:</p>

<p>Make sure that the user-submitted ebuild doesn't contain custom headers like this:</p>

# Ebuild updated by: me <me@me.com>

# Ebuild updated by: me <me@me.com>

</pre>

</pre>

comment syntax. <b>Always ensure that the ChangeLog gives proper credit to the user

comment syntax. <b>Always ensure that the ChangeLog gives proper credit to the user

<p>Also ensure that any new ebuilds you commit contain the following line:</p>

<p>Also ensure that any new ebuilds you commit contain the following line:</p>

<pre>

<pre>

<p>Quite a few user-submitted ebuilds are based on files from rsync, which can contain

<p>Quite a few user-submitted ebuilds are based on files from rsync, which can contain

incorrect header lines.</p>

incorrect header lines.</p>

an upgrade.  By doing this, we can help avoid the re-introduction of

an upgrade.  By doing this, we can help avoid the re-introduction of

previously-fixed bugs into our "new" ebuilds. If you are not working from a user-submitted

previously-fixed bugs into our "new" ebuilds. If you are not working from a user-submitted

diff but a complete ebuild, then use the <c>diff</c> command to see what has changed, keeping

diff but a complete ebuild, then use the <c>diff</c> command to see what has changed, keeping

an eye open for anything from our current ebuild that should appear in the new ebuild, or

an eye open for anything from our current ebuild that should appear in the new ebuild, or

you <e>want</e> to clean up the ebuild on his or her behalf.  Even so, it's often better

you <e>want</e> to clean up the ebuild on his or her behalf.  Even so, it's often better

to have the user do the work so that they can learn from their mistakes and submit cleaner ebuilds

to have the user do the work so that they can learn from their mistakes and submit cleaner ebuilds

in the future. Be sure to be thankful for any submission, even if it isn't very good. Be polite

in the future. Be sure to be thankful for any submission, even if it isn't very good. Be polite

but honest -- if an ebuild isn't usable, the user can be told in a way that does not insult their

but honest -- if an ebuild isn't usable, the user can be told in a way that does not insult their

current ebuild-writing abilities. Remember that the user who submitted that broken ebuild may

current ebuild-writing abilities. Remember that the user who submitted that broken ebuild may

</body>

</body>

</section>

</section>

</chapter> 

</chapter> 

<chapter>

<chapter>

<title>QA policy</title>

<title>QA policy</title>

<section>

<section>

Only the Portage Maintainer has the

Only the Portage Maintainer has the

authority to roll new releases of Portage for use by users, either

authority to roll new releases of Portage for use by users, either

masked or unmasked versions. <b>No one</b> else is allowed to roll new

masked or unmasked versions. <b>No one</b> else is allowed to roll new

<p>

<p>

The only exception to this rule is for situations where the Portage Maintainer may be

The only exception to this rule is for situations where the Portage Maintainer may be

unavailable for extended periods of time and there is a major bug in

unavailable for extended periods of time and there is a major bug in

Portage. In this emergency situation, it would be allowable for a senior

Portage. In this emergency situation, it would be allowable for a senior

<p>

<p>

Before using this "escape clause," please ask yourself: is the Portage Maintainer really

Before using this "escape clause," please ask yourself: is the Portage Maintainer really

</body>

</body>

</section>

</section>

</chapter>

</chapter>

<chapter>

<chapter>

<title>Variables</title>

<title>Variables</title>

<section>

<section>

<title>Required variables</title>

<title>Required variables</title>

<body>

<body>

</p>

</p>

</body>

</body>

</section>

</section>

<section>

<section>

<title>DEPEND and RDEPEND</title>

<title>DEPEND and RDEPEND</title>

<body>

<body>

particular package, and set <c>RDEPEND</c> to the dependencies required to

particular package, and set <c>RDEPEND</c> to the dependencies required to

<e>run</e> a particular package. You only need to explicitly specify <c>RDEPEND</c>

<e>run</e> a particular package. You only need to explicitly specify <c>RDEPEND</c>

if the ebuild's runtime dependencies are different than what you specified in

if the ebuild's runtime dependencies are different than what you specified in

<c>DEPEND</c>; if not specified, <c>RDEPEND</c> will default to your <c>DEPEND</c>

<c>DEPEND</c>; if not specified, <c>RDEPEND</c> will default to your <c>DEPEND</c>

</p>

</p>

<p>

<p>

<c>RDEPEND</c> dependencies are satisfied when one installs a binary

<c>RDEPEND</c> dependencies are satisfied when one installs a binary

<c>.tbz2</c> package; use this information to help you choose the correct

<c>.tbz2</c> package; use this information to help you choose the correct

<c>RDEPEND</c> dependencies. If undefined, and ebuild's <c>RDEPEND</c> setting

<c>RDEPEND</c> dependencies. If undefined, and ebuild's <c>RDEPEND</c> setting

dependency. If it works with <c>libfoo-1.2.x</c>, don't depend on

dependency. If it works with <c>libfoo-1.2.x</c>, don't depend on

<c>&gt;=libfoo-1.2</c>. Otherwise, things may start breaking horribly when

<c>&gt;=libfoo-1.2</c>. Otherwise, things may start breaking horribly when

when the different packages providing <c>virtual/foo</c> have identical

when the different packages providing <c>virtual/foo</c> have identical

interfaces.  Consider <c>virtual/jdk-1.3</c> for example. Some packages don't

interfaces.  Consider <c>virtual/jdk-1.3</c> for example. Some packages don't

work with <c>ibm-jdk-1.3</c> while they do work with <c>sun-jdk-1.3</c>. For

work with <c>ibm-jdk-1.3</c> while they do work with <c>sun-jdk-1.3</c>. For

this reason, be sure that your package is tested against all virtual providers

this reason, be sure that your package is tested against all virtual providers

before unmasking.  It may be possible to only depend on a subset of those

before unmasking.  It may be possible to only depend on a subset of those

</body>

</body>

</section>

</section>

</chapter>

</chapter>

</guide>

</guide>