User:Shunlir/An Overlay Tutorial

From Gentoo Wiki
Jump to:navigation Jump to:search

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:

FILE ~/my-overlay/profiles/repo_name
my-overlay
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 "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:

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
  
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:

FILE ~/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>
Note
* 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  :
    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.

FILE /etc/portage/repos.conf/my-overlay.conf
[localrepo]
location = /home/my-name/my-overlay
priority = 100
Retrieved from "https://wiki.gentoo.org/index.php?title=User:Shunlir/An_Overlay_Tutorial&oldid=936585"