User:Shunlir/An Overlay Tutorial

Introduction

 * 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.
 * 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 and with repo name as

Creating an empty overlay
A empty repository layout without packages is:

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

Add the following two files correspondingly:

Adding a package into the overlay
Packages in overlay are organized by category. Take VSCodium as an example.

Make a directory for the package:

Add metadata for the package:

Add a ebuild for the package: {{FileBox|filename=~/my-overlay/app-editors/vscodium-bin/vscodium-bin-1.43.0.ebuild|1= EAPI=7 MY_PN="${PN/-bin/}" inherit eutils desktop xdg-utils DESCRIPTION="Free/Libre Open Source Software Binaries of VSCode" HOMEPAGE="https://vscodium.com" SRC_URI="https://github.com/VSCodium/vscodium/releases/download/${PV}/VSCodium-linux-x64-${PV}.tar.gz" RESTRICT="mirror strip bindist" LICENSE="MIT" SLOT="0" KEYWORDS="~amd64" IUSE="" DEPEND="" RDEPEND="${DEPEND} >=dev-libs/nss-3.47.1-r1:0 >=media-libs/alsa-lib-1.1.8:0 >=media-libs/libpng-1.2.46:0 >=net-print/cups-2.1.4:0 >=x11-libs/cairo-1.14.12:0 >=x11-libs/gtk+-2.24.31-r1:2 >=x11-libs/libXtst-1.2.3:0" QA_PREBUILT="opt/${MY_PN}/*" S="${WORKDIR}" 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 { xdg_desktop_database_update xdg_icon_cache_update xdg_mimeinfo_database_update } pkg_postrm { xdg_desktop_database_update xdg_icon_cache_update xdg_mimeinfo_database_update
 * 1) Copyright 1999-2020 Gentoo Authors
 * 2) Distributed under the terms of the GNU General Public License v2

}}

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

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 file, usually in the overlay:

Using Layman
Add the overlay into layman's overlay list permanently:

To add the overlay in portage:

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