% !TEX root = BuildWithGBP.nw
\part{Grundlagen}

In diesem Teil des Buches gibt es zunächst ein wenig Theorie. Sodann wird 
die Einrichtung des Systems einschließlich des Git-Repositoriums, welches 
für \textit{git-buildpackage} essentiell ist, beschrieben.

\chapter{Lektüre}

Manche fragen, was sie gelesen haben sollten, bevor sie mit dem Bauen von 
\texttt{Debian}-Paketen beginnen. Andere wollen wissen, wo sie hilfreiche 
Informationen finden können. Daher gibt es hier Leseempfehlungen für alle, 
die \texttt{Debian}-Pakete bauen (wollen).

Eine kurze Einführung in das Thema \enquote{Paketieren für Debian} 
enthält das \texttt{Simple Packaging Tutorial}\cite{SimplePackagingTutorial2019}.
 
Die folgenden drei Dokumente gehören zur \enquote{Pflichtlektüre} eines jeden
Paket"=Betreuers.

\section{\texttt{Debian} Free Software Guidelines}

Allen, die bei \texttt{Debian} mitwirken wollen, wird die Lektüre des 
Gesellschaftsvertrages\index{Gesellschaftsvertrag} empfohlen. Die
\texttt{Debian Free Software Guidelines (DFSG)}\cite{DFSG} sind
wesentlicher Bestandteil des Gesellschaftsvertrages. Sie enthalten die
Bedingungen, die eine Lizenz erfüllen muss, um als \enquote{frei} zu gelten.
Diese Bedingungen sind bereits bei der Auswahl der zu paketierenden
Software bedeutsam (Kapitel~\ref{sec:SourceVerification}, 
Seite~\pageref{sec:SourceVerification}).

Die \texttt{Debian Free Software Guidelines (DFSG)} gelten nicht 
nur für Software"=Lizenzen, sondern gemäß Ziffer 1 der Version 1.1 des 
Gesellschaftsvertrages (\enquote{alle Komponenten}) auch für die 
Lizenzen von Bildern, Tönen, Texten etc.

\section{\texttt{Debian} Policy-Handbuch}
\label{sec:PolicyHandbuch}

Das \texttt{Debian} Policy-Handbuch\cite{DebianPolicy} 
\index{Debian-Policy} beschreibt die Richtlinien für die Distribution
\texttt{Debian GNU/Linux}. Beschrieben werden die Struktur und der
Inhalt des \texttt{Debian}-Archivs, verschiedene Design-Entscheidungen
des Betriebssystems und technische Anforderungen, die jedes Paket
erfüllen muss, um in die Distribution aufgenommen zu werden. Dieses
Dokument steht nur in englischer Sprache zur Verfügung.

Es steht auch als \texttt{Debian}-Paket \textit{debian-policy} bereit.

Der \index{FHS} \texttt{Filesystem Hierarchy Standard}\cite{fhs} ist eine
wichtige Ergänzung zum Policy-Hand\-buch.

Daneben gibt es ergänzend noch weitere 
Regelwerke.\footnote{\url{https://www.debian.org/devel/index.en.html}}

\section{\texttt{Debian} Entwicklerreferenz}

In der \index{Entwicklerreferenz} Entwicklerreferenz\cite{Debian-Entwicklerreferenz}
\index{Debian-Entwicklerreferenz}
werden die Verfahren und Ressourcen für \texttt{Debian}"=Entwickler
aufgeführt. Das Dokument beschreibt, wie man ein neuer Entwickler für das
\texttt{Debian}-Projekt wird, die Upload-Prozedur, wie die Fehlerdatenbank
(Bug-Tracking-System), die Mailinglisten, Inter\-net-Server etc. bedient
werden.

Dieses Dokument ist als Referenzhandbuch für alle \texttt{Debian}-Entwickler gedacht. 
Es steht  als \texttt{Debian}-Paket \textit{developers-reference-de} auch
in deutscher Sprache zur Verfügung. \cite{Debian-Entwicklerreferenz}

\section{Referenz für \textit{Git-Buildpackage}}

Es gibt verschiedene Verfahren und Werkzeuge für das Bauen von 
\texttt{Debian}-Paketen. In diesem Buch wird \textit{git-buildpackage} 
\index{git-buildpackage} verwendet.

Zusätzlich empfehlen wir daher noch die Referenz für das von uns gewählte 
Build-System \textit{git-buildpackage}\cite{Guenther2006-2017}.

\section{Handbuch für \texttt{Debian}-Betreuer}

Dieses Handbuch \index{Handbuch} für \texttt{Debian}-Betreuer\cite{Leitfaden_Debian-Betreuer} 
beschreibt den Bau eines \texttt{Debian}-Paketes mittels des 
\textit{debmake}-Befehls. 
Es ist für normale Benutzer und angehende Paketbetreuer gedacht.

Der Fokus liegt auf dem modernen Paketierungsstil. 
Es enthält viele einfache Beispiele. 

Dieses \enquote{Handbuch für \texttt{Debian}-Betreuer} soll als Erbe 
des \enquote{\texttt{Debian}-Leit\-faden für Neue Paketbetreuer} 
betrachtet werden.
 
Es steht auch in deutscher Sprache und als \texttt{Debian}-Paket 
\textit{debmake-doc} zur Verfügung. \cite{Leitfaden_Debian-Betreuer}

\section{\texttt{Debian} Leitfaden für Neue Paketbetreuer}

Dieses reife \index{Leitfaden f. neue Betreuer} Werk\cite{maint-guide} 
versucht, das Erstellen von \texttt{Debian}-Paketen für normale Anwender 
und zukünftige Entwickler verständlich mit funktionierenden Beispielen 
zu beschreiben.

Anders als frühere Dokumente baut dieses auf \textit{debhelper}
\index{debhelper} und weiteren Werkzeugen, die einem Entwickler zur
Verfügung stehen, auf.\cite{maint-guide}

Auch dieses Dokument steht in deutscher Sprache und als \texttt{Debian}-Paket 
zur Verfügung.

\section{Weitere Informationen}

Weitere nützliche \index{Literatur} Literatur findet man unter 
\url{https://www.debian.org/doc}.

Zum Thema des Bauens von \texttt{Debian}-Paketen kann man im Internet an
weiteren Stellen Dokumente finden. Es 
gilt jedoch zu beachten: \enquote{Das Internet vergisst nichts, und irgendwo 
ist immer noch eine veraltete Dokumentation verlinkt, deren Hinfälligkeit 
mangels Verfallsdatums auch nicht zu erkennen ist.}
\footnote{Über dieses Buch, Kapitel 2.9 im Buch Debian-Paketmanagement}\cite{DPMB2021}

\chapter{Was ist ein \texttt{Debian}-Paket?}
\label{chap:DebianPackage}

Um den Weg zu verstehen, sollte man das Ziel kennen. Das Ziel des Paket-Bauens 
ist ein \texttt{Debian}-Paket\index{Debian-Paket}\cite{SimplePackagingTutorial2019}. 

Was aber ist ein \texttt{Debian}-Paket? 

Eine formale Antwort lautet: Ein \texttt{Debian}-Paket ist ein 
Software-Paket, welches vom \texttt{Debian}-Projekt\index{Debian-Projekt} 
veröffentlicht wurde. 

Damit ein Paket vom \texttt{Debian}-Projekt 
veröffentlicht wird, muss es Anforderungen genügen, die vom 
\texttt{Debian}-Projekt aufgestellt, schriftlich niedergelegt und zwecks 
Transparenz veröffentlicht worden sind.

Ein \texttt{Debian}-Paket ist ein Software-Paket, welches vor allem den 
Anforderungen genügt, die in der \texttt{Debian}-Policy\cite{DebianPolicy}
beschrieben werden. 
Es gehört zur vom \texttt{Debian}-Projekt gepflegten Transparenz, dass die 
genaue Version der \texttt{Debian}-Policy, die beim Bauen des Paketes 
beachtet wurde, in der Datei \textit{debian/control} angegeben wird.
(Kapitel~\ref{subsec:DebianControl}, Seite~\pageref{subsec:DebianControl})

Ein \texttt{Debian}-Paket ist eine Sammlung von Dateien, die es ermöglichen, 
Anwendungen oder Bibliotheken über das \texttt{Debian}-Paketverwaltungssystem
zu verteilen. Das Ziel der Paketierung ist es, die Automatisierung der 
Installation, der Aktualisierung, der Konfiguration und des Entfernens von 
Software für \texttt{Debian} auf eine konsistente Weise zu 
ermöglichen.\cite{SimplePackagingTutorial2019}\cite{Package2020}

Ein \texttt{Debian}-Paket ist mehr als nur eine Archiv-Datei mit 
ausführbarem Code mit der Endung \textit{.deb}. Ein \texttt{Debian}-Paket 
besteht aus insgesamt \textbf{vier} Dateien; davon sind drei Archive.

\begin{enumerate}
 \item Eine Archiv-Datei mit der Endung \textit{.orig.tar.gz} bzw. 
\textit{.orig.tar.xz} enthält den Quellcode, aus dem das Paket gebaut wird.
  \item Eine weitere Archiv-Datei mit der Endung \textit{.debian.tar.xz} 
enthält die debian-spezifi\-schen Dateien, die den Bauvorgang und die 
Installation steuern oder zusätzliche Informationen enthalten.
  \item Eine Datei enthält neben beschreibenden Angaben zum Paket die
  Prüfsummen der beiden vorgenannten Archiv-Dateien. Diese Datei 
hat die Endung \textit{.dsc}. Diese Datei ist signiert.
  \item Den ausführbaren Code enthält schließlich das Archiv mit der 
Endung \textit{.deb}. Auch diese Datei ist signiert.
\end{enumerate}

In der Regel werden nur die erstgenannten drei Quellcodedateien vom
Maintainer hochgeladen. Die Datei, die den ausführbaren Code enthält,
wird aus den Quellcodedateien auf der Projekt-Infrastruktur gebaut.

Das \texttt{Debian}-Paket-System ermöglicht die Nachvollziehbarkeit vom
Upstream"=Quellcode bis zum binären \texttt{Debian}"=Paket. Angestrebt 
und auch oft erreicht wird eine bitgenaue Reproduzierbarkeit 
\index{Reproduzierbarkeit} des Bauprozesses\cite{Team2020}.

Wie dies nachgeprüft werden kann, wird in Kapitel~\ref{chap:ReproducibleBuilds}
(Seite~\pageref{chap:ReproducibleBuilds}) beschrieben.

Diese Transparenz gibt dem Anwender Sicherheit, dass das Binär-Paket auch 
nachvollziehbar aus dem veröffentlichen Quellcode gebaut wurde.

Wer Software aus seinem Build-System in irgendein Archiv im
\textit{deb}-Format speichert, ohne sich um Standards und Regeln zu
kümmern, packt kein \texttt{Debian}-Paket.

Vom \texttt{Debian}-Projekt werden zu jedem Zeitpunkt mehrere Varianten
(Releases) angeboten, nämlich in erster Linie \textit{stable}\index{stable},
\textit{testing}\index{testing} und \textit{unstable}\index{unstable}. 
Nach der Veröffentlichung jeder neuen \textit{Stable}-Version wird die 
bisherige \textit{Stable}-Version noch einige Zeit lang als \textit{Oldstable} 
\index{oldstable} gepflegt. Desweiteren gibt es noch \textit{Oldoldstable} 
\index{oldoldstable} und einen Zweig 
\textit{Experimental}\index{experimental}. Dort werden Änderungen ausprobiert, 
die gravierende Auswirkungen auf das Gesamtsystem haben könnten.

Der Zweig \textit{experimental} ist allerdings keine komplette Distribution, 
sondern funktioniert nur als Erweiterung von \textit{unstable}
\cite{DebianExperimental2020}.

Der Zweig \textit{unstable} (\textit{sid}) ist der erste Anlaufpunkt für neue 
Programme und neue Versionen von Programmen, bevor sie in \textit{testing} 
integriert werden. Die Entwicklung eines \texttt{Debian}-Paketes beginnt
somit in der Regel im Zweig \textit{unstable}.
\footnote{DPMB, I.Konzepte, Kapitel 2.10.1\cite{DPMB2021}}

Jedes \texttt{Debian}-Paket gehört zu einem definierten Entwicklungsstadium der 
\texttt{Debian}-Distribution, also zu einer bestimmten, veröffentlichten Version. 
Diese werden als Releases bezeichnet.\footnote{DPMB,Kapitel 2.10 in \cite{DPMB2021}}. 

Jedes Paket muss auf diese Veröffentlichung abgestimmt sein. Es darf 
keine Abhängigkeiten zu einer anderen Veröffentlichung haben. 
Bibliotheken dürfen in einer Veröffentlichung grundsätzlich nur in 
einer Version vorhanden sein, damit Sicherheitsaktualisierungen für den 
Anwender einfach möglich sind. Ein \texttt{Debian}-Paket darf also keine 
eigene Version einer solchen Bibliothek enthalten.
\footnote{Kapitel 7.1 \cite{DebianFAQ2019}}

\chapter{Auswahl der zu paketierenden Software}

Oft wird die Frage an das Projekt gestellt, welches Paket sich denn zum 
Starten eigne. Zum Erlernen des Paketierens gibt es kein eigens dafür 
erstelltes \enquote{Schulungs-}Paket. Vielmehr erlernt man das 
Paketieren durch das Packen von \texttt{Debian}-Paketen (\enquote{Learning 
by doing}).

Es wird von Anfang an darauf Wert gelegt, dass die Motivation 
mitgebracht wird, sich Schritt für Schritt in die Thematik des Paketierens 
einzuarbeiten. Eine gute Voraussetzung dafür ist auch, dass es eine Software 
ist, die man gerne selber als \texttt{Debian}-Paket nutzen und anderen 
zur Verfügung stellen möchte.

Oft gibt es auch Pakete, für die die Maintainer Hilfe benötigen oder die 
verwaist sind. Dies kann auch auf selbstgenutzte Pakete zutreffen.
Um herauszufinden, ob und welche der installierten Pakete betroffen sind, 
gibt es ein Werkzeug, das man sich zusätzlich als Paket \textit{how-can-i-help}
\cite{HowCanIHelp2021} installieren kann. 

Diese Installation führt dazu, dass \textit{apt} am Schluss  
\textit{how-can-i-help -{}-apt} aufruft. Damit werden dann hilfebedürftige
Pakete aufgelistet, die gerade in der lokalen Installation aktualisiert wurden.

Mit \textit{how-can-i-help -{}-old} kann man sich anzeigen lassen, welche 
der installierten Pakete Hilfe benötigen.

Mit \textit{how-can-i-help -{}-all} werden alle Pakete angezeigt, für die 
Hilfe benötigt wird\footnote{Weitere Einzelheiten zu \textit{how-can-i-help} 
werden in Debian-Paketmanagement\cite{DPMB2021} in Kapitel 37.3.6 
beschrieben.}.

Unter \url{https://www.debian.org/devel/wnpp/} findet man auch diese Informationen.
Das Akronym \textit{wnpp} kürzt \textit{Work-Needing and Prospective Packages} ab
und steht sinngemäß für Pakete, an denen Arbeit erforderlich ist und die im
Entstehen sind (angehende Pakete).

Motivierend und hilfreich ist es auch, wenn man im Upstream-Projekt 
aktiv ist. In diesen Fällen ist eine gewisse Nachhaltigkeit der Betreuung 
des Paketes gewährleistet.

Für viele Kategorien von Paketen haben sich Betreuer-Teams gebildet
\footnote{Eine Liste der Teams findet sich im Wiki\cite{DebianTeams}}. 
Wählt man ein Paket, welches in das Portfolio eines solchen Teams passt, 
hat man bessere Chancen, Unterstützung und Sponsoren zu finden. 
Unterstützung findet man auch auf den Mailinglisten der jeweiligen Teams.

Bevor man mit dem Paketieren anfängt, sollte man natürlich prüfen, ob die
Software bereits paketiert ist. Mit \textit{apt search <name>} kann
festgestellt werden, ob es bereits ein entsprechendes
\texttt{Debian}-Paket gibt. Auf \textit{salsa.debian.org} kann
nachgeforscht werden, ob schon Paketierversuche im Gange sind.

Für alle Fragen zum Paketieren für \texttt{Debian} gibt es auch eine 
spezielle Mailingliste\footnote{\url{https://lists.debian.org/debian-mentors/}}. 
Schon das Mitlesen dieser Liste ist sinnvoll.

\chapter{Prüfung der Quellen}
\label{sec:SourceVerification}

Nach der Auswahl der für \texttt{Debian} zu paketierenden Software muss 
der Quellcode näher untersucht werden. Ziel dieser Untersuchung ist 
die Feststellung, dass die ausgewählte Software vom Paketbetreuer für 
\texttt{Debian main} paketiert werden kann. Dazu ist zu prüfen, ob 
\textbf{alle} Teile des Quellcodes konform zu den \texttt{Debian
Free Software Guidelines} (\texttt{DFSG})\cite{DFSG} \index{DFSG} und mit 
der \texttt{Debian}-Policy\cite{DebianPolicy} \index{Debian-Policy} 
vereinbar sind. 

Dies erfordert eine intensive Prüfung \textbf{aller} 
Quellcode-Dateien.

\section{Lizenzprüfung}\index{Lizenzprüfung}
\label{sec:LicenseCheck}

In \texttt{Debian} darf im Zweig \texttt{main} \index{main} ausschließlich
Freie Software \index{Freie Software} im Sinne der \texttt{Debian Free
Software Guidelines} \cite{DFSG} \index{DFSG} veröffentlicht werden.
Dabei ist zu beachten, dass die \texttt{Debian Free Software Guidelines
(DFSG)} nicht nur für Software-Lizenzen gelten, sondern gemäß Ziffer~1
der Version~1.1 des Gesellschaftsvertrages (\enquote{alle Komponenten}) auch
für die Lizenzen von Bildern, Tönen, Texten etc.

Die Prüfung dieser Anforderung hat 
einen großen Anteil an der Arbeit eines Paket-Betreuers, besonders um 
ein neues Paket in \texttt{Debian} zu veröffentlichen.

Bei der Erstellung und Pflege der \textit{debian/copyright}-Datei wird
dann diese Arbeit verwendet. Damit ist diese Datei auch 
eine der wichtigsten Dateien eines \texttt{Debian}-Paketes. Sie 
beschreibt die urheberrechtliche Situation.

Diese Datei muss das Copyright und die Lizenzen aller Dateien eines Quellpakets 
genau unter Verwendung einer spezifischen Syntax beschreiben (DEP-5).\cite{DEP-5}

Die \textit{debian/copyright}-Datei wird von den FTP-Mastern\cite{FTPMaster2020} 
überprüft, wenn ein neues Paket im \texttt{Debian}-Projekt angenommen 
werden soll. 

Um zu vermeiden, dass hierzu Einträge übersehen werden, gilt mindestens 
ein Vier-Augen-Prinzip \index{Copyright-Review} 
(Peer-Review)\cite{CopyrightReviewTools2021}.

Der Inhalt der Copyright-Datei muss also die Lizenzen \index{Lizenzen} 
aller Dateien genau wiedergeben. Die Lizenz \index{Lizenz} wird oft 
in den Kommentaren einer Quelldatei angegeben.

Der gesamte Quellcode ist unter diesem Aspekt zu prüfen. Es gibt einige 
Hilfsmittel, die dem Paket-Betreuer helfen, diese Tests durchzuführen.
\footnote{\url{https://wiki.debian.org/CopyrightReviewTools}}

\subsection{\textit{debmake}}
\label{subsec:debmake}

Der Befehl \textit{debmake -cc} \index{debmake} wird auch vom Programmskript 
zur Erstellung der Datei \textit{debian/copyright} genutzt 
(Kapitel~\ref{subsec:d/copyright}, Seite~\pageref{subsec:d/copyright}).

In der Praxis zeigt sich, dass dies manchmal nicht ausreicht. Dies liegt 
daran, dass die Informationen zu den Lizenzen und den Urhebern nicht 
einem Standard folgend abgelegt sind. Daher findet das Programm 
\textit{debmake} nicht alle Einträge bezüglich des benötigten
\textit{Copyrights}. Es werden also weitere Tests benötigt.

\subsection{\textit{licensecheck}}

Das Programm \textit{licensecheck} (aus dem gleichnamigen Paket) 
ist in der Lage, Quelldateien zu scannen und meldet das Copyright und 
die darin angegebenen Lizenzen. Er fasst diese Informationen jedoch nicht 
zusammen: Für jede Datei eines Pakets wird eine Copyright-Zeile generiert.

Der Test wurde mit der Befehlszeile

\begin{verbatim}
    licensecheck --check '.*' --recursive \
                 --deb-machine --lines 0 -- *
\end{verbatim}

wie im Wiki\footnote{\url{https://wiki.debian.org/CopyrightReviewTools\#licensecheck}} 
ausgeführt.

Leider ist die Handbuchseite (Manpage) von \textit{licensecheck} eher 
unergiebig. Mehr Informationen liefert der Befehl:

\begin{verbatim}
 licensecheck --help
\end{verbatim}

Die Ausgabe muss manuell ausgewertet werden, da \textit{licensecheck} auch 
versucht, das Copyright für sogenannte Binärdateien (z.~B. Bilder, Fonts)  
anzuzeigen.

\subsection{\textit{scan-copyrights}}

Mit dem Programm \textit{scan-copyrights} aus dem Paket 
\textit{libconfig-model-dpkg-perl} kann eine vorhandene Copyright-Datei 
durch erneutes Scannen der Quelle aktualisiert werden.

Die Befehlszeile dazu lautet:

\begin{verbatim}
 scan-copyrights   
\end{verbatim}

Das Programm kann auch eine solche Datei von Grund auf neu erstellen. 
Dies erfolgt im DEP-5-Format. \cite{DEP-5}

Dieses Programm ist in \texttt{Perl} geschrieben und nutzt 
\textit{licensecheck}.

\subsection{\textit{licensing}}

Der Befehl \textit{licensing} aus dem Paket \textit{licenseutils} kann den 
Quellcode scannen und gefundene Lizenzen mit dem Befehl

\begin{verbatim}
    licensing detect *
\end{verbatim}

melden. Es kann auch Lizenz-Vorlagen zu neuem Code hinzufügen.

\subsection{\textit{cme}}
\label{subsec:cme}

Ein weiteres Tool ist \index{cme}\textit{cme}. \textit{cme} prüft 
und/oder editiert die Daten in den Konfigurationsdateien. Damit kann man 
unter anderem prüfen, ob die vom Original-Autor \index{Original-Autor} 
bereitgestellte Copyright-Datei alle notwendigen Informationen enthält. 

Der Befehl \textit{cme fix dpkg} prüft die \textit{dpkg}-Dateien, 
aktualisiert veraltete Parameter und wendet alle Korrekturen an 
(Kapitel~\ref{sec:cmefix}, Seite~\pageref{sec:cmefix}).

Mit
\begin{verbatim}
    cme update dpkg-copyright  
\end{verbatim}

werden die in den Headern der Quellcodedateien aufgeführten Lizenzen 
geprüft und aufgelistet.

Mit
\begin{verbatim}
    cme check dpkg-copyright -file <Pfad/Dateiname> 
\end{verbatim}

können Daten aus einer beliebigen Datei gelesen werden.

Zu diesem Paket gibt es mit \textit{libcomcnfig-model-tkui-perl} 
auch eine graphische Oberfläche.

\subsection{Manuell}

Der Gebrauch dieser Werkzeuge ist manchmal nicht ausreichend. Es kann
vorkommen, dass irgendwo im Code weitere Autoren genannt werden. Hiernach
kann mit folgenden Befehlen gesucht werden:

\begin{enumerate}
    \item grep -{}-recursive -{}-ignore-case ``(c)`` .
    \item grep -{}-recursive -{}-ignore-case ``copyright`` .
    \item grep -{}-recursive -{}-ignore-case ``author`` .
\end{enumerate} 

\subsection{Stolperfallen}

Es gibt folgende Stolperfallen:
\begin{enumerate}
    \item {mitgelieferte Build-Abhängigkeiten}
    \item {Microcode}
    \item {mitgelieferte unfreie Dokumente}
    \item {vom Upstream-Autor unvollständig beachtete Lizenzen}
\end{enumerate}

Solche Dateien müssen aus dem zu veröffentlichenden \textit{*.orig.tar.xz} 
ausgeschlossen werden, sofern dies sinnvoll möglich ist. Dabei ist auch 
eine entsprechende Versionsbezeichnung zu wählen. \cite{debian-mentorsFAQ}. 
In diesem Programmskript ist vorgesehen, die Dateien mithilfe der Datei 
\textit{debian/copyright} auszuschließen (Kapitel~\ref{subsec:ExcludeFiles}, 
Seite~\pageref{subsec:ExcludeFiles})

Wenn im Quellcode-Paket unterschiedlich lizenzierte Dateien enthalten 
sind, ist neben der Prüfung der Lizenzen\index{Lizenzen} der einzelnen 
Quellcode-Dateien auch das Quellcode-Paket insgesamt zu untersuchen. Es 
ist zu prüfen, ob die verwendeten Lizenzen miteinander kompatibel sind. 
Hierbei ist 
\textit{FINOS Open Source License Compliance Handbook}\cite{OpenSourceLicenceCompliance2019} 
hilfreich.

\section{Feststellung der Programmiersprache}

Software wird in unterschiedlichen Programmiersprachen geschrieben. Es gibt 
auch Programme, die in mehreren Programmiersprachen geschrieben sind. 
Je nach Programmiersprache sind verschiedene Compiler- und Build-Systeme 
zu verwenden. 

Für das Bauen der \texttt{Java}-Pakete gibt es mehrere Build-Systeme. 
Dies wird in einem eigenen Kapitel ausführlich beschrieben
(Kapitel~\ref{chap:JavaPaketeBauen}, Seite~\pageref{chap:JavaPaketeBauen}).

\section{Prüfung der Abhängigkeiten}
\label{sec:CheckDependencies}

Es wird zwischen zwei Arten von Abhängigkeiten unterschieden:

\begin{itemize}
     \item Software, die für das Bauen des Paketes notwendig ist
     (build dependencies),
     \item Software, die für die Installation und/oder den Ablauf des
     paketierten Programms erforderlich ist (runtime dependencies) 
\end{itemize}

Um ein Paket in \texttt{Debian main} veröffentlichen zu können, müssen 
\textbf{alle} Abhängigkeiten \index{Abhängigkeit} (inklusive Build-Abhängigkeiten) 
bereits in \texttt{Debian main} verfügbar sein\cite{DebianPolicy}. Dies 
bedeutet, dass Abhängigkeiten, die noch nicht verfügbar sind, zunächst 
zu paketieren sind.

Wie die Abhängigkeiten ermittelt werden können, hängt von der Programmiersprache 
ab. Hinweise auf unerfüllte Build-Abhängigkeiten findet man auch in den 
Fehlermeldungen beim Bauen eines Paketes. Angaben dazu, warum das Bauen
fehlgeschlagen ist findet man in der Datei \textit{<Paketname>\_<Version>.build}.

Für \texttt{Java}-Programme gibt es verschiedene Orte, an denen diese 
Informationen gefunden werden können. Dies wird im entsprechenden Kapitel 
beschrieben (Kapitel~\ref{chap:JavaPaketeBauen}, Seite~\pageref{chap:JavaPaketeBauen})

Die dann gefundenen Build- und Runtime-Abhängigkeiten
müssen in der Datei \textit{debian/control} im passenden Abschnitt
aufgeführt werden (Kapitel~\ref{subsec:DebianControl},
Seite~\pageref{subsec:DebianControl}).

\subsection{Abhängigkeiten ermitteln mit \textit{packages.debian.org}}

Zur Ermittlung, ob die benötigte Abhängigkeit bereits paketiert ist, kann
die Webseite \textit{packages.debian.org} eine Anlaufstelle sein. 

Im Abschnitt \textit{Durchsuchen der Paket-Verzeichnisse} sind die
Optionen \textit{Nur Paketnamen} und \textit{Quellpaket-Namen} interessant.

Im Abschnitt \textit{Durchsuchen des Inhalts von Paketen} ist es dann die
Option \textit{ Pakete mit Dateien, deren Namen das Suchwort enthalten}.

Als Distribution sollte dann \textit{alle} bzw. \textit{Unstable}
ausgewählt werden.

\subsection{Abhängigkeiten ermitteln auf \textit{codesearch.debian.net}}

Manchmal kann es hilfreich sein, nach Quellcode zu suchen, in dem ein
ähnliches Problem schon mal gelöst wurde.

Ein Beispiel ist, dass in einem Paket, das mit \texttt{Maven} gebaut wurde,
schon einmal ein bestimmter Eintrag in der Datei \textit{debian/maven.rules}
erfolgte.

Eine solche Suche kann -- wie folgt -- durchgeführt werden:

\begin{verbatim}
    https://codesearch.debian.net/search?q=<SearchString>
\end{verbatim} 

\subsection{Suche nach Abhängigkeiten auf der Konsole}
% II.Werkzeuge, Kapitel 8.20\cite{DPMB2021}

Mit \textit{apt-file search} 
\footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}}
(Alias: \textit{apt-file find}) kann festgestellt werden, ob benötigte
Abhängigkeiten bereits in Debian paketiert sind. Mit
\textit{apt-file list <Paketname>} (Alias: \textit{apt-file show}) kann
der Inhalt eines Paketes aufgelistet werden. Hier kann dann nach
Programmnamen gesucht werden. Die gleichen Informationen erhält man mit
\textit{dpkg -L <Paketname>}.
 
\section{Änderungen am Quellcode}

Der Quellcode ist sorgfältig darauf zu prüfen, ob Änderungen an ihm für 
das \texttt{Debian}-Paket vorgenommen werden müssen. Eine solche 
Notwendigkeit kann verschiedene Ursachen haben.

Das Upstream-Release kann Teile enthalten, die nicht der 
\texttt{Debian}"=Policy\cite{DebianPolicy} \index{Debian-Policy} oder den 
\texttt{Debian}"=Free"=Software"=Guidelines\cite{DFSG} \index{DFSG} 
entsprechen. 

Änderungen am Quellcode speziell für das \texttt{Debian}-Paket können wie 
folgt vorgenommen werden:

\begin{itemize}
    \item Es können ganze Dateien ausgeschlossen werden. Dies geschieht beim Bauen 
einer neuen Version (Kapitel~\ref{subsec:ExcludeFiles}, 
Seite~\pageref{subsec:ExcludeFiles}).
    \item Es können Änderungen an Upstream-Dateien durch \textit{Patchen} 
(Kapitel~\ref{subsec:AenderungQuellcodeDateien}, Seite~\pageref
{subsec:AenderungQuellcodeDateien}) vorgenommen werden. Dies erfolgt durch
das Pro\-grammskript beim Bauen einer neuen Revision 
(Kapitel~\ref{chap:Aenderungen_am_Upstream_Code_vornehmen}, 
Seite~\pageref{chap:Aenderungen_am_Upstream_Code_vornehmen}).
\end{itemize}

\subsection{Ganze Dateien ausschließen}
\label{subsec:Dateien_ausschliessen}

Wenn ganze Dateien ausgeschlossen werden müssen, muss ein Quellcode-Paket 
erstellt werden, dass diese Dateien nicht mehr enthält.

Bevor \textit{mk-origtargz} aufgerufen wird, ermöglicht das Programmskript 
einzelne Quellco\-de-Dateien von der Aufnahme in das \textit{orig}-Archiv 
auszuschließen.

Die Dateien, die nicht der \texttt{Debian}-Policy\cite{DebianPolicy} oder 
den \texttt{Debian}-Free-Soft\-wa\-re-Guidelines (\texttt{DFSG})\cite{DFSG} 
entsprechen, sind zu entfernen. 

Dabei ist immer eine neue Version zu bauen, auch dann, wenn kein neues 
Upstream-Quellcode-Archiv verwendet wird.

Die Ausschlüsse sollen mit ihrer Begründung in der Datei \textit
{debian/README.source} (Kapitel~\ref{subsec:ReadmeSource}, Seite~\pageref
{subsec:ReadmeSource}) dokumentiert werden.

\subsubsection{Auflistung der auszuschließenden Dateien}

Die auszuschließenden Dateien können entweder in einer separaten Datei 
oder in der Datei \textit{debian/copyright} im \textit{DEP-5-Format}
\cite{DEP-5} aufgelistet werden.

Beispiel:
\scriptsize
\begin{verbatim}
    Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
    Upstream-Name: <UpstreamName>
    Source: <URL to upstream source>
    Files-Excluded: <all files to be excluded>
    Comment: <description, why the files are excluded>    
\end{verbatim}
\normalsize

In der Aufzählung werden die Dateien, die auszuschließen sind, durch 
Leerzeichen oder Zeilenumbruch mit Einrückung um ein Zeichen separiert. 

%Dabei sind die Hinweise der FTP-Master entsprechend abzuarbeiten. 
%Dies kann auch dazu führen, dass bereits erfolgte Einträge in den Dateien 
%im Verzeichnis \textit{debian/} angepasst werden müssen.

\subsubsection{Fallunterscheidungen}

Oft steht schon vor der Einreichung des Paketes zur \textit{New Queue} fest, 
dass Dateien auszuschließen sind. Da es zu diesem Zeitpunkt noch keine 
Datei \textit{debian/copyright} gibt, bietet es sich an, die 
auszuschließenden Dateien in einer separaten Datei aufzulisten.

Auf die entsprechende Frage im Programmskript ist anzugeben, dass 
Dateien auszuschließen sind. Dann ermittelt das Programmskript, wo die 
Informationen zum Ausschluss von Dateien hinterlegt werden sollen. 
Dies ist vor der Einreichung des ersten Paketes eines neuen Projektes 
eine separate Datei. 

Dazu wird eine Datei \textit{<SourceName>-excluded} im Verzeichnis 
\textit{PrjPath} (Kapitel~\ref{subsec:PathDefinition}, 
Seite~\pageref{subsec:PathDefinition}) erstellt.

Die Informationen in dieser Datei sind bei der Erstellung der Datei 
\textit{debian/copyright} dorthin zu übertragen 
(Kapitel~\ref{subsec:d/copyright}, Seite~\pageref{subsec:d/copyright}).

Nach einer Zurückweisung aus der \texttt{New Queue} muss das Paket neu 
für eine Veröffentlichung bereit gestellt werden. 
Auch hierbei kann es vorkommen, dass Dateien, deren Lizenz nicht 
\texttt{DFSG}-konform ist, ausgeschlossen werden müssen. Der Ausschluss 
der Dateien gilt bereits für das zu veröffentlichende 
*.orig.tar.(gz | bz2 | xz). 
Meist steht zu diesem Zeitpunkt aber keine weitere (neuere) 
Upstream-Version zur Verfügung. Die zu erstellende Version muss jedoch 
größer sein als die bisherige Version aber kleiner als die nächste zu 
erwartende Upstream-Version.

Im Falle des Entfernens von Dateien, die nicht DFSG-konform sind, ist 
dies der Anhang \textit{+dfsg}, der sich direkt an die Upstream-Version 
anschließt. Ist dieser Anhang bereits vorhanden, so wird er nach 
\textit{+dfsg1} hochgezählt (s. Kapitel~\ref{subsubsec:BenamungPakete}, 
Seite~\pageref{subsubsec:BenamungPakete}). So kann mit \textit{mk-origtargz} ein 
neuer Tarball mit einer größeren Versionsbezeichnung erstellt werden. 
(Kapitel~\ref{sec:schema}, Seite~\pageref{sec:schema})

Die Namen der auszuschließenden Dateien werden der dann schon 
vorhandenen Datei \textit{debian/copyright} im DEP-5-Format\cite{DEP-5} 
hinzugefügt. Nach dem Commit dieser Anpassungen im Verzeichnis \textit{debian/} 
kann eine neue Version gebaut werden. Dazu wird das bisherige Upstream-Archiv 
verwandt. 

Auf diese Weise wird ein neuer Orig-Tarball mit \textit{mk-origtargz} 
ohne die auszuschließenden Dateien aus dem bisherigen *.tar.gz erstellt 
und dessen Inhalt mit \textit{gbp import-orig} in das vorhandene 
Git-Repositorium eingefügt (Kapitel~\ref{subsec:GbpImportOrig}, 
Seite~\pageref{subsec:GbpImportOrig}).

Wird es bei einer neuen Upstream-Version notwendig, dass Dateien 
auszuschließen sind, oder ändern sich die auszuschließenden Dateien, 
ist genauso zu verfahren, wie soeben dargelegt. 
Es muss die Copyright-Datei geändert und ein entsprechender Commit 
ausgeführt werden. Wiederum ist beim Bauen der neuen Version anzugeben, 
dass Dateien auszuschließen sind.

\subsubsection{Benamung der Pakete beim Ausschluss von Dateien}
\label{subsubsec:BenamungPakete}

Damit die Versionsbezeichnung dieser neuen Version größer als die der 
bisherigen, aber kleiner als die zu erwartenden nächsten Upstream-Version 
ist, wird die bisherige Versionsbezeichnung mit einem Anhang versehen. 
Dieser macht zugleich deutlich, dass und warum der Upstream-Code 
verändert wurde.

Übliche Ergänzungen der Versionsbezeichnung sind \textit{+dfsg} und 
\textit{+ds}\footnote{\url{https://wiki.debian.org/DebianMentorsFaq} in
section
\textit{What does \enquote{dfsg} or \enquote{ds} in the version string mean}}.

Wenn Lizenzen einzelner Dateien des Upstream-Quellcodes nicht den
\texttt{Debian Free Software Guildelines (DFSG)} genügen und daher nicht
als Quellen durch \texttt{Debian} veröffentlicht werden sollen, wird als
Ergänzung\textit{+dfsg} benutzt. 
Erfordern andere Gründe den Ausschluss, nimmt man \textit{+ds} (\enquote{Debian 
Source}).\cite{debian-mentorsFAQ} 

Es kann nämlich passieren, dass zunächst nur Dateien ausgeschlossen wurden, 
die nicht der \texttt{Debian}-Policy entsprechen. 

Wird später festgestellt, dass das hochgeladene Original-Archiv noch 
unfreie Dokumente enthält, führt dies dann zu einer Versionsbezeichnung 
nach dem Muster \textit{<Versionsnummer>+ds+dfsg}\footnote{s. Mentors-FAQ 2.6\cite{
debian-mentorsFAQ}}

In manchen Fällen kann ein Pluszeichen (+) Probleme vor allem beim Bauen 
von Java-Paketen verursachen.

Die dargestellte Benamung der \texttt{Debian}-Pakete hat auch Konsequenzen 
für den Inhalt der Datei \textit{debian/watch} (Kapitel~\ref{sec:uscanwatch} 
Seite~\pageref{sec:uscanwatch} und Kapitel~\ref{sec:uscan} 
Seite~\pageref{sec:uscan}).

\subsection{Änderungen in einzelnen Quellcode-Dateien (Patchen)}
\label{subsec:AenderungQuellcodeDateien}

Änderungen an Quellcode-Dateien\index{Patchen} sind dann notwendig, 
wenn aufgrund unterschiedlicher Build-Umgebungen 
\index{Build-Umgebungen} Anpassungen vorzunehmen sind. Andere Fälle sind 
Fehlerbehebungen\index{Fehlerbehebung}, vor allem 
\textit{Security-Patches}\index{Security-Patches}.

Die klassische Methode ist die im Folgenden beschriebene mit 
\textit{quilt}.

Daneben kann dies auch in einem \textit{Patch-Queue}-Zweig mit \textit{gbp pq} 
erfolgen (Kapitel~\ref{subsubsec:BeschreibungPQ}, 
Seite~\pageref{subsubsec:BeschreibungPQ})

\subsubsection{Patchen mit \textit{quilt}}

Änderungen an Quellcode-Dateien erfolgen durch sogenannten Patch-Datei\-en. 
Diese dokumentieren den ursprünglichen Quellcode und die jeweiligen Änderungen. 
Eine weitere Datei (\textit{debian/patches/series}) steuert die Reihenfolge 
der Anwendung der Patches. Herkömmlicherweise geschieht dies mit 
\textit{quilt}. \textit{Dquilt} ist eine \texttt{debian}-spezifische 
Anpassung für \textit{quilt}. 

Hierzu gibt es eine Beschreibung im \textit{Debian-Leitfaden für Neue 
Paketbetreuer}\footnote{\url{https://www.debian.org/doc/manuals/maint-guide/modify.de.html}} 
und im \textit{Debian-Wiki}\cite{UsingQuilt2020}. 
Daneben gibt es eine allgemeine Einführung in die Nutzung von Quilt \cite{Gruenbacher2012}.

In Kapitel~\ref{sec:QuiltEinrichtung} (Seite~\pageref{sec:QuiltEinrichtung}) 
wird beschrieben, wie die \texttt{debian}-spezifische Anpassung erzeugt wird.

\subsubsection{Patchen in einem \textit{Patch-Queue}-Zweig}
\label{subsubsec:BeschreibungPQ}

Da ein Arbeitsablauf mit \texttt{Git} bzw. \textit{git-buildpackage} 
\cite{Guenther2006-2017} 
zum Bauen der Debian-Pakete genutzt wird, bietet es sich an, 
\textit{gbp pq}\index{gbp pq} statt \index{quilt} 
\textit{quilt}\footnote{section gbp.patches.html 
\cite{Guenther2006-2017}} einzusetzen.

Die Änderungen erfolgen dann in einem eigenen \texttt{Git}.Zweig 

Bei der Nutzung von \textit{gbp pq} erfolgen in diesem Zweig dann 
\emph{alle} Codeänderungen. Diese Änderungen sollten thematisch und 
kleingliedrig sein. Dann können die Patches einfacher nach Upstream 
fließen oder von anderen Distributionen übernommen werden. Dies 
erleichtert auch die Anpassung an eine neue Upstream-Version.

Die Grundidee ist, dass Patches vom \texttt{Debian}-Zweig in den 
Patch-Queue-Zweig so importiert werden, dass jeweils eine Patch-Datei 
in \textit{debian/patches} jeweils einem Commit auf dem 
Patch-Queue-Zweig entspricht.

Die Anlage des Patch-Queue-Zweiges erfolgt mit \textit{gbp pq import}.
(s.~a. Kapitel~\ref{subsec:CreatePQMigration},
Seite~\pageref{subsec:CreatePQMigration})
 
Der erstellte Zweig wird nach dem Zweig benannt, aus dem er importiert 
wurde. Zur Unterscheidung wird \textit{patch-queue/} vorangestellt.
Wird also die \texttt{Debian}-Paketierung auf \textit{debian/sid} gemacht 
und ein \textit{gbp pq import} ausgeführt, wird der neu erstellte Zweig 
\textit{patch-queue/debian/sid} genannt. 

Das Programmskript ermöglicht diesen Import (Kapitel~\ref{subsec:CreatePQMigration}, 
Seite~\pageref{subsec:CreatePQMigration}).

Im Patch-Queue-Zweig kann mit den bekannten \texttt{Git}-Befehlen 
(\textit{rebase}, \textit{commit} und \textit{-{}-amend}, etc.) an den 
Commits gearbeitet werden. Wenn dies erledigt ist, wird 
\textit{gbp pq export} verwendet, um die Commits auf dem 
\textit{Patch-Queue-Zweig} wieder in Patches in 
\textit{debian/patches/}-Dateien umzuwandeln 
%toDo: Hier muss noch der Verweis angepasst werden
(Kapitel~\ref{sec:WorkingwithGbpPq}, 
Seite~\pageref{sec:WorkingwithGbpPq}).

Dieser beschriebene Workflow erleichtert z.~B. das Cherry-Picking von 
Patches für stabile Releases, die Weiterleitung von Patches an neue 
Up\-stream-Versionen durch die Verwendung von \textit{git rebase} auf den 
Patch-Queue-Zweig (bereits angewandte 
Patches werden automatisch erkannt) sowie das Neuordnen, Ablegen und 
Umbenennen von Patches, ohne auf \textit{quilt} zurückgreifen zu müssen.
Die erzeugten Patches in \textit{debian/patches/} haben alle notwendigen 
Informationen, 
um sie nach Upstream weiterzuleiten, da sie ein Format ähnlich dem 
\textit{git-format-patch} verwenden.

Der Hauptnachteil dieses Arbeitsablaufes ist der Mangel an Historie im 
Patch-Queue-Zweig, da er häufig fallen gelassen und neu erstellt wird. 
Aber es gibt natürlich eine vollständige Historie auf dem 
\texttt{Debian}-Zweig im Verzeichnis \textit{debian/patches/}.

Zu beachten ist, dass \textit{gbp pq} derzeit keine vollständige 
Unterstützung für DEP3-Header\cite{DEP-3} bietet. 

Zunächst wird versucht, mit git-mailinfo\cite{GitMailinfo2020} zu parsen, 
was nur die Felder \textit{From} und Subject unterstützt. 
Wenn keines dieser beiden vorhanden ist, wird \textit{gbp pq} versuchen, 
den Patch vom DEP3-Format in ein git-mailinfo(1)-kompatibles Format zu 
konvertieren. 
Dabei wird zuerst aus den Feldern ``Autor'' und ``Betreff'' über die erste Zeile des 
Feldes Beschreibung geladen. 
Anschließend werden alle zusätzlichen Felder (wie ``Origin'' und ``Forwarded'') 
und der Rest der Beschreibung (falls vorhanden) an den \textit{mail body} 
angehängt.

\chapter{Versionierung der Pakete}
\label{chap:VersioningPackage}

Sowohl die Software, die für Debian gebaut werden soll, als auch 
\texttt{Debian}-Pakete haben Versionsbezeichnungen. Dabei sollte die 
Versionsbezeichnung der Upstream-Software in der des Debian-Paketes 
enthalten sein.

Die Namen aller Debian-Binärpaketdateien sind folgendermaßen aufgebaut:

\small 
\textless{}foo\textgreater{}\_\textless{}Versionsnummer
\textgreater{}-\textless{}Debian-Revisionsnummer\textgreater{}\_
\textless{}Debian-Architektur\textgreater{}.deb.
\normalsize
\footnote{DebianFAQ2019, Kapitel 7.3\cite{DebianFAQ2019}}

\section{Paketname}

Vor der Versionsbezeichnung kommt der Paketname.

Dieser muss gänzlich in Kleinbuchstaben geschrieben werden. Die 
Versionsbezeichnung kann auch Ziffern enthalten. 
Zusätzlich können +, -, \textasciitilde{} enthalten sein.

Die Versionsbezeichnung muss mit einer Ziffer beginnen.

\section{Versionierungsschema}
\label{sec:schema}

Die Versionierung \index{Versionierungsschema} der Pakete folgt einem fest 
definierten Schema. Damit
wird sichergestellt, dass alle Werkzeuge, die diese Versionierung verwenden, 
auf die gleiche Systematik zugreifen können. Dabei muss sichergestellt 
werden, dass das System die neue Versionsbezeichnung 
\index{Versionsbezeichnung} auch als größer als 
die vorherige Versionsbezeichnung erkennt.
(s.a Kapitel~\ref{subsec:IdentifyUpstreamVersion}, 
Seite~\pageref{subsec:IdentifyUpstreamVersion})

Wie muss also die Versionsbezeichnung des zukünftigen Paketes zusammensetzt 
sein? Nach der Versionsbezeichnung des Upstream-Paketes können 
debian-spezifische Zusätze erfolgen. Diese können anzeigen, ob und warum 
Teile der Upstream-Software entfernt wurden oder ob das Paket auf ein 
älteres Paket zurückportiert wurde. Außerdem ist in der 
Versionsbezeichnung des Paketes eine \texttt{Debian}-Revisionsnummer 
enthalten. Diese Revisionsnummer \index{Revisionsnummer} 
wird insbesondere dann erhöht, wenn das 
Paket wegen Korrekturen in Dateien im Verzeichnis \textit{debian/} neu 
gebaut wurde.

Mögliche Varianten können mit dem folgenden Befehl auf ihre Tauglichkeit 
überprüft werden:\index{compare-version}

\begin{verbatim}
dpkg --compare-versions Version1 Operant Version2 && \
echo "OK"
\end{verbatim}
Als Operanden sind diese zu nutzen: lt le eq ne ge gt

\begin{description}
    \item[lt] kleiner als (<)
    \item[le] kleiner oder gleich (<=)
    \item[eq] gleich (=)
    \item[ne] ungleich (!=)
    \item[ge] größer oder gleich (>=)
    \item[gt] größer als (>)
\end{description}
    
Die Versionsvergleichsregeln \index{Vergleichsregeln} können wie folgt 
zusammengefasst werden:\footnote{New Maintainer Guide, Kapitel 2.6 
\cite[Kapitel 2.6]{maint-guide} s.a. Debmake-doc, Kapitel 5.2}

\begin{itemize}\itemsep2pt
    \item Zeichenketten werden von Anfang bis Ende verglichen.
    \item Buchstaben sind größer als Ziffern.
    \item Ziffern werden als Ganzzahlen verglichen.
    \item Buchstaben werden in ASCII-Sortierreihenfolge verglichen.
    \item Es gibt besondere Regeln für Punkt (.), Plus- (+) und Tilde- 
    (\textasciitilde) Zeichen, wie folgt:
    \emph{Beispiel:} 0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0\textasciitilde rc1 < 1.0 
    < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0
\end{itemize}

In manchen Fällen kann ein Pluszeichen (+) Probleme vor allem beim Bauen 
von Java-Paketen verursachen.

Die ``richtige'' Versionierung spielt eine Rolle, wenn diese von Programmen 
gelesen und genutzt werden soll. Dies sind vor allem die Programme 
\textit{dpkg}\index{dpkg}, \textit{apt}\index{apt} und \textit{uscan}.

\section{\textit{apt} und \textit{dpkg}}

Die korrekte Versionierung des \texttt{Debian}-Paketes ist dann nicht 
ganz einfach, wenn nicht für \texttt{Debian}-Sid gebaut wird 
(Kapitel~\ref{sec:Versioning}, Seite~\pageref{sec:Versioning}).

\textit{dpkg} bzw. \textit{apt} müssen zutreffend ermitteln können, ob 
ein neueres Paket im jeweiligen Release-Zweig zur Verfügung steht.

\section{\textit{uscan} und die Datei \textit{debian/watch}}
\label{sec:uscanwatch}

\textit{uscan}\index{uscan} ist ein nützliches Werkzeug im 
\texttt{Debian}-Projekt. 
Mittels \textit{uscan} kann geprüft werden, ob es eine Upstream-Version 
gibt, die aktueller (also höher versioniert) ist, als das aktuelle 
\texttt{Debian}-Paket.

Das Programm \textit{uscan} wird mit dem Paket \textit{devscripts}\index{devscripts} 
zur Verfügung gestellt.

Anhand der in \textit{debian/watch} enthaltenen Daten prüft \textit{uscan},
ob neuere Versionen in der Originalquelle\index{Originalquelle} vorhanden
sind (Kapitel~\ref{sec:uscan}, Seite~\pageref{sec:uscan}), und kann sie 
gegebenenfalls herunterladen (Kapitel~\ref{sec:ImportWithUscan}, 
Seite~\pageref{sec:ImportWithUscan}).

Die durch \textit{uscan} gewonnene Informationen werden auch auf der 
Seite des jeweiligen Maintainers 
\\
\url{https://qa.debian.org/developer.php?<Maintainer>@debian.org}
\\
dargestellt.

Dafür benötigt \textit{uscan} vor allem eine taugliche Datei 
\textit{debian/watch}\index{Watch (Datei)}. Die Erstellung dieser Datei,
die auch beim Herunterladen des Quellcodes mit \textit{uscan} 
(Kapitel~\ref{sec:ImportWithUscan}, Seite~\pageref{sec:ImportWithUscan})
benötigt wird, wird vom Programmskript unterstützt 
(Kapi\-tel~\ref{subsec:DebianWatch}, Seite~\pageref{subsec:DebianWatch}).

Wenn Dateien ausgeschlossen werden und die \textit{*.orig.tar.xz}-Datei 
entsprechend be\-namt wurde (Kapitel~\ref{subsubsec:BenamungPakete}, 
Seite~\pageref{subsubsec:BenamungPakete}), sind entsprechende Optionen
in die Datei \textit{debian/watch} einzufügen. Diese Optionen sind 
\textit{repack}, 
\textit{compression}, \textit{repacksuffix} und \textit{dversionmangle}.
Dann kann bei der nächsten neuen Upstream-Version das Herunterladen mit 
\textit{uscan} durchgeführt werden. Dies gilt auch für die Prüfung 
mittels \textit{uscan}, ob es eine neue Upstream-Version gibt.

Beispiel:
\begin{verbatim}
    opts=repack,\
    compression=xz,\
    repacksuffix=+dfsg,\
    dversionmangle=s/\+dfsg// \
\end{verbatim}

\chapter{\textit{dh\_make}}
\label{chap:DhMake}

Es gibt erfreulicherweise viele nützliche Programme 
(Hilfsprogramme)\index{Hilfsprogramme}, 
die das Bauen von \texttt{Debian}-Paketen erleichtern und vereinheitlichen. 
Wer sich mit dem Bauen von \texttt{Debian}-Paketen befasst, wird immer 
wieder auf das Werkzeug \textit{dh\_make}\index{dh\_make} stoßen. Das
Paket heißt \textit{dh-make} (mit Bindestrich).

\textit{dh\_make} zeigt auf, wie ein \texttt{Debian}-Paket potenziell 
aussehen kann. Dies ermöglicht das Erlernen des Paketierens an konkreten 
Beispielen. Lehrreich sind vor allem die im Programmpaket enthaltenen 
Vorlagen (Templates).

\textit{dh\_make} erstellt viele Dateien in dem  Verzeichnis 
\textit{debian/}. Für die meisten Pakete wird nur eine Teilmenge davon 
benötigt. 

Die Praxis zeigt, dass jedes Mal geprüft werden muss, welche Dateien 
für das konkrete Paket nicht benötigt werden. Auch sind die erzeugten 
Dateien unvollständig und erfordern einiges an Handarbeit.

Um \textit{dh\_make} nutzen zu können, sind einige Vorbereitungen 
zu treffen. Dazu wird ein entsprechendes \enquote{Arbeitsverzeichnis} 
angelegt. Darin wird das heruntergeladene Quellco\-de-Archiv abgelegt. 
Bevorzugt wird ein hierfür vorgesehenes Tar-Archiv.

Dieses Tar-Archiv wird dort entpackt. Dies kann auf der Konsole durchgeführt
werden.mit

\begin{verbatim}
    tar --extract --auto-compress --file=<Tar-Archiv>.tar.gz
\end{verbatim}

\textit{dh\_make} muss in dem Verzeichnis aufgerufen werden, das den 
Quellcode enthält. Dabei kann es vorkommen, dass der Name des Verzeichnisses 
mit dem Quellcode außer Kleinbuchstaben noch weitere Zeichen enthält. 
\textit{dh\_make} benötigt jedoch einen Namen, der Einschränkungen 
unterliegt und dem Schema <paketname>-<version> entspricht. \textit{dh\_make}
akzeptiert bei Paketnamen nur Kleinbuchstaben.

Damit \textit{dh\_make} die Vorlagen korrekt füllen kann, wird in 
solchen Fällen an \textit{dh\_make} die zusätzliche Option 
\textit{-{}-packagename} hinzugefügt. Hiermit kann die Verwendung des 
nachfolgenden Namens als Name des Quellcodepaketes erzwungen werden. 
Dieser Verzeichnisname muss die Versionsbezeichnung enthalten. 
Zwischen Paketnamen und Versionsbezeichnung muss ein Bindestrich stehen.

So kann nach dem Wechsel in dieses Verzeichnis dort mit

\begin{verbatim}
  dh_make --createorig --packagename <SourceName>
\end{verbatim}

das Quellarchiv in der von \texttt{Debian} gewünschten Form 
\textit{<SourceName>.orig.tar.gz|xz} erzeugt werden. Daneben wird ein 
Entwurf der Dateien im Verzeichnis \textit{debian/} erstellt.

Dabei werden folgende Informationen abgefragt.
\begin{description}
    \item[Type of package = Paketklassen] single, indep, library, python mit folgender 
    Bedeutung
    \begin{description}
        \item[single] Es wird ein einzelnes Binary-Paket (*.deb) erstellt. 
        Dies ist der Normalfall
        \item[indep] Es wird ein Binary-Paket erstellt, das von der Architektur 
        unabhängig ist.
        \item[library] Es werden mindestens zwei Binärdateien erstellt.
        Ein Bibliothekspaket, das nur die lib in /usr/lib enthält, und 
        ein weiteres *-dev\_*.deb-Paket, das die Dokumentation und 
        C-Header enthält.
        \item[python]
    \end{description}
    \item[Einzelheiten zun Paket] Es werden die ermittelten Werte für 
    \textit{Maintainer Name}, \textit{Email-Address}, \textit{Date},
    \textit{Package Name}, \textit{Version}, \textit{License} und 
    \textit{Package Type} zur Bestätigung angezeigt.
\end{description}

Es werden folgende Dateien erzeugt. Dabei werden zunächst die Dateien 
gelistet, die auf jeden Fall benötigt werden, jeweils in alphabetischer 
Reihenfolge. Die Dateien \textit{README.Debian} und \textit{README.source}
können zu Informationszwecke genutzt werden. Zum Schluss folgen solche 
Vorlagen, die nur in sehr wenigen Paketen genutzt werden.

\begin{itemize}
    \item changelog
    \item control
    \item copyright
    \item rules
    \item salsa-ci.yml.ex
    \item source/format
    \item watch.ex
    \item README.Debian
    \item README.source
    \item manpage.1.ex
    \item manpage.sgml.ex
    \item manpage.xml.ex
    \item postinst.ex
    \item postrm.ex
    \item preinst.ex
    \item prerm.ex
    \item <packagename>.cron.d.ex
    \item <packagename>.doc-base.EX
    \item <packagename>-docs.docs
\end{itemize}

Die nicht benötigten Dateien werden aus dem Verzeichnis \textit{debian/} 
entfernt.

Dass der Verzeichnisname die jeweilige Versionsbezeichnung enthalten muss, 
ist bei der Verwendung von \textit{git} ungünstig. Es wird bisher davon 
abgesehen, dieses Hilfsprogramm im Programmskript einzusetzen. 

\chapter{\texttt{Java}-Pakete bauen}
\label{chap:JavaPaketeBauen}

Das Bauen von \texttt{Java}-Paketen weist besondere Herausforderungen auf.
Diese Besonderheiten werden im Folgenden ausführlich beschrieben.

Für das Packen von \texttt{Java}-Paketen gibt es eine speziellen 
Richtlinie, die\index{Java-Policy} \texttt{Debian}-\texttt{Java}-Policy\cite{JavaPolicy}.

Ferner gibt es noch eine Beschreibung über das Paketieren mit den 
\texttt{Java}tools\cite{Koschany}. Darin werden die\index{javahelper} 
\texttt{Java}-Helper beschrieben. Dieses Tutorial ist auch Bestandteil des 
\texttt{Debian}-Paketes \textit{javahelper}.

Weitere Informationen erhält man auch aus der\index{Java-FAQ} 
\texttt{Java}-FAQ\cite{Werner2014}, vor allem im Abschnitt 
2.4\footnote{\url{https://www.debian.org/doc/manuals/debian-java-faq/ch2.en.html\#s2.4}}

\section{Herausforderungen}

In einem Blog-Artikel\cite{Steiner2019}
beschreibt Hans-Christoph Steiner zutreffend die Herausforderungen für ein 
\texttt{Debian}-Paket in Bezug auf \texttt{Java}-Software.

Das \texttt{Debian}-\textit{Java}-Team muss demnach konsequent gegen die 
\textit{Java}-Stan\-dard\-pra\-xis ankämpfen, alle Abhängigkeiten in einer 
einzigen \textit{*.jar}-Datei zu bündeln. Dies bedeutet, dass es keine 
gemeinsamen Sicherheitsaktualisierungen gibt. Jeder Entwickler muss jede 
Abhängigkeit\index{Abhängigkeit} in diesem Modell selbst aktualisieren. 
Das funktioniert hervorragend für große Unternehmen mit Mitarbeitern, 
die sich dieser Aufgabe widmen.

Für die Mehrheit der \texttt{Debian}-Anwendungsfälle funktioniert das 
schlecht. \texttt{Debian} hält das Versprechen ein, dass die Leute 
\textit{foo} einfach passend installieren können, damit es funktioniert, 
und Sicherheitsaktualisierungen erhalten. Der Benutzer muss nicht einmal 
wissen, in welcher Sprache das Programm geschrieben ist, es funktioniert 
einfach.

Die Hoffnung, dass die \textit{Java}-Entwickler-Gemeinschaft sich den 
Wert dieser Anwendungsfälle zu eigen macht und \texttt{Debian} hilft, 
indem sie es einfacher macht, \textit{Java}-Projekte in der 
Standard-Distributionsmethode zu paketieren, mit gemeinsamen 
Abhängigkeiten, die unabhängig aktualisiert werden, hat sich bislang 
nur rudimentär erfüllt.

\section{Anwendungen und Bibliotheken}

Es gibt zwei Kategorien von \texttt{Java}-Paketen:
Anwendungen\index{Java-Anwendung} und Bibliotheken\index{Java-Bibliothek}. 
Sowohl \texttt{Java}-Anwendungen als auch \texttt{Java}-Bibliotheken 
können im Quellcode (weitere) Bibliotheken enthalten, die vorkompiliert 
sind.

Sollen in \texttt{Java} geschriebene Anwendungen paketiert werden, müssen 
in der Regel auch \texttt{Java}-Bibliotheken als \texttt{Debian}-Pakete 
bereitgestellt werden.

Sowohl Anwendungen als auch Bibliotheken werden in \textit{*.jar}-Dateien 
als \textit{Zip}-Archiv bereitgestellt.

Beide Arten müssen grundsätzlich als \texttt{Java}-Bytecode (*.class-Dateien, 
verpackt in einem *.jar-Archiv) und mit einer \enquote{\textit{Architecture: all}} 
(Kapitel~\ref{subsec:rules}, Seite~\pageref{subsec:rules}) ausgeliefert werden.

Hat man von einer zu paketierenden Anwendung oder Bibliothek zunächst nur 
ein (kompiliertes) \textit{*.jar}-Archiv, kann ein Blick in die Datei 
\textit{MANIFEST.MF} des jeweiligen \textit{~.jar}-Archivs helfen, 
diejenige \textit{URL} zu ermitteln, unter der der Quellcode 
veröffentlicht worden ist.

\subsection{\texttt{Java}-Programme paketieren}

\texttt{Java}-Programme\index{Java-Programm} sind dazu bestimmt, von 
Endbenutzern ausgeführt zu werden. Diese benötigen auch eine Manpage, 
soweit es sich um selbstständig ausführbare Programme handelt.
\footnote{Kapitel 2.3 der \texttt{Java}-Policy\cite{JavaPolicy}}

Das Paket muss auch sicherstellen, dass die richtige Klasse als 
Hauptklasse verwendet wird.

Zusätzliche Klassen im Paket müssen in ein oder mehrere 
\texttt{Java}-Archiv(e) (\textit{*.jar}-Datei(en) gepackt werden, die in 
\textit{/usr/share/java} (wenn sie für die Verwendung durch andere 
Programme vorgesehen sind) oder in \textit{/usr/share/<package>} als ein
\enquote{privates} Verzeichnis abgelegt werden können.

\subsection{\texttt{Java}-Bibliotheken paketieren}

\texttt{Java}-Bibliotheken\index{Java-Bibliothek} dienen der Erfüllung 
von Abhängigkeiten von Programmen. Dies können Build- und/oder 
Laufzeitabhängigkeiten sein.

\subsection{Name des \texttt{Java}-Paketes}
\label{subsec:Paketname}

Eine besondere Herausforderung ist die Bildung des korrekten Namen des
\texttt{Java}-Paketes.



\section{Abhängigkeiten bei \texttt{Java}-Paketen}

\texttt{Java}-Anwendungen hängen immer auch von \texttt{Java}-Bibliotheken 
ab. Außerdem wird für die \texttt{Java}-Pakete immer \textit{default-jdk}
als Abhängigkeit benötigt. Dahinter verbirgt sich in der Regel die aktuell 
verfügbare OpenJDK-Version, eine freie \texttt{Java} Implementierung mit 
Langzeitunterstützung (JDK = \texttt{Java} Development Kit).

Daneben gibt es spezielle Abhängigkeiten, die sich aus dem Build-System 
ergeben. Diese werden bei den einzelnen Build-Systemen im Folgenden 
besprochen.

\subsection{Weitere Abhängigkeiten feststellen}
\label{subsec:DetectDependencies}

\texttt{Java}-Entwickler fügen ihren Quellcode-Paketen die benötigten 
Build-Ab\-hängigkeiten - auch Bibliotheken von Drittanbietern - in 
kompilierter Form als *.jar-Archive hinzu.

Gerade unter \texttt{Java}-Entwicklern ist es leider sehr 
verbreitet, auf irgendwo im \texttt{World Wide Web} veröffentlichte 
Bibliotheken zurückzugreifen und diese dann vorkompiliert mit auszuliefern. 
Diese Bibliotheken müssen durch in \texttt{Debian} veröffentlichte Pakete 
ersetzt werden.

Zur Feststellung von Abhängigkeiten ist also im Quellcode nach 
\textit{*.jar}-Archiven zu suchen.

In diesem Falle ist für den \texttt{Debian}-Maintainer ein Repacking zum Entfernen 
dieser Dateien aus dem Upstream-Tarball notwendig. 
(Kapitel~\ref{chap:Aenderungen_am_Upstream_Code_vornehmen}, 
Seite~\pageref{chap:Aenderungen_am_Upstream_Code_vornehmen})

Die ausgeschlossenen Bibliotheken müssen durch eigenständige Pakete 
verfügbar gemacht werden.

\subsection{Abhängigkeiten ermitteln}
\label{VerifyDependencies}

Hat man Abhängigkeiten festgestellt, so ist zu ermitteln, wie diese 
Abhängigkeiten erfüllt werden können. Hierzu ist als erstes zu prüfen, 
ob bereits entsprechende \texttt{Debian}-Pakete existieren. Um zu 
ermitteln, ob eine Abhängigkeit bereits in \texttt{Debian} paketiert 
wurde, gibt es mehrere Wege.

\texttt{Debian}-Wiki (für Maven-Pakete):

\url{https://wiki.debian.org/Java/MavenPkgs}

\section{Build-Systeme für \texttt{Java}-Pakete}

Zum Bauen von \texttt{Java}-Paketen werden verschiedene Build-Systeme 
\index{Java-Build-System} genutzt. Hierbei handelt es sich um 
\textit{maven}, \textit{ant} und \textit{gradle}. Daraus ergeben sich 
Eigenheiten, die beim Paketieren für \texttt{Debian} beachtet werden 
müssen. Es gibt auch \texttt{Java}-Pakete, die ohne eines dieser 
Build-Systeme gebaut werden. Die folgenden Beschreibungen orientieren sich 
an den gemachten Erfahrungen der Autoren.

\subsection{Das Build-System \textit{maven}}
\label{subsec:JavaPaketMaven}

\texttt{Apache Maven}\index{Maven} ist ein Werkzeug zur Verwaltung und 
zum Verstehen von Softwareprojekten. 

Ein wesentliches Erkennungsmerkmal ist die Datei
\textit{pom.xml}\index{pom.xml} für das \texttt{Maven}-Build-System.
Diese enthält alle Informationen zum jeweiligen Softwareprojekt und folgt
einem standardisierten \textit{XML}-Format.

Wesentlich ist auch die Standard-Verzeichnisstruktur
\index{Verzeichnisstruktur Maven} eines 
\texttt{Maven}-Pro\-jektes, die im Folgenden dargestellt wird.\cite{ASF-Maven2020}

\begin{description}\itemsep0pt
    \item[src/main/java] Anwendungs- / Bibliotheksquellen
    \item[src/main/resources] Anwendungs- / Bibliotheksressourcen
    \item[src/main/filters] Ressourcenfilterdateien
    \item[src/main/webapp] Webanwendungsquellen
    \item[src/test/java] Testquellen
    \item[src/test/resources] Ressourcen testen
    \item[src/test/filters] Testen Sie Ressourcenfilterdateien
    \item[src/it] Integrationstests (hauptsächlich für Plugins)
    \item[src/assembly] Assembly-Deskriptoren
    \item[src/site] Website
    \item[LICENSE.txt] Lizenz des Projektes
    \item[NOTICE.txt] Hinweise und Zuordnungen für Bibliotheken, von denen 
                      das Projekt abhängt
    \item[README.txt] Readme des Projektes
    \item[pom.xml] Beschreibung des Projektes und der Konfiguration
\end{description}

In den meisten Fällen reicht es aus, den Zweig 
\textit{src/main/} als \texttt{Debian}-Paket zu bauen. Dies gilt besonders 
dann, wenn Bibliotheken gebaut werden, die als Abhängigkeiten für Anwendungen 
benötigt werden.

Das Upstream-Paket muss bestimmte Voraussetzungen erfüllen, um mit dem 
Build-System \texttt{Maven} gebaut werden zu können.
 
Dazu gehört auf jeden Fall mindestens eine \textit{pom.xml}-Datei. 
Diese Datei kann an verschiedenen Stellen innerhalb des Quellcodes liegen. 
Manchmal wird sie - besonders im \texttt{Maven}-Repositorium 
(\url{https://mvnrepository.com/}.) - nur zusätzlich bereitgestellt.
 
Wenn vorhanden, ist es jedoch oft besser, \texttt{Github} oder andere 
Git-Repositorien als Quelle zu wählen. Dabei ist auf die Version zu 
achten! Für manche Pakete wird der Quellcode auch unter der Domain 
\url{https://gitbox.apache.org/repos/asf} veröffentlicht.

\subsection{Paketieren mit \textit{maven}}

Für \textit{maven}-basierte Pakete wird die Verwendung von 
\textit{maven-debian-helper}\footnote{\url{https://manpages.debian.org/unstable/maven-debian-helper/index.html}} 
empfohlen\index{Maven}.

In der Datei \textit{debian/rules} (Kapitel~\ref{sec:Rules4MavenDH}, 
Seite~\pageref{sec:Rules4MavenDH}) wird dazu \textit{-{}-buildsystem=maven}
hinzugefügt.

Zur Unterstützung des Bauens mit \textit{maven} enthält dieses Paket
folgende Befehle:

\begin{description}\itemsep0pt
 \item[mh\_genrules(1)] generiert, zumindest teilweise, die Datei 
 \textit{debian/rules}
 \item[mh\_lspoms(1)] sucht nach allen POM-Dateien, die im Quellcode des 
 Projektes angegeben sind.
 \item[mh\_make(1)] generiert durch Lesen der Informationen aus der
  Maven-POM das \texttt{Debian}-Paket.
 \item[mh\_resolve\_dependencies(1)] löst die Abhängigkeiten auf und 
 erzeugt die Datei \textit{<Paketname>.substvars}, die die Liste der
 abhängigen Pakete enthält, zur Nutzung von \textit{debian/control}.
\end{description}

Zu diesen Befehlen gibt es auch entsprechende \textit{Man-Pages}.

Hiervon wird zunächst nur der Befehl 
\textit{mh\_make}\footnote{url{https://manpages.debian.org/unstable/maven-debian-helper/mh\_make.1.en.html}} 
im Plugin \textit{build-gbp-maven-plugin.sh} genutzt.
(Kapitel~\ref{chap:MavenPlugin}, Seite~\pageref{chap:MavenPlugin})

Bei der Nutzung von \textit{mh\_make}\index{mh\_make} ist zu beachten, 
dass dort, wo \textit{mh\_make} gestartet wird, alle Abhängigkeit des zu
bauenden Paketes vorhanden sein sollten. Andernfalls sind etwaige Einträge
in den einschlägigen Dateien (z.B. \textit{debian/control}) manuell
nachzuholen. (Kapitel~\ref{sec:MavenDateienBearbeiten}, 
Seite~\pageref{sec:MavenDateienBearbeiten}) 

Dazu empfiehlt es sich, diese Operationen in einer eigens dafür 
eingerichteten \textit{Chroot}\index{Chroot (maven)} durchzuführen, in der 
alle Abhängigkeiten installiert werden können, ohne das eigentliche 
Host-System zu belasten. Die Einrichtung derselben ist in 
Kapitel~\ref{sec:MoreChrootSystems} 
(Seite~\pageref{sec:MoreChrootSystems}) beschrieben.

Von \textit{mh\_make} werden folgende Dateien im Verzeichnis 
\textit{debian/}angelegt:

\begin{itemize}\itemsep2pt
 \item maven.cleanIgnoreRules
 \item maven.rules
 \item maven.ignoreRules
 \item maven.properties
 \item <Paketname>.poms
 \item maven.publishedRules   
\end{itemize}
 
Zusätzlich werden von \textit{mh\_make} auch die (Standard-)Dateien 

\begin{itemize}\itemsep2pt
 \item changelog
 \item control
 \item copyright
 \item rules
 \item README.source   
\end{itemize}

erstellt. Dies ist bei den weiteren Arbeiten an diesen Dateien zu 
berücksichtigen (Kapitel~\ref{sec:DateienInDebian}, 
Seite~\pageref{sec:DateienInDebian}).

Mit \textit{apt-file find}\footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}}
kann festgestellt werden, ob es zu einer 
\textit{artifactID} ein \texttt{Debian}-Paket gibt. 
Diese Funktion wird auch von \textit{mh\_make} genutzt. Die \textit{artifactID} 
befindet sich in der \textit{pom.xml}-Datei aus dem Upstream-Code. 

Unter \url{wiki.debian.org/Java/MavenPkgs/Unstable} befindet sich eine 
Liste aller in \texttt{Debian} bereits paketierten \textit{Maven}-Pakete.
\footnote{ Dank an Thorsten Glaser und der Firma Tarent 
\url{https://www.tarent.de/} für diese Unterstützung}

\textit{mh\_make} erstellt aus der \textit{pom.xml} auch die Datei 
\textit{debian/<Paketna\-me>.poms}.

In dieser Datei werden alle im Paket vorkommende \textit{pom.xml}-Dateien 
mit ihrem relativen Pfad aufgelistet. Diese können dann dort mit den 
aufgelisteten Optionen versehen werden.

<<debian/JavaPackage.poms>>=
# List of POM files for the package
# Format of this file is:
# <path to pom file> [option]*
# where option can be:
#   --ignore: ignore this POM and its artifact if any
#   --ignore-pom: don't install the POM. To use on POM files that are created
#     temporarily for certain artifacts such as Javadoc jars.
#     [mh_install, mh_installpoms]
#   --no-parent: remove the <parent> tag from the POM
#   --package=<package>: an alternative package to use when installing
#     this POM and its artifact
#   --has-package-version: to indicate that the original version of the
#     POM is the same as the upstream part of the version for the package.
#   --keep-elements=<elem1,elem2>: a list of XML elements to keep in the POM
#      during a clean operation with mh_cleanpom or mh_installpom
#   --artifact=<path>: path to the build artifact associated with this POM,
#      it will be installed when using the command mh_install. [mh_install]
#   --java-lib: install the jar into /usr/share/java to comply with Debian
#      packaging guidelines
#   --usj-name=<name>: name to use when installing the library in
#     /usr/share/java
#   --usj-version=<version>: version to use when installing the library
#     in /usr/share/java
#   --no-usj-versionless: don't install the versionless link in
#     /usr/share/java
#   --dest-jar=<path>: the destination for the real jar.
#     It will be installed with mh_install. [mh_install]
#   --classifier=<classifier>: Optional, the classifier for the jar.
#     Empty by default.
#   --site-xml=<location>: Optional, the location for site.xml if it
#     needs to be installed. Empty by default. [mh_install]
#
@

Eine häufig verwendete Zeile ist \textit{pom.xml --no-parent 
--has-package-ver\-sion}. Dies bedeutet, dass das <parent> Tag beim Bauen 
aus der POM entfernt wird. Die Option \textit{--has-package-version} gibt 
an, dass die Originalversion der POM dieselbe sei, wie der Upstream-Teil
der Paketversion.

Diese Datei kann innerhalb des Bauprozesses einer neuen 
\texttt{Debian}-Revi\-sion 
angepasst werden. (Kapitel~\ref{sec:MavenDateienBearbeiten},
Seite~\pageref{sec:MavenDateienBearbeiten}).

Liegt die \textit{pom.xml} im Wurzelverzeichnis des Quellcodes, werden 
durch \textit{mh\_make} die weiteren Dateien für das Verzeichnis 
\textit{debian/} erstellt.

Im \texttt{Maven}-Repositorium wird die Datei \textit{pom.xml} oft nur 
separat bereitgestellt. Diese Datei wird dann im \textit{debian/} 
Verzeichnis abgelegt.

Daher sind hier einige Einträge in \textit{debian/rules} 
(Kapitel~\ref{subsec:rules}, Seite~\pageref{subsec:rules} erforderlich:

Nach dem Aufruf aller \textit{debhelper} (\textit{dh \$@}) wird das
\textit{dh\_auto\_build} zunächst mit einem \textit{override}
außer Kraft gesetzt, um noch einige vorbereitenden Konfigurationen 
durchzuführen.

Dazu gehört auch das Kopieren von Dateien an den Ort, wo das Build-System 
diese Dateien benötigt, um das gewünschte Programm zu bauen.

<<maven-build>>=
override_dh_auto_build:
        cp debian/pom.xml .
        dh_auto_build
@

\textbf{Weitere Literatur}

%ToDo: Quellen ausarbeiten
\begin{enumerate}
 \item \url{https://wiki.debian.org/Java/MavenBuilder}
 \item \url{https://wiki.debian.org/Java/MavenRepoSpec}
 \item \url{https://wiki.ubuntu.com/JavaTeam/Specs/MavenSupportSpec}
\end{enumerate}

Mit \textit{apt-file find}\footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}}
kann festgestellt werden, ob es zu einer 
\textit{artifactID} ein \texttt{Debian}-Paket gibt. 
Diese Funktion wird auch von \textit{mh\_make} genutzt. Die \textit{artifactID} 
befindet sich in der \textit{pom.xml}-Datei aus dem Upstream-Code. 

Unter \url{wiki.debian.org/Java/MavenPkgs/Unstable} befindet sich eine 
Liste aller in \texttt{Debian} bereits paketierten \textit{Maven}-Pakete.
\footnote{Dank an Thorsten Glaser und der Firma Tarent 
\url{https://www.tarent.de/} für diese Unterstützung}

\subsection{Paketieren mit \textit{ant}}
\label{subsec:JavaPaketAnt}

Das Build-System \textit{ant} erkennt man daran, dass es eine Datei 
\textit{build.xml} gibt.
\footnote{\url{https://wiki.debian.org/Java/Packaging/Ant}}

\subsection{Paketieren mit \textit{gradle}}

\section{\texttt{Java}-Pakete bauen ohne Build-System}

Es ist auch möglich , einfach eine \texttt{Java}-Bibliothek aus einem Verzeichnis 
mit *.java-Dateien zu bauen. Dies ist dann sinnvoll, wenn aus einem größeren 
Programmpaket nur eine oder wenige einzelne Java-Klasse benötigt wird, um 
Buildabhängigkeiten anderer Pakete zu erfüllen.

Dabei gibt es für ein solches Java-Verzeichnis kein Build-System wie die 
noch zu beschreibenden \textit{ant} \index{ant}(Kapitel~\ref{subsec:JavaPaketAnt}, 
Seite~\pageref{subsec:JavaPaketAnt} bzw. \textit{maven} \index{maven}
(Kapitel~\ref{subsec:JavaPaketMaven}, Seite~\pageref{subsec:JavaPaketMaven}.

<<java-builds>>=
export DH_VERBOSE=1
export DH_OPTIONS=-v

Class-Path: src/net/numericalchameleon/util/phoneticalphabets.jar
export CLASSPATH=/usr/share/java/sugar.jar

%:
        dh $@ --with javahelper --sourcedirectory=src/net/numericalchameleon/util/

override_jh_build:

        javac -encoding UTF-8 src/net/numericalchameleon/util/phoneticalphabets/*
        jh_build
        jar cvf src/phoneticalphabets.jar \
        src/net/numericalchameleon/util/phoneticalphabets/*.class

        javac -encoding UTF-8 src/net/numericalchameleon/util/spokennumbers/*
        jh_build
@



Das \textit{javahelper}-Paket bietet Hilfestellung beim Bauen mit \textit{dh}. 
Diese wird für die Java-Paketierung dringend empfohlen.

Ferner wird die Datei \textit{debian/javabuild} benötigt. Diese enthält 
zwei Spalten.

Anzugeben ist in der ersten Spalte die zu bauende \textit{*.jar}-Datei 
und in der zweiten Spalte das Verzeichnis des Quellcodes, in dem die 
\textit{*.java}-Dateien liegen.

Beispiel:
\begin{verbatim}
#NameOfJarFile SourceDirToPackage 
\end{verbatim}

Das Skript ermöglicht das Erstellen dieser Datei 
(Kapitel~\ref{subsec:javabuild}, Seite~\pageref{subsec:javabuild}.

\chapter{\texttt{Mozilla}-Erweiterungen bauen}
\label{chap:WebextBauen}

Das Paketieren von \texttt{Mozilla}-Erweiterungen als \texttt{Debian}-Pakete
bietet für Nutzer und Administratoren den Vorteil, dass Erweiterungen
zusammen mit der Hauptanwendung aktualisiert werden können. 

\texttt{Debian}-Pakete werden zentral für alle Systemnutzer
\index{Systemnutzer} installiert. Die Aktualisierungen\index{Aktualisierung}
erfolgen auch mit dem Paketmanagementsystem\index{Paketmanagementsystem}
der Distribution. Es bedarf dann nur eines Werkzeuges für diesen Zweck.

Bei Sicherheitsaktualisierungen oder neuen Versionen der Anwendungen sind
diese Aspekte besonders relevant.

Dies hat den weiteren Vorteil, dass alle Nutzer mit den gleichen
Versionsständen arbeiten.

\section{Quellen der Erweiterungen}
\label{sec:SourcesMozillaAddOns}

Unter \url{addons.mozilla.org} findet man Erweiterungen für den 
\texttt{Firefox} veröffentlicht von Mozilla.

Für den \texttt{Thunderbird} werden unter 
\url{addons.thunderbird.net} die Erweiterungen veröffentlicht.

Diese liegen dort als \textit{.xpi}-Archive vor. Sofern dies Quellcode-Pakete 
sind, gibt es nicht zwingend auch separate Quellcode-Archive.

Im Falle einer \textit{.xpi}-Datei bedarf es spezieller Einträge in der
Datei \textit{debian/watch} zum Umpacketieren. Das \textit{.xpi}-Format
ist ein besonders spezifiziertes \textit{.zip}-Archiv. Nachstehend ist
die \textit{debian/watch}-Datei für die \texttt{Thunderbird}-Erweiterung
\texttt{Mailmindr} dargestellt.

<<watch4xpi>>=
version=4
opts=\
repack,compression=xz,\
uversionmangle=s/-?([^\d.]+)/~$1/;tr/A-Z/a-z/,\
filenamemangle=s/.+\/v?(\d\S+)\.*/$1/,
https://addons.thunderbird.net/en-US/thunderbird/addon/mailmindr/versions/ \
(\d.\d.\d)
@

Manchmal findet man auch Quellcode-Veröffentlichungen von Personen und 
Projekten beispielsweise auf Github (\url{github.com}) oder auf 
selbstgehosteten Seiten. Diese können auch als \textit{.tar.gz}- oder 
\textit{.zip}-Archive vorliegen.

Erfahrungsgemäß sind dort die Versionen, die bereits im
\textit{addons}-Archiv veröffentlicht worden sind, nicht immer zeitnah
als neue Version gekennzeichnet.

\section{Integration ins Dateisystem}
\label{sec:IntegrationFileSystem}

Um alle gewünschten \texttt{Mozilla}-Erweiterungen einheitlich zu bauen, 
werden die benötigten Teile des Skriptes als \textit{Webext-Plugin} 
realisiert (Kapitel~\ref{chap:WebextPlugin}, 
Seite~\pageref{chap:WebextPlugin}). Damit wird auch eine einheitliche 
Integration in das System gewährleistet.

Ab der Version (>=78.2) des \texttt{Thunderbird}s\index{Thunderbird} können 
ausschließlich \textit{Mail=Extensions}\index{Mail-Extension} genutzt 
werden. Die alten (für TB <= 68.x) Erweiterungen funktionieren nicht mehr.

Die Erweiterung muss nun im Verzeichnis \textit{/usr/share/webext} mit 
der Bezeichnung (id) aus der Datei \textit{manifest.json} ergänzt und 
mit der Endung (.xpi) als Zip-Archiv abgelegt werden 
(Kapitel~\ref{subsec:webext.install}, Seite~\pageref{subsec:webext.install}).

Dazu wird die Datei \textit{debian/rules} 
entsprechend erweitert (Kapitel~\ref{subsec:webextrules}, 
Seite~\pageref{subsec:webextrules}). Zusätzlich sind immer die Dateien 
\textit{<Paketname>.install} (Kapitel~\ref{subsec:webext.install}, 
Seite~\pageref{subsec:webext.install}) und \textit{<Paketname>.links} 
(Kapitel~\ref{subsec:webext.links-tb}, Seite~\pageref{subsec:webext.links-tb})
so zu erstellen, dass \texttt{Thunderbird} die Erweiterung auch findet.

\chapter{\texttt{Python}-Pakete bauen}
\label{chap:PythonBauen}

\chapter{Dokumentation paketieren}
\label{chap:PackageDoc}



\section{Dokumentation für \texttt{Debian} bauen}
\label{sec:DebianDoc}

Diese Dokumentation kann als Beispiel dafür dienen, wie man Dokumentationen
als \texttt{Debian}-Paket bereitstellt.

Diese Dokumentation ist bereits auf \textit{salsa.debian.org}
\footnote{\url{https://salsa.debian.org/ddp-team/dpb}} veröffentlicht.
Dies bietet die Möglickeit, das Buch als \textbf{natives} \texttt{Debian}-Paket
zu bauen.

Ein natives Quellpaket ist nach der \texttt{Debian}-Policy
\footnote{Kapitel 4 der \texttt{Debian}-Policy\cite{DebianPolicy}} ein
Paket, das nicht zwischen \texttt{Debian}-Paketveröffentlichungen und
Upstream-Veröffentlichungen unterscheidet. Ein natives Quellpaket enthält
eine einzelne \textit{tar}-Datei mit Quellmaterial, und die Versionierung
hat keine \texttt{Debian}-spezifische Komponente. Native Pakete werden
normalerweise (aber nicht ausschließlich) für Software verwendet, die keine
unabhängige Existenz außerhalb von \texttt{Debian} hat, wie z.~B. Software,
die speziell für ein \texttt{Debian}-Paket geschrieben wurde. Gleiches gilt
für Dokumentation, die speziell für \texttt{Debian} geschrieben wurde. Ein
nicht-natives Quellpaket trennt die Upstream-Veröffentlichung von der
\texttt{Debian}-Paketierung und allen \texttt{Debian}-spezifischen
Änderungen.

Die Information, dass es sich um ein natives Paket handelt, wird in der
Datei \textit{debian/source/format} als \textit{3.0 (native)} abgelegt
(Kapitel~\ref{subsec:d/source/format},
Seite~\pageref{subsec:d/source/format}).

Native Pakete benötigen keine Datei \textit{debian/upstream/metadata}
(Kapitel~\ref{subsec:d/upstream/metadata},
Seite~\pageref{subsec:d/upstream/metadata}). und keine Datei
\textit{debian/watch} (Kapitel~\ref{subsec:DebianWatch},
Seite~\pageref{subsec:DebianWatch}). Die Versionsbezeichnung enthält keine
Revisionsbezeichnung (Kapitel~\ref{subsec:Versionsbezeichnung},
Seite~\pageref{subsec:Versionsbezeichnung} und
Kapitel~\ref{subsec:Orig2changes}, Seite~\pageref{subsec:Orig2changes}).

Das Bauen \textit{nativer} Pakete wird vom Programmskript unterstützt 
(Kapitel~\ref{subsec:Orig2changes}, Seite~\pageref{subsec:Orig2changes}).

\section{Upstream-Dokumentation bauen}

Wird vom Upstream-Projekt eine umfangreiche oder mehrsprachige Dokumentation
bereitgestellt, empfiehlt es sich, diese Dokumentation in gesonderten
\texttt{Debian}-Paketen zu veröffentlichen.

\chapter{Metapakete bauen}

\textit{Metapakete} sind solche \texttt{Debian}-Pakete, die von einer 
Gruppe von Paketen abhängen. Damit werden Gruppen von Paketen zusammengefasst, 
bei denen es sinnvoll ist, sie gemeinsam zu installieren. Beispiele sind
Erweiterungen für eine bestimmte Software.

Metapakete weisen einige Besonderheiten auf.

\section{Kein Upstream-Quellcode}
Da es keinen Upstream-Quellcode gibt, benötigt ein Metapaket auch keine 
Datei \textit{debian/watch}

\section{Natives \texttt{Debian}-Paket}
\subsection{\textit{debian/source/format}}

\subsection{\textit{debian/control}}

\subsection{\textit{debian/rules}}

\subsection{\textit{debian/changelog}}

\chapter{Konfiguration zur Installation}

\section{\textit{debconf}}

\textit{Debconf} ist ein Konfigurationsmanagementsystem für \texttt{Debian}. 
Dies dient dazu, Informationen für die Installation vom Nutzer 
abzufragen und diese dann bei der Installation zu berücksichtigen.
\footnote{\url{https://wiki.debian.org/debconf}}

Mit \textit{sudo dpkg-reconfigure debconf} kann \textit{debconf} 
selbst konfiguriert werden. Dies beinhaltet auch die grafische 
Oberfläche.

\begin{verbatim}
first step: https://wiki.debian.org/debconf
            https://wiki.debian.org/debconf
\end{verbatim}

\section{\textit{dbconfig-common}}

\textit{Dbconfig-common} stellt eine einfache,zuverlässige und konsistente 
Methode zur Verwaltung von Datenbanken bereit, die von \texttt{Debian}-Paketen 
verwendet werden.

\chapter{System einrichten}
\label{chap:SystemSetup}

Es wird davon ausgegangen, dass bereits ein installiertes und lauffähiges 
\texttt{Debian}-System existiert. Dabei ist es unerheblich, welcher Zweig
(unstable, testing oder stable) darauf läuft.

Zum Signieren der vom Programmskripts erzeugten Dateien muss ein 
\textit{GPG}-Schlüs\-sel \index{GPG-Schlüssel} des Nutzers auf dem System 
zur Verfügung stehen. Dieser sollte sinnvollerweise der für das 
\texttt{Debian}-Repositorium vorgesehene Schlüssel sein.

Dies gilt auch, wenn für das Bauen eine virtuelle Maschine eingerichtet
und genutzt wird.

\section{Abhängigkeiten für das Programmskript}
\label{sec:ScriptDependencies}

Die Pakete, die zum Einsatz des Programmskriptes erforderlich sind, 
sind in den Kopfzeilen desselben aufgeführt 
(Kapitel~\ref{sec:scriptdependency}, 
Seite~\pageref{sec:scriptdependency}).

Einige der darin enthaltenen Programme werden im folgenden beschrieben:

\subsection{Generelle Abhängigkeiten}

Die nachstehend aufgeführten, hilfreichen Programme werden regelmäßig 
vom Programmskript zum Bauen eines \texttt{Debian}-Paketes eingesetzt:

\begin{description}
\item[mk-origtargz]
\label{desc:mkorigtargz}
aus dem Paket \textbf{\textit{devsripts}} \index{devscripts} benennt den Tarball
der Originalautoren um, ändert wahlweise die Komprimierung und entfernt
unerwünschte Dateien. Dazu stehen unterschiedliche Optionen zur
Verfügung\cite {Devscripts2020} (s. Verwendung in Kapitel~\ref{subsec:mkorigtargz},
Seite~\pageref{subsec:mkorigtargz}).

\item[gbp import-orig]
aus dem Paket \textbf{\textit{git-buildpackage}} \index{git-buildpackage}
importiert eine neue Upstream-Ver\-si\-on in ein Git-Repositorium (s.
Verwendung in Kapitel~\ref{subsec:GbpImportOrig},
Seite~\pageref{subsec:GbpImportOrig}).

\item[gbp import-dsc] aus dem Paket \textbf{\textit{git-buildpackage}}
importiert ein existierendes \texttt{Debian}-Quellpaket in ein
\texttt{Git}-Repositorium (s. Verwendung in Kapitel~\ref{sec:ImportPackage},
Seite~\pageref{sec:ImportPackage}). Auf diesem Weg kann ein Mentor ein
Paket \enquote{sponsorn} (Kapitel~\ref{sec:Import4Sponsoring},
Seite~\pageref{sec:Import4Sponsoring}).

\item[dh\_make]
aus dem Paket \textbf{\textit{dh-make}} \index{dh\_make} kann die benötigten 
\texttt{Debian}-Dateien erstellen. Die Praxis zeigt, dass dies sehr 
unvollständig ist und einiges an Handarbeit erfordert. Daher wird bisher
davon abgesehen, dieses Hilfsprogramm im Programmskript einzusetzen.
(s. Kapitel~\ref{chap:DhMake}, Seite~\pageref{chap:DhMake})

\item[debmake -cc]
aus dem gleichnamigen Paket \textbf{\textit{debmake}} durchsucht die Quelldateien
nach Copyright- und Lizenztexten (s. Kapitel~\ref{subsec:debmake},
Seite~\pageref{subsec:debmake}). Dieser Befehl wird vom Programmskript
zur Erstellung der Datei \textit{debian/copyright} verwandt.
(s. Verwendung in Kapitel~\ref{subsec:d/copyright}, Seite~\pageref{subsec:d/copyright}).

\item[gbp dch]
ist auch im Paket \textbf{\textit{git-buildpackage}} enthalten. Im Programmskript
wird \textit{dch} über \textit{gbp dch} verwandt (s. Verwendung in
Kapitel~\ref{sec:DebianChangelog}, Seite~\pageref{sec:DebianChangelog}).
Weitere Optionen für \textit{dch} können an \textit{gbp dch} durch
\textit{-{}-dch-opt=<dch-Optionen>} übergeben werden.

\item[gbp buildpackage] ist ebenfalls im Paket
\textbf{\textit{git-buildpackage}} enthalten. Mit diesem Befehl wird ein
Paket aus dem \texttt{Git}-Repositorium erstellt (s. Verwendung in
Kapitel~\ref{subsec:buildwithgbp}, Seite~\pageref{subsec:buildwithgbp})

\item[lintian] aus dem Paket \textbf{\textit{lintian}} ist ein
Analysewerkzeug für \texttt{Debian}-Pakete. Es berichtet Fehler und
Verletzungen der \texttt{Debian}-Policy \cite{DebianPolicy}. Jeder
\texttt{Debian}-Betreuer sollte mit diesem Werkzeug das Paket vor dem
Hochladen ins Archiv prüfen. Das Programmskript erwendet \textit{lintian}
mit den Optionen \textit{-{}-pedantic} und \textit{-{}-display-experimental}.
(s. Verwendung in Kapitel~\ref{sec:RunningLintian},
Seite~\pageref{sec:RunningLintian}).

Während des Bauens wird \textit{lintian} durch \textbf{\textit{dh\_lintian}}
aus dem Paket \textbf{\textit{devscripts}} aufgerufen.

\item[uscan] in \textbf{\textit{devsripts}}

\item[debsign] in \textbf{\textit{devscripts}} auch zum Signieren beim Sponsoring

\item[dput] in \textbf{\textit{dput}} bzw \textbf{\textit{dput-ng}}

\item[mh\_make (Plugin)]

\end{description}

\subsection{Abhängigkeiten für das Bauen von \texttt{Java}-Paketen}
\label{subsec:DependencyJava}

Die folgenden Abhängigkeit werden für das Bauen mit Build-Systemen für 
\texttt{Java}-Pakete benötigt.

\begin{verbatim}
 gradle-debian-helper, maven-debian-helper, libmaven-bundle-plugin-java
\end{verbatim}

\subsection{Abhängigkeiten für Erweiterungen, die \textit{Zip}-Archive sind}
\label{subsec:DependencyZipPlugin}

Manche Erweiterungen (Plugins) werden als \textit{Zip}-Archive (z.~B.
für \texttt{Libreoffice} \textit{.oxt}, für \texttt{Mozilla} \textit{.xpi})
verteilt, die den Quellcode enthalten.

Für diese Erweiterungen muss in der Datei \textit{debian/control}
(Kapitel~\ref{subsec:DebianControl}, Seite~\pageref{subsec:DebianControl})
\textit{zip} als Buildabhängigkeit aufgeführt werden.

Für \texttt{Mozilla}-Erweiterungen wird dies vom \textit{Web-Extension-Plugin}
erledigt (Kapitel~\ref{subsec:WebextControl},
Seite~\pageref{subsec:WebextControl}). 

\section{Verzeichnisse und Dateien}
\label{sec:FolderStructure}

\subsection{Pfade zu den Projekten}
\label{subsec:ProjectPath}

Es ist sinnvoll, die Paketierprojekte jeweils als Unterverzeichnisse eines
Projektverzeichnisses anzulegen. Ein Beispiel für ein solches
Projektverzeichnis ist:

\begin{verbatim}
    ~/Projekte/Git/01_Salsa
\end{verbatim}

Dieser Pfad wird in jeder Konfigurationsdatei in der Variablen
\textit{ProjectPath} hinterlegt.

Ferner kann dieser Pfad auch in der Variablen \textit{DefaultProjectPath}
für viele Projekte als Standardwert in der Datei
\textit{\textasciitilde/.debian\_project/DefaultValues} aufgenommen
werden (Kapitel~\ref{subsubsec:DefaultValues},
Seite~\pageref{subsubsec:DefaultValues}).

\textit{PrjPath} ist das Unterverzeichnis des Projektverzeichnisses
(\textit{ProjectPath}), in dem das einzelne Projekt liegt. Der Name
dieses Unterverzeichnisses ist der Name des entsprechenden Projektes
(\textit{OrigName}). In dieses Unterverzeichnis werden die fertigen
Pakete abgelegt.

In diesem Unterverzeichnis befindet sich ein weiteres Unterverzeichnis
(\textit{GitPath}), welches das Git-Repositorium enthält.

Diese Unterverzeichnisse werden, wenn nötig, vom Programmskript angelegt
(s.~a. Kapitel~\ref{subsec:AnlegenVerzeichnisse},
Seite~\pageref{subsec:AnlegenVerzeichnisse})

\subsection{Konfigurationsdateien}
\label{subsec:ConfigurationFiles}

\subsubsection{Für jedes Projekt}
\label{subsubsec:KonfigProjekt}

Für jedes Projekt wird eine eigene Konfigurationsdatei\index{Konfigurationsdatei} 
erstellt. 
Diese wird im Homeverzeichnis des Nutzers im Verzeichnis 
\textit{.debian\_project/} als Datei \textit{<Projektname>} abgelegt. 
Darin werden projektspezifische\index{projektspezifisch} Informationen hinterlegt.

Die Konfigurationsdatei\index{Konfigurationsdatei} ist technisch ein 
Shell-Skript, welches von dem Programmskript erstellt und geladen 
wird. Dieses Shell-Skript enthält Variablen, denen dort Werte 
zugewiesen werden. Die in der Konfigurationsdatei mit Werten 
versehenen Variablen können durch das Laden vom Programmskript verwendet 
werden.

Ferner enthält die Datei Kommentare. Diese können vom 
Nutzer beliebig erstellt werden. Ein Teil der Kommentare wird jedoch vom 
Programmskript erstellt. Diese enthalten ein Eigenschafts-Werte-Paar, 
welches wie die Zuweisung eines Wertes an eine Variable aufgebaut ist. 
Technischer Hintergrund ist, dass im Eigenschaftsnamen 
sinnvollerweise Zeichen vorkommen, die im Bezeichner einer Variablen nicht 
verwendet werden dürfen. 

Existiert die Konfigurationsdatei\index{Konfigurationsdatei}, so wird sie 
zunächst geladen. (Kapitel~\ref{sec:ConfigFileLaden}, 
Seite~\pageref{sec:ConfigFileLaden}). Man kann sie dann, wenn nötig, 
editieren. Andernfalls wird diese Datei durch das Skript erstellt. 
(Kapitel~\ref{sec:ConfigFileCreate}, Seite~\pageref{sec:ConfigFileCreate})

Folgende Informationen werden dort hinterlegt:

\begin{description}
    \setlength{\itemsep}{-1mm}
    \item[\#] !/usr/bin/bash
    \item[\#] ConfigFile for <OrigName>
    \item[\#\#] General parameters
    \item[SourceName] 
    \item[PackName]
    \item[ProjectPath]= \textasciitilde/Projekte/Git/01\_Salsa
    \item[SalsaName]
    \item[Java-Package] ~
    \begin{description}
        \item[SalsaName] = java-team/<SourceName>.git
        \item[JavaFlag]
        \item[MavenPluginFlag]
			\item[Maintainer]=Maintainer=Debian\_Java\_Maintainers \\
            \_@lt@pkg-ja\-va-main\-tainers@lists.alioth.debian.org@gt@
        \item[Uploader]=Mechtilde\_Stehmann\_@lt@mechtilde@debian.org@gt@
    \end{description}
    \item[Web-Extension-Packages] ~
    \begin{description}
        \item[SalsaName] = webext-team/
        \item[WebextFlag]
        \item[Maintainer]
        \item[Uploader]
    \end{description}
    \item[Python-Packages]
    \begin{description}
        \item[SalsaName] = python-team/packages/
        \item[PythonFlag]
        \item[Maintainer]
        \item[Uploader]
    \end{description}
    \item[DefaultBranch]
    \item[RecentBranch] = debian/sid
    \item[RecentUpstreamSuffix] = .tar.gz
    \item[RecentRepackSuffix] = +dfsg | +ds
    \item[master\_Dist]
    \item[DownloadUrl]
    \item[DownloadZip]
    \item[Maintainer] Mechtilde Stehmann <mechtilde@debian.org>
    \item[ExcludeFile]
\end{description}

\subsubsection{Für viele Projekte}
\label{subsubsec:DefaultValues}

In der Datei \textit{\textasciitilde/.debian\_project/DefaultValues} 
werden Variablen Werte zugewiesen, die für viele Projekte gelten.

<<DefaultValues>>=
#!/usr/bin/bash

HOME=/home/<user>
DefaultProjectPath=${HOME}/Projekte/Git/01_Salsa
@

\subsubsection{Fingerprint des Maintainer-Schlüssels}

Im Verzeichnis \textit{\textasciitilde/.debian\_project/} befindet 
sich auch eine Datei \textit{fingerprint}, die den Fingerprint\index{Fingerprint} 
des Maintainer-Schlüssels\index{Maintainer-Schlüssel} enthält. 
Mit diesem Schlüssel werden die Pakete signiert \index{signieren}. 
(Kapitel~\ref{sec:GettingFingerprint}, Seite~\pageref{sec:GettingFingerprint})

\subsection{\textit{.bashrc}}
\label{subsec:bashrc}

In die Datei \textit{.bashrc}\index{\textasciitilde/.bashrc} sind
folgende Einträge aufzunehmen:

\begin{verbatim}
    DEBFULLNAME="<Vor- und Nachname des Maintainer>"
    DEBEMAIL="<E-Mail-Adresse des Maintainers>"
    export DEBEMAIL DEBFULLNAME
\end{verbatim}

Verschiedene Debian-Werkzeuge erkennen Ihre E-Mail-Adresse und Ihren
Namen anhand der Shell-Umgebungsvariablen \$DEBEMAIL\index{DEBEMAIL} und
\$DEBFULLNAME\index{DEBFULLNAME}. \footnote{Kapitel 3.1 in \cite{maint-guide}}

Diese Einträge werden auch von der Funktion \textit{DEBValues} des
Programmskripts ausgelesen. (Kapitel~\ref{subsec:DebNameAndEmail},
Seite~\pageref{subsec:DebNameAndEmail})

Auch für \textit{dquilt} ist die Datei \textit{.bashrc} zu ergänzen.
(Kapitel~\ref{sec:QuiltEinrichtung},
Seite~\pageref{sec:QuiltEinrichtung})

\section{\textit{PBuilder} einrichten}
\label{sec:configurepbuilder}

\textit{Gbp buildpackage} \index{gbp buildpackage} verwendet 
\textit{cowbuilder} \index{cowbuilder}.
Der Befehl \textit{cowbuilder} ist ein Wrapper für \textit{pbuilder}, 
welcher die Nutzung eines \textit{pbuilder}-ähnlichen Interfaces in einer 
\textit{cowdancer}-Umgebung \index{cowdancer} ermöglicht. 

\subsection{\textit{Chroot}}

Das Paket \textit{pbuilder} \index{pbuilder} enthält Programme, um eine 
\index{Chroot} \textit{Chroot}-Umgebung aufzubauen und zu betreuen.

\textit{Chroot} bedeutet \textit{Change root}

Es entspricht guter Praxis, \texttt{Debian}-Pakete in einer \textit{Chroot}
zu bauen. Damit soll gewährleistet werden, dass das Paket mit den Ressourcen
der jeweilige Distribution gebaut werden kann.

Beim Bauen eines \texttt{Debian}-Paketes in dieser \textit{Chroot}-Umgebung 
wird nämlich geprüft, ob alle erforderlichen Build-Abhängigkeiten erfüllbar
sind. Hierdurch können \index{FTBFS} FTBFS-Fehler (FTBFS = Failed To Build 
From Source) vermieden werden. Unter Umständen kann es jedoch noch zu 
solchen Fehlermeldungen kommen.

\subsection{Konfiguration des \texttt{Pbuilders}}
\label{subsec:PbuilderConfiguration}

Zunächst muss das Verzeichnis \textit{/var/cache/pbuilder/result} angelegt 
werden. Dieses Verzeichnis muss für den Nutzer beschreibbar sein. 
Danach wird die Konfiguration des \textit{pbuilder} durchgeführt. 

Die Konfiguration des \textit{pbuilder} ist nicht völlig trivial, was 
gegebenenfalls die Fehlersuche erschwert. Daher gehen wir hier sehr 
ausführlich darauf ein.

Die Standard-Konfiguration wird aus der Datei 
\textit{/usr/share/pbuilder/pbuilderrc} genommen.

\scriptsize
\begin{verbatim}
# pbuilder defaults; edit /etc/pbuilderrc to override these and see
# pbuilderrc.5 for documentation

# Set how much output you want from pbuilder, valid values are
# E => errors only
# W => errors and warnings
# I => errors, warnings and informational
# D => all of the above and debug messages
LOGLEVEL=I
# if positive, some log messagges (errors, warnings, debugs) will be colored
# auto => try automatically detection
# yes  => always use colors
# no   => never use colors
USECOLORS=auto

BASETGZ=/var/cache/pbuilder/base.tgz
#EXTRAPACKAGES=""
#export DEBIAN_BUILDARCH=athlon
BUILDPLACE=/var/cache/pbuilder/build
# directory inside the chroot where the build happens. See #789404
BUILDDIR=/build
# what be used as value for HOME during builds.  See #441052
# The default value prevents builds to write on HOME, which is prevented on
# Debian buildds too.  You can set it to $BUILDDIR to get a working HOME, if
# you need to.
BUILD_HOME=/nonexistent
MIRRORSITE=http://deb.debian.org/debian
#OTHERMIRROR="deb http://www.home.com/updates/ ./"
#export http_proxy=http://your-proxy:8080/
USESHM=yes
USEPROC=yes
USEDEVFS=no
USEDEVPTS=yes
USESYSFS=yes
USENETWORK=no
USECGROUP=yes
BUILDRESULT=/var/cache/pbuilder/result/

# specifying the distribution forces the distribution on "pbuilder update"
#DISTRIBUTION=sid
# specifying the architecture passes --arch= to debootstrap; the default is
# to use the architecture of the host
#ARCHITECTURE=$(dpkg --print-architecture)
# specifying the components of the distribution, for instance to enable all
# components on Debian use "main contrib non-free" and on Ubuntu "main
# restricted universe multiverse"
COMPONENTS="main"
#specify the cache for APT
APTCACHE="/var/cache/pbuilder/aptcache/"
APTCACHEHARDLINK="yes"
REMOVEPACKAGES=""
#HOOKDIR="/usr/lib/pbuilder/hooks"
HOOKDIR=""
EATMYDATA=no
# NB: this var is private to pbuilder; ccache uses "CCACHE_DIR" instead
# CCACHEDIR="/var/cache/pbuilder/ccache"
CCACHEDIR=""

# make debconf not interact with user
export DEBIAN_FRONTEND="noninteractive"

#for pbuilder debuild
BUILDSOURCEROOTCMD="fakeroot"
PBUILDERROOTCMD="sudo -E"
# use cowbuilder for pdebuild
#PDEBUILD_PBUILDER="cowbuilder"

# Whether to generate an additional .changes file for a source-only upload,
# whilst still producing a full .changes file for any binary packages built.
SOURCE_ONLY_CHANGES=no

# additional build results to copy out of the package build area
#ADDITIONAL_BUILDRESULTS=(xunit.xml .coverage)

# command to satisfy build-dependencies; the default is an internal shell
# implementation which is relatively slow; there are two alternate
# implementations, the "experimental" implementation,
# "pbuilder-satisfydepends-experimental", which might be useful to pull
# packages from experimental or from repositories with a low APT Pin Priority,
# and the "aptitude" implementation, which will resolve build-dependencies and
# build-conflicts with aptitude which helps dealing with complex cases but does
# not support unsigned APT repositories
PBUILDERSATISFYDEPENDSCMD="/usr/lib/pbuilder/pbuilder-satisfydepends"

# Arguments for $PBUILDERSATISFYDEPENDSCMD.
# PBUILDERSATISFYDEPENDSOPT=()

# You can optionally make pbuilder accept untrusted repositories by setting
# this option to yes, but this may allow remote attackers to compromise the
# system. Better set a valid key for the signed (local) repository with
# $APTKEYRINGS (see below).
ALLOWUNTRUSTED=no

# Option to pass to apt-get always.
export APTGETOPT=()
# Option to pass to aptitude always.
export APTITUDEOPT=()

# Whether to use debdelta or not.  If "yes" debdelta will be installed in the
# chroot
DEBDELTA=no

#Command-line option passed on to dpkg-buildpackage.
#DEBBUILDOPTS="-IXXX -iXXX"
DEBBUILDOPTS=""

#APT configuration files directory
APTCONFDIR=""

# the username and ID used by pbuilder, inside chroot. Needs fakeroot, really
BUILDUSERID=1234
BUILDUSERNAME=pbuilder

# BINDMOUNTS is a space separated list of things to mount
# inside the chroot.
BINDMOUNTS=""

# Set the debootstrap variant to 'buildd' type.
DEBOOTSTRAPOPTS=(
    '--variant=buildd'
    '--force-check-gpg'
    )
# or unset it to make it not a buildd type.
# unset DEBOOTSTRAPOPTS

# Keyrings to use for package verification with apt, not used for debootstrap
# (use DEBOOTSTRAPOPTS). By default the debian-archive-keyring package inside
# the chroot is used.
APTKEYRINGS=()

# Set the PATH I am going to use inside pbuilder: default is 
# "/usr/sbin:/usr/bin:/sbin:/bin"
export PATH="/usr/sbin:/usr/bin:/sbin:/bin"

# SHELL variable is used inside pbuilder by commands like 'su'; 
# and they need sane values
export SHELL=/usr/bin/bash

# The name of debootstrap command, you might want "cdebootstrap".
DEBOOTSTRAP="debootstrap"

# default file extension for pkgname-logfile
PKGNAME_LOGFILE_EXTENSION="_$(dpkg --print-architecture).build"

# default PKGNAME_LOGFILE
PKGNAME_LOGFILE=""

# default AUTOCLEANAPTCACHE
AUTOCLEANAPTCACHE=""

#default COMPRESSPROG
COMPRESSPROG="gzip"

# pbuilder copies some configuration files (like /etc/hosts or 
# /etc/hostname)
# from the host system into the chroot.  If the directory specified here
# exists and contains one of the copied files (without the leading /etc) that
# file will be copied from here instead of the system one
CONFDIR="/etc/pbuilder/conf_files"
\end{verbatim}
\normalsize

Diese Werte können gegebenenfalls von Werten in der Datei 
\textit{/etc/pbuilderrc} überschrieben werden.

Nach einer Neuinstallation sieht die \textit{/etc/pbuilderrc} wie folgt aus:

\scriptsize
\begin{verbatim}
# this is your configuration file for pbuilder.
# the file in /usr/share/pbuilder/pbuilderrc is the default template.
# /etc/pbuilderrc is the one meant for overwriting defaults in
# the default template
#
# read pbuilderrc.5 document for notes on specific options.
MIRRORSITE=http://ftp.de.debian.org/debian/

\end{verbatim}
\normalsize

Diese habe ich wie folgt eingerichtet:

\scriptsize
\begin{verbatim}
# this is your configuration file for pbuilder.
# the file in /usr/share/pbuilder/pbuilderrc is the default template.
# /etc/pbuilderrc is the one meant for overwriting defaults in
# the default template
#
# read pbuilderrc.5 document for notes on specific options.
# adapt from Mechtilde - 2019-09-07 (analog wiki)
MIRRORSITE=http://ftp.de.debian.org/debian/
AUTO_DEBSIGN=${AUTO_DEBSIGN:-no}
HOOKDIR=/var/cache/pbuilder/hooks
# Codenames for Debian suites according to their alias. 
# Update these when needed.
# EXPERIMENTAL_CODENAME ="experimental"
UNSTABLE_CODENAME="sid"
TESTING_CODENAME="bookworm"
STABLE_CODENAME="bullseye"
STABLE_BACKPORTS_SUITE="$STABLE_CODENAME-backports"
\end{verbatim}
\normalsize

Neben der globalen Konfigurationsdatei \textit{/etc/puilderrc} kann auch 
eine nutzerspezifische Datei \textit{\textasciitilde/.pbuilderrc} angelegt 
werden.
Der Inhalt dieser Datei überschreibt die systemweiten Einstellungen.

\scriptsize
\begin{verbatim}
# BINDMOUNTS is a space separated list of things to mount
# inside the chroot.
BINDMOUNTS="/var/local/repository" # lokales Verzeichnis einbinden (mounten)
OTHERMIRROR="deb http://deb.debian.org/debian/ buster-backports main \
| deb [trusted=yes] file:///var/local/repository ./"
# OTHERMIRROR="$OTHERMIRROR | deb file:///var/local/repository ./"
# Fertige Pakete im lokalen Repository ablegen
# BUILDRESULT=..

# Added after reading: 
# https://lists.debian.org/debian-backports/2018/09/msg00021.html

# List of Debian suites.
DEBIAN_SUITES=($UNSTABLE_CODENAME $TESTING_CODENAME \
$STABLE_CODENAME $STABLE_BACKPORTS_SUITE
    "experimental" "unstable" "testing" "stable") 

# Mirrors to use. Update these to your preferred mirror.
DEBIAN_MIRROR="ftp.de.debian.org"

# Added after reading https://wiki.debian.org/cowbuilder
BASEPATH="/var/cache/pbuilder/base.cow/"

\end{verbatim}
\normalsize

Neben den systemweiten und nutzerspezifischen Konfigurationen werden auch 
paketspezifische Konfigurationen des Pbuilders benötigt. 
Diese Dateien können im Projektverzeichnis abgelegt und mit 
\textit{-{}-configfile <Konfigurationsdatei>} eingelesen werden. Mit dieser 
Konfiguration werden eventuell schon vorhandene Werte überschrieben.
Hier können dann die Informationen zu den Projekten abgelegt werden, wenn 
für diese Veröffentlichungen im Backports-Zweig benötigt werden. Diese
Datei wird nach allen anderen Konfigurationsdateien eingelesen.

Siehe dazu auf Seite 

\url{https://wiki.debian.org/BuildingFormalBackports}

den Abschnitt \textit{\#Advanced:\_Building\_multi-dependency\_packages}

Dies kann auch in der Datei \textit{\textasciitilde/.pbuilderrc} hinzugefügt 
werden, wenn es diese Datei gibt. 
Als MIRROR wird ein gängiger gut erreichbarer \texttt{Debian}-Mirror angegeben. 
Falls vorhanden, kann hier auch die Adresse eines vorhandenen lokalen
Spiegel eingetragen werden.

Für die \textit{Hook}-Skripte ist ein Verzeichnis 
\textit{\textasciitilde/.pbuilder/} anzulegen.

\subsection{Hooks einrichten}
\label{subsec:HooksEinrichten}

\textit{Hooks} sind Skripte, die an bestimmten, vordefinierten Punkten 
während des Bauprozesses Dinge erledigen. 
Mit den sogenannten \textit{Hooks} (Haken) kann der Prozess in der 
Build-Chroot auch an vordefinierten Positionen unterbrochen werden, um 
noch manuell in den Prozess eingreifen zu können.

Die \textit{Hook}-Skripte befinden sich im Verzeichnis \textit{\textasciitilde/.pbuilder/}

Der Name des Hook-Skriptes bestimmt, an welcher Stelle im Bauprozess der 
\textit{Hook} ausgeführt wird.

Dabei gilt folgende Konversation:

\begin{verbatim}
X<digit><digit><whatever-else-you-want-as-name>
\end{verbatim}

Das \enquote{X} (A bis G) bestimmt die Hook-Klasse, die folgenden 
2 Ziffern die Reihenfolge, in der die Hooks einer Klasse ausgeführt werden. 
Der Rest dient als Beschreibung. 

Leider entspricht die Reihenfolge, in der die Klassen im Build-Prozess 
ausgeführt werden, nicht der alphabetischen Reihenfolge. 

\begin{description}
\item[A] Ist für das -{}-build Ziel. 
Es wird vor dem Baubeginn ausgeführt. D.h. nach dem Entpacken des Bausystems, 
des Quelltextes und nach der Erfüllung der Bau-Abhängigkeit.
\item[B] Wird ausgeführt, nachdem das Bausystem den Bau erfolgreich 
abgeschlossen hat, bevor das Bauergebnis zurückkopiert wird. - Unterbrechung 
nach erfolgreichem Bauen
\item[C]Wird nach einem Build-Fehler, vor der Bereinigung ausgeführt. - 
Unterbrechung nach gescheitertem Build
\item[D] Wird vor dem Entpacken der Quelle innerhalb der Chroot-Umgebung 
ausgeführt, nachdem die Chroot-Umgebung eingerichtet wurde. 
Erstellt \$TMP und \$TMPDIR wenn erforderlich. 
Dies wird aufgerufen, bevor die Build-Abhängigkeit befriedigt ist. Auch 
nützlich für den Aufruf von apt update. -- Möglichkeit zum Editieren der 
Sources.list.\footnote{weiteres~s.~a.
\url{https://wiki.debian.org/PbuilderTricks\#How\_to\_include\_local\_packages\_in\_the\_build}}

\item[E] Wird ausgeführt, nachdem \textit{pbuilder -{}-update} und 
\textit{pbuilder -{}-create} die Arbeit von apt-get mit dem Chroot beendet 
hat, bevor das Kernel-Dateisystem (/proc) umountet und der Tarball aus 
dem Chroot erzeugt wird. 
\item[F] Is executed just before user logs in, or program starts executing, 
after chroot is created in -{}-login or -{}-execute target.
\item[G] Is executed just after debootstrap finishes, and configuration 
is loaded, and pbuilder starts mounting /proc and invoking apt 
install in -{}-create target.
\item[H] Wird unmittelbar nach dem Auspacken von chroot, mounting proc 
und jedem in BINDMOUNTS angegebenen bind mount ausgeführt. Es wird für 
jedes Ziel ausgeführt, das die entpackte Chroot benötigt. Es ist nützlich, 
wenn Sie die Chroot-Einbauten dynamisch ändern wollen, bevor irgendetwas 
anfängt, sie zu benutzen.
\item[I] Wird ausgeführt, nachdem das Bausystem den Bau erfolgreich
abgeschlossen hat, nach dem Zurückkopieren der Build-Ergebnisse.

\end{description}

\subsection{Hooks - Beispiele}
Diese stehen alle im Verzeichnis: \textit{\textasciitilde/.pbuilder/}

\subsubsection{Hook A}

Dieser Hook könnte z.B. \textit{A10shell} heißen.

<<Hook-A>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell before build starts.

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

apt-get install -y "${APTGETOPT[@]}" nano less
cd "$BUILDDIR"/*/debian/..
echo "Hook A - the dependencies are installed. Now the build can start."
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook B}

Dieser Hook könnte z.B. \textit{B20shell} heißen.

<<Hook-B>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell if build fails.

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

# apt-get install -y "${APTGETOPT[@]}" vim less
cd "$BUILDDIR"/*/debian/..
echo "Hook B - The build was built successfully"
echo "You can check it with ls -la ../"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook C}

Hier können dann noch Pakete hinzu installiert werden, die zwingend 
benötigt werden, wenn der Build fehlschlägt.

Dieser Hook könnte z.B. \textit{C10shell} heißen.

<<Hook-C>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell if build fails.

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

apt-get install -y "${APTGETOPT[@]}" vim less mc unzip locate
cd "$BUILDDIR"/*/debian/..
echo "Hook C - The build wasn't built successfully"
echo "After analysing the errors you can continue with using CTRL-D"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook D}

<<Hook-D>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell before unpacking the source
# inside the chroot

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

apt-get install -y "${APTGETOPT[@]}" less nano
#cd "$BUILDDIR"/*/debian/..
echo "Hook D -"
echo "After unpacking the sources the dependencies"
echo "can be downloaded and unpacked."
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty

@

\subsubsection{Hook E}

<<Hook-E>>=
echo "Hook E"
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook F}

<<Hook-F>>=
echo "Hook F"
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook G}

<<Hook-G>>=
echo "Hook G"
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook H}

<<Hook-H>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell if build fails.

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

echo "Hook H"
echo "Executed after preparing the chroot \n and before installing the depencencies"
echo "Here you can include dependency from e.g a local repo for testing."
echo "Next the source code of the package to be built is unpacked."
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
@

\subsubsection{Hook I}

<<Hook-I>>=
#!/usr/bin/bash
# example file to be used with --hookdir
#
# invoke shell if build fails.

BUILDDIR="${BUILDDIR:-/tmp/buildd}"

#apt-get install -y "${APTGETOPT[@]}" vim less
#cd "$BUILDDIR"/*/debian/..
echo "Hook I"
echo "Please use CTRL-D to continue"
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty

@

\subsection{Alternative \textit{Chroot}-Umgebungen}

Es hat sich bewährt, für die verschiedenen \texttt{Debian}-Zweige eigene 
\textit{Chroot}-Umgebungen bereitzustellen.

Dazu wird eine Kopie von dem Verzeichnis \textit{/var/cache/pbuilder/base.cow} 
angelegt. Darin kann dann z.B. Die Datei \textit{/etc/apt/sources.lists} 
entsprechend angepasst werden.

Dabei kann es bei einer Aktualisierung der Pakete notwendig sein, dass 
zunächst auch Abhängigkeiten dieser Pakete aktualisiert werden müssen. 
Diese stehen jedoch nur mit Zeitverzögerung im Repo zur Verfügung. Hier 
kann es helfen für die weiteren Tests schon einmal die Zeile

\small
\begin{verbatim}
deb http://incoming.debian.org/debian-buildd buildd-unstable main
\end{verbatim}
\normalsize

in der \textit{/etc/apt/sources.lists} zu aktivieren. Damit stehen die 
dortigen Pakete für das Bauen in der \textit{Pbuilder}-Chroot zur Verfügung.

\section{Konfiguration von \textit{sbuild}}
\label{sec:confFileSBuild}

\textit{sbuild} kann ohne Root-Rechte genutzt werden. In diesem Fall ist
der Paketbetreuer in die Gruppe \textit{sbuild} aufzunehmen.

Für diese Nutzung sind folgende Pakete zu installieren.\cite{SBuild2024}

\begin{verbatim}
sudo apt install sbuild mmdebstrap uidmap
\end{verbatim}

Die benötugten Verzeichnisse sind wie folgt zu installieren:

\begin{verbatim}
mkdir -p ~/.cache/sbuild
\end{verbatim}

Nun wird der Tarball der Chroot erstellt.

\small
\begin{verbatim}
mmdebstrap --variant=buildd unstable ~/.cache/sbuild/unstable-amd64.tar.zst
\end{verbatim}
\normalsize

Danach wird eine neue Konfigurationsdatei \textit{\textasciitilde/.sbuildrc}
erstellt. Eine bereits bestehende Datei wird überschrieben. 
Sollten Sie bereits eine \textit{\textasciitilde/.sbuildrc} haben,
erstellen Sie bei Bedarf eine Sicherungskopie. 

<<.sbuild.rc>>=
$chroot_mode = 'unshare';
#$distribution = 'unstable';
$build_source = 1;
$source_only_changes = 1;
$verbose = 1;
#$run_autopkgtest = 1;
$autopkgtest_root_args = '';
$autopkgtest_opts = [ '--apt-upgrade', '--', 'unshare', '--release', '%r', '--arch', '%a' ];
@

%Die Erstellung der \texttt{Sbuild}-Chroot wird in 
%Kapitel~\ref{subsec:CreateSchroot} (Seite~\pageref{subsec:CreateSchroot}) 
%beschrieben.

\section{Weitere \textit{Chroot-}Systeme}
\label{sec:MoreChrootSystems}

Neben dem Bauen in einer \textit{pbuilder}-Chroot gibt es noch weitere 
Situationen, in denen die Nutzung eines separates Systems nützlich sein 
kann. Dies gilt besonders für das Ausführen von \textit{mh\_make}. 
(Kapitel~\ref{sec:BuildWithMaven}, Seite~\pageref{sec:BuildWithMaven})

Diese Einrichtung einer \textit{Maven-Chroot}\index{Chroot (maven)}
wird als Beispiel beschrieben:

Zunächst ist das Paket \textit{debootstrap}, sofern noch nicht vorhanden, 
zu installieren. Dann wird mit 

\begin{verbatim}
sudo mkdir --parents /srv/maven-chroot
\end{verbatim}
ein entsprechendes Verzeichnis für die \textit{Maven-Chroot} angelegt. Die 
Chroot selber wird mit 

\begin{verbatim}
sudo /usr/sbin/debootstrap --arch amd64 sid \
/srv/maven-chroot http://ftp.de.debian.org/debian
\end{verbatim}

erstellt.\cite{Hildebrandt2014}

Danach kann der Nutzer \textit{root} mit dem Befehl \textit{chroot} ein 
neues Wurzelverzeichnis starten.

Die konkreten Befehle lauten (als root):
\begin{verbatim}
 # mount --options bind /proc /srv/maven-chroot/proc
 # mount devpts /dev/pts --types devpts
 # LANG=C chroot /srv/maven-chroot /usr/bin/bash
\end{verbatim}
Die letzte Zeile startet die angelegte Chroot.

Dieser User \textit{root} kann dann nicht mehr auf Dateien außerhalb des 
neuen Wurzelverzeichnisses zugreifen.

Die Chroot-Umgebung kann wie folgt wieder beseitigt werden:

\begin{verbatim}
sudo umount /srv/maven-chroot/proc # Unmount first!
sudo rm -rf /srv/maven-chroot/
\end{verbatim}

Der Ablauf des Programmskript wird auf Wunsch zur Nutzung einer
\textit{Maven-Chroot} angehalten (Kapitel~\ref{sec:BuildWithMaven}, 
Seite~\pageref{sec:BuildWithMaven}).

\section{\texttt{Quilt} fürs Patchen einrichten}
\label{sec:QuiltEinrichtung}

Mit diesem Skript wird für das Patchen unter anderem \textit{dquilt} \index{dquilt} 
verwendet. 
Dies ist eine \texttt{debian}-spezifische Anpassung für \textit{quilt} \index{quilt}.

Um diese Anpassung zu erzeugen, bedarf es der Datei \textit{.quiltrc-dpkg} 
mit folgendem Inhalt 
\footnote{\url{https://www.debian.org/doc/manuals/maint-guide/modify.html}}:

<<DQuilt>>=
d=. ; while [ ! -d $d/debian -a `readlink -ev $d` != / ]; do d=$d/..; done
if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
    # falls in Debian-Paketbaum mit ungesetztem $QUILT_PATCHES
    QUILT_PATCHES="debian/patches"
    QUILT_PATCH_OPTS="--reject-format=unified"
    QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
    QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
    QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;\
    31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi
@

Dazu gehört für den manuellen Betrieb auch der Eintrag in der Datei 
\textit{\textasciitilde/.bashrc} \index{\textasciitilde/.bashrc}. Dieser 
Eintrag sieht wie folgt aus:

\begin{verbatim}
    # wird fuer die Patch-Verfolgung mit Quilt benoetigt
    alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
    complete -F -quilt-completion $_quilt_complete_opt dquilt
\end{verbatim}

Zu beachten ist, dass Einstellungen in der Datei 
\textit{\textasciitilde/.bashrc} \index{\textasciitilde/.bashrc} bei der 
Ausführung dieses Programmskriptes nicht beachtet werden. 
Es müssen also alle notwendigen Einstellungen im Programmskript komplett
abgebildet werden.

Die Verwendung von \textit{quilt} bzw. \textit{dquilt} wird in Kapitel 
\textit{Nutzung von Quilt} (Kapitel~\ref{sec:NutzungQuilt}, 
Seite~\pageref{sec:NutzungQuilt}) beschrieben.

\chapter{\texttt{Git} einrichten}

\section{Branches}

Das \texttt{Git}-Repositorium eines \texttt{Debian}-Paketes hat in der 
Regel mindestens folgende Zweige:

\begin{itemize}\itemsep2pt
    \item debian/sid
    \item upstream
    \item pristine-tar
\end{itemize}

Der Branch \textit{debian/sid} kann auch \textit{master} oder
\textit{main} genannt werden.

Es kann einen zusätzlichen Branch für \textit{experimental} geben. 
Außerdem können Branches für \textit{backports} und \textit
{update-proposal} angelegt werden.

Solche weiteren Branches können auch vom Programmskript angelegt werden. 
(Kapitel~\ref{sec:NeuenBranchErstellen}, Seite~\pageref{sec:NeuenBranchErstellen})

\section{Mergen}

Wird von \textit{debian/experimental} nach \textit{debian/sid} gemergt, 
wird in der Regel ein Fast-Forward-Merge durchgeführt. 

Dies ist dann der Fall, wenn - wie hier - zunächst in \textit{}
{debian/experimental} weitere Aktualisierungen zum Testen eingepflegt 
wurden, dann aber die Entwicklung in \textit{debian/sid} fortgeführt 
werden soll.

Wurden jedoch in der Zwischenzeit auch im Branch \textit{debian/sid} 
Änderungen hinzugefügt, kann nur ein Recursive-Merge durchgeführt werden.

Gegebenenfalls müssen einige Anpassungen, z.B. im Verzeichnis 
\textit{debian/} einzeln ausgewählt und dem jeweiligen Zweig hinzugefügt 
werden (\textit{git cherry-pick}).

Eine dazu bewährte Befehlszeile ist:

\begin{verbatim}
    git cherry-pick --edit -x <commit> 
\end{verbatim}

Sollen mehrere Commits auf einmal dem Zweig zugeführt werden, gilt 
folgende Befehlszeile:

\begin{verbatim}
    git cherry-pick --no-commit <commit> <commit> \dots
\end{verbatim}

\section{\textit{gbp.conf}}
\label{sec:GbpConf}

Das Programmskript nutzt die Anwendungen aus dem \texttt{Debian}-Paket 
\textit{git-buildpackage}.

\textit{git-buildpackage (gbp)} kann und sollte konfiguriert werden.

Die Konfigurationsdatei \textit{gbp.conf} \index{gbp.conf} wird zur 
Steuerung dieser Anwendung verwandt. Sie kann an verschiedenen
Stellen im Dateisystem platziert werden.

\subsection{Reihenfolge}

Die Konfigurationsdateien für gbp werden in folgender Reihenfolge eingelesen:

\begin{enumerate}
 \item /etc/git-buildpackage/gbp.conf, die systemweite Konfigurationsdatei
 \item \textasciitilde/.gbp.conf, die nutzerspezifische Konfigurationsdatei
 \item debian/gbp.conf, Konfiguration für das Repositorium oder den Branch
 \item git/gbp.conf, Konfiguration für das lokale Repositorium
\end{enumerate}

Alle Konfigurationsdateien haben das gleiche Format.
\footnote{\cite{Guenther2006-2017}, Abschnitt \textit{Configuration Files}
und die Manpage zu \textit{gbp-conf}}

Durch Setzen der Umgebungsvariablen \textit{GBP\_CONF\_FILES} kann diese 
Reihenfolge überschrieben werden. Der Inhalt dieser Variable kann mit 
\textit{echo \$GBP\_CONF\_FILES} ermittelt werden.
\footnote{\cite{Guenther2006-2017} Abschnitt 
\textit{Configuration Files/Overriding Parsing Order}}.
 
\subsection{Abschnitte in der \textit{gbp.conf}}

Es gibt verschiedene Abschnitte in der \textit{gbp.conf}. Diese Abschnitte 
sind alle optional.

Für jeden \textit{gbp}-Befehl\footnote{\cite{Guenther2006-2017} Manpage zu 
\textit{gbp-conf}} kann ein eigener Abschnitt erstellt werden.
Zusätzlich gibt es einen Abschnitt, der für alle Befehle gilt

Einige wichtige Abschnitte werden im Folgenden aufgeführt. 

\begin{description}
    \item[\lbrack{}DEFAULT\rbrack{}] In diesem Abschnitt angegebenen 
    Optionen werden auf alle \textit{gbp}-Befehle angewandt.
    \footnote{\cite{Guenther2006-2017} Manpage zu \textit{gbp-conf}}
    \item[\lbrack{}import-orig\rbrack{}]Die Optionen dieses Abschnittes 
    überschreiben die entsprechenden Abschnitte unter
    \textit{\lbrack{}DEFAULT\rbrack{}}.
    Sie werden auf den Befehl \textit{gbp import-orig} angewandt.
    \item[\lbrack{}pq\rbrack{}] Die Optionen dieses Abschnittes werden 
    auf den Befehl \textit{gbp pq} angewandt und überschreiben die 
    des Abschnittes \textit{\lbrack{}DEFAULT\rbrack{}}.
    \item[\lbrack{}dch\rbrack{}] Die Optionen dieses Abschnittes werden 
    auf den Befehl \textit{gbp dch} angewandt und überschreiben die 
    Optionen des Abschnittes \textit{\lbrack{}DEFAULT\rbrack{}}.
    \item[\lbrack{}buildpackage\rbrack{}] Die Optionen dieses Abschnittes 
    werden auf den Befehl \textit{gbp buildpackage} angewandt und 
    überschreiben die Optionen des Abschnittes \textit{\lbrack{}DEFAULT\rbrack{}}.
\end{description}

\subsection{Syntax der Optionen}

Die Optionen in den Abschnitten der \textit{gbp.conf} werden aus den 
Befehlszeilenoptionen gebildet. Die möglichen Optionen zu den einzelnen 
\textit{gbp}-Befehlen können der jeweiligen Manpage entnommen werden. 

Diese werden ohne das einleitende doppelte Minuszeichen angegeben. Aus 
Befehlszeilenoption \textit{-{}-patch-num-format=\%02d\_} wird dann
\textit{patch-num-format=\%02d\_}.

Im Falle von \textit{gbp buildpackage} ist zusätzlich auch \textit{git-} 
wegzulassen\footnote{Manpage zu \textit{gbp-conf}\cite{Guenther2006-2017}}.

Der Eintrag \textit{pbuilder-options=PBUILDER\_OPTION} in der 
\textit{gbp.conf} entspricht also 
\textit{-{}-git-pbuilder-options=PBUILDER\_OPTION}. 

\subsection{Beispiel}
Im Homeverzeichnis des Nutzers kann eine Datei \textit{\textasciitilde/.gbp.conf} 
\index{gbp.conf} beispielsweise wie folgt angelegt werden:

<<gbp.conf>>=

[DEFAULT]
sign-tags = True
# keyid for signing the package
keyid = 0x<keyid>
pristine-tar = True
# generate gz compressed orig file
# compression = xz
# If you want to use normally sbuild
# builder = sbuild

[buildpackage]
postbuild = lintian $GBP_CHANGES_FILE
cleaner = /bin/true
# If you want to use normally pbuilder
# pbuilder = True
pbuilder-options = --source-only-changes --hookdir /home/mechtilde/.pbuilder

#[buildpackage]
# use a build area relative to the git repository
# export-dir=../build-area
# to use the same build area for all packages use an absolute path:
#export-dir=/home/debian-packages/build-area

[dch]
id-length = 7

# Options only affecting gbp pq
[pq]
#patch-numbers = False
# The format specifier for patch number prefixes
#patch-num-format = '%04d-'
patch-num-format = '%02d_'
# Whether to renumber patches when exporting patch queues
#renumber = False
renumber = True
# Whether to drop patch queue after export
#drop = False
@

In der Datei \textit{/etc/git-buildpackage/gbp.conf} werden die 
Konfigurationsmöglichkeitenaufgeführt.

\section{\texttt{Git}-Repositorien auf eigener Infrastruktur}
\label{sec:GitRepoLocal}

\subsection{Lokales \texttt{Git}-Repositorium}
Das lokale Git-Repositorium wird entweder vom Skript angelegt 
(Kapitel~\ref{sec:LokalesGitRepoAnlegen}, Seite~\pageref{sec:LokalesGitRepoAnlegen}) 
oder durch Klonen erzeugt (Kapitel~\ref{sec:SalsaDebianOrg}, 
Seite~\pageref{sec:SalsaDebianOrg}). Außerdem kann es mit
\textit{gbp import-dsc} erzeugt werden (Kapitel~\ref{sec:ImportPackage}, 
Seite~\pageref{sec:ImportPackage}).

Ihm können weitere Branches hinzugefügt werden 
(Kapitel~\ref{sec:NeuenBranchErstellen}, 
Seite~\pageref{sec:NeuenBranchErstellen}).

\subsection{Eigener \texttt{Git}-Server}
\label{subsec:EigenerGitServer}
Das lokale Git-Repositorium kann auch auf einem eigenen Git-Server 
\enquote{gespiegelt} werden.

Die Einrichtung des Servers erfolgt manuell. 
Die Verwendung von \textit{cgit} oder \textit{gitweb} erleichtern den Zugriff.

Im Programmskript können der Name oder die IP des eigenen Git-Servers 
eingegeben werden (Kapitel~\ref{sec:NameEigenerGitServer}, 
Seite~\pageref{sec:NameEigenerGitServer}).

Der \enquote{Workflow} ist dann wie folgt:
Nach der Anlage der Konfigurationsdatei wird zunächst der Name oder die 
IP des eigenen Git-Servers eingegeben (Kapitel~\ref{sec:NameEigenerGitServer}, 
Seite~\pageref{sec:NameEigenerGitServer}), bevor mit dem Bauen eines neuen 
Paketes begonnen wird (Kapitel~\ref{chap:CreateNewProject}, 
Seite~\pageref{chap:CreateNewProject}).

Das \enquote{fertige} Paket kann dann auf den eigenen Git-Server 
hochgeladen werden (Kapitel~\ref{sec:HochladenEigenerGitServer}, 
Seite~\pageref{sec:HochladenEigenerGitServer}).

\chapter{\textsl{Salsa}-Repositorien}
\label{chap:SalsaRepo}

\textsl{Salsa} ist der Name eines gemeinschaftlichen Entwicklungsserver für
\texttt{Debian}, der auf der \texttt{GitLab}-Software basiert.
\textsl{Salsa} soll die notwendigen Werkzeuge für die kollaborative
Entwicklung für Paketbetreuer, Paketierungsteams und andere debian-bezogene
Einzelpersonen und Gruppen bereitstellen.\cite{Salsa2023}

\textsl{Salsa} bietet alle Funktionen von \texttt{GitLab}. Der Dienst
steht unter \url{https://salsa.debian.org} zur Verfügung. Es gibt eine
Dokumentation der debian-spezifischen Eigenheiten \cite{SalsaDoc2023},
mit denen man sich zunächst vertraut machen sollte.

\section{\textsl{Salsa}-Account anlegen}

Das Anlegen eines Accounts auf \textsl{Salsa} ist sehr einfach. Man ruft
die Seite \url{https://salsa.debian.org/users/sign_up} auf, welche
selbsterklärend ist.

\section{Anlage eines \textsl{Salsa}-Repositoriums}
\label{sec:ManuelleAnlage}

Ein \texttt{Git}-Repositorium auf \textit{salsa.debian.org} wird nicht vom
Programmskript eingerichtet.

Nach dem Login und der Authentifizierung auf \url{https://salsa.debian.org} 
kann dort im jeweiligen Team ein neues Repositorium angelegt werden.

Für die Anlage von neuen Projekten auf \url{https://salsa.debian.org } 
sind entsprechende Rechte erforderlich. Dies können die Rechte eines
\texttt{Debian}-Developers sein. Für die team-betreuten Projekte können
diese Rechte auch an weitere Personen von den Betreuenden vergeben werden.

Eine Beschreibung der Anlage eines Projektes im Java-Team erfolgt in 
Kapitel~\ref{sec:JavaTeam}, Seite~\pageref{sec:JavaTeam}.

Nach dem Login auf der Seite \url{https://salsa.debian.org} und der 
Auswahl des passenden Projektes für das neue Paket, wird mit dem Klick 
auf den Button \textit{Neu erstellen} und der Auswahl der Funktion
\textit{Neues Projekt/Repository} die entsprechende Seite aufgerufen.
Dort ist meist \textit{Ein leeres Projekt} auszuwählen. Dann gibt man
den Projektnamen ein. Dies ist meist der Name des Quellcodepaketes.
Als Sichtbarkeitsgrad (Visibility Level) wird \textit{Öffentlich} ausgewählt. 
Dann folgt der Klick auf den Button \textit{Projekt anlegen}.

Auf der folgenden Web-Seite gibt es noch einige Erläuterungen. 
Vieles davon wird zunächst lokal mit dem beschriebenen Programm angelegt.

In der linken Navigationsleiste werden nun im Bereich \textit{Einstellungen} 
weitere Konfigurationen zum Projekt vorgenommen.

Hier ist es wichtig unter \textit{CI/CD} den Pfad und den verwendeten 
Datei\-namen anzugeben.
 
\begin{description}
 \item[\textit{CI}] steht für Continuous Integration
 \item[\textit{CD}] steht für Continuous Delivery 
\end{description}

Die hier verwendete Datei heißt \textit{salsa-ci.yml} 
(Kapitel~\ref{subsec:SalsaCi}, Seite~\pageref{subsec:SalsaCi}) im 
Verzeichnis \textit{debian/}.

Das Build-Skript trägt das \textsf{Salsa}-Repositorium als
\enquote{Remote-Repositori\-um} ein und erinnert den Nutzer an die Anlage auf
\textit{salsa.debian.org} (Kapitel~\ref{subsec:SalsaRepoAnlegen},
Seite~\pageref{subsec:SalsaRepoAnlegen}) 

\section{\textsl{Salsa}-Repositorium für das \texttt{Java}-Team}
\label{sec:JavaTeam}

\textsl{Salsa}-Repositorien, die einem speziellen Projekt (wie
beispielsweise dem \texttt{Java}-Team) zugeordnet sind, sollten möglichst
einheitlich angelegt werden. Häufig wird hierzu ein Skript vom Projekt
bereitgestellt, welches hierzu verwandt werden soll.

Dazu wechselt man in das gewünschte Team-Verzeichnis. 

\begin{figure}[h]
\centering
\includegraphics[width=30em]{Pictures/SalsaJavaMaintainers.png} 
\caption{Information zum \texttt{Java}-Team\protect\footnote{Quelle:
\url{https://salsa.debian.org/java-team/}}}.
\end{figure}

\subsection{Quelle des Skripts}

Unter

\scriptsize
\url{https://salsa.debian.org/java-team/pkg-java-scripts/
blob/master/setup-salsa-repository}
\normalsize
kann das Skript des \textit{Java-Teams} heruntergeladen werden. Es ist 
auch im Anhang beigefügt 
(Kapitel~\ref{sec:CreateJavaTeam}, Seite~\pageref{sec:CreateJavaTeam}).

\subsection{Abhängigkeiten}

Dieses \textit{Setup-Skript} nutzt \textit{jq}. \textit{jq} ist ein
leichtgewichtiger und flexibler \textit{JSON}-Prozessor für die
Kommandozeile. Er hat nur minimale Laufzeitabhängigkeiten. Es gibt ein
gleichnamiges \texttt{Debian}-Paket. Dieses Paket muss lokal installiert
sein (Kapitel~\ref{subsec:DependencyJava},
Seite~\pageref{subsec:DependencyJava}).

\subsection{Zugangstoken beschaffen}

Für die Anpassung wird noch ein projektspezifischer 
Token\index{Zugangstoken} benötigt.

Nach dem Login auf \textit{salsa.debian.org} wird im Dropdown-Menü des 
Nutzers \textit{Einstellungen} gewählt. Damit wird die Seite 
\textit{Benutzereinstellungen} des eingeloggten Nutzers aufgerufen.

In der linken Leiste befindet sich nun der Eintrag \textit{Zugangs-Token}. 
Dort wird die Seite 
\textit{https://salsa.debian.org/profile/personal\_access\_tokens} 
zur Erstellung eines solchen Token aufgerufen. Er wird für jedes Projekt 
neu generiert. 

\begin{figure}[h]
\centering
\includegraphics[height=45ex]{Pictures/AccessToken.png} 
\caption{Zugangstoken erstellen\protect\footnote{Quelle:\url{https://salsa.debian.org}}}
\end{figure}

Dort wird der Name des zu erstellenden Projektes eingegeben. Ferner wird 
ein Ablaufdatum für das Token eingegeben. Danach wird der 
Gültigkeitsbereich des Tokens festgelegt. Als \textit{Scope} ist hier 
\textit{api} auszuwählen. Mit dem Klick auf den Button 
\textit{Create personal access token} erscheint oben auf der Seite der
Zugangstoken.

\subsection{Token eintragen}

Das generierte Token ist als \textit{SALSA\_TOKEN} in das Skript einzutragen. 
Das Kommentarzeichen ist zu entfernen

Es erscheint sinnvoll, dieses Skript jeweils im Projektverzeichnis abzulegen.

\subsection{Skript aufrufen}

Das Skript wird nun mit dem Namen des neuen Projektes (Paketes) als 
Parameter aufgerufen:

\begin{verbatim}
    ./setup-salsa-repository.sh <packagename>
\end{verbatim}

Danach werden folgende Meldungen ausgegeben 
(anhand des Beispiels BeanValidationApi):

\begin{verbatim}
 ./setup-salsa-repository.sh beanvalidation-api
 Creating the beanvalidation-api repository\dots
 Configuring the BTS tag pending hook\dots
 Configuring the KGB hook\dots
 Configuring email notification on push\dots

 Done! The repository is located at 
    https://salsa.debian.org/java-team/beanvalidation-api
\end{verbatim}

Erscheint lediglich die erste Zeile, sind das verwendete Skript 
(s. Kapitel~\ref{sec:CreateJavaTeam}, 
Seite~\pageref{sec:CreateJavaTeam}) und Token zu prüfen.

\section{Aufgaben auf \textit{salsa.debian.org}}

\subsection{Merge Request}

Manchmal gibt es auch sogenannte Merge Request, in dem andere Patches 
bereitstellen.

Auf \textit{salsa.debian.org} gibt es in der linken Navigationsleiste 
dann einen Eintrag \enquote{Merge-Requests}. Dort kann dieser dann 
bearbeitet werden.

Dies erfolgt durch Klicken auf die Commit-Message.

\chapter{Paketieren jenseits vom Zweig \textit{Unstable}}
\label{chap:JenseitsUnstable}

Es gibt verschiedene Gründe, warum von dem generellen Weg, neue
Upstream-Versionen ausschließlich für \textit{Unstable = sid} zu paketieren,
abgewichen werden darf und wird. Auch das Programmskript ermöglicht dies
(Kapitel~\ref{chap:BuildBeyondSid},
Seite~\pageref{chap:BuildBeyondSid}).

Die Entwicklerreferenz \cite{Debian-Entwicklerreferenz} bezeichnet das
Hochladen in die Distribution \textit{Stable} und \textit{Oldstable} als
\enquote{Sonderfall}. \footnote{Kapitel 5.5.1 in der Developer-Reference\cite{Debian-Entwicklerreferenz}}

Ein wesentlicher Grund ist das Vorhandensein eines schwerwiegenden 
Fehlers oder eines Sicherheitsproblems. Schwerwiegende Fehler in einem 
Paket werden in der Regel durch einen entsprechend eingestuften 
Fehlerbericht gemeldet.

Eine weitere Abweichung von der generellen Regel gibt es bezüglich der Pakete
der \texttt{Mozilla}-Suite, \texttt{Firefox} und \texttt{Thunderbird}. 
Diese Pakete werden zeitnah nach ihrem Upstream-Release für die 
\textit{ESR = Extended Support Release} Version auch als  
\textit{Security-Updates} (Kapitel~\ref{sec:SecurityUpdates}, 
Seite~\pageref{sec:SecurityUpdates}) für das \textit{Stable}-Release 
bereitgestellt.

Daraus können sich z.B. für die Erweiterungen, hier als Webextensionen
(Kapitel~\ref{chap:WebextBauen}, Seite~\pageref{chap:WebextBauen}) 
beschrieben, Inkompatibilitäten mit der dann aktuellen Version im 
\textit{Stable}-Release ergeben. Dies ist ebenfalls ein Grund, eine
Aktualisierung im \textit{Stable}-Release vorzunehmen (s.a. 
Kapitel~\ref{subsec:MozillaDependencies},
Seite~\pageref{subsec:MozillaDependencies}).

Daneben ist es bei Desktop-Anwendungen oft wünschenswert, aktuellere 
Versionen derselben in einer stabilen Betriebssystemumgebung zu nutzen.
Dazu werden die gewünschten Pakete als sogenannte \textit{Backports} (d.h.
Rückportierungen) zur Verfügung gestellt. 
(s. Kapitel~\ref{sec:StableBackports}, 
Seite~\pageref{sec:StableBackports})

Es gibt auch gute Gründe, Pakete zunächst nach \textit{Experimental}
(auch \textit{rc-buggy} genannt)
hochzuladen. Dies gilt besonders für neue Pakete. In dem Zeitraum, in 
dem die bestehenden Versionen \enquote{eingefroren} sind und nur 
Fehlerbehebungen für das nächste Release erlaubt sind, werden neue 
Versionen oft vorab nach \textit{Experimental} hochgeladen.
(s. Kapitel~\ref{sec:Experimental}, Seite~\pageref{sec:Experimental})

\begin{figure}[h] 
\centering 
\includegraphics[width=30em]{Pictures/PackageCycle.png}
\caption{Arbeitsabläufe \cite{DebianReleases}
\protect\footnote{\textcopyright 2016 Antoine Beaupr\'{e}
anarcat@debian.org, CC-BY-SA 4.0}}
\end{figure}

\section{Security-Updates}
\label{sec:SecurityUpdates}

Wichtig ist die Rückportierung\index{Rückportierung} von Änderungen an 
Quellcode-Dateien wegen Sicherheitsproblemen\index{Security-Patches}.

Immer, wenn ein Sicherheitsproblem bekannt wird, soll der Maintainer 
mit dem Sicher\-heits-Team\index{security-Team} zusammenarbeiten, um für 
das \textit{Stable}-bzw. \textit{Oldstable}-Release eine korrigierte 
Version bereitzustellen. Die Fehlerbehebung sollte gezielt 
erfolgen. Patches sollten so klein wie möglich gehalten werden. Weitere
Informationen befinden sich in den Kapiteln
\href{https://www.debian.org/doc/manuals/developers-reference/developer-duties.de.html#maintain-packages-in-stable}{3.1.2} 
und \href{https://www.debian.org/doc/manuals/developers-reference/pkgs.de.html#bug-security}{5.8.5}
der \texttt{Debian}-Entwicklerreferenz\cite{Debian-Entwicklerreferenz}.

\section{(Old-)Stable-Proposal}
\label{sec:StableProposal}

Sollen Pakete mit schwerwiegenden Fehlern, die nicht die IT-Sicherheit 
betreffen, aktualisiert werden, kann dies unter bestimmten 
Voraussetzungen in \textit{Proposed-Updates}\index{Proposed-Updates} 
erfolgen. Gleiches gilt hinsichtlich der Erweiterungen für
\texttt{Firefox} und \texttt{Thunderbird}.

Als Kriterien für das Hinzufügen von Paketen zu \textit{stable-updates} 
sind folgende genannt worden.
\footnote{\url{https://lists.debian.org/debian-devel-announce/2011/03/msg00010.html}}:

\begin{itemize}\itemsep2pt

 \item Die Aktualisierung ist dringend und nicht sicherheitsrelevant. Die
Sicherheitsaktualisierungen erfolgen im oben genannten Wege 
(Kapitel~\ref{sec:SecurityUpdates},
Seite~\pageref{sec:SecurityUpdates}).

 \item Das fragliche Paket ist ein Datenpaket, und die Daten müssen 
zeitnah aktualisiert werden (z.B. tzdata). 

 \item Korrekturen an Paketen, die durch externe Änderungen beeinträchtigt 
sind und von denen kein anderes oder nur wenige andere Pakete abhängig sind. 

 \item Pakete, die aktuell sein müssen, um nützlich zu sein (z.B. clamav).
 
\end{itemize}

Wer glaubt, dass die angestrebte Aktualisierung diese Kriterien 
erfüllt, sollte sich vertrauensvoll an das Release Team über die 
Mailingliste debian-release@lists.debian.org, und erläutern, dass diese 
Aktualisierung auch über \textit{stable-updates} erfolgen sollte.

Das für die Rückportierung auf diesem Wege vorgesehene Paket sollte 
bereits in \textit{Unstable} oder besser noch in \textit{Testing} 
veröffentlicht worden sein.

Während Backports in einem eigenen Repositorium  gesammelt werden, werden 
\textit{Propo\-sed-Updates} in das \textit{Stable}-Proposed-Repositorium eingefügt. 
Diese Pakete werden dazu von den \texttt{Debian}-Entwicklern nach \textit{Stable} 
hochgeladen. Dies gilt für Oldstable-Proposed-Updates entsprechend.
Die Veröffentlichung erfolgt im nächsten Point-Release.

\subsection{Fehlerbericht}

Eine notwendige Voraussetzung ist auch hier zunächst ein aussagekräftiger
Fehlerbericht (Bug-Report) (s.a. Kapitel~\ref{chap:StartEMail},
Seite~\pageref{chap:StartEMail}). Dieser wird an
\textit{submit@bugs.debian.org} gesandt. Vorzugsweise sollte dafür das
Programm \texttt{Reportbug} genutzt werden.

Dieser Fehlerbericht benötigt folgende Parameter:

\begin{verbatim}
Package: release.debian.org
Severity: normal
Tags: <ReleaseName>
User: release.debian.org@packages.debian.org
Usertags: pu
X-Debbugs-Cc: <SoureName>@packages.debian.org, <Maintainer>@debian.org
Control: affects -1 + src:<SourceName>

[ Reason ]

This package is ... # Why should it be updated?

[ Impact ]

Otherwise ... # What happens instead?

[ Risks ]

# Which packages are affected?

[ Checklist ]
  [X] *all* changes are documented in the d/changelog
  [X] I reviewed all changes and I approve them
  [X] attach debdiff against the package in (old)stable
  [X] the issue is verified as fixed in unstable

[ Changes ]

# What are the changes?

[ Other info ]

# Do you have further infos?
\end{verbatim}

Dieser Fehlerbericht wird gegen das Pseudopaket \textit{release.debian.org} 
erstellt. Der Schweregrad eines solchen Fehlerberichtes ist im Allgemeinen 
maximal \textit{normal}. Im Betreff wird der Name des Paketes aufgeführt, 
das für \textit{Proposed-Updates} gebaut wird. 

\textit{Proposed-Updates}\index{Proposed-Updates} werden, wie dargelegt,
nur unter besonderen Umständen zugelassen. 
Das \textit{Release-Team}\index{Release-Team} entscheidet, ob die 
Veröffentlichung erfolgt.

Daher muss der Fehlerbericht eine Begründung enthalten, warum diese Version 
in \textit{stable} aktualisiert werden soll. Sofern es bereits eine dazugehörige 
Fehlernummer gibt, ist diese anzugeben. Dieser Fehlerbericht 
\textbf{muss} einen Schweregrad von \textit{important} oder höher aufweisen.

Ein entsprechender Fehlerbericht muss gegebenenfalls auch für
\textit{Old-Stable} erstellt werden.

Weist dieser Fehlerbericht den notwendigen Schweregrad nicht auf, ist er
zu berichtigen. Wie dies erfolgt, wird in Kapitel~\ref{sec:ChangeBugReport} 
(Seite~\pageref{sec:ChangeBugReport})

\subsection{Anforderungen an einen Patch}

Ein Fehler sollte mit einem möglichst kleinen und passgenauen Patch 
behoben werden können. Damit soll verhindert werden, dass neue Fehler 
entstehen. Es dürfen auch keine neuen Abhängigkeiten hinzukommen. Auch 
muss berücksichtigt werden, welche anderen Pakete von diesem Paket abhängen.
\footnote{Kapitel 5.5.1 in der Developer-Reference\cite{Debian-Entwicklerreferenz}}

Diese passgenauen Patches werden mit \textit{debdiff <BisherigesPaket>.dsc 
<NeuesPaket>.dsc > <Dateiname>.txt} dokumentiert. Es wird die Differenz 
angegeben, die zwischen der aktuellen Paketversion in Stable/Oldstable
(bisheriges Paket) und der Version besteht, die hochgeladen werden soll (neues
Paket). Wie diese Dokumentation mit dem Programmskript erstellt werden
kann, wird in Kapitel~\ref{subsec:debdiff}
(Seite~\pageref{subsec:debdiff}) beschrieben.

\subsection{Abhängigkeiten zu \texttt{Mozilla}-Paketen}
\label{subsec:MozillaDependencies}

Eine hinreichende Begründung für \textit{Webextensions} kann auch die 
oben (s. Kapitel~\ref{chap:JenseitsUnstable}, 
Seite~\pageref{chap:JenseitsUnstable}) erwähnte Ausnahmeregelung für 
die Pakete der \texttt{Mozilla}-Suite sein. 

Für diese Erweiterungen können sich nämlich Inkompatibilitäten mit der 
dann aktuellen Version von \texttt{Firefox} oder\texttt{Thunderbird} im 
\textit{Stable}-Release ergeben. Dann sind die bisherigen Versionen 
unbrauchbar, was vor allem im produktiven Betrieb ein beachtliches 
Problem darstellt. (Kapitel~\ref{chap:BuildBeyondSid}, 
Seite~\pageref{chap:BuildBeyondSid})

\section{Stable-Backports}
\label{sec:StableBackports}

Um Pakete für Backports bauen zu können, sind einige Vorbereitungen zu 
treffen. 

Oft lässt sich ein solches Paket nicht ohne Weiteres in einer \textit{}
{Stable}-Umgebung bauen. 

Dann werden weitere Pakete aus Backports benötigt. 
Pakete aus Backports werden aber nicht automatisch auch in einer solchen 
\textit{Chroot} installiert. 

Daher ist es notwendig, in \textit{/etc/apt/preferences} eine solche 
Installation zu ermöglichen.

Dazu werden im \textit{pbuilder} \textit{Hooks} verwendet 
(Kapitel~\ref{subsec:HooksEinrichten}, 
Seite~\pageref{subsec:HooksEinrichten}).

\url{https://wiki.debianforum.de/Pbuilder\_-\_personal\_package\_builder}

\section{Backports-Repositorium}

Regelmäßig werden die Pakete für den Unstable-Zweig gebaut.Von dort gelangen 
sie dann - sofern keine Fehler gefunden werden - in den Testing-Zweig. Beim 
Release wird der Testing-Zweig zunächst eingefroren und dann zum neuen 
Stable-Zweig. Es wird dann ein neuer Testing-Zweig eröffnet.

Werden Programmversionen aus \textit{testing} oder (ausnahmsweise
\footnote{in der Regel nur Sicherheits-Updates}) auch aus \textit{unstable}
in ein früheres Release übertragen, nennt man dies \textit{backporting}.

Durch die an der Praxis orientierten Releasezyklen der stabilen 
\texttt{Debian}-Version ist es manchmal wünschenswert, Softwarepakete oder neuere 
Versionen aus Testing auch unter Stable verfügbar zu haben. 

Hierzu dient das Backports-Repositorium.

Versionierung (z.B. +deb9u1)

Backports gibt es für das Stable- und Oldstable-Release.

\section{Experimental}
\label{sec:Experimental}

%\section{Backporten fremder Pakete}
%pristine-tar 
%NMU
%Abhängigkeiten aus Backports

%Verweis auf (Kapitel~\ref{chap:BauenBackports}, 
%Seite~\pageref{chap:BauenBackports})
%\footnote{\cite{Debian-Entwicklerreferenz} Abschnitt \textit{upload-stable}} 
%für die Veröffentlichung nach \textit{Propo\-sed-Up\-dates} für 
%\textit{Stable} bzw. \textit{Old-Stable}.

\section{Versionierung}
\label{sec:Versioning}

Die Ursache bzw. Herkunft der Aktualisierung hat auch Einfluss auf die 
Versionierung. Dabei ist sicherzustellen, dass \textit{dpkg} neuere 
Versionen korrekt als Upgrades interpretieren kann. Ein Blick auf die 
nächste zu erwartende Versionsnummer kann dabei helfen.

Beim Bauen für \textit{experimental} wird in der Datei
\textit{debian/changelog} folgender Versionseintrag empfohlen:

<Versionsnummer>-<Revisionsnummer>\textasciitilde exp<Laufende Nummer>

Die Revisionsnummer ist in der Regel: 1

Beim Bauen für \textit{Proposed-Updates} sind zwei Fälle zu unterscheiden. 

\begin{description}
 \item[Fall A] Eine im \textit{Stable}-Release vorhandene Version soll unter 
Beibehaltung dieser Versionsnummer korrigiert werden.

 \item[Fall B] Ausnahmsweise soll eine neue Version in das Release aufgenommen werden.

Für den Versionseintrag in \textit{debian/changelog} ist zwingend folgende 
Nomenklatur zu verwenden:

 \item[Fall A] <Ursprüngliche Versions- und Revisionsnummer>
 +deb<Debian-Release-Num\-mer>u<Revisionsnummer des Updates>
 
 \item[Fall B] <Versions- und Revisionsnummer aus Unstable/Testing>\textasciitilde 
 deb<Debian-Release-Nummer>u<Revisionsnummer des Updates>

Die Verwendung der \textasciitilde bewirkt, dass die Version in Stable 
kleiner als die in Testing (für das nächste Release) ist. Dies sichert den 
Aktualisierungspfad.

\end{description}

\chapter{Zum Start eine E-Mail}
\label{chap:StartEMail}

Bevor das Paketieren mit dem Ziel der Veröffentlichung im 
\texttt{Debian}-Reposito\-rium beginnen kann, bedarf es einer E-Mail. Diese 
löst einen \enquote{Bugreport} aus, dessen Nummer in der Datei 
\textit{debian/changelog} zu vermerken ist. Durch die Veröffentlichung des 
Paketes soll nämlich dann dieser Bugreport geschlossen werden.

Weitere Informationen dazu gibt es unter 
\url{https://www.debian.org/devel/wnpp/}

\section{ITP - Intent To Package}

\textit{ITP} bedeutet \enquote{Intent to Package}. Dies bedeutet, 
dass an diesem Paket gearbeitet wird.

Dies ist die Bezeichnung eines Bug-Reportes, der gegen das Paket 
\textit{WNPP} erstellt wird, was \textit{Work-Needing and Prospective 
Package} bedeutet. Dies kann mit \textit{Arbeitsbedürftige und 
voraussichtliche Pakete} übersetzt werden. 

Das Paketieren von neuer Software sollte rechtzeitig angekündigt werden.
Vielleicht gibt es ja noch Hinweise, was bei dem geplanten Paket zu
beachten ist. Auch wird so verhindert, dass verschiedene Gruppen versuchen,
dieselbe Software für \texttt{Debian} zu paketieren.

Eine Möglichkeit ist, dies mit dem auf jedem \texttt{Debian}-System installierten 
Tool \textit{reportbug} durchzuführen. Es gibt aber auch die Möglichkeit 
einfach eine E-Mail-Vorlage zu nutzen. Die folgende Vorlage basiert auf 
dem \textit{itp\_template} mit dem \textit{reportbug} diese E-Mail erstellt.

\begin{verbatim}
To: submit@bugs.debian.org
Subject: ITP: <Source Name> - <Short Description>
Package: wnpp
Severity: wishlist

* Package name : <Package Name>
  Version : x.y.z
  Upstream Author : Name <somebody@example.org>
* URL : http://www.example.org/
* License : (GPL, LGPL, BSD, MIT/X, etc.)
  Programming Lang: (C, C++, C#, Perl, Python, etc.)
  Description :  <Short Description>

(Include the long description here.)

<And answer following questions:>

* Why is this package useful/relevant?
* Is it a dependency for another package?
* Do you use it yourself?
* If there are other packages providing similar functionality, 
  how does it compare?
* How do you plan to maintain it? Do you plan to maintain it
  inside a packaging team?
  (check list at https://wiki.debian.org/Teams)
* Are you looking for co-maintainers? Do you need a sponsor?

\end{verbatim} 

Der Text in der ersten Zeile hinter dem \textit{To:} kommt in die 
Adresszeile. Der Text in der zweiten Zeile hinter dem \textit{Subject:} 
kommt in die Betreffzeile, wobei die Platzhalter durch den Namen des 
Quellcodes und einer kurzen Beschreibung ersetzt werden.

Wird das Paket hochgeladen, muss diese Nummer aus dem Bug-Tracking-System
im \textit{debian/changelog} vermerkt werden (Closes:\#XXXXXX)

\section{RFP - Request For Package}
\textit{RFP} bedeutet \textit{Request for Package}. Dies bedeutet, dass 
ein solches Paket in \texttt{Debian} erwünscht ist.

Auch hierzu habe ich einmal eine E-Mail-Vorlage erstellt.

\begin{verbatim}
To: submit@bugs.debian.org
Subject: RFP: <Sourcecode Name> - <Short Description>
Package: wnpp
Severity: wishlist

* Package name : <Package Name>
  Version : x.y.z
  Upstream Author : Name <somebody@example.org>
* URL : http://www.example.org/
* License : (GPL, LGPL, BSD, MIT/X, etc.)
  Programming Lang: (C, C++, C#, Perl, Python, etc.)
  Description :  <Short Description>

(Include the long description here.)

<And answer following questions:>

* Why is this package useful/relevant?
  Is it a dependency for another package?
* Do you use it yourself?
* If there are other packages providing similar functionality,
  how does it compare?
* How do you plan to maintain it? Do you plan to maintain it
  inside a packaging team?
  (check list at https://wiki.debian.org/Teams)
* Are you looking for co-maintainers? Do you need a sponsor?   
\end{verbatim}

Auch hier gilt: Der Text in der ersten Zeile hinter dem \textit{To:} 
kommt in die Adresszeile. Der Text in der zweiten Zeile hinter dem 
\textit{Subject:} kommt in die Betreffzeile, wobei die Platzhalter durch 
den Namen des Quellcodes und einer kurzen Beschreibung ersetzt werden.

\section{ITA - Intent To Adoption}
Dies wird verwendet, wenn ein Paket, dass mit \enquote{O} oder 
\enquote{RFA} gekennzeichnet ist, übernommen werden soll.

Dazu muss der vorherige Fehlerbericht umbenannt und \enquote{O} bzw.  
\enquote{RFA} durch \enquote{ITA} ersetzt werden.

Dabei tragen Sie sich als Besitzer ein.

Soll ein Fehlerbericht umbenannt oder der Besitzer geändert werden, muss 
dies per E-Mail an \textit{control@bugs.debian.org} oder direkt an den 
Fehlerbericht über die Nummer (xxxxxx@bugs.debian.org) erfolgen\footnote{\url{https://www.debian.org/devel/wnpp/}}.

Dabei ist ein strukturierter \textit{Pseudo-Header} zu nutzen.
\footnote{\url{https://www.debian.org/Bugs/Reporting\#control}}

\section{RFA - Request for Adoption}

\section{RFH - Request For Help}

\section{O - Orphaned}


\section{RFS - Request For Sponsor}

Wie auf \url{https://mentors.debian.net/sponsor/rfs-howto} beschrieben,
wurde die Vorlage angepasst.

\begin{verbatim}
 To: submit@bugs.debian.org
Subject: RFS: <Package Name> - <Short Description>
Package: sponsorship-request
Severity: normal 
          [important for RC bugs, wishlist for new packages]

Dear mentors,

I am looking for a sponsor for my package "<Source Name>":

* Package name : <Source Name>
  Version : x.y.z
  Upstream Author : Name <somebody@example.org>
* URL : http://www.example.org/
* License : (GPL, LGPL, BSD, MIT/X, etc.)
  Programming Lang: (C, C++, C#, Perl, Python, etc.)
  Description :  <Short Description>

It builds those binary packages:

  <Name of the Binaries>

To access further information about this package, please visit 
the following URL:

  https://mentors.debian.net/package/<package name>

Alternatively, one can download the package with dget using
this command:

  dget -x https://mentors.debian.net/debian/pool/main/<p> \
  /<package name>/<package name>_x.y.z.dsc

Changes since the last upload:
  [your most recent changelog entry]

Regards,
   
\end{verbatim}

\chapter{Änderungen am Fehlerbericht}
\label{sec:ChangeBugReport}

Im Laufe eines solchen Prozesses kann es vorkommen, dass Änderungen am 
Fehlerbericht erfolgen müssen. Eine solche Änderung kann eine Änderung 
des Maintainers, des Titels oder auch Anderes sein.

Dazu werden die Befehle des \textit{Kontroll-E-Mail-Server} genutzt. Unter 
\url{https://www.debian.org/Bugs/server-control} findet sich die
Beschreibung dazu.

Dies kann mit einer strukturieren E-Mail erfolgen. Diese wird an die
Adresse \textit{control@bugs.debian.org} gesandt.

Befehle, die eigentlich an control@bugs.debian.org zu senden sind,
funktionieren auch, wenn sie an submit@bugs.debian.org oder an
<bug number>@bugs.debian.org gesandt werden
\footnote{\url{https://www.debian.org/Bugs/Reporting\#control}} 

\section{Anpassung des Schweregrades}

Im Betreff kann hier \textit{Change severity} angegeben werden.

\begin{verbatim}
severity <bug number> important
thank you 
\end{verbatim}

Für die automatische Auswertung der relevanten Informationen in der E-Mail
muss sie mit \textit{thanks}, \textit{thankyou}, \textit{thank you} oder
einer anderen Endemarkierung wie \textit{quit} oder \textit{stop}
abgeschlossen werden. 

\section{Anpassung des Titels}

Für die Änderung des Titels wird dann zusätzlich eine Zeile wie folgt

\begin{verbatim}
    retitle <bug number> -1 <neuer Titel>
\end{verbatim}

eingefügt.

\section{Änderung des Maintainers}

Für die Änderung des Maintainers wird die folgende Zeile hinzugefügt:

\begin{verbatim}
    Control: owner -1 <Neuer Maintainer oder wnpp@debian.org>
\end{verbatim}

\section{Öffnen eines geschlossenen Fehlerberichtes}

Gegebenenfalls muss ein fälschlich geschlossener Bericht wieder geöffnet
werden. Dies erfolgt mit

\begin{verbatim}
    reopen Fehlernummer [ <Urheber-Adresse> | = | ! ]
\end{verbatim}

\section{Schließen eines Fehlerberichtes}

\begin{verbatim}
    close Fehlernummer [ Urheber-Adresse | = | ! ]
\end{verbatim}

\section{\textit{usertags} hinzufügen}

Im Laufe eines Maintainer-Lebens kommt es immer wieder vor, dass 
Fehlermeldungen mit tags versehen werden müssen oder sollten. 

Z.~B. ist es hilfreich für sogenannten \textit{Bug Squashing Parties}, die 
geplanten und durchgeführten Fehlerbehebungen auch zu kennzeichnen.

Dafür wird eine E-Mail an den Fehlerbericht geschrieben. Adresse lautet 
dann \textit{<Bugnummer>@debian.org}. Diese E-Mail soll
auch \textit{CC} an \textit{control@bugs.debian.org} gehen.

Am Anfang einer solchen E-Mail steht dann:

\begin{verbatim}
    user debian-release@lists.debian.org
    usertags -1 + <Titel der BSP>
    thank you
\end{verbatim}

\chapter{Reportbug einrichten}

Das Comand-Line-Interface ist bereits Bestandteil der Basisinstallation. 
Zusätzlich kann mit dem Paket \textit{reportbug-gtk} noch ein graphisches 
Nutzerinterface installiert werden.

\chapter{Schwierigkeiten überwinden}

\section{Ein Paket loseisen}

Eine Schwierigkeit ergibt sich daraus, dass es vor einem geplanten Release 
eine Zeitspanne gibt, in der die Pakete nicht mehr automatisch von 
\textit{unstable} nach \textit{testing} migrieren.

Im vollständigen \enquote{Freeze} benötigen alle Pakete, die noch von \textit{unstable}
nach \textit{testing} migrieren sollen, eine Entsperrung durch das 
Release-Team.\cite{Release-Team2021}. Diese muss mit einem 
\textit{Unblock Bugreport} beantragt werden.

\subsection{Beantragung einer Entsperrung}

Dazu wird zunächst eine Datei mit \textit{debdiff} erstellt (s.a. 
Kapitel~\ref{sec:StableProposal}, Seite~\pageref{sec:StableProposal}).

Damit wird die Differenz zwischen der Version in \textit{testing} (alte 
Version) und \textit{Unstable} (neue Version) mit der jeweiligen 
\textit{dsc} erstellt.

Diese Differenz-Datei ist darauf zu prüfen, dass sie keine unwichtigen 
Änderungen für die gewünschte Fehlerbehebung hat.

Anschließend wird mit dem Werkzeug \textit{reportbug} ein Fehlerbericht 
gegen das Paket \textit{release.debian.org} erstellt und die Differenz-Datei 
angehängt. Dieser Fehlerbericht enthält eine ausführliche Begründung für 
die Änderungen und Verweise auf Fehlernummern. Ebenso enthält sie eine 
prägnante Beschreibung des Problems, das behoben wurde.

Dabei sollte auf folgende Fragen eingegangen werden.

\begin{verbatim}
    Package: release.debian.org
User: release.debian.org@packages.debian.org
Usertags: unblock
Severity: normal

Please unblock package <source name>

(Please provide enough (but not too much) information to help
the release team to judge the request efficiently. E.g. by
filling in the sections below.)

[ Reason ]
(Explain what the reason for the unblock request is.)

[ Impact ]
(What is the impact for the user if the unblock isn't granted?)

[ Tests ]
(What automated or manual tests cover the affected code?)

[ Risks ]
(Discussion of the risks involved. E.g. code is trivial or
complex, key package vs leaf package, alternatives available.)

[ Checklist ]
  [ ] all changes are documented in the d/changelog
  [ ] I reviewed all changes and I approve them
  [ ] attach debdiff against the package in testing

[ Other info ]
(Anything else the release team should know.)
\end{verbatim}

\section{Releasekritische Fehler beheben}

Vor einer neue Veröffentlichung ist es oft notwendig, die Maintainer 
dabei zu unterstützen, Fehler zu beheben, die einer Veröffentlichung des 
Paketes entgegenstehen.

Dies geschieht häufig auf dafür organisierten Veranstaltungen
\footnote{\url{https://wiki.debian.org/BSP}}.

Unter

\scriptsize
\url{https://www.debian.org/doc/manuals/developers-reference/pkgs.html#non-maintainer-uploads-nmus}
\normalsize

ist das gewünschte Vorgehen beschrieben.

Wesentlich ist dabei, dass in der Datei \textit{debian/changelog} 
(Kapitel~\ref{sec:DebianChangelog}, Seite~\pageref{sec:DebianChangelog}) 
ein entsprechender Eintrag in der zweiten Zeile erfolgt.

\begin{verbatim}
    Non-maintainer upload
\end{verbatim}

\section{Paket aus Repositorien entfernen}

In der Developer-Reference \footnote{\cite{Debian-Entwicklerreferenz},
Abschnitt 5.9-Pakete entfernen}
wird auch beschrieben, wie ein Paket entfernt werden kann.

Dazu muss zunächst festgestellt werden, dass kein weiteres Paket dieses
als Abhängígkeit benötigt.

\subsection{Feststellung der Rückwärtsabhängigkeit}

Zu prüfen ist, ob andere Pakete das zu entfernende Paket benötigen. 

Überflüssig sind vor allem Bibliotheken, die von keiner Anwendung (mehr)
benötigt werden.

Die Prüfung kann mit

\begin{verbatim}
	apt-cache rdepends <Paketname>
\end{verbatim}

erfolgen. Als <Paketname> ist der Name des Binar-Paketes anzugeben.

\subsection{Fehlerbericht}

Für die Durchführung ist nun ein Fehlerbericht zu erstellen. Dieser wird
gegen das Pseudopaket \textit{ftp.debian.org} erstellt.
\footnote{s.~a.\cite{Debian-Entwicklerreferenz},
Abschnitt 5.9-Pakete entfernen}

\chapter{Autopkgtest}

\chapter{Lintian-Meldungen}
\label{chap:LintianMessages}

Das Ergebnis des Bauens eines \texttt{Debian}-Paketes wird mit
\textit{lintian} überprüft (Kapitel~\ref{sec:RunningLintian}, 
Seite~\pageref{sec:RunningLintian}).

Es gibt ein User's Manual zu \texttt{Lintian}, das auch im Paket
\textit{lintian} als Datei \textit{lintian.rst} (in englischer Sprache)
vorliegt\cite{LintianUserManual2023}.

Hierbei wird der Maintainer oft mit Fehlermeldungen konfrontiert.

Ein vollständiges Verzeichnis der möglichen Meldungen befindet sich unter 
\url{https://udd.debian.org/lintian-tag.cgi}.

Eine Liste aller Fehlermeldungen erhält man auch im Terminal:

\begin{verbatim}
    lintian-explain-tags --list-tags | less
\end{verbatim}

Die Erläuterung zu einer einzelnen Fehlermeldung erhält man mit

\begin{verbatim}
    lintian-explain-tags <Lintian message>
\end{verbatim}

Nachstehend einige Beispiele:

\begin{description}
\item[bad-jar-name] Der Name entspricht nicht den Richtlinien der
\texttt{Java}-Policy.
\footnote{Kapitel 2.4 der \texttt{Java}-Policy\cite{JavaPolicy}}
\item[codeless-jar] Die *.jar Datei enthält keinen kompilierten 
\texttt{Java}-Code.
\item[empty-binary-package] Das gebaute Paket ist leer.
\item[javalib-but-no-public-jars] Im Verzeichnis \textit{/usr/share/java/} 
gibt es kein \textit{*.jar}-Archiv. Dann fehlt in der Regel der Eintrag 
\textit{--java-lib} in der entsprechenden Datei
\textit{debian/<paketname.poms}.
\item[new-package-should-close-itp-bug] In der Datei 
\textit{debian/changelog} ist der ITP-Bug zu schließen 
(Closes: \#nnnnnn)
\item[rules-requires-root-missing] In die Datei 
\textit{debian/control} wird im ersten Abschnitt der Eintrag 
\textit{Rules-Requires-Root: no} benötigt.
\item[wildcard-matches-nothing-in-dep5-copyright]
\item[backports-changes-missing]
\item[out-of-date-standard]
\item[testsuite-autopkgtest-missing]

\end{description}

Ein Werkzeug zur automatischen Fehlerbehebung ist \textit{lintian-brush}.
Dieses Programm befindet sich im gleichnamigen Paket. Allerdings enthält
es Skripte für nur etwas mehr als 10 \% der möglichen Meldungen.

Mit \textit{lintian-brush -{}-list-tags} kann ermittelt werden, welche
Korrekturskripte zur Verfügung stehen. 

\chapter{Reproduzierbare Builds}
\label{chap:ReproducibleBuilds}


\section{reprotest}

\chapter{piuparts}