User:Shunlir/An Overlay Tutorial

From Gentoo Wiki
Jump to: navigation, search


  • An ebuild repository is a layout of directories and files (including ebuilds,metadata, ...).
  • The main (ebuild) repository on a Gentoo system is known as the Gentoo ebuild repository.
  • Other ebuild rebpsitories are also colloquially known as overlays, because when they are used, they are overlay on the main (ebuild) repository, means that a package with the same name and version in the overlay will take precedence over that in the main ebuild repository when user installs package via emerge.
  • Official overlays are the ones registered/added in the global repository list of Gentoo overlay project, while unofficial overlays are not.
  • Tools such as layman and eselect-repository can be used to manage official/unofficial overlays, such as adding/deleting, enabling/disabling and sync-ing of overlays
  • Conventional, a manually created ebuild repository in the system is called local ebuild epository or custom (ebuild) repository, typically under /var/db/repos/localrepo and with repo name as localrepo

Creating an empty overlay

A empty repository layout without packages is:

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

Create the overlay layout somewhere, here, under current user's home:

user $ mkdir -p ~/my-overlay/{profiles,metadata}

Add the following two files correspondingly:

FILE ~/my-overlay/profiles/repo_name
FILE ~/my-overlay/metadata/layout.conf
masters = gentoo
sign-commits = false
sign-manifests = false

Adding a package into the overlay

Packages in overlay are organized by category. Take VSCodium as an example.

Make a directory for the package:

user $mkdir -p ~/my-overlay/app-editors/vscodium-bin

Add metadata for the package:

FILE ~/my-overlay/app-editors/vscodium-bin/metadata.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "">
  <maintainer type="person">
  <longdescription lang="en">
    VSCodium is a community-driven, freely-licensed binary distribution of Microsoft’s editor VSCode
    <remote-id type="github">VSCodium/VSCodium</remote-id>

Add a ebuild for the package:

FILE ~/my-overlay/app-editors/vscodium-bin/vscodium-bin-1.43.0.ebuild
# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
inherit eutils desktop xdg-utils
DESCRIPTION="Free/Libre Open Source Software Binaries of VSCode"
RESTRICT="mirror strip bindist"
src_install() {
    # Install in /opt
    dodir /opt
    cp -pPR "${S}" "${D}/opt/${MY_PN}"
    fperms 0755 /opt/${MY_PN}
    dosym "../../opt/${MY_PN}/bin/codium" "/usr/bin/${MY_PN}"
    dosym "../../opt/${MY_PN}/bin/codium" "/usr/bin/codium"
    make_desktop_entry "${MY_PN}" "VSCodium" "${MY_PN}" "Development;IDE"
    newicon "resources/app/resources/linux/code.png" "${MY_PN}.png"
pkg_postinst() {
pkg_postrm() {

Add a Manifest file for the package, it can be generated via repoman, run the following command under the package directory:

user $repoman manifest

Publishing the unofficial overlay

It's useful to push the overlay to a public remote git repository so that users can install packages from it.

To let layman or eselect-repository find the location of the unofficial overlay, it's necessary to create a repositories.xml file, usually in the overlay:

FILE ~/my-overlay/repositories.xml
<?xml version="1.0" ?>
<repositories version="1.0">
  <repo quality="experimental" status="unofficial">
      <description lang="en">my-name's Custom Gentoo Overlay.</description>
        <owner type="person">
<feed></feed> </repo> </repositories>
  • repositories.xml file is not needed by local repo
  • The repository list file name must be repositories.xml for eselect-repository

Using Layman

Add the overlay into layman's overlay list permanently:

FILE /etc/layman/layman.cfg
overlays  :

To add the overlay in portage:

root # layman -f
root # layman -a my-overlay
root # layman -s my-overlay

Using eselect-repository

root # eselect repository add my-overlay git git://
root # emaint sync -r my-overlay


Sometime, it's convenient to temporarily configure the overlay as local repository for test purpose, this can avoid frequently pushing temporary work to remote git repository.

FILE /etc/portage/repos.conf/my-overlay.conf
location = /home/my-name/my-overlay
priority = 100