Gentoo Development

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

Overlays and layman

• 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

General Ebuild development guide

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

• 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. You must be root when running ebuild digest.

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

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

use doc && dodoc doc/manual.pdf

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

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

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

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

Java Ebuild writing guide

• Official Guide

• ANT_TASKS can be set (and should be set) manually on the ebuild, but only in src_compile() or src_test(). Note that ANT_TASKS basically controls the Ant class path, which is different than the one for javac. So -Dgentoo.classpath, for example, does not affect Ant classpath. Nor does it affect the classpath for the <java> task (although this seems to be in development). Currently it only interacts with the classpath for the <javac> task.

• The jar names should not contain version number, if you need to rename them, there is an eclass for that: java-pkg_newjar.

• If a package provides differents APIs, the package should be always SLOTed based on the version of the API.

• If you use eclasses such as java-pkg_getjars twice, the jars will be recorded twice in package.env.

• If some library needs to be used only during the build, use java-pkg_getjars --buildonly. The dependency won't be recorded into package.env.

• To get the dependencies of one library (during ebuild writing), use --with-dependencies. Note that this is a java-config option.

• Inheriting java-ant-2 adds dev-java/ant-core in DEPEND, so no need to add it explicitly.

• If a package installs an Ant task, it should be registered in src_install() with java-pkg_register-ant-task. There should also be an RDEPEND on >=dev-java/ant-core-1.7.0.

• If the package uses an Ant build system with hardcoded classpath inside the build.xml (example: classpath="lib/helper_library.jar"), the best way currently it to use the eclass java-pkg_jarfrom to create a symlink to the Gentoo installed version.

• The following eclass can be used to rewrite an Ant buildfile with your own classpath. The program actually used is /usr/bin/xml-rewrite-2.py, and you can look at the source code to see exactly what can be done.

java-ant_xml-rewrite -f build.xml --change -e java -a classpath -v "${sitemesh_classpath}" || die

Note that the file that has to be rewritten must be valid XML. If it is an included file, just rewrite the file that includes it. It will just get embedded in the included file.

• Report bugs in Java packages both in the main tree and the java-overlay. Don't report bugs in the experimental overlay though.

• When compiling Java code, there are two important options to Ant/javac: -source and -target. -target is the version of the bytecode that will be produced. -source is the version of the Java source. Note that necessarily, target >= source.

• Beware the value of the property build.compiler in Ant files. It can produce bugs, this value may be safely switched to "modern" most of the time.

• Creating a launcher is very easy - just use the java-pkg_dolauncher eclass. Just be careful that if you use any argument at all (such as --jar or --main), you will also need to specify the name of the launcher as the first argument).

• USE flags that should be handled by Java eclasses functions (such as doc and source) should be in the variable JAVA_PKG_IUSE rather than IUSE. Note that this variable must be defined at the top of the ebuild.

• Use ant-nodeps if you need optional Ant tasks that don't need any third party library.

Java Development Guide (Python)

• When working with java-config (the main program used by the Gentoo system), don't forget that it initially imports source files from the system location. If you are doing development make sure the correct Python source files are used. This is also true for depend-java-query.

• The class EnvironmentManager maintains a list of Virtual Machines and Packages available.

• The class VersionManager deals with the version string parsing and comparisons. version_satisfies(self, dependencyString, virtualMachine) is useful: given a dependency string and a VM, it returns True if the VM satisfies the dependency string.

• A dependency string for java-config is of the form >=virtual/(jdk|jre)-1.4. See Python source file VersionManager.py for the exact regular expression used.

• java-config can determine the current active VM via the environment variable GENTOO_VM.

• depend-java-query is the program used to find the VM needed at build time; gjl is the Gentoo Java Launcher. It gets invoked by the packages that have a launcher installed. Both programs then call java-config afterwards.

• The eclass currently coded for Java virtuals only deal with the writing of the correct configuration files to disk.

• Doing development with java-config-2 is possible easily if you symlink the program to your development space. Eg:

ln -s /home/elvanor/development/gentoo/virtuals/depend-java-query /usr/bin/depend-java-query

• Warning, depend-java-query needs the -p (--need-virtual) option before the --get-vm one. Else it will be ignored.

Specific Ebuilds

• Ebuilds Notes