====== Gentoo: FeM-Overlay ======

<WRAP warning 50% center>
Das FeM-Overlay ist von Bitbucket in das FeM-GitLab umgezogen.
Die neue Upstream-URL lautet:

https://gitlab.fem-net.de/gentoo/fem-overlay.git

Bitte passt eure ''/etc/portage/repos.conf'' an und erstellt neue Commits ab sofort immer im GitLab.
Der Bitbucket-Mirror wird ca. Dezember 2021 abgeschaltet.
</WRAP>

Das FeM-Overlay ist ein Portage Overlay für die Gentoo Paketverwaltung. Hier werden Ebuilds und Patches für Software gepflegt, die auf FeM Servern Einsatz findet, so aber nicht im offiziellen Portage-Tree enthalten ist. 

Hinweis: Manchmal sind Pakete nur temporär im FeM-Overlay bis die Erweiterungen / Patches in den offiziellen Portage-Tree eingepflegt wurden.

Kontaktadresse: [[fem-overlay@technik.fem-net.de]]

===== Nutzung =====

  * URL des Overlays (git): https://gitlab.fem-net.de/gentoo/fem-overlay.git
    * Upstream-Repository. Alle Commits werden hier in den master gemerged.

==== Ohne Layman über repos.conf ====
Diese Variante bietet sich an, wenn man selber am Repository Änderungen vornehmen möchte.
<code>
[fem-overlay]
location = /var/db/repos/fem-overlay
sync-type = git
sync-uri = https://gitlab.fem-net.de/gentoo/fem-overlay.git
auto-sync = yes
</code>

==== Mit eselect-repository ====
Diese Variante verwendet in der Standardeinstellung ein [[https://github.com/gentoo-mirror/fem-overlay|Clone vom Repository]] mit zusätzlich generierten Metadaten, was emerge beschleunigt.
Empfiehlt sich für Systeme, die das Overlay nur nutzen, aber lokal selbst keine Änderungen hinzufügen.
<code>
eselect repository enable fem-overlay
</code>

==== Mit Layman ====
Das Overlay ist in der offiziellen Liste enthalten.

Hinzufügen des Overlays
<code>
layman -a fem-overlay
</code>

=== layman wieder loswerden ===
<code>
# layman Referenzen entfernen
rm /etc/portage/repos.conf/layman.conf
sed -i -e '/source \/var\/lib\/layman\/make.conf/d' /etc/portage/make.conf
sed -i -e '/\*/d' /etc/eix-sync.conf

emerge -C layman

rm -rf /var/lib/layman

eix-sync # oder emerge --sync
</code>


===== Ebuilds einreichen =====

Für einen schreibenden Zugriff benötigt man einen Login im [[technik:dienste:gitlab|GitLab]].
Die ist üblicherweise der FeM LDAP-Zugang.
Neue ebuilds können per Fork und anschließendem Merge Request eingericht werden.
Für zusätzliche Berechtigunge (MRs selbst mergen, Issues bearbeiten, etc.) kann man sich an <fem-overlay@technik.fem-net.de> wenden.
==== Regeln für erfolgreiche Ebuilds im FeM-Overlay ====

  * Verwende bei neuen Ebuilds die aktuellste [[http://devmanual.gentoo.org/ebuild-writing/eapi/index.html|EAPI]]. ([[http://dev.gentoo.org/~ulm/pms/head/eapi-cheatsheet.pdf|EAPI Cheat-Sheet]])
    * Einzelne eclasses unterstützen nicht die neueste EAPI. In diesem Fall kann die nächstältere benutzt werden. EAPIs, die im Overlay als veraltet markiert sind, //dürfen nicht// in neuen ebuilds benutzt werden.
  * Im Files-Ordner sollen keine Archive, sondern nur Skripte und Patches liegen.
  * Alle Ebuilds besitzen einen validen Header
<code|Header>
# Copyright 1999-2XXX Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
</code>
  * Variablen sollten in der richtigen Standard-Reihenfolge vorliegen

<code|Standard-Reihenfolge>
EAPI

inherit

MY_P
DESCRIPTION
HOMEPAGE
SRC_URI

LICENSE
SLOT
KEYWORDS
IUSE

DEPEND
RDEPEND
BDEPEND

S
RESTRICT

DOCS
</code>

  * Variablen, die evtl. Leerzeichen enthalten könnten müssen bei Verwendung mit Kommandos gequotet werden
    * standardmäßig: ''${S}, ${WORKDIR}, ${FILESDIR}, ${DISTDIR}, ${ROOT}, ${D}''

<code|Beispiel>
# Quoting nicht nötig, da Ergebnis eine Variable ist
S=${WORKDIR}/${PN}

# Quoting nötig, da der Pfad u.U. Leerzeichen enthält
cd "${S}" || die
</code>

  * möglichst eine metadata.xml anlegen mit Informationen, wer das Paket im Overlay betreut und welche Useflags verwendet werden. Die E-Mail-Adressen der Betreuer werden in der [[https://gitlab.fem-net.de/gentoo/fem-overlay-ci-tools/-/settings/ci_cd|CI-Konfiguration]] der fem-overlay-ci-tools hinterlegt, um eine automatische Zuweisung von Issues aufgrund der betroffenen Pakete zu ermöglichen.
<file|Beispiel für metadata.xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
        <maintainer type="person">
                <email>mamu@fem.tu-ilmenau.de</email>
                <name>Max Mustermann</name>
        </maintainer>
        <use>
                <flag name="ftps">Support for backing up on FTPS</flag>
        </use>
</pkgmetadata>
</file>
  * Manifest erstellen mit pkgdev oder RepoMan:
    * ''pkgdev manifest''
    * ''repoman manifest''
  * RepoMan zur Prüfung des Ebuilds verwenden
      * ''repoman full -dx'' (Prüft alle Ebuilds im aktuellen Verzeichnis)
  * pkgdev oder RepoMan zum commiten benutzen
      * ''repoman commit''
      * ''pkgdev commit''
  * pkgcheck zur Prüfung des Ebuilds verwenden
    * ''pkgcheck scan'' (prüft Ebuilds im aktuellen Verzeichnis auf gängige Konventionen und Fehler)

(Ideen aus den [[http://overlays.gentoo.org/proj/sunrise/wiki/CodingStandards|Coding-Standards des Sunrise-Overlays]].)

Das Overlay wird bei Änderungen u.A. mittels [[https://wiki.gentoo.org/wiki/Repoman|Repoman]] und pkgcheck per CI-Pipeline geprüft.
Zudem werden ebuilds per [[https://blogs.gentoo.org/ago/2020/07/04/gentoo-tinderbox/|Tinderbox]] gebaut und Fehler gemeldet.
**Sämtliche Pakete müssen erfolgreich die CI-Pipeline durchlaufen, um akzeptiert zu werden.**

==== Historie ====
  * ca. 2008 - Das Overlay wurde angelegt
  * 2017-11-23 - Migration auf Git
  * 2018-03-23 - Aufnahme in overlays.gentoo.org
  * 2021-07-29 - Erste Arbeiten an der Umstellung auf den neuen Upstream https://gitlab.fem-net.de/gentoo/fem-overlay
  * 2021-08-02 - Änderung des Upstream-Repos für ''api.gentoo.org'' auf GitHub
  * 2021-08-13 - Das Overlay benutzt nun das GitLab als Upstream-Repository