User:CosmicOz/overlays
Borrowed from 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
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:
<?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:
# 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:
<?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:
...
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.
[localrepo]
location = /home/my-name/my-overlay
priority = 100