Ebuild Maintenance

This guide aims to explain common everyday ebuild maintenance routines, as well as other rarer maintenance routines which developers may not be familiar with.

Adding a new ebuild

What (not) to put in the Portage tree

Before writing a new ebuild, check bugs.gentoo.org to see if an ebuild has already been written for the package, but has not yet been added to the Portage tree. Go to bugs.gentoo.org, choose query and select Advanced Search; as product select Gentoo Linux, as component select ebuilds. In the search field put the name of the ebuild and as status select all possible fields, then submit the query. For you lazy people, click here.

In general, the Portage tree should only be used for storing .ebuild files, as well as any relatively small companion files, such as patches or sample configuration files. These types of files should be placed in the /usr/portage/mycat/mypkg/files directory to keep the main mycat/mypkg directory uncluttered. Exceptions to this rule are for larger patch files (we recommend this for patches above 20KB) which should be distributed as tarballs via the Gentoo mirror system so that people do not waste excessive amounts of bandwidth and hard drive space. Also, you should not add binary (non-ASCII) files to the git tree. Also, speaking of merging changes, any patches you add to Portage should generally not be compressed. This will allow git to merge changes and correctly inform developers of conflicts.

Remember, the packages that you commit must be ready out of the box for end users when committed as stable. Make sure that you have a good set of default settings that will satisfy the majority of systems and users that will use your package. If your package is broken, and you are not sure how to get it to work, check some other distributions that have done their own versions of the package. You can check Mandriva or Debian or Fedora for some examples.

When committing to git, all developers should use repoman commit instead of git commit to submit their ebuilds. Before committing, please run repoman full to make sure you didn't forget something.

Initial Architecture Keywords

When adding a new ebuild, you should only include KEYWORDS for architectures on which you have actually tested the ebuild, confirming that it works as it should and that USE flags are properly honoured in the resulting package which would be installed. If possible, you should give the actual library or application thorough testing as well, since you would be responsible for any breakages for your architecture(s). Minimal testing such as checking that the application starts up without any errors should always be performed.

If you are adding a user-submitted ebuild, do not assume that the submitter has done testing on various architectures: often, KEYWORDS are cloned across packages or generated from documentation in the source packages, which does not signify that the package does indeed work on those architectures.

Git Commit Message Format

It is important to format the commit messages properly so that they communicate the changes to the reader in a clear and concise way. Additionally, consistency in message format allows for easier parsing by external tools. The first line of the commit message should contain a brief summary of the changes, followed by an empty new line. From the third line onward should be a detailed, multiline explanation of the changes introduced by the commit. At the very end, auxiliary information such as the bugs related to the commit, contributors, and reviewers should be listed using RFC822/git style tags. The length of the lines in the message should be 70-75 characters at maximum.

The summary line should start with referencing what is affected by the change followed by a colon ':' character. Use the rules in the following list to determine the proper format based on what has changed, substituting the package, category and eclass names appropriately:

  • ${CATEGORY}/${PN}:Single Package (Note that repoman commit automatically inserts this for you)
  • ${CATEGORY}: Package Category
  • profiles: Profile Directory
  • ${ECLASS}.eclass: Eclass Directotry
  • licenses: Licenses Directory
  • metadata: Metadata Directory
For packages where ${CATEGORY}/${PN}: is long, the line length limit can be exceeded, if absolutely necessary, to ensure a more useful summary line. If a commit affects multiple directories, prepend the message with which reflects the intention of the change best. If there are any bugs on Gentoo Bugzilla associated with the commit, id of the bug can be appended to the summary line using the format #BUG-ID. If you are modifying keywords, clearly state what keywords are added/removed.

For non-trivial commits, the message should contain a detailed explanation of what the commit intends to change, why it is required, and how it is accomplished, along with any other supplementary information.

Finally the commit message should list auxiliary information such as people who are involved in authoring, suggesting, reviewing and testing the changes, and revelant bugs. Use RFC822/git style tags as explained in the Linux Kernel patch guideline. Additionally, the following tags are used in Gentoo:

  • Gentoo-Bug: Use this to reference bugs in Gentoo Bugzilla by either the bug ID or the bugzilla URI. Multiple bugs can be referenced by inserting more tags of this type or separating bug IDs with a comma in the same tag. The bug IDs may include an optional '#' prefix. There is no consensus on referencing bugs in the summary line versus referencing with a tag in the message body. The developer has the option to choose either.
  • Package-Manager: This is automatically inserted by repoman commit and it specifies the version of sys-apps/portage on the system.
  • RepoMan-Options: This is automatically inserted by repoman commit and records the options passed to repoman (such as --force) for the commit.

When committing user contributions, make sure to credit them in your commit message with the user's full name and email address. Be aware and respectful of their privacy: some users prefer to be only known by a nickname. Take advantage of the tags such as Suggested-By or Reported-By:when entering such information to the commit message.

An example commit message is shown below:

app-misc/foo: version bump to 0.5

This also adds a new USE flag 'bar' which controls the
new bar functionality introduced with this version.

Gentoo-Bug: 01234

Git Commit Policy

  • Always run repoman scan before you commit.
  • Please run repoman full before you commit.
  • Always test that package.mask is okay by doing emerge --pretend mypkg before you commit and check that it doesn't contain any conflicts.
  • Always commit the updated package.mask before the updated package.
  • Always do atomic commits; if you commit a package with a new license, or that is masked, then first commit the revised package.mask and/or license, then commit the ebuild, patches and metadata.xml all in one go .

The files Directory

As noted earlier, under each package subdirectory is a files/ directory. Any patches, configuration files, or other ancillary files your package might require should be added to this directory; any files bigger than 20KB-or-so should go to the mirrors to lower the amount of (unneeded) files our users have to download. You may want to consider naming patches you create yourself just to get your package to build with a version-specific name, such as mypkg-1.0-gentoo.diff, or more simply, 1.0-gentoo.diff. Also note that the gentoo extension informs people that this patch was created by us, the Gentoo Linux developers, rather than having been grabbed from a mailing list or somewhere else. Again, you should not compress these patches.

Consider prefixing or suffixing (such as mypkg-1.0) every file you put into the files/ directory, so that the files used for each individual version on an ebuild are distinguishable from one another, and so that the changes between different revisions are visible. This is generally a really good idea :). You may want to use a different suffix if you wish to convey more meaning with the patch name.

If you have many files that should go into the files/ directory, consider creating subdirectories such as files/1.0/ and putting the relevant files in the appropriate subdirectory. If you use this method, you do not need to add version information to the names of the files, which is often more convenient.

Touching other developers ebuilds

Usually you don't just change other developers ebuilds without permission unless you know that developer does not mind or if you are part of the project involved in maintenance (this information can typically be found in metadata.xml). Start with filing a bug or trying to catch them on IRC or via email. Sometimes you cannot reach them, or there is no response to your bug. It's a good idea to consult other developers on how to handle the situation, especially if it's a critical issue that needs to be handled ASAP. Otherwise a soft limit of 2 to 4 weeks depending on the severity of the bug is an acceptable time frame before you go ahead and fix it yourself.

Respect developers' coding preferences. Unnecessarily changing the syntax of an ebuild can cause complications for others. Syntax changes should only be done if there is a real benefit, such as faster compilation, improved information for the end user, or compliance with Gentoo policies.

Stabilizing ebuilds

Only architecture maintainers for a given architecture should mark packages as stable on that architecture. The maintainer of the package should always be contacted just in case there are reasons not to do so. The exception to this is if you are part of an architecture team, in which case you may mark the package stable for that architecture. If you are not part of an architecture team, you should consult the guidelines below; if the architecture you are looking for is not listed then please consult the relevant lead.

You should never stabilize packages on architectures for which you cannot test and instead you should file a bug to the relevant architecture team, such as sparc@gentoo.org asking them to stabilize the ebuild. Alternatively, you may be able to find Gentoo developers on IRC who could help you with your request.

It is best to not use arch-maintainers@gentoo.org, adding architecture teams onto a bug's CC list individually instead. That way teams can remove themselves from the list when they are done, giving a clear indication of which teams still have to stabilize a package.

Stabilization rules

SPARC: You must have prior permission from the arch lead. Usually we expect you to be on the sparc alias for QA reasons, although other arrangements can be made if you will only be working with a small group of packages.

ALPHA: Maintainers may keyword their own packages but are reminded to inform the Alpha team if they can help out with testing and keywording packages so the team can keep an eye out for possible keywording mistakes.

Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short on manpower, so it's best if you avoid opening stabilization bugs for them unless it is absolutely necessary (eg, a reverse dependency for your package). More about keywording policies can be found in the keywording section.

Some architectures (like m68k, mips, s390, sh) do not maintain a stable keyword. So there is no use in marking a package stable for one of these architectures.

Upgrading ebuilds

New ebuilds should rarely go in with "arch" keywords and even if they do not, the package must be tested on any architectures listed in the KEYWORDS variable of the new ebuild.

Exceptions to the no "arch" rule are major bug fixes, or security fixes. If the previous version of the ebuild contains KEYWORDS which you cannot test for, you should downgrade them: turn any "arch" keyword to "~arch". If you think that your package may not work at all even on "~arch" then it is best to leave the keyword out and request testing from the relevant team: if you are to do this, you must file a bug to the team in question.

If a new version introduces new dependencies which are not available on some architectures, then you should file a bug or ask on IRC before you upgrade the package. If you really need to get the ebuild added in a hurry, for example, for a security fix, then you should drop any KEYWORDS which are causing problems and CC the relevant architectures on the bug - you should file a new bug to the architecture in question regarding this if no bug is already available.

If there are no new dependencies, do not remove keywords if your commit fails with repoman - please try a full git pull and if you still have problems, then commit with repoman -I and file a bug to the broken architecture, noting it in your git commit message.

Moving a package

Moving a package in the tree requires several operations. Firstly, the package directory needs to be moved to the correct category using git mv. After this, a new entry needs to be added to the latest file in profiles/updates/ in the following format:

move old-category/package-name new-category/package-name

Following the update entry, ebuilds that have a dependency to this package (in other words, the reverse dependencies of the package to be moved) need to be updated properly.

Next is checking the files under profiles/ such as profiles/package.mask and update them to reflect the ebuild move. Various eclasses automatically provide some of the dependencies upon inherit, so the files under eclass/ should be checked and updated properly. If the package metadata.xml has tags with restrict attribute, they should be updated to reflect the move. The metadata.xml for various packages may contain references to the package being moved using the <pkg> tag which need to be updated accordingly as well. Lastly, the titles of the open bugs related to the package should be updated.

Here is an example where the package net-misc/fwbuilder is transparently moved to net-firewall/fwbuilder:

  1. Issue git mv net-misc/fwbuilder net-firewall/fwbuilder
  2. Add the following entry to the latest file in profile/updates/:

    move net-misc/fwbuilder net-firewall/fwbuilder

  3. Update the reverse dependencies of the package
  4. Update profiles/package.mask and other related files under profiles/
  5. Check the eclasses that may be referencing the package
  6. Update all the metadata.xml files which contain a reference to this package using the <pkg> tag or the restrict attribute.
  7. Stage all the changed files using git add. For example: git add profiles/package.mask
  8. Commit all the changes in one commit using: git commit --gpg-sign
  9. Update any news items referencing the package in a Display-If-Installed header or in the item's body (and increment their Revision).
  10. Update any open bugs related to the package

It is very important to commit all the changes in a single commit to ensure that no breakage occurs. The commit message should follow a format similar to the following:

commit d391643289097344a0b18ab2665bb26198a0e3a1
Author: Guilherme Amadio <amadio@gentoo.org>
Date:   Tue Nov 3 20:26:52 2015 +0100

  media-fonts/nanumfont: renamed to media-fonts/nanum

Changing ebuild's SLOT

The process for changing the ebuild's SLOT is very similar to the previous process. Besides changing the SLOT in the ebuild file, you also need to create a new entry in profiles/updates/ in the Portage tree in the following format:

slotmove app-text/gtkspell 0 2

Make sure that you have fixed all the reverse dependencies and that you have updated every file in profiles/ directory that happens to contain an entry which may be affected by your change.

Removing ebuilds

When removing an ebuild make sure that no dependencies in Portage are broken due to the removal - additionally, your git commit message should explain clearly why the ebuild is being removed from the git repository.

If you need to remove ebuilds, make sure you do not accidentally remove the newest/only stable ebuild for any architecture. If you would like to get a newer version marked stable, then please file a bug or ask on IRC.

You should also not cause an unnecessary downgrade for any "~arch" when removing ebuilds - instead, it is best to get the newest version marked "~arch" first and then remove redundant versions of the ebuild.

Removing a package

When removing packages follow these steps:

  1. Make sure that no dependencies in Portage are broken due to the removal
  2. Send last rites to gentoo-dev-announce and gentoo-dev
  3. Mask the package
  4. Wait 30 days (or more)
  5. Remove from the git tree unless the reason for removal has been fixed
  6. Remove package.mask entry
  7. Remove the <pkg> tags referencing this package in the metadata.xml files of other packages.
  8. Close open bugs as WONTFIX

Here is a list of commands that will delete dev-util/pmk from the tree:

# cd dev-util
# git rm -rf pmk
# git commit --gpg-sign

An example commit message is shown below:

commit e0bbcf8291501dc7de6b4b120d4372061367dd7a
Author: Michael Palimaka <kensington@gentoo.org>
Date:   Fri Jan 29 07:11:01 2016 +1100

  dev-util/pmk: remove last-rited package

  Gentoo-bug: 541522

Conflicting files

When you encounter a package that is trying to install files that are already provided by another package (detectable with FEATURES=collision-protect for example) you have to fix this situation before you can commit the ebuild or, if you encounter this with an existing package, file a bug about that package (see below for a few exceptions). The reason file conflicts are critical is because if "foo" provides the file /usr/bin/example and "bar" is going to overwrite it, and later "bar" is unmerged, Portage will remove /usr/bin/example and it is therefore likely it will break "foo".

The most obvious fix is to add a blocking dependency to both packages that want to install that file, so they can't be installed at the same time. But unless there are also other reasons for those packages to block each other you should avoid this if possible and rather fix the package, which could include one or more of the following steps:

In some cases conflicting files can't be really fixed or aren't critical, currently known exceptions are Perl module manpages (overwriting the ones from Perl itself) and CONFIG_PROTECT'ed files (which should still be fixed, but aren't critical as Portage won't overwrite them).

Homepage unavailable

If the HOMEPAGE of your package seems to be unavailable or it never existed at all, please set the HOMEPAGE variable in every ebuild to https://wiki.gentoo.org/wiki/No_homepage