1.  Common Ebuild Writing Mistakes

Introduction

Here is a list of common ebuild mistakes that are common in user-submitted ebuilds. Please make sure the ebuilds you submit don't violate any of these. Before submitting any ebuilds, make sure you read the (Gentoo ebuild Development Policy) and the (Gentoo ebuild HOWTO). Also, make sure you read a couple (eg. more than one or two) of the ebuilds in the tree to make sure you know the style that ebuilds are written in.

Also it would be useful to read a couple of ebuilds that use eclasses and understand how to use them by reading the (Eclass HOWTO). Finally, you must read the Contributing Ebuilds Guide carefully before submitting your ebuild(s).

Missing/Invalid/Broken Header

When you submit your ebuilds, the header should be exactly the same as the one in /usr/portage/skel.ebuild. Most importantly, do not modify it in any way and make sure that the $Header: $ line is intact.

The first three lines must look like this:

# Copyright 1999-2004 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

Only if you are submitting a patched or version bumped ebuild, should you not need to modify the $Header: $ line. But the line must be present. When we check the ebuild into CVS, it will modify that header with the appropriate version and date information. So there is no need for you to manually modify it.

IUSE Missing

By far the most common omission is the IUSE variable. You must (according to the (Gentoo ebuild HOWTO)) include the IUSE variable even if there are no USE flags in use. If there are no USE flags supported, then just add the following:

IUSE=""

Redefined P, PV, PN, PF

You should never redefine those variables. Always use MY_P, MY_PN, MY_PV, P0, etc. See other ebuilds that do it in portage for more information. Most ebuilds use bash "Parameter Expansion". Please read the man page for bash to understand how "Parameter Expansion" works.

By the way, if you find a package that re-defines it, don't copy it. Submit a bug about that ebuild.

Including version numbers in SRC_URI and S

You should try not to include version numbers in the SRC_URI and S. Always try to use ${PV} or ${P}. It makes maintaining the ebuild much easier. If a version number is not consistent with the tarball/source, then use MY_P. An example dev-python/pyopenal fetches a tarball called PyOpenAL, so we redefine it like:

MY_P=${P/pyopenal/PyOpenAL}
SRC_URI="http://oomadness.tuxfamily.org/downloads/${MY_P}.tar.gz"
S=${WORKDIR}/${MY_P}

DEPEND has syntactical errors

There are many things that go wrong with user submitted DEPEND and RDEPEND fields. Here are some important points to follow when you write the dependency part.

• Always include the CATEGORY.
  For example, use >=x11-libs/gtk+-2 and not >=gtk+-2.
• Do not put an asterisk (*) for >= dependencies.
  For example, it should be >=x11-libs/gtk+-2 rather than >=x11-libs/gtk+-2*.
• GTK specific. Always use =x11-libs/gtk+-1.2* for GTK+1 apps.
• Never depend on a meta package.
  So don't depend on gnome-base/gnome, always depend on the specific libraries like libgnome.
• One dependency per line.
  Don't put multiple dependency on the same line. It makes it ugly to read and hard to follow.

DEPEND is incomplete

This is another very common error. The ebuild submitter submits an ebuild that "just works" without checking if the dependencies are correct. Here are some tips on how to find the correct dependencies.

• Look in configure.in or configure.ac
  Look for checks for packages in here. Things to look out for are pkg-config checks or AM_* functions that check for a specific version.
• Look at included .spec files
  A good indication of dependencies is to look at the included .spec files for relevant deps. However, do not trust them to be the definitive complete list of dependencies
• Look at the application/library website
  Check the application website for possible dependencies that they suggest are needed.
• Read the README and INSTALL for the package
  They usually also contain useful information about building and installing packages.
• Remember non-binary dependencies such as pkg-config, doc generation programs, etc.
  Usually the build process requires some dependencies such as intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those are clearly stated.

LICENSE Invalid

Another common mistake users make when submitting ebuilds is supplying an invalid license. For example, GPL is not a valid license. You need to specify GPL-1 or GPL-2. Same with LGPL. Make sure the license you use in the LICENSE field is something that exists in /usr/portage/licenses. As a tip, check the COPYING in a source tarball for the license. If a package does not specify it uses GPL-1 or GPL-2, it is very likely it uses GPL-2.

If the license for the package you submit is unique and not in /usr/portage/licenses/, then you must submit the new license in a separate file.

Untested ARCHs in KEYWORDS

Please do not add other ARCHs into KEYWORDS unless the ebuild has been tested on that ARCH. Also all new ebuilds should be ~x86 or whatever architecture it is. Make sure when you bump a version, the stable KEYWORDS are all marked as ~.

SLOT missing

Make sure you have the SLOT variable in the ebuild. If you don't plan to use it, don't remove it. Put in:

SLOT="0"

DESCRIPTION and HOMEPAGE wrong

Please check the if the HOMEPAGE variable is right and leads users to the right page if they want to find out more about the package. And make sure the DESCRIPTION is not overly long. Good descriptions will describe the main function of the package in a sentence.

Wrongfully used spaces instead of TABS

It is no fun reformatting lines of ebuilds because the submitter did not follow the guidelines to use TABS rather than spaces. So please use tabs!

Trailing whitespace

I'm often guilty of this. Remember to run repoman over your ebuilds so it can tell you if there is trailing whitespace at the end of lines or on empty lines.

Adding redundant S=${WORKDIR}/${P}

If S=${WORKDIR}/${P}, then you should not add it to your ebuild. This is implied already, you should only add it if it is something other than ${WORKDIR}/${P}.

Documentation missing

If your package has documentation, make sure you install it using dodoc or in /usr/share/doc/${PF}. Remember to check for errors when running dodoc/doins.

1.  Common Ebuild Submission Mistakes

Introduction

Please submit ebuilds properly by following the Contributing Ebuild HOWTO on the Gentoo Docs Page.

Tarball'ing an ebuild

Please please please do not attach ebuilds as tarballs. Attach patches separately as well so we can easily examine them.

Inlining Ebuilds

Don't cut and paste an ebuild into bugzilla's comment field.

No description on what the package is

Please let us know what the package is, and fill in the URL with the home page of the application, if any exists.

Package updates without changing the ChangeLog

If you submit a package update, then make sure you explain what changes you made to the ebuild. For example if a package introduces a new features/option and you use a USE flag, list it in your bug. Don't make us hunt for it.

It is wise to submit a diff for a package update rather than the whole ebuild. The best way to generate it would be:

$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.diff

Submitting unchanged ebuilds for version bumps

If you are submitting a new version for a package in portage, make sure the existing ebuild works and make sure changes are incorporated in the new ebuild (such as added documentation.) If there are no required changes to the ebuild from the previous version, then don't attach the ebuild. Just say so in the bug report that you copied the ebuild over and verified that the package works and installs properly.

1.  Comments and Suggestions

Comments, corrections and suggestions should go to Alastair Tse.