Project:ComRel/Developer Handbook/Ebuild policy
This section outlines the ebuild policy which every ebuild in Portage must follow.
This document is outdated. Please refer to the Gentoo Developer Manual for the latest documentation about ebuild writing and policies.
General guidelines
Here are some general development guidelines to follow:
- Always check in your changes with pkgcheck; use pkgdev commit instead of git commit.
- If a package is either broken in its current version or it has a really nasty build/install process, take a look at how other distributions do it:
- Debian
- Mandriva
- Fedora
- Your package, when complete and unmasked, is supposed to "just work" for the end-user. Tweaking the installed product to get it to work should be optional; thus you need to install the package with reasonable default settings.
- Don't be afraid to consult our on-line documentation and ebuilds written and maintained by more senior developers. Feel free to contact senior developers directly with any technical or policy questions.
- Be cautious about what you commit. Remember that your commits can potentially harm thousands of users. If your commits cause any breakage in the tree, they must be fixed in a timely fashion.
- Every package must be accompanied by a metadata.xml file which lists - amongst other information - what herd (and/or individual maintainers) are in charge of the package.
Specific guidelines
Perl
New Perl modules are to be added to portage only when one of the following conditions is met:
- The module(s) fulfill a dependency.
- The module(s) cannot be handled by g-cpan.
- The module(s) add functionality to existing ebuilds.
- The module(s) provide tools, applications or other features (i.e. more than what their .PM offers).
Please make sure that at least one member of the perl herders approves your addition.
Ebuild policy
Naming policy
Ebuild file names consist of four logical subsections:
pkg-ver{_suf{#{-r#}.ebuild}}
The brackets (
{}) delineate optional fields and do not appear in the literal package name. # represents any non-zero positive integer.The first subsection, pkg, is the package name, which should only contain lowercase letters, the digits 0-9, and any number of single hyphen (-), underscore (_) or plus (+) characters. Examples: util-linux, sysklogd, and gtk+. We have some packages in Portage that don't follow these rules, but your packages should.
The second subsection, ver, is the version of the package, which should 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 as 1.2 or 4.5.2, and may have a single letter immediately following the last digit; e.g., 1.4b or 2.6h. The package version is joined to the package name with a hyphen. Examples: foo-1.0, bar-2.4.6.
The third subsection, {_suf{#}}, is optional may contain one of these predefined suffixes, listed in least-recent to most-recent order:
| Suffix | Meaning |
|---|---|
| _alpha | Alpha release |
| _beta | Beta release |
| _pre | Prerelease |
| _rc | Release candidate |
| (none) | Normal release |
| _p | Patch level (normally accompanied by trailing integer) |
Any of these suffixes may be immediately followed by a non-zero positive integer, e.g., linux-2.4.0_pre10. Assuming identical version parts, the suffixes are ordered as follows (lower means older): _alpha < _beta < _pre < _rc < (no suffix) < _p.
When comparing identical suffixes with trailing integers, the one with the larger integer will be considered most recent. Example: foo-1.0_alpha4 is more recent than foo-1.0_alpha3.
The fourth subsection of the package name is the Gentoo Linux-specific revision number ({-r#}). This subsection, like the suffix, is also optional. # is a non-zero positive integer; e.g., package-4.5.3-r3.
This revision number is independent of the version of the source tarball and 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 revision number; e.g., package-4.5.3 and are considered by Portage to have a revision number of zero. This means that counting goes as follows: 1.0 (initial version), 1.0-r1, 1.0-r2, etc.
Versioning and revision bumps
Package revision numbers should be incremented by Gentoo Linux developers 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 resultant installed files, but the ebuild uses the same source tarball as the previous release. If you make an internal, stylistic change to the ebuild that does not change any of the installed files, then there is no need to bump the revision number. Likewise, if you fix a compilation problem in the ebuild that was affecting some users, there is no need to bump the revision number, since 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 installed (since compilation failed) and thus have no need for the new revision number to force an upgrade. A revision bump is also not necessary if a minority of users will be affected and the package has a nontrivial average compilation time; use your best judgement in these circumstances.
Whenever you create a new revision of an ebuild, be sure to update the ChangeLog file in the ebuild directory. Failing to do so is considered to be in very poor taste and may result in disciplinary action.
Ebuilds should be based on the previous version of the ebuild to ensure that fixes aren't dropped accidentally. Fixes should include appropriate comments in the ebuild explaining what they are for and why they are needed. If you are not familiar with the fixes, or unable to determine if they are still needed, you should not be updating the ebuild.
Scope
Whenever an ebuild is sourced, the functions and variables within it are loaded into memory by the script interpreter. However, only variables and instructions that are not part of a function are interpreted - functions such as src_compile() are only executed by Portage when the ebuild has reached the compile stage.
The code within these functions are considered in "local scope" while everything outside of the functions is in the "global scope" meaning they are executed every time the ebuild is sourced.
An external application (such as grep, sed or awk) should never be called in global scope for performance reasons, and alternatives such as using built-in bash replacement should be used instead. Useful alternatives can be found in the Advanced Bash Scripting Guide.
Additionally, any external application that may be called in global scope can not be guaranteed to exist on the system. If the command is placed in local scope (for example, in the pkg_setup() function), we can guarantee its presence by placing it in the ebuild's ${DEPEND}.
CVS sources policy
There are two different ways to build an ebuild based on sources from a CVS 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, mirroring the sources on our official distfile repository, and writing an ebuild to specifically use this tarball snapshot. These types of CVS ebuilds will be referred to as "CVS snapshot ebuilds" below.
The other method of creating a CVS-based ebuild is to use cvs.eclass to create a "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 up-to-date as possible. These types of CVS ebuilds will be referred to as "'live' ebuilds" below.
The following paragraphs detail the policy relating to the use of CVS-based ebuilds. Note that there are strict rules relating to the addition of such ebuilds to the Portage tree.
Snapshot cvs ebuilds are greatly preferred over "live" cvs.eclass cvs ebuilds.
Snapshot cvs ebuilds are allowed if a cvs snapshot contains known fixes that 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 better" than the normal release version.
"Live" cvs.eclass ebuilds are generally only intended for the convenience of developers and should always be masked with a ~[arch] keyword. It is impossible to guarantee the reliability of a "live" cvs.eclass ebuild since the upstream cvs tree may change at any time, which is why they should always be masked.
Whether a "live" CVS ebuild or a "snapshot" CVS ebuild, you the developer are responsible for ensuring that the ebuild works correctly. This is particularly difficult to do with "live" cvs ebuilds for obvious reasons.
If ebuilds (of any kind) do not work correctly or are flaky, they should be fixed or removed from the Portage tree. If they are "live" ebuilds, they may be ~[arch] keyword masked for their lifetime (this special exception is detailed below).
If a user or users specifically request a "live" cvs ebuild, you can add one for them. It should have a ~[arch] keyword so that other users don't merge it unsuspectingly.
This way, the user(s) requesting them (likely developers) can install them but other users will be protected from merging them accidentally. Again, this only applies to situations where a user or users specifically request a "live" cvs.eclass CVS ebuild. Snapshot 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 of said software.
Snapshot ebuilds of pre-release CVS sources should be named as follows: foo-x.y_preYYYYMMDD.ebuild.
foo is the package name, x.y is the version number of the upcoming release, _pre is a literal string, and YYYYMMDD is a timestamp of the day the CVS snapshot was taken. Use this naming convention to ensure that a x.y.1 release version won't be considered to be older than a x.y snapshot, while at the same time ensuring that the official x.y release will be considered newer than your CVS snapshot version. For CVS snapshots of already-released CVS sources, use the format foo-x.y_pYYYYMMDD.ebuild (notice the _p for "patchlevel.") This will ensure that your CVS ebuild will be considered newer than the standard x.y release.The policy for naming "live" cvs ebuilds is to use the "-9999" suffix.
User-submitted ebuilds
User-submitted ebuilds should never be blindly trusted and should always be well-tested and audited before being committed to CVS. If a user-submitted ebuild has problems, you will be held accountable. By committing it to CVS, you are vouching that the ebuild meets all Gentoo Linux development standards.
Make sure that the user-submitted ebuild doesn't contain custom headers like this:
# Ebuild updated by: me <me@me.com>
This information should be added to the ChangeLog using proper ChangeLog comment syntax. Always ensure that the ChangeLog gives proper credit to the user who submitted the ebuild. This information should appear in the first ChangeLog entry.
Also ensure that any new ebuilds you commit contain the following line:
# $Header: $
Quite a few user-submitted ebuilds are based on files from rsync, which can contain incorrect header lines.
Encourage users to submit diffs to existing ebuilds if they are submitting 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 diff but a complete ebuild, then use the diff command to see what has changed, keeping an eye open for anything from our current ebuild that should appear in the new ebuild, or anything in the new ebuild that should be fixed or removed.
In general, let the user do the work required to get his or her ebuild up to par, unless you want 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 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 current ebuild-writing abilities. Remember that the user who submitted that broken ebuild may be a skilled and productive member of our project in the future -- that is, if they receive the right amount of encouragement and support and continue to improve in their abilities.
QA policy
Portage / baselayout release policy
Only members of the Portage team (who know who they are) have the authority to release new releases of Portage. No one else is allowed to roll new releases of Portage.
Only members of the baselayout team (who know who they are) have the authority to release new releases of baselayout. No one else is allowed to roll new releases of baselayout.
Masked packages
/var/db/repos/gentoo/profiles/package.mask contains a list of packages that should not be merged by users and comments detailing the specific reason why. package.mask is used to prevent merging of packages that are broken, break something else, or badly need testing before going into ~ARCH KEYWORDS in the tree. When adding to package.mask, always commit package.mask prior to committing the masked ebuild. This prevents the ebuild from hitting users before the updated package.mask does.
Great care must be taken any time a package is removed from package.mask. Keep in mind that if an ebuild is in package.mask, it's there for a reason. If you didn't mask the ebuild, always contact the developer listed in the package.mask comments prior to taking any action. Additionally, if the masked ebuild is a core package, a dependency of a core package, or the unmasking has any possibility for adverse effects, the change must be discussed internally on the developer mailing list.
~ARCH in KEYWORDS
The purpose of ~arch is for testing new packages added to Portage.
There is a difference between using package.mask and ~arch for ebuilds. The use of ~arch denotes an ebuild requires testing. The use of package.mask denotes that the application or library itself is deemed unstable. For example, if gimp-1.2.0 is the stable release from Gimp developers, and a new bug fix release is available as 1.2.1, then a developer should mark the ebuild as ~arch for testing in portage because the release is deemed to be stable. In another example, if Gimp decides to release an unstable/development series marked as 1.3.0, then these ebuilds should be put in package.mask because the software itself is of development quality and is not recommended by the developers for distribution.
Any new package that enters Portage must be marked ~arch for the architecture(s) that this version is known to work on. The developer who commits the ebuild must verify it is in working order, and the KEYWORDS are correct.
Moving package versions from ~ARCH to ARCH
When a package version has proved stable for sufficient time and the Gentoo maintainer of the package is confident that the upgrade will not break a regular Gentoo user's machine, then it can be moved from ~ARCH to ARCH. An indication of the package's stability would be no verified or unresolved bug report for a month after the version's introduction.
It is up to the maintainer of the package to deem which versions are stable or if development versions should be in package.mask or left in ~arch.
You must also ensure that all the dependencies of such a package version are also in ARCH.
Remember that arch teams alone are responsible for marking packages stable on their arch. Package maintainers should open stabilization bugs; they may not just mark packages stable. However, if the maintainer is also part of an arch team, then he or she may stabilize the package for his or her arch.
The ~ARCH step may only be ignored if and only if the concerned package version contains a security fix or is needed to fix an important bug in the Gentoo system.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Seemant Kulleen, Shyam Mani, Karl Trygve Kalleberg, Mike Frysinger, Alastair Tse, Paul De Vrieze, Nicholas D. Wolfwood, Marius Mauch, Daniel Black, Wernfried Haas, Chrissy Fullam, Łukasz Damentko, Daniel Robbins, Markos Chandras, John P. Davis, Tim Yamin, Jorge Paulo, Zack Gilburd, Benny Chuang, Erwin, Jon Portnoy, Carl Anderson, Donny Davies, Peter Gavin, Dan Armak, Owen Stampflee, and Ciaran McCreesh on March 3, 2012
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.