Building a Personal Gentoo Overlay

2020-04-23 by Quinlan Pfiffergentoo software how-to

I’ve been running Gentoo again recently, and one of the things I wanted to try out was building a personal overlay. The information here is cobbled together from things I learned personally, looking at the gentoo developer overlays, and just trying stuff until it worked.

Note: In this document my repo name will be qpfiffer.

The Bare Minimum

Start a git repository somewhere on your machine, and add, at least, these files:

.
├── LICENSE
├── metadata
│   └── layout.conf
├── profiles
│   └── repo_name

layout.conf is pretty simple:

masters = gentoo
thin-manifests = true

And profiles/repo_name looks like this (for me):

qpfiffer

That’s really it. Now you can push it up to some git hosting provider.

Adding it to your Gentoo Box

The Gentoo developer guide for personal overlays says you need a bunch of random packages to do this, like Layman or Repoman, but I prefer to just change the files myself. The first thing to do is add your new repo to your /etc/portage/repos.conf:

[qpfiffer]
location = /var/db/repos/qpfiffer
sync-type = git
sync-uri = https://git.sr.ht/~qpfiffer/overlay
auto-sync = yes

From there you should be able to sync it with the following command:

$ emaint sync -r qpfiffer

If you jumped ahead and added your own packages, you should be able to see them after updating eix (or emerge --search or whatever):

$ eix 38-moths
[I] www-misc/38-moths [1]
     Available versions:  (~)0.4
     Installed versions:  0.4(09:01:01 AM 04/03/2020)
     Homepage:            http://38-moths.shithouse.tv/
     Description:         38-Moths micro-web framework

[1] "qpfiffer" /var/db/repos/qpfiffer

Adding a Package

Adding a package is pretty simple, but requires knowing about ebuilds. There are a ton of resources around ebuilds and a lot of them are out of date, but you can hack one together one pretty easily by poking around in other people’s overlays, following guides and just generally being resourceful.

At a bare minimum, for a package, you’ll need to add something like the following directory structure to your repository:

└── www-misc
    └── 38-moths
        ├── 38-moths-0.4.ebuild
        ├── files
        │   └── destdir-0.4.patch
        ├── Manifest
        └── metadata.xml

In here you’ll notice a couple things: www-misc/38-moths is the package name that Portage will show you, 0.4 will be our listed version, we have a single patch (destdir-0.4.patch) and a couple of meta files (Manifest and metadata.xml).

Manifest we’ll get to in a little bit, and metadata.xml you can just go look at because it’s not very interesting. It’s exactly what it says on the box: metadata about the package.

The ebuild for 38-moths, as of right now, looks like this:

# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7

DESCRIPTION="38-Moths micro-web framework"
HOMEPAGE="http://38-moths.shithouse.tv/"
SRC_URI="https://git.sr.ht/~qpfiffer/ThirtyEight-Moths/archive/v${PV}.tar.gz"

LICENSE="MIT"
SLOT="0"
KEYWORDS="~amd64"
IUSE=""

S="${WORKDIR}/ThirtyEight-Moths-v${PV}"

PATCHES=(
    "${FILESDIR}/destdir-0.4.patch"
)

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

It’s pretty simple, but took a while to figure out. You’ll have to play around with the steps to actually installing a package via Portage, but in general I’ve found the simpler the better.

Generating the Manifest

The last file you’ll need, the Manifest, can actually be generated by emerge which makes it super useful. Rather than writing out all the hashes for files yourself, you can just check out the repository on your own box and then run the following, in the git checkout of your overlay:

$ GENTOO_MIRRORS="" ebuild 38-moths-0.4.ebuild manifest

This will spit out a shiny-new Manifest file which you can check in to your overlay.

Unmasking your packages

Gentoo is very stingey about which things are masked and which aren’t. You may have noticed the following line in the .ebuild above:

KEYWORDS="~amd64"

This means that the package isn’t production ready. This is a good thing, because it shows others that maybe your code isn’t ready. It’s up to you whether or not you want your code to be distributed this way.

To unmask, you can either do two things:

Change the keyword to amd64
Allow the package to be merged on your system

In general I prefer the latter, because it’s on a machine-to-machine basis whether or not your package should me merged if it’s not quite production-ready. To do this, you can add the following to a file in your /etc/porage/package.accept_keywords directory:

=www-misc/38-moths-0.4::qpfiffer ~amd64

This will specifically allow the package to be merged, and no other packages/versions.

Conclusion

From here, if everything went as planned, you can re-sync your overlay to your gentoo box and then emerge your heart away.

That’s it! Ebuilds might be covered in a later post, but for now that’s all you need to get started setting up your own overlay. I’m learning this as I go, so please drop me a line if something looks out of place or there are corrections. Happy hacking.

Malevolent Cartography

Contact