Technical Deep Dive: Gentoo Overlays & GURU

Gentoo’s official repository has ~20,000 packages. That sounds like a lot until you need that one obscure tool that isn’t there.

Enter overlays: third-party package repositories that extend Gentoo’s capabilities.

What’s an Overlay?

Think of overlays as PPAs (Ubuntu) or the AUR (Arch), but for Gentoo. They contain ebuilds (package recipes) maintained by the community or individuals.

Why use them?

  • Bleeding-edge package versions
  • Software not yet accepted into the main tree
  • Custom patches or configurations
  • Niche tools (Discord, proprietary apps, etc.)

GURU: The Official Community Overlay

GURU (Gentoo User Repository) is the official community-maintained overlay. It’s the closest thing Gentoo has to Arch’s AUR.

Enabling GURU

# Install the repository management tool
emerge app-eselect/eselect-repository

# Enable GURU
eselect repository enable guru

# Sync it
emerge --sync
# Or sync just GURU:
emaint sync -r guru

Verify It’s Working

eselect repository list

# Output should include:
# [X]  guru   https://github.com/gentoo/guru.git

Search and Install from GURU

# Search for a package
eix -RO guru discord

# Install (note the ::guru suffix)
emerge -av net-im/discord::guru

The ::guru suffix forces installation from GURU specifically, useful when a package exists in multiple repositories.

Managing Multiple Overlays

List Available Overlays

# All available (hundreds exist)
eselect repository list

# Currently enabled
eselect repository list -i
# Steam and gaming
eselect repository enable steam-overlay

# Bleeding-edge stuff
eselect repository enable bleeding-edge

# Scientific computing
eselect repository enable science

# Media/codecs
eselect repository enable multimedia

Disable/Remove Overlays

# Disable (keeps files)
eselect repository disable overlay-name

# Remove completely
eselect repository remove overlay-name
rm -rf /var/db/repos/overlay-name

Creating a Local Overlay

Sometimes you need a package that doesn’t exist anywhere. Or you want to patch an existing package. Local overlays solve this.

Step 1: Create the Structure

mkdir -p /var/db/repos/local/{metadata,profiles}

# Required metadata
cat > /var/db/repos/local/metadata/layout.conf << 'EOF'
masters = gentoo
auto-sync = false
EOF

# Repository name
echo "local" > /var/db/repos/local/profiles/repo_name

Step 2: Register with Portage

cat > /etc/portage/repos.conf/local.conf << 'EOF'
[local]
location = /var/db/repos/local
auto-sync = false
priority = 10
EOF

Higher priority means packages from this overlay are preferred over the main tree.

Step 3: Create Your First Package

# Category and package directory
mkdir -p /var/db/repos/local/app-misc/my-tool

# Create the ebuild
cat > /var/db/repos/local/app-misc/my-tool/my-tool-1.0.ebuild << 'EOF'
EAPI=8

DESCRIPTION="My custom tool"
HOMEPAGE="https://example.com"
SRC_URI="https://example.com/my-tool-${PV}.tar.gz"

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

src_install() {
    dobin my-tool
}
EOF

# Generate manifest (checksums)
cd /var/db/repos/local/app-misc/my-tool
ebuild my-tool-1.0.ebuild manifest

Step 4: Install

emerge -av app-misc/my-tool::local

Overlay Priority and Conflicts

When a package exists in multiple repositories, Portage uses priority to decide which one to install.

Check Package Source

# See all available versions and their sources
eix -e firefox

# Output shows:
# [I] www-client/firefox
#     Available versions:  
#     (0)    115.0::gentoo
#     (0)    116.0::gentoo
#     (0)    117.0-r1::testing-overlay

Force Specific Source

# Install from specific overlay
emerge -av www-client/firefox::gentoo

# Mask overlay version to prevent accidental installation
echo "www-client/firefox::testing-overlay" >> /etc/portage/package.mask

GURU Security Considerations

GURU packages are community-maintained. They receive less scrutiny than official Gentoo packages.

Best practices:

  1. Review ebuilds before installing

    cat /var/db/repos/guru/net-im/discord/discord-*.ebuild

  2. Check maintainer activity

    • Is the package regularly updated?
    • Are bugs being addressed?

  3. Pin critical packages to ::gentoo

    # Force system packages from official repo
echo "sys-libs/glibc::gentoo" >> /etc/portage/package.accept_keywords

  4. For production servers: minimize overlay usage

    • Use official packages when possible
    • Overlays are fine for desktops and development

Troubleshooting

”Overlay not syncing"

# Check configuration
cat /etc/portage/repos.conf/eselect-repo.conf

# Manual sync
emaint sync -r overlay-name

# Check permissions
ls -la /var/db/repos/overlay-name
chown -R portage:portage /var/db/repos/overlay-name

"Dependency conflicts with overlay package"

# Mask the problematic overlay version
echo "=category/package-version::overlay" >> /etc/portage/package.mask

# Or mask the entire package from that overlay
echo "category/package::overlay" >> /etc/portage/package.mask

"Package blocks official version”

Sometimes an overlay has a newer version that isn’t compatible with stable dependencies:

# Unmask specific version from official repo
echo "=category/package-version::gentoo" >> /etc/portage/package.unmask

Overlays are one of Gentoo’s superpowers. They let you have bleeding-edge when you want it, stable when you need it, and custom when nothing else works. Just remember: with great power comes great responsibility to read ebuilds before running them.