My avatar


Level 10 Computer Mage

Gentoo overlays for noobs

Published on 2021-03-29 by flewkey

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:

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 "">
	<maintainer type="person">
		<name>John Doe</name>

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



KEYWORDS="~amd64 ~x86"


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


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="${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.


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 shows the following dependencies:

Looking closely, we can also see that pkgconfig is used in, 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.

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.


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 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)


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


inherit meson

DESCRIPTION="Wallpaper tool for Wayland compositors"
SRC_URI="${PN}/archive/$.tar.gz -> ${P}.tar.gz"

KEYWORDS="~amd64 ~x86"

	man? ( app-text/scdoc )

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

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


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.

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!

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

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

Alpine Linux does not make the news

My Linux distribution of choice for several years has been Alpine Linux. It’s a small, efficient distribution which ships a number of tools I appreciate for their simplicity, such as musl libc. It has a very nice package manager, apk, which is fast and maint…

From Drew DeVault's blog
Published on July 25, 2023

On Furries and the Media

Recently, there has been a lot of misinformation and propaganda flying around the American news media about the furry fandom. Unfortunately, this seems to be increasing with time. Consequently, there are a lot of blanket statements and hot takes floating …

From Dhole Moments
Published on June 6, 2023

Question #30: What is the F*cking “Colour” of Light?

Hello. I just wanted to let you know that the dimwitted author set their password to “password”. This left a glaring security hole in their website. I’ve just read over all of this nonsense, and I’d like to tell you all that you’ve wasted your time. The a…

From The Hitchhiker's Guide to Digital Colour
Published on March 18, 2023

Generated with the spectacular power of openring