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
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:
my-overlay ├── 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:
~/my-overlay/profiles/repo_name
my-overlay
~/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:
~/my-overlay/app-editors/vscodium-bin/metadata.xml
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> <maintainer type="person"> <email>my-name@email.com</email> <name>my-name</name> </maintainer> <longdescription lang="en"> VSCodium is a community-driven, freely-licensed binary distribution of Microsoft’s editor VSCode </longdescription> <upstream> <remote-id type="github">VSCodium/VSCodium</remote-id> <bugs-to>https://github.com/VSCodium/VSCodium/issues</bugs-to> </upstream> </pkgmetadata>
Add a ebuild for the package:
~/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 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
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:
~/my-overlay/repositories.xml
<?xml version="1.0" ?> <repositories version="1.0"> <repo quality="experimental" status="unofficial"> <name>my-overlay</name> <description lang="en">my-name's Custom Gentoo Overlay.</description> <homepage>https://github.com/my-name/my-overlay</homepage> <owner type="person"> <name>my-name</name> <email>my-name@my-email.com</email> </owner> <source type="git">git://github.com/my-name/my-overlay.git</source> <feed>https://github.com/my-name/my-overlay/commits/master.atom</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:
/etc/layman/layman.cfg
... overlays : https://api.gentoo.org/overlays/repositories.xml https://raw.githubusercontent.com/my-name/my-overlay/master/repositories.xml ...
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://github.com/my-name/my-overlay.git
root #
emaint sync -r my-overlay
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.
/etc/portage/repos.conf/my-overlay.conf
[localrepo] location = /home/my-name/my-overlay priority = 100