How to Write Gentoo Ebuilds

Ebuild Structure

To create your own ebuild, you must start with the correct *.ebuild file. Your ebuild file is the heart of your whole ebuild. The ebuild file depends on many other files, much like make does. In fact, in most cases, your ebuild will depend on make, though it is your choice. The following is the tree of neovim:
/mnt/SW/projects/System/Gentoo/gentoo/app-editors/neovim
├── files
│ ├── neovim-0.4.3-gcc-10-fix.patch
│ ├── neovim-0.4.4-cmake_luaversion_patch
│ ├── neovim-0.4.4-cmake-release-type.patch
│ └── sysinit.vim
├── Manifest
├── metadata.xml
├── neovim-0.4.4-r100.ebuild
└── neovim-9999.ebuild

So, what do you use these files for in your application? The *.ebuild file is the obvious file. This file contains the SRC_URI, which directly points to the code. Other information in the file includes the description, the website, and further information necessary for compiling the package.

The Manifest file contains the hash that uniquely identifies the code.

The metadata.xml file contains the maintainer’s name and email address, the project name, and a few flags for compiling. The remote identity is also located in this file, like the GitHub repository for the upstream. The files directory contains any patches you may need and any special settings that you require. The above example shows a file with appropriate settings according to the Gentoo maintainers.

Inside the Ebuild File

The values inside the file are easy to understand, for the most part. The Description and Homepage are for the developer’s help. The EAPI number indicates which version of Gentoo will be run. You also have the License, which is quite clear; match the License to the code for which you are building an ebuild file.

Even trickier is SLOT, which is used if you need to have several versions. SLOT will then point this build to the version that you are supporting. Most software will have the 0 value, allowing only one version at a time.

KEYWORDS is the value that indicates which platforms to which your source code can compile. The given ones are amd65, x86, and possibly arm64. A full list is available on your Gentoo system. Note that if you want to contribute, you must set a tilde (~) in front of the architecture. This means that the code is untested, so make sure that the code is well-tested before you remove this symbol. Preferably, have many users view the code before removing the tilde.

The IUSE variable returns to the parameters that you want to set for your compiler.

You also have DEPEND, which comes in three different types. The RDEPEND values are the values that you use while running the code. The BDEPEND values are the build-dependent values. The package that you are trying to add to Gentoo will contain a file describing the necessary dependencies.

For simple packages, you do not need anything else. However, the specific package that you are working on will probably have some things that must be done before compiling the code. If this does not match what Gentoo developers have expected, you can set up your own.

Functions

In the file, the installer will use certain functions for the whole process. For example, to apply patches before running the command, the src_prepare() function will handle this situation.

The src_configure() function uses econf to set, i.e., ‘use_enable.’ In this function, you can unpack your files using the unpack command. You can also pass args to ./configure for your project using econf. As you can see, these functions are named according to their make equivalents, and many times, they pass arguments across.

The src_install() function performs the same function that make install would do in a C/C++ build. However, it does contain many options that you can look up in the reference document.

Most functions are there for when you have special case software. You will probably start digging through these functions when you try implementing your first package.

Example: SimulIDE Package File

Here, we present a file that was created for the SimulIDE package. The package requires a Qt5 development environment, so you will need to add that in your ebuild file. In the following image, you can see the RDEPEND values reflecting this idea. The libraries are already contained within the Gentoo repositories, which makes it easy to point to.

In the src_prepare() function, you can see that the package is unpacked before use.

Overlay

When you have trimmed and cleaned all your mistakes, you may want to add your package to the Gentoo project. Layman was created so that you can use experimental software for your main distribution install. The project is called Overlays, but the command to install it is called Layman.

Conclusion

Creating new packages for Gentoo is an undertaking that may stretch your abilities. Even so, if you have built many packages before using make and the gcc suite of tools, you should be able to pick this process up rather quickly. Also, be sure to contribute back to the community as much as you can.