[ << ] [ < ] [ 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.

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 any ebuild, check bugs.gentoo.org for an ebuild corresponding to the ebuild you want to write, but that has not yet been put into the Portage tree. Go to bugs.gentoo.org, choose query; 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 which should be put onto the Gentoo mirrors so that people do not waste excessive amounts of bandwidth and hard drive space. Also, in general, it's not a good idea for developers to add binary (non-ASCII) files to CVS. However, if this is necessary (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 Mandrake or Debian for some examples.

Double-check the ebuild and cross it with the Common Gentoo ebuild Mistakes section.

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, then commit the ebuild, ChangeLog and license all in _one_ go, unless you want to break the 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. 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 diffs 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 sections:

The first section is the package name, which should only contain lowercase letters, the digits 0-9, and any number of single hyphen ('-'), underscore ('_') or plus ('+') characters. Some examples are util-linux, sysklogd, mod_php, and gtk+.

The second section 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 numbers separated by periods, such as 1.2 or 4.5.2 (although very long period-separated number sequences are supported), 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, etc.

The third (optional) section contains a special suffix; either _alpha, _beta, _pre (pre-release), _rc (release candidate), or _p (patch). Any of these suffixes may be immediately followed my a number; e.g., linux-2.4.0_pre10; Assuming identical version parts, an _alpha package is older than _beta, _beta older than _pre, _pre older than _rc, and _rc older than no suffix, no suffix older than any _p. This section is meant to reflect upstream versions only.

The fourth (optional) section of the package name is the Gentoo Linux-specific revision number, which is specified by -r#, where # is an 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 rev of a particular package is available.

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. Initial releases normally have no revision number, e.g. package-4.5.3, and are considered by Portage to have a a revision number of zero. This means that counting goes as follows: 1.0 (initial version), 1.0-r1, 1.0-r2, etc. Remember to always make mentions of your changes in the ChangeLog. You are in serious trouble if you do not do this, your CVS access may be revoked.

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

Contents of an ebuild file

Variables

The first part of every ebuild file is made up of a number of variables. They fall under 3 categories (and are marked below with these numbers):

• READ: variables you can utilize but never set
• MUST: variables you must always set
• OPT: variables that you should set

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.

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.

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 can put the following snippet at the bottom of .emacsrc file (for GNU Emacs) or init.el (for XEmacs) to make sure your using the correct settings when editing anything Gentoo-related.

(defun ebuild-mode ()
  (shell-script-mode)
  (sh-set-shell "bash")
  (make-local-variable 'tab-width)
  (setq tab-width 4))
(setq auto-mode-alist (cons '("\\.ebuild$" . ebuild-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.eclass$" . ebuild-mode) auto-mode-alist))

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. The use command prints out <variable> if it is present in the user's USE. 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 IFS. 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 :).

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.

DEPEND="virtual/glibc
        sys-libs/zlib"
RDEPEND="virtual/glibc"

This tells Portage that to build foo-x.y.z, the packages virtual/glibc (more on virtuals in a bit) and sys-libs/zlib are needed. It does not say anything about which version of glibc or zlib 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 central libraries like glibc, which strives 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.

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

1.f. Testing and deploying

ChangeLog

Whenever you update a (or write a new) 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.

Useful testing tools

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

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