[ << ] [ < ] [ Home ] [ > ] [ >> ]

1. Ebuild HOWTO

• The Portage tree
• Ebuild scripts
• File system Locations
• The Portage scripts and utilities
• Package Dependencies
• Testing and deploying

1.a. The Portage tree

Introduction

The Portage tree is typically found at /usr/portage and is organized in a hierarchical structure consisting of category directories, followed by specific package directories. Here's an example; you can find the util-linux-2.11y.ebuild file in the /usr/portage/sys-apps/util-linux directory. There may be several other versions of util-linux ebuilds alongside util-linux-2.11y.ebuild. This is because all ebuilds for a particular package (regardless of version), share the same mycat/mypkg directory in /usr/portage, unless you have portage overlays installed.

Checking Out the Portage Tree from CVS

If you are unfamiliar with the CVS system, please read the CVS Tutorial for more information.

The Portage tree can be found in the gentoo-x86 module of the Gentoo Linux tree. To check out the module (about 350 megabytes) you would first set up CVS via the above guide, then check out the gentoo-x86 module.

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 NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), 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 put onto the Gentoo mirrors 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 Portage CVS tree. If you need to do this in another CVS tree, for example, if you need to add a small PNG graphic for whatever reason, be sure to add it to CVS by using the -kb option, like so:

# cvs add -kb myphoto.png

The -kb option tells CVS that myphoto.png is a binary file and should be treated specially. For example, merging the differences between two different versions of this file should not be allowed to happen, for obvious reasons. Also, speaking of merging changes, any patches you add to Portage should generally not be compressed. This will allow CVS 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 CVS, all developers should use repoman commit instead of cvs commit to submit their ebuilds. Before committing, please run repoman full to make sure you didn't forget something.

CVS 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 update the ChangeLog before you commit.
• Always commit the updated package.mask before the updated package, in case conflicts occur while you commit package.mask.
• 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, ChangeLog, patches and metadata.xml all in one go to avoid breaking users' installations.

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 because CVS does not play well with binary files.

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.

1.b. Ebuild scripts

Introduction

Ebuild scripts are the basis for the entire portage system. They contain all the information required to download, unpack, compile and install a set of sources, as well as how to perform any optional pre/post install/removal or configuration steps. While most of Portage is written in Python, the ebuild scripts themselves are written in bash, since using bash allows us to call commands as we would from the command-line. One of the important design principles behind ebuild scripts is to have the commands therein be analogs of those one would type on the command-line if installing the package manually. For this purpose, using bash syntax is a very good thing.

Ebuild scripts are interpreted by the ebuild and emerge commands. Think of the ebuild command as a low-level building tool. It can build and install a single ebuild, but no more. It will check to see if dependencies are satisfied, but it will not attempt to auto-resolve them. On the other hand emerge is a high level engine for ebuild, and has the ability to auto-merge dependencies if needed, perform pretend merges so that user can see what ebuilds would be merged, and more. Generally, emerge blows ebuild out of the water except in one area. With ebuild, you can incrementally step through the various parts of a package emerge (fetching, unpacking, compiling, installing and merging) one at a time. For developers, this is an invaluable debugging tool, because it allows you to isolate ebuild problems to a specific portion of the ebuild.

Naming ebuild files

Ebuild file names consist of four logical subsections:

pkg-ver{_suf{#}}{-r#}.ebuild

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. For example: foo-1.0, bar-2.4.6.

The third subsection, {_suf{#}}, is optional and may contain one of these predefined suffixes, listed in least-recent to most-recent order:

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.

If you make non-trivial improvements to an existing ebuild file, you should copy the ebuild file to a new file with the revision number incremented by 1. Remember to always make mentions of your changes in the ChangeLog when you bump a revision and in your CVS commit message; not doing so is against policy.

... and I suppose that we actually have a fifth section of the ebuild name as well -- the .ebuild extension itself.

Contents of an ebuild file

This section is an introduction to ebuilds. For the full listing of everything possible in an ebuild, there is a manpage which talks about the internal format, variables, and functions in an ebuild script: man 5 ebuild.

Headers

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

The first three lines should look something like this:

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

Variables

The first part of every ebuild file is made up of a number of variables. See the devmanual for information on the different variables.

Functions

There are a number of different functions that you can define in ebuild files that control the building and installation process of your package.

Helper Functions

You can also use the following helper functions in your ebuilds.

Helper Functions provided by eutils.eclass

You can use the following helper functions that are provided by the "eutils" eclass in your ebuilds. You must make sure that inherit eutils is present for these functions to work.

Helper Functions provided by flag-o-matic.eclass

You can use the following helper functions that are provided by the "flag-o-matic" eclass in your ebuilds. You must make sure that inherit flag-o-matic is present for these functions to work. You should never modify any compiler settings directly, instead please use flag-o-matic to perform any actions such as filtering flags that cause trouble.

Helper Functions provided by toolchain-funcs.eclass

You can use the following helper functions that are provided by the "toolchain-funcs" eclass in your ebuilds. You must make sure that inherit toolchain-funcs is present for these functions to work. You should never explicitly specify any compiler or binutils settings directly, instead please use toolchain-funcs to specify compilers and binutils.

The purpose of using the below functions is to support cross-compiling and the icc compiler. These should be used whenever a package explicitly uses gcc, g++, ld, ranlib or any of the below tools. In general packages that use autoconfiguration tools detect cross compiling automatically and do not need the following functions.

Rules for writing an ebuild file

Since ebuild files are really just shell scripts, you should use your editor's shell-script mode for editing them. You should use proper indentation, using only tab characters -- no spaces. Make sure you set up your editor to put tab stops at 4 spaces. Always make sure you use braces around your environment variables; e.g. ${P} instead of just $P.

Long lines are wrapped with ' \', thus:

./configure \
--prefix=/usr || die "configure failed"

For further details, refer to skel.ebuild (usually residing in /usr/portage).

If you use Vim for ebuild/eclass editing, the default Gentoo vimrc file, /etc/vim/vimrc, already ensures that correct indentation and filetype settings are used for ebuild and eclass files. For better results, including special syntax highlighting for ebuild keywords, emerge app-vim/gentoo-syntax.

On non-Gentoo systems, you can obtain similar results by using the following lines in your vimrc, or better yet by installing the gentoo-syntax scripts which can be downloaded from Gentoo mirrors.

au BufRead,BufNewFile *.e{build,class} let is_bash=1|setfiletype sh
au BufRead,BufNewFile *.e{build,class} set ts=4 sw=4 noexpandtab

If you're using Emacs, you should emerge app-emacs/gentoo-syntax (for GNU Emacs) or app-xemacs/gentoo-syntax (for XEmacs). These packages provide Emacs major modes for automatic indentation and syntax highlighting of ebuilds and other Gentoo specific file types.

If you're using nano, then you're in luck! Just edit /etc/nanorc and uncomment the section referring to ebuild's.

USE Variables

The purpose of USE variables is to allow you to configure Portage to globally and automatically enable or disable certain optional build-time features. Here's an example. Let's say you're a GNOME fan, and you'd like any ebuild that has the option of compiling-in optional GNOME support to do so. In this case, you'd add gnome to the USE variable in /etc/make.conf, and then Portage will automatically add optional GNOME functionality to packages if it is available. Likewise, if you don't want optional GNOME features to be added to your ebuilds if they are available, simply edit /etc/make.conf and make sure that gnome is not set in the USE variable. Gentoo Linux has an almost overwhelming number of USE options, allowing you to have your system configured exactly the way you want it.

In your own ebuilds, you can check whether a USE variable is set by using the use <variable> command. You would normally use this command as follows:

if use X; then
  # Commands specific to X...
fi

USE variables can also be used to set dependencies. For example, you may only want to require a package if a certain USE variable is set. This is done by using the syntax flag? ( mycat/mypackage ) in the DEPEND variable for your ebuild. In this example, mycat/mypackage will only be required if flag is present in USE. It is also possible to specify what dependency should be used if some USE flag is set, and what dependency to use if it is not set: flag? ( mycat/mypackage) and !flag? ( othercat/otherpackage ). In this case, if flag is not set, othercat/otherpackage is used instead of mycat/mypackage. Make sure that your ebuilds use this syntax and not Bash if's. Bash conditionals interfere with Portage's dependency caching, and the use of them will break your ebuild.

Here's an important tip about how to use USE. Most of the time, a package will have a ./configure script used to perform configuration steps. Generally, if your ebuild uses ./configure, any optional build-time functionality will be enabled or disabled by passing the appropriate arguments to the ./configure command. Here's the best way to handle this:

DEPEND="X? ( >=x11-base/xfree-4.3 )
mysql? ( >=dev-db/mysql-3.23.49 )
apache2? ( >=net-www/apache-2 )
!apache2? ( =net-www/apache-1* )"

src_compile() {
  econf \
    $(use_enable X x11) \
    $(use_enable mysql) \
    || die "Error: econf failed!"
  emake || die "Error: emake failed!"
}

This approach has a very nice result. We don't have to worry about what the default setting is for mysql or X (enable/disabled), we explicitly tell econf what we want it to do based upon the USE variable. Not to mention it's quite clean in terms of readability :).

Occasionally, ebuilds will have conflicting optional features. Checking for these conflicts and returning an error is not a viable solution. Instead, you must favor one of the features over the others. As to which, consult upstream (what they use as typical default), or consider which option provides more common functionality, or just flip a coin. One example comes from the msmtp ebuilds. The package can use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS has a lot more features compared to OpenSSL, it is favoured:

src_compile() {
    local myconf

    if use gnutls ; then
        myconf="${myconf} --enable-ssl --with-ssl=gnutls"
    elif use ssl ; then
        myconf="${myconf} --enable-ssl --with-ssl=openssl"
    else
        myconf="${myconf} --disable-ssl"
    fi

    econf \
        # Other stuff
        ${myconf} \
        || die "configure failed"

    emake || die "make failed"
}

To view a continuously updated table of USE variables, please go here.

1.c. File system Locations

Introduction to the FHS

The file system layout standards used in Gentoo Linux closely follow the FHS, short for File system Hierarchy Standard. A simplified description of the standard is given here; for a complete specification go to http://www.pathname.com/fhs/.

How to fit your packages into the file system

Usually, if the package uses autoconf and automake, the default installation destinations are mostly correct, with a few exceptions:

• If you're installing a program into /bin, /sbin, /usr/bin, or /usr/sbin, then the program's corresponding man page should be installed into the /usr/share/man tree. This can often be accomplished by specifying a ./configure --mandir=/usr/share/man in the ebuild.
• GNU info files should always be installed to /usr/share/info, even if the info files are about X11, GNOME or KDE-specific programs or tools. Make a note: /usr/share/info is the only official location for GNU info files. Since many ./configure scripts default to installing GNU info files in /usr/info, it's often necessary to call ./configure with the --infodir=/usr/share/info argument.
• Documentation files are installed in /usr/share/doc, into a subdirectory reflecting the name, version, and revision of the particular program. This applies to all programs: GNOME, KDE, X11 and console alike. However, some programs may install additional documentation and support files into a /usr/share hierarchy for their own purposes.
• X11-specific programs and libraries should always be installed into /usr, not directly into /usr/X11R6. We reserve the /usr/X11R6 hierarchy for the X Window System, Version 11 Release 6 itself. This is perhaps a more to-the-letter interpretation of the FHS than some other distributions have made.
• GNOME and KDE programs, similarly, should always be installed into /usr.

In general, you should have ebuilds install their files into the /usr tree. Some programs can be compiled and linked with or without GNOME, KDE, and X11 libraries, which can cause confusion. Our solution is to install everything into /usr which avoids ambiguity and needless complexity for ebuild authors. The location in which to install a program's files should not depend on the presence or absence of specific USE variables. Therefore, the ebuilds in the portage tree almost always install into the /usr hierarchy exclusively.

1.d. The Portage scripts and utilities

Public scripts

These are scripts used by the system-administrator to install and remove packages, and maintain the package database.

ebuild is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: ebuild path/to/package.ebuild command. The commands available are:

emerge recursively merges a package and all of its dependencies into your file system. This command has many options, try emerge --help for a list of them.

env-update updates the configuration files (including, but not limited to /etc/ld.so.conf and /etc/profile.env) to include changes made by installed packages.

Private Scripts and Commands

These are scripts you can use in your ebuild files to perform common tasks.

For you down and dirty people, look at the scripts themselves in /usr/lib/portage/bin.

1.e. Package Dependencies

Why dependencies are important

Portage is more than just a convenience script that gives you a unified way to build any one project (program, library) from source. It will also fetch and install any necessary dependencies if you take care to specify these in your ebuild.

In the official ebuilds, all dependencies have already been specified, so when you issue emerge net-www/mozilla/mozilla-1.0, Portage will insure that all libraries necessary for Mozilla to build and run are properly installed before Mozilla itself is built.

Portage even distinguishes between build-time dependencies and run-time dependencies. (Caveat: Currently, Portage installs all build-time and run-time dependencies and leaves it at that. At a later stage, it will be possible to trim your installation so that only the run-time dependencies are left installed).

How to Specify Dependencies in Your ebuild Files (a.k.a. DEPEND Atoms)

The DEPEND variable inside your foo-x.y.z.ebuild tells Portage about which packages are needed to build foo. The RDEPEND variable specifies which packages are needed for foo to run. RDEPEND should be set explicitly even if it's the same as DEPEND because in the future it defaulting to DEPEND is planned to be removed from Portage.

DEPEND="virtual/opengl
	dev-libs/libxml2"
RDEPEND="${DEPEND}"

This tells Portage that to build foo-x.y.z, the packages virtual/opengl (more on virtuals in a bit) and dev-libs/libxml2 are needed. It does not say anything about which version of opengl or libxml2 that are needed, which means "anything goes".

The "anything goes" is of course a bit scary, and will not work in the general case. But for libraries, which strive very hard to be 100% binary compatible all the time, it actually works. For other libraries, we can of course specify version dependencies.

>=sys-apps/bar-1.2
=sys-apps/baz-1.0

>= and = do what you would expect; sys-apps/bar version 1.2 or newer is okay (this means that sys-apps/bar-2.0 is okay), while sys-apps/baz version 1.0 is the only version that is accepted. For more information on the version schema of packages, see the section above on Naming ebuild Files.

Other methods of specifying version dependencies are as follows:

~sys-apps/qux-1.0
=sys-apps/foo-1.2*
!sys-libs/gdbm

~sys-apps/qux-1.0 will select the newest portage revision of qux-1.0.

=sys-apps/foo-1.2* will select the newest member of the 1.2 series, but will ignore 1.3 and later/earlier series. That is, foo-1.2.3 and foo-1.2.0 are both valid, while foo-1.3.3, foo-1.3.0, and foo-1.1.0 are not. Please note that foo-1.22.3 will also match, which can become a problem at times.

!sys-libs/gdbm will prevent this package from being emerged while gdbm is already emerged.

Important Notes

There are many things that go wrong with the DEPEND and RDEPEND variables. Here are some important points to follow when you write the dependencies.

• 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*.
• 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 dependencies on the same line. It makes it ugly to read and hard to follow.
• GTK: Always use =x11-libs/gtk+-1.2* for GTK+1 apps.

Additionally, it is important to ensure that all the dependencies are complete for your package:

• 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.

For all the latest details about these DEPEND Atoms, please see the section 5 manpage on ebuilds: man 5 ebuild.

1.f. Testing and deploying

ChangeLog

Whenever you update (or write a new) an ebuild, you must also update its (or create a new) ChangeLog. The skel.ChangeLog contains a sample ChangeLog that you can use as a basis.

The purpose of the ChangeLog is to document what is being done, why it is being done, and by whom. This allows both developers and users to trace the changes made in an easy way.

The ChangeLog is primarily targeted at users, so be sure to keep your writing short, to the point, and avoid getting verbose about the internal technical details.

Storing your own ebuilds locally

In order to be able to test your ebuilds and let Portage know about them, you must place those in a known directory. Portage will use the PORTDIR_OVERLAY variable which you can define in /etc/make.conf. You should set this variable to your directory (e.g. /usr/local/portage).

In that directory, you must use the same structure (and categories) as in /usr/portage.

Using this PORTDIR_OVERLAY, your ebuilds remain on your system, even after an emerge sync, and they are still known to Portage.

Testing the package

Have a think about how you will test whether this package works. Sometimes the developers have already included a make test or make check routine that will test the basic functionality of the package. If so, then running FEATURES=test ebuild foo-x.y.z.ebuild test will execute it. If it is broken try to fix it so that it works (and submit the patch to the upstream developers).

If this is not the case consider adding a src_test routine to your ebuild. This is executed before the src_install routine and can be very helpful for testing the program works across various architectures. The architecture developers will appreciate if you add a routine here so that they do not require knowledge of the package's functionality.

Please keep in mind the general requirements of an ebuild here. The src_test routine must not be interactive. If the test routine depends on other packages use the test USE flag to specify the optional compile time DEPENDancies. Also, please note that src_test routines are not recommended for graphical X applications as the user running portage often cannot run them successfully.

Useful testing tools

We have a few useful tools to help you with writing and maintaining your ebuilds.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.