In Gentoo, packages are stored in ebuild repositories. The primary repository is the Gentoo repository, and users can add secondary repositories (overlays) on top of it. All you need to make an overlay of your own is a text editor.

You should also install a quality assurance tool to check your work. The two that I know of are app-portage/repoman and dev-util/pkgcheck.

Creating the overlay

1. mkdir test-overlay && cd $_
2. mkdir profiles metadata
3. echo test-overlay > profiles/repo_name
4. echo masters = gentoo > metadata/layout.conf

Congratulations, you now have the basic directory structure of a Gentoo overlay. Now that we’ve named our repository and set the repository master to the Gentoo ebuild repository, we are ready to go.

At this point, you can turn this folder into a git repository, create your initial commit, and push it somewhere. I personally recommend doing this since it makes changes easy to track, and allows you to sync it between devices. If you don’t want to do this, add auto-sync = false to your layout.conf to tell Portage not to sync it with anything.

To check that your repository is good, run repoman or pkgcheck scan in the root of your repository. It is good to keep an eye on it to keep the quality of your ebuilds from going in the gutter.

After that, let’s tell Portage about it! Create /etc/portage/repos.conf/test-overlay.conf and add the following:

[test-overlay]
location = /path/to/test-overlay
auto-sync = No

Your repository is now ready for packaging data.

Our first ebuild

In Gentoo, ebuilds are used to make packages. An ebuild is like a recipe that tells Portage how to build and install a package. For this example, we’re going to make an ebuild for gui-apps/swaybg. Don’t peek at the Gentoo ebuild yet!

First, let’s create a folder for the package.

mkdir -p gui-apps/swaybg && cd $_

Before we make an ebuild, let’s create a metadata.xml file. Vim users will notice that this is already filled out, thanks to the power of gentoo-syntax. We can specify a bit more, but all we need is a maintainer.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
	<maintainer type="person">
		<email>john@example.com</email>
		<name>John Doe</name>
	</maintainer>
</pkgmetadata>

Now we can create an ebuild. First, open the swaybg repository and check the version that we want to package. The only version is “1.0”, so we can package that. Let’s create a file called “swaybg-1.0.ebuild”. For vim users the gentoo-syntax tool should have already filled part of this out for you. If not, it should be something like this.

# Copyright 2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

DESCRIPTION=""
HOMEPAGE=""
SRC_URI=""

LICENSE=""
SLOT="0"
KEYWORDS="~amd64 ~x86"

DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""

By the way, information about naming ebuilds is available on the development guide.

Information

Now, we should fill out the metadata. Let’s add a description, paste in the homepage link, and specify the license as “MIT”. The SRC_URI should link to a copy of the latest version, like so:

SRC_URI="https://github.com/swaywm/${PN}/archive/${PV}.tar.gz -> ${P}.tar.gz"

A list of variables that you can use are also available on the development guide, by the way.

Dependencies

We can see that swaybg uses meson to build, so we will write inherit meson at the top of the ebuild to inherit meson.eclass. This will automatically make our ebuild use the Meson build system.

Now, we deal with dependencies. Runtime dependencies go in RDEPEND, and build dependencies are split between BDEPEND and DEPEND. In practice, DEPEND is used to list dependencies required for both building and using the package, hence the RDEPEND="${DEPEND}" line. A look into meson.build shows the following dependencies:

• wayland-client
• wayland-protocols
• cairo
• gdk-pixbuf-2.0
• scdoc (optional)

Looking closely, we can also see that pkgconfig is used in meson.build, so pkgconfig is a dependency as well. We also won’t need to list meson as a dependency, since we already inherited meson.eclass. (If the version of Meson it requires is unstable though, it might be worth adding it to prevent Portage from trying and failing to build it with the stable version.)

Now let’s track down the packages for our dependencies.

• dev-libs/wayland
• dev-libs/wayland-protocols
• x11-libs/cairo
• x11-libs/gdk-pixbuf
• virtual/pkgconfig
• app-text/scdoc

Shoving them all into the DEPEND variable wouldn’t be the end of the world, but it is good to sort them out. All of these are required for building the package, so none of them will go in RDEPEND. As for BDEPEND, we know that pkgconfig and wayland-protocols obviously won’t be needed to run it.

This leaves scdoc. We know that it goes in BDEPEND, but it is an optional dependency that is only used to build documentation, so we will make it optional.

Optional manpages

First, we will add the man USE flag to our ebuild, and use the + sign to enable it by default. Because this is a global use flag, we do not need to define it in metadata.xml.

IUSE="+man"

Then, we will specify app-text/scdoc as an optional dependency in BDEPENDS:

man? ( app-text/scdoc )

Finally, we need to tell Meson to only build documentation when the “man” USE flag is enabled. The meson.build file shows that the man-pages Meson option controls this. It is passed to the “required” argument, making it a feature option.

The meson.eclass docs provide us with an example of how to configure Meson based on USE flags, so I will blatantly copy that.

src_configure() {
	local emesonargs=(
		$(meson_feature man man-pages)
	)
	meson_src_configure
}

Finishing

Now, we will generate a Manifest, which will allow Portage to check the integrity of the ebuild and it’s source files. We can use the ebuild tool to do this.

ebuild ./swaybg-1.0.ebuild manifest

Alternatively, repoman users can use the following command to generate the Manifest for an entire folder.

repoman manifest

All right, this should be complete! Now, it is time to run repoman or pkgcheck scan to look for issues. If it looks similar to what’s below, then all should be good.

# Copyright 2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

inherit meson

DESCRIPTION="Wallpaper tool for Wayland compositors"
HOMEPAGE="https://github.com/swaywm/swaybg"
SRC_URI="https://github.com/swaywm/${PN}/archive/$.tar.gz -> ${P}.tar.gz"

LICENSE="MIT"
SLOT="0"
IUSE="+man"
KEYWORDS="~amd64 ~x86"

DEPEND="
	dev-libs/wayland
	x11-libs/cairo
	x11-libs/gdk-pixbuf
"
RDEPEND="${DEPEND}"
BDEPEND="
	dev-libs/wayland-protocols
	virtual/pkgconfig
	man? ( app-text/scdoc )
"

src_configure() {
	local emesonargs=(
		$(meson_feature man man-pages)
	)
	meson_src_configure
}

After this, you should try to merge your ebuild to check for issues. Assuming that you have added your repository to repos.conf, you can merge it like a normal ebuild.

emerge -1 gui-apps/swaybg::test-overlay

Alternatively, assuming that your dependencies are already installed, you can merge it directly.

ebuild ./swaybg-1.0.ebuild merge

Committing

In an ebuild repository, it is generally a good idea to prefix your commit message with the name of your package. We will add our Manifest and ebuild, then commit.

git add Manifest swaybg-1.0.ebuild

git commit -m "gui-apps/swaybg: New package"

Users of repoman can also use repoman commit, which will automatically prefix their commit with the package name and add some extra information. Once you’re happy, feel free to push your work. Just make sure that it is in good shape. Changing history and forcing a git push in an ebuild repository is a terrible idea.

Checking our work

Now let’s look at swaybg-1.0.ebuild and see how we did.

Despite trying to be thorough for the sake of the blog post, I still missed some things.

• x11-libs/gdk-pixbuf and x11-libs/cairo are under BDEPEND
  • I did not notice that they were statically linked since I don’t understand Meson well.
• It prevents swaybg from running alongside versions of gui-wm/sway below 1.1_alpha1
  • Likely because that is the version where swaybg became standalone.
• I forgot to remove the -Werror compiler flag
  • Leaving it enabled can break things.
• The ebuild uses usex instead of meson_feature
  • meson_feature wasn’t added until 2019-03-17, so the authors probably just missed it.

Hopefully this gave a bit of insight into making ebuilds in Gentoo. Making an ebuild is easy, but making a good quality ebuild takes practice.

There are many techniques to learn while making ebuilds, and the resources below will help greatly. Use them, keep making ebuilds, and they will improve with time. Good luck, and godspeed!

• Gentoo Ebuild Repository
  • It is smart to see how Gentoo developers do their work.
• Gentoo Development Guide
  • Contains the eclass reference, function reference, etc.
• Gentoo Python Guide
• #gentoo-dev-help @ freenode
• Gentoo Portage Overlays
  • Allows you to search for ebuilds from different overlays.

Sharing with others

If you’ve made your overlay into a git repository, you can easily share it with your friends! Although they could always clone it and add it to their repos.conf manually, it is easier to do so using a tool. The two I know of are app-eselect/eselect-repository and app-portage/layman.

For eselect-repository, they can run the following command:

eselect repository test-overlay git https://git.example.com/test-overlay.git

For layman, the only easy way I know of is to create your own repositories.xml list with your repository in it, upload it somewhere, and get people to specify it with layman.

layman -f -o https://example.com/repositories.xml -a test-overlay

You will likely want to get your repository added to the Gentoo overlays list, which will allow users to add your repository by name and avoid the shenanigans above. Information on how to do this is available on the wiki.

By the way, if you would like your ebuilds to go to the most people, you can always contribute to the GURU project, or some other appropriate overlay.

Have fun writing ebuilds!

Articles from blogs that I like

Generated with the spectacular power of openring