Gentoo Development

Links

• Official handbook
• Ebuilds Notes

System configuration

General setup

• Your ~/.cvsrc file should contain the following:

cvs -q -z0
diff -u -b -B
checkout -P
update -d -P

• You should add FEATURES="test" to your make.conf file. Note that the test USE flag on the ebuilds is only used to trigger additional dependencies that may be required for testing. This test USE flag is automatically on if you have FEATURES="test", thus you cannot turn off tests per package via /etc/portage/package.use. It is even hard to turn off tests per package, the only way is manually emerging with FEATURES="-test" the problematic package.

Repositories (Main, overlays and layman)

• To check out the main tree (still in CVS):

cvs -d elvanor@cvs.gentoo.org:/var/cvsroot co gentoo-x86

• To change the location of your Portage tree, to test out an ebuild you just modified:

PORTDIR="/home/elvanor/development/org.gentoo/gentoo-x86/" emerge -a eclipse-ecj:3.4 

• Overlays are additional ebuilds repertories in addition to the main, stable Gentoo tree. As such they are useful for development activities or hosting of unstable ebuilds.

• layman is a tool for overlay management. It uses a list of overlays. This list is stored somewhere (generally on a remote server). The main configuration file for layman is /etc/layman/layman.cfg.

• When adding URI for overlay lists in that file, be sure to add a space or tab before every new line! This is mandatory, else layman won't parse the file correctly. I personally consider this a bug...

• Unofficial overlays can be listed with the -k (nocheck) switch:

layman -L -k

Creating a private corporate overlay

• To secure the distribution files transfers, you need to use SSH. A possible way is to change the FETCHCOMMAND that Portage uses to fetch the files. By default Portage uses wget that does not support sftp / scp, however curl does:

FETCHCOMMAND="/usr/bin/curl -f -L -u root: --key /etc/portage/com.shoopz.distfiles_dsa --pubkey /etc/portage/com.shoopz.distfiles_dsa.pub -o
    \"\${DISTDIR}/\${FILE}\" \"\${URI}\"
RESUMECOMMAND="/usr/bin/curl -f -L -u root: --key /etc/portage/com.shoopz.distfiles_dsa --pubkey /etc/portage/com.shoopz.distfiles_dsa.pub -C - -o
    \"\${DISTDIR}/\${FILE}\" \"\${URI}\""

Note that it seems Portage uses the portage user when performing the fetch. Thus the key you will create to authorize distfiles transfers needs to be readable by the portage user.

• The -L option tells curl to follow redirects (HTTP 301, 302 status codes).
• You can then use scp:// scheme in your ebuilds for SRC_URI. You also need to set RESTRICT="mirror".

Useful tools

• pkg-config is a tool that is used to keep trace of the configuration and install options of packages. For example, it can gives you the C flags options, or the value of a specific variable (sdkdir for xulrunner). It creates *.pc files that are stored in /usr/lib/pkgconfig (on Gentoo). You query these files with the command-line pkg-config tool.

• Use repoman (which is included as part of Portage) as a QA tool. It will report basic errors in ebuilds. Adjust manually PORTDIR and PORTDIR_OVERLAY environment variables if need be.

• Currently you cannot use repoman commit with several directories, it will always act in the current directory.

General Ebuild development guide

• If you write a simple ebuild, you still have to place it in the main Portage tree or in an overlay to install it via Portage.

• Emerge app-portage/gentoolkit-dev which contains several utilities needed when developing on Gentoo.

• The PORTDIR environment variable controls the location of your Portage tree.

• Patches must be kept in the files/ directory of the ebuild location if they are small. They should not be compressed.

• Create a patch in the following way:

diff -u original-file.c modified-file.c > packagename-1.2.5-file.patch

Note that it is better to apply patches from the "${S}" directory. That means you have to create the patch in the top-level directory. One way to proceed too is to duplicate the whole source tree and create the patch with the -r (recursive) flag to diff. Note however that patches are a pain to maintain when doing version bumps. Especially if a patch is applied to a set of files. Consider using sed if you can.

• Apply it like this (in an ebuild):

epatch "${FILESDIR}/${P}-file.patch"

• Always use the program echangelog to document your changes. When you're using an overlay, use echangelog-tng (from the package overlay-utils). UPDATE: It seems echangelog-tng no longer exists and its functionality has been merged into echangelog. Set the environment variable ECHANGELOG_USER:

export ECHANGELOG_USER="Jean-Noël Rivasseau <elvanor@gmail.com>"

When creating or copying a new ebuild, the ChangeLog file should be deleted. Once echangelog is ran, it will be created and then can be added to CVS / SVN.

• Naming Rules: Use syntax like package-1.1_rc2. package-1.1-rc2 is an error. If you create a tarball from a Subversion checkout, name it package-1.1_pre1536 or package-1.1_pre20070628 (revision number or date).

• To clean the temporary work dir, or if anything goes strange, use ebuild clean command.

• To get the latest version of an installed package, you can use best_version. It will work somehow with SLOTs - you can specify stuff like

best_version=dev-java/package-2.5.6*

best_version is an helper function.

• All packages should specify a slot. Those that don't need slotting specify SLOT="0".

• For metadata.xml, use the skeleton in /etc/portage/skel.metadata.

Manifests

• ebuild myebuild-1.0.ebuild digest will create the manifest for you. It must be able to access the distribution file. If the SRC_URI does not work yet, put the distfile in /usr/portage/distfiles directly.

• The "--force" option will prevent ebuild from marking the local distfile as invalid if it does not match an existing manifest entry. Usually you should not use it, except if you are also upstream for the ebuild you are writing, and you just changed the distfile.

Variables

• A list of important variables available when writing ebuilds:
  • ${S}: Path to the temporary build directory.
  • ${D}: Path to the temporary install directory.
  • ${P}: Package name and version.
  • ${PV}: Package version.

• The RESTRICT variable can be useful too. In particular RESTRICT="mirror" prevents Portage from trying to fetch the file from common Gentoo mirrors. This can be useful for private ebuilds with restricted distribution files.
• RESTRICT="test" should be used to disable failing tests.

Versions

• The "*" symbol cannot be used with >= style syntax in DEPEND or RDEPEND; only with "=".
• SLOT dependencies (since EAPI 1) are possible with the ":" syntax.
• More information.

Install Step (src_install)

• doins will NOT respect file permissions. You need to use doexe or dobin if you need to install executable files.
• doins will also act strangely with respect to empty directories. It may not create them. In this case you should use dodir or cp -r to copy a hierarchy of directories to the image install location.
• Changing permissions of files work normally using chmod.

Helper Functions

• dohtml should be used to install HTML documentation files. Note it accepts an "-r" recursive option for installing a directory.

• dodoc always acts even if doc USE flag is not set, thus write something like:

use doc && dodoc doc/manual.pdf

Also note that currently dodoc does not have an -r option, but it's planned for EAPI-3.

Profiles

• The best documentation to understand profiles is the PMS (Package Manager Specifications) right now. The drafts are available in PDF format.
• The new way of laying out profiles is arch/ia64. There is also default/linux/ia64. The default-linux directory seems to be deprecated.

Inheritance

• In a profile, the parent files reference other files that will add some data to the profile. For instance, /usr/portage/profiles/default/linux/x86/2008.0/desktop references /usr/portage/profiles/arch/x86, and even /usr/portage/profiles/base. Same for /usr/portage/profiles/releases and /usr/portage/profiles/targets.

Per package USE flag masking

• A globally masked USE flag can be enabled for a specific package by writing (here we take the real USE flag example):

media-libs/xine-lib -real

Note the "-".

Gentoo init scripts

• Writing basic init scripts in Gentoo is easy. Those scripts are ran via the /sbin/runscript.sh shell script. If you want to start a daemon, you should use the start-stop-daemon binary. It has options for starting a daemon, and kill older daemons via a pidfile and / or an executable name (see the man page).
• You cannot call exit() in your script. If the daemon you are launching kills the start-stop-daemon or runscript.sh processes, this will cause problems with Gentoo's init system.

Java Gentoo Development

• Some additional knowledge is required when writing Java-based ebuilds.

Upstream Actions

• Contacted Groovy ML to try to get an option to disable Maven entirely in the build.