File: Part3.nw

package info (click to toggle)
dpb 0.9.9
links: PTS, VCS
area: main
in suites: sid, trixie
size: 11,344 kB
sloc: sh: 77; makefile: 19
file content (10504 lines) | stat: -rw-r--r-- 315,722 bytes
% !TEX root = BuildWithGBP.nw
\part{Wie ein Shell-Skript hilft, ein \texttt{Debian}-Paket zu bauen}

\chapter{Erste Schritte im Programmskript}
\label{chap:FirstSteps}

Bevor die Arbeit mit dem Programmskript starten kann, werden noch zwei
Dinge benötigt:

\begin{itemize}
	\item ein Account auf \url{https://salsa.debian.org} und
	\item ein GPG-Schlüssel zum Signieren der Pakete.
\end{itemize}

Der Fingerprint des zu verwendenden Schlüssels sollte in der Datei 
\textit{\textasciitilde/.debian\_projekt/fingerprint} abgelegt werden.

Nun geht es mit dem Programmskript\index{Programmskript} los. 
Dieses hilft beim Bauen eines 
\texttt{Debian}-Paketes und unterstützt das Hochladen desselben. Dabei 
gibt der Programmablauf\index{Programmablauf} eine zweckmäßige Reihenfolge 
der notwendigen Schritte vor. Das Programmskript baut also keine 
\texttt{Debian}-Pakete, sondern unterstützt als Assistent den Maintainer. 
Hierauf wird im Eingangsdialog auch ausdrücklich hingewiesen.
(Kapitel~\ref{sec:Intro}, Seite~\pageref{sec:Intro})

Voraussetzung ist, dass alle benötigten Pakete installiert und das System
entsprechend eingerichtet ist (Kapitel~\ref{chap:SystemSetup}, 
Seite~\pageref{chap:SystemSetup}).

Das Programmskript ist modular aufgebaut, sodass man an vielen Stellen 
\enquote{aussteigen} und später wieder \enquote{einsteigen} kann. 
Man muss also den Bauprozess nicht immer bis zum Abschluss \enquote{in einem 
Zug} durchführen.

Der für den Nutzer sichtbare Programmablauf beginnt in jedem Fall mit 
einem Startdialog\index{Startdialog} (Kapitel~\ref{sec:Intro},
Seite~\pageref{sec:Intro}).

Das Bauen eines neuen \texttt{Debian}-Paketes erfordert zunächst die 
Anlage eines neuen Projektes (Kapitel~\ref{chap:CreateNewProject}, 
Seite~\pageref{chap:CreateNewProject}).

Alle nachfolgende Punkte werden zumindest im Wesentlichen vom
Programmskript erledigt.

\begin{description}
  \item[Konfigurationsdatei] Das Programm benötigt eine \index{Konfigurationsdatei} 
  Konfigurationsdatei (Kapitel~\ref{sec:ConfigFileCreate}, 
  Seite~\pageref{sec:ConfigFileCreate}), die zunächst vom Programmskript 
  angelegt wird. Diese kann jederzeit geändert werden.
  \item[Systemeinrichtung] Um ein \texttt{Debian}-Paket zu bauen, müssen 
  unter anderem folgende vorbereitende Aufgaben erfüllt werden:

  \begin{description}
  \item[Bereitstellung der benötigten Verzeichnisse] Die Erstellung der 
  Verzeichnisse wird in Kapitel~\ref{subsec:AnlegenVerzeichnisse}, 
  (Seite~\pageref{subsec:AnlegenVerzeichnisse}) beschrieben. 
  \item[Einrichten eines Git-Repositoriums] Die Einrichtung des lokalen 
  Git"=Repositoriums (Kapitel~\ref{sec:LokalesGitRepoAnlegen}, 
  Seite~\pageref{sec:LokalesGitRepoAnlegen}) 
  muss vor der Ausführung von \textit{gbp import-orig}
  (Kapitel~\ref{subsec:GbpImportOrig}, Seite~\pageref{subsec:GbpImportOrig}) 
  erfolgen. 
  \end{description}

  \item[Bereitstellung des Quellcodes] Dies wird in 
  Kapitel~\ref{sec:DownloadTools}, 
  Seite~\pageref{sec:DownloadTools} beschrieben.
  \item[Bereitstellung der benötigten Dateien im Verzeichnis 
  \textit{debian/}] Die Erzeugung der Dateien im Verzeichnis \textit{debian/}
  erfolgt im Rahmen des Bauens der \texttt{Debian}-Revision 
  (Kapitel~\ref{chap:NeueRevisionBauen},
  Seite~\pageref{chap:NeueRevisionBauen}).
  \item[Bauen] Dies wird in Kapitel~\ref{chap:Bauen},
  Seite~\pageref{chap:Bauen} beschrieben
  \item[Testen -- soweit wie möglich] Dies wird in Kapitel~\ref{chap:Ueberpruefungen},
  Seite~\pageref{chap:Ueberpruefungen} beschrieben.
  \item[Hochladen] Dies wird in Kapitel~\ref{chap:UploadPackage},
  Seite~\pageref{chap:UploadPackage} beschrieben.
\end{description}

Bis zum Hochladen ist es ein langer Weg. Doch auch der längste Weg
beginnt bekanntlich mit dem ersten Schritt. Dabei ist noch zu beachten,
dass das Programmskript tastaturbetont (mit der TAB-Taste) bedient
wird. Eine Steuerung mit der Maus kann zu unerwarteten Effekten führen.

\section{Der Anfang steht am Schluss}
\label{sec:Hauptprogramm}

Das Programmskript enthält viele Funktionen.

Das Hauptprogramm\index{Hauptprogramm} ruft lediglich die Funktion 
\textit{BuildApp} auf. Es steht am Ende des Programmskriptes.

<<MainProgram>>=
##############
# Here it starts
BuildApp

############## 
# This is the end, my friend
@

\section{Und das sieht der Nutzer als Erstes}
\label{sec:Intro}

Die Funktion \textit{BuildApp} steuert den Programmablauf\index{Programmablauf} 
im Wesentlichen durch den Aufruf weiterer Funktionen. 

Sie stellt dem Nutzer als Erstes das Programm vor.

<<BuildApp>>=
function BuildApp {
    # Called by main program

    ##############

    # Intro

    ##############

    intro="Assistant to build simple Debian packages\nusing git-buildpackage\n
Authors: Mechtilde Stehmann\n
         Michael Stehmann\n
Version: 0.9.9\n
License: GPL v3+\n
This program does not build Debian packages itself.
It is only an assistant for the package maintainer."

    whiptail --title "Introduction" --msgbox "$intro" 20 60

<<BuildApp3>>
@

Dazu erscheint der folgende Begrüßungsdialog.

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex,keepaspectratio]{Pictures/Intro.png} 
\caption{Startbildschirm}
\end{figure}

Danach fragt diese Funktion den Namen des entsprechenden 
Projektes\index{Projekt} mit der Funktion 
\textit{AskOrigName} ab (Kapitel~\ref{sec:ProjektnamenAbfragen}, 
Seite~\pageref{sec:ProjektnamenAbfragen}).

<<BuildApp3>>=
    # Definitions of Project
    AskOrigName
    CreateDirsAndLogFile

    # Flag for additional gbp buildpackage options
    OptFlag=0

    ##############

    # End of intro

<<BuildApp7>>
@

Schließlich prüft diese Funktion \textit{BuildApp} das Vorhandensein der 
notwendigen  lokalen Infrastruktur (Konfigurationsdatei 
(Kapitel~\ref{sec:ConfigFileCreate}, 
Seite~\pageref{sec:ConfigFileCreate}), Verzeichnisse 
(Kapitel~\ref{subsec:AnlegenVerzeichnisse}, 
Seite~\pageref{subsec:AnlegenVerzeichnisse}), 
Git-Repositorium (Kapitel~\ref{sec:AuswahlGitBranch}, 
Seite~\pageref{sec:AuswahlGitBranch})) und sorgt gegebenenfalls für deren Anlage. 

\section{Projektname abfragen}
\label{sec:ProjektnamenAbfragen}

Es wird nun der Projektname\index{Projektname} eines existierenden Projektes 
abgefragt oder für ein neues Projekt festgelegt. Das Einfügen des 
Projektnamens kann auch per \textit{Copy \& Paste} erfolgen. Diese 
Möglichkeit ist eine Besonderheit von \textit{whiptail}.

<<AskOrigName>>=
function AskOrigName {
    # Called by BuildApp ConfigFileLEC and itself
    
    # Name of the project (without this name the app cannot work)
    OrigName=$(whiptail --title "This name is required!" \
    --inputbox "Name of the project:" \
    --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
<<AskOrigName1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em]{Pictures/ProjectName.png}
\caption{Angabe des Projektnamens.}
\end{figure}

Eine \textit{whiptail -{}-inputbox} erfordert Umleitungen der Ausgabe unter 
Verwendung von Dateibezeichnern (\texttt{3>\&2 2>\&1 1>\&3}).

<<AskOrigName1>>=
    if [ $? -ne 0 ]
    then
        whiptail --title "Bye" --msgbox "Bye" 15 60
        exit
    fi

<<AskOrigName2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em]{Pictures/bye.png}
\caption{Bye}
\end{figure}

Nur die ersten drei Dateibezeichner (beginnend mit 0) haben eine 
standardisierte Bedeutung:
\begin{itemize}
 \item{0 - stdin ~- Standard-Eingabe}
 \item{1 - stdout - Standard-Ausgabe}
 \item{2 - stderr ~- Standard-Fehleranzeige}
\end{itemize}

Wenn das Projekt bereits existiert, geht es mit der Anzeige der 
Konfigurationsdatei (Kapitel~\ref{sec:ConfigFileLaden}, 
Seite~\pageref{sec:ConfigFileLaden}), der Auswahl eines Git-Zweiges  
(Kapitel~\ref{sec:AuswahlGitBranch}, 
Seite~\pageref{sec:AuswahlGitBranch}) und dann der Aufgabenauswahl 
(Kapitel~\ref{sec:Aufgabenauswahl}, 
Seite~\pageref{sec:Aufgabenauswahl}) weiter.

Wird \textbf{kein} Projektname eingegeben, erfolgt ein Hinweis. Die 
Eingabe eines Projektnamens ist zwingend erforderlich. Mit \textit{Exit} 
wird das Programm abgebrochen.

<<AskOrigName2>>=
    if [ -z "${OrigName}" ]
    then
        whiptail --title "No project name" \
        --msgbox "You have to identify a project name\n \
        even it is a new project!" 15 60
        AskOrigName
    fi
    ConfigFileLEC
}

<<BuildApp>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em]{Pictures/NoProjectName.png}
\caption{Kein Projektname angegeben.}
\end{figure}

Nach der Bestätigung von \textit{OK} wird erneut der Eingabedialog angezeigt.

\section{Weiterer Ablauf}

Der weitere Ablauf hängt nun davon ab, ob schon eine 
Konfigurationsdatei\index{Konfigurationsdatei} für das Projekt, wie in 
Kapitel~\ref{subsubsec:KonfigProjekt}, 
Seite~\pageref{subsubsec:KonfigProjekt} beschrieben, existiert.

In diesem Fall wird diese \enquote{geladen} (Kapitel~\ref{sec:ConfigFileLaden}, 
Seite~\pageref{sec:ConfigFileLaden}).

Andernfalls wird die Konfigurationsdatei neu angelegt.

\chapter{Anlegen eines neuen Projektes}
\label{chap:CreateNewProject}

Zur Anlage eines neuen Projektes werden zunächst die Konfigurationsdatei 
erstellt und die notwendige Infrastruktur angelegt.

\section{Konfigurationsdatei erstellen}
\label{sec:ConfigFileCreate}

Die Konfigurationsdatei wird im Homeverzeichnis \index{Homeverzeichnis}
des Nutzers im Verzeichnis \textit{.debian\_project/} als Datei
\textit{<Projektname>} gespeichert. 

<<ConfigFileLEC>>=
function ConfigFileLEC {
    # Called by AskOrigName CreateNewBranch TaskSelect OwnServer

    ## Load, edit or create config file - using AskConfig

    # Path to config files directory
    ConfigPath=~/.debian_project/
    changeflag=0

<<ConfigFileLEC1>>
@

Die Funktion \textit{ConfigFileLEC} prüft zunächst, ob eine 
Konfigurationsdatei mit dem Projektnamen vorhanden ist. Ist das Ergebnis 
der Prüfung negativ, erfolgt die Meldung, dass keine Konfigurationsdatei 
mit diesem Namen gefunden werden konnte. 

<<ConfigFileLEC4>>=
    else
        if whiptail --title "Config file not found" \
        --yesno "There is no config file for ${OrigName}\n \
        which you can edit.\n \
        Do you want to create a new project?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            changeflag=1
<<ConfigFileLEC5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=22em]{Pictures/NoConfigFileFound.png}
\caption{Keine Konfigurationsdatei gefunden.}
\end{figure}

Ein \textit{whiptail --yesno} gibt 0 bzw true zurück, wenn die Frage 
bejaht wird, und 1 bzw false, wenn sie verneint wird.

Wird diese Frage bejaht, wird vorsorglich auch das 
Verzeichnis \textit{.debian\_project} als \textit{ConfigPath}, sofern 
noch nicht vorhanden, angelegt.
Dann wird die Funktion \textit{AskConfig} aufgerufen, mit der die 
Konfigurationsdatei erstellt wird.

<<ConfigFileLEC5>>=
            mkdir --parents ${ConfigPath}
            AskConfig
        else
            AskOrigName
        fi
    fi
    set -e
}

<<CreateDirsAndLogfile>>
@

Die Abfrage, ob ein neues Projekt erstellt werden soll, ermöglicht dem 
Nutzer, Tippfehler bei der Eingabe des Projektnamens zu korrigieren, 
wenn er sie verneint.

In den folgenden Abschnitten werden die in der Konfigurationsdatei 
enthaltenen Variablen besprochen. 
Zunächst folgen die Variablen, die für alle Pakete erforderlich sind. 
Danach folgen die Variablen. die nur für jeweils eine Gruppe von Paketen 
benötigt werden (für \texttt{Java}-Pakete s. Kapitel~\ref{subsubsec:ParameterJava}, 
Seite~\pageref{subsubsec:ParameterJava}, für \textit{webext}-Pakete s. 
Kapitel~\ref{subsubsec:ParameterWebext}, Seite~\pageref{subsubsec:ParameterWebext}).

\subsection{Abfrage allgemeiner Variablen für die Konfigurationsdatei}
\label{subsec:AskConfig}

Die Funktion \textit{AskConfig} ordnet in ihrem ersten Teil den Variablen, 
die in der Konfigurationsdatei enthalten sein sollen, Werte zu. 
Dies geschieht durch die Abfrage der einzelnen Variablen. Das 
Speichern der Konfigurationsdatei wird dann in Kapitel~\ref{subsec:SaveConfig}, 
Seite~\pageref{subsec:SaveConfig} beschrieben.

Es wird geprüft, ob der jeweiligen Variablen ein Wert zugewiesen wurde. 

Dies geschieht als Erstes für den Namen des Quellpaketes, welcher als 
Wert der Veriablen \textit{SourceName} zugewiesen wird.

Der Name des Quellpaketes ist der Name, den das Upstream-Projekt seiner 
Software gegeben hat.

<<AskConfig>>=
function AskConfig {
    # Called by ConfigFileLEC

    if [ -z "${SourceName}" ]
    then
        SourceName=$(whiptail --title "Source Package Name" \
        --inputbox "Name of the source package:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

        if [ $? -ne 0 ] # Cancel-Button was pressed
        then
            exit
        else
            changeflag=1
        fi
    fi

<<AskConfig1>>
@
\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SourceName.png}
\caption{Name des Quellcode-Paketes}
\end{figure}


Enthält die Variable einen Wert, wird gefragt, ob dies der richtige Wert 
sei. 
Dies dient zum Einen der Kontrolle der vorherigen Eingabe und zum Anderen 
eröffnet dies die Möglichkeit des Editierens 
(Kapitel~\ref{sec:ConfigFileLaden}, Seite~\pageref{sec:ConfigFileLaden})
der Konfigurationsdatei mittels der Funktion \textit{AskConfig}.

<<AskConfig1>>=
    if ! whiptail --title "Source Package Name" \
    --yesno "The name of the source package is ${SourceName}" \
    --yes-button "Yes" --no-button "No" 15 60
<<AskConfig2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SourcePackageName.png}
\caption{Namen des Quellpaketes angeben}
\end{figure}

<<AskConfig2>>=
    then
        SourceName=$(whiptail --title "Name of the source package" \
        --inputbox "Real name of the source package:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

        if [ ${#SourceName} -eq 0 -o $? -ne 0 ]
        then
            exit
        else
            changeflag=1
        fi
    fi

<<AskConfig3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RealSourceName.png}
\caption{Korrekten Namen des Quellpaketes angeben}
\end{figure}

Nun wird der Name des zu bauenden Paketes ermittelt. Dafür wird der
Variablen \textit{PackName}, wenn sie noch nicht existiert, der Wert der
Variablen \textit{SourceName} als Standardwert zugewiesen. Auch hierzu
wird eine Bestätigung abgefragt und eine Korrekturmöglichkeit eröffnet.

<<AskConfig3>>=
    if [ -z "${PackName}" ]
    then
        PackName=${SourceName}
        tadd=", too?"
    else
        tadd="?"
    fi

    if ! whiptail --title "PackName" \
    --yesno "The name of the package is ${PackName}${tadd}" \
    --yes-button "Yes" --no-button "No" 15 60
<<AskConfig3-1>>
@

Wenn die Variable \textit{PackName} noch nicht existierte:

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PackageName.png}
\caption{Ist der Paketname korrekt?}
\end{figure}

Wenn die Variable \textit{PackName} bereits existierte:

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PackageName1.png}
\caption{Ist der Paketname korrekt?}
\end{figure}

<<AskConfig3-1>>=
    then
        PackName=$(whiptail --title "Name of the Debian Package" \
        --inputbox "Real name of the package,\nwhich should be built from ${SourceName}:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

        if [ ${#PackName} -eq 0 -o $? -ne 0 ]
        then
            exit
        else
            changeflag=1
        fi
    fi

<<AskConfig4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RealPackageName.png}
\caption{Korrekten Name des Paketes angegeben.}
\end{figure}

Nun wird der Name der Gruppe abgefragt, unter welcher das Git-Reposi\-torium 
auf \textit{salsa.debian.org} angelegt werden soll.

<<AskConfig4>>=
    if [ -z "${SalsaName}" ]
    then
        SalsaName=$(whiptail --title "Group at Salsa" \
        --inputbox "Group on salsa.debian.org:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
        if [ $? -ne 0 ] # Cancel-Button was pressed
        then
            exit
        else
            SalsaName=${SalsaName}"/"${SourceName}".git"
        fi
    fi

<<AskConfig5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SalsaGroup.png}
\caption{Name der Gruppe auf \textit{salsa.debian.org} angegeben.}
\end{figure}

Es gibt verschiedene Paketier-Teams (beispielsweise für \texttt{Java}- 
oder \texttt{Py\-thon}-Pa\-kete)\footnote{
\url{https://wiki.debian.org/Teams\#Packaging_teams}}.

Beim \texttt{Python}-Team muss zusätzlich das Verzeichnis \textit{packages} 
angegeben werden, also \textit{python-team/packages}.

Diese Teams verfügen über eigene Gruppen auf \textit{salsa.debian.org}.
Mit \url{https://salsa.debian.org/explore/groups} können alle öffentlichen
Gruppen angezeigt werden.

Soll ein Paket unabhängig von einem Paketier-Team betreut werden, ist als 
Gruppe \textit{Debian} einzutragen.

<<AskConfig5>>=
    if ! whiptail --title "Salsa Name" \
    --yesno "Group and project name of the repo on salsa.debian.org is $SalsaName" \
    --yes-button "Yes" --no-button "No" 15 60
<<AskConfig5-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SalsaGroupRepo.png}
\caption{Name der Gruppe auf \textit{salsa.debian.org} angegeben.}
\end{figure}

<<AskConfig5-1>>=
    then
        SalsaName=$(whiptail --title "Salsa Group and Project Name" \
        --inputbox "Real group and project name of the repo on salsa.debian.org:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

<<AskConfig5-2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SalsaGroupRepoReal.png}
\caption{Name der Gruppe auf \textit{salsa.debian.org} angegeben.}
\end{figure}

<<AskConfig5-2>>=
        if [ ${#SalsaName} -eq 0 -o $? -ne 0 ]
        then
            exit
        else
            changeflag=1
        fi
    fi

<<AskConfig6>>
@

Es wird nun geprüft, ob im Verzeichnis 
\textit{\textasciitilde/.debian\_project} eine Datei 
\textit{DefaultValues} existiert. In dieser Datei werden Variablen Werte 
zugewiesen, die für viele Projekte gelten 
(Kapitel~\ref{subsubsec:DefaultValues}, 
Seite~\pageref{subsubsec:DefaultValues}). Das Skript \textit{DefaultValues} 
wird dann ausgeführt.

<<AskConfig6>>=
    if [ -f ${ConfigPath}/DefaultValues ]
    then
        . ${ConfigPath}/DefaultValues
    fi

<<AskConfig7>>
@

Der Variablen \textit{DefaultProjectPath} ist als Wert der Pfad 
zugewiesen, welcher zu dem Verzeichnis führt, das die einzelnen 
Projektverzeichnisse als Unterverzeichnisse enthält.

<<AskConfig7>>=
    if [ -n "${DefaultProjectPath}" ]
    then
        ProjectPath=${DefaultProjectPath}
    fi

    if [ -z "${ProjectPath}" ]
    then
        ProjectPath=$(whiptail --title "Path to Project Directory" \
        --inputbox "Path to the project directory on your local machine\n \
        (without '/${OrigName}':)" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<AskConfig8>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PathProjectDir.png}
\caption{Pfad zum Projektverzeichnis auf der lokalen Maschine}
\end{figure}

<<AskConfig8>>=

        if [ -z "${ProjectPath}" ]
        then
            echo -e "Path to the project directory on your local machine\n \
            (without '/${OrigName}':)"
            read ProjectPath
        fi
        changeflag=1
    fi

    if ! whiptail --title "ProjectPath" \
    --yesno "Path to the project directory on your local machine \
    is ${ProjectPath}/${OrigName}" \
    --yes-button "Yes" --no-button "No" 15 60

<<AskConfig9>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PathProjectDirOrigName.png}
\caption{Pfad zum Projektverzeichnis auf der lokalen Maschine mit OrigName}
\end{figure}

<<AskConfig9>>=
    then
        ProjectPath=$(whiptail --title "Path to Project Directory" \
        --inputbox "Real path to the project directory on your local machine\n \
        (without '/${OrigName}':" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<AskConfig9-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RealPathProjectDir.png}
\caption{Pfad zum Projektverzeichnis auf der lokalen Maschine (real)}
\end{figure}

<<AskConfig9-1>>=
        if [ -z "${ProjectPath}" ]
        then
            echo -e "Path to the project directory on your local machine\n \
            (without '/${OrigName}':)"
            read ProjectPath
        fi
        if [ -z "${ProjectPath}" ]
        then
            exit
        else
            changeflag=1
        fi
    fi

<<AskConfig10>>
@

\subsection{Abfrage spezieller Variablen für die Konfigurationsdatei}

Nun werden die Variablen ermittelt, die nur für spezielle Arten von 
Paketen benötigt werden. Begonnen wird mit den Variablen für 
\texttt{Java}-Paketen (Kapitel~\ref{subsubsec:ParameterJava}, 
Seite~\pageref{subsubsec:ParameterJava})

Außerdem wird gegebenenfalls in die 
Konfigurationsdatei der Pfad zu einem benötigten Plugin eingetragen.

\subsubsection{Ermittlung der Plugin-Pfade}
\label{subsubsec:DetectPlugins}

Bestimmte Arten von Paketen werden unter Verwendung von Plugins zum 
(Haupt-)Skript gebaut. Es handelt sich hierbei um Pakete, die mit
\texttt{Java}, \textit{maven} gebaut werden, um
\texttt{Mozilla}-Erweiterungen und \texttt{Python}-Programme.

Die Funktion \textit{DetectPlugins} ermittelt die Pfade zu 
Plugin-Skriptda\-teien. Sie kann für weitere Plugins verwendet werden.
Sie wird derzeit nicht benutzt.

Beim Aufruf von \textit{DetectPlugins} müssen zwei Optionen übergeben 
werden. Dabei wird die erste Option (\textit{\$1}) an \textit{PluginName} 
und die zweite (\textit{\$2}) an \textit{PluginFile} übergeben.

<<DetectPlugins>>=
function DetectPlugins {
    # Not Used.
    # Funktion to find Plugins

    # This function needs two options: the name of the plugin
    # and the name of the plugin script file
    PluginName=$1
    PluginFile=$2

    # Determine path to the (needed) plugin script
    PluginPathL=$(locate ${PluginFile})
    PluginPathA=(${PluginPathL})

    # If there is only one result
    if [ ${#PluginPathA[@]} -eq 1 ]
    then
        PluginPath=${PluginPathA[0]}
    # If there are some results    
    elif [ ${#PluginPathA[@]} -gt 1 ]
    then            
        i=0; slct=''
        for element in ${PluginPathA[*]}
        do
            slct=$slct' '$i' '${element}' off '
            i=$(expr $i + 1)
        done

        PluginNr=$(whiptail --title "${PluginName} plugin found" \
        --radiolist "Select:" 15 60 5 $slct \
        --cancel-button "Cancel" 3>&2 2>&1 1>&3)

<<DetectPlugins3>>
@

% ToDo Exit ausarbeiten

<<DetectPlugins3>>=
        if [  $? -eq 1 ]
        then
            return 24
        fi

        PluginPath=${PluginPathA[${PluginNr}]}
    # If there is no result
    else 
        PluginFlag=0
        whiptail --title "File not found" \
        --msgbox "'${PluginFile}' was not located!" \
        15 60
        return 24
    fi
}

<<AskConfig>>
@

\subsubsection{Variablenabfrage für \texttt{Java}-Pakete}
\label{subsubsec:ParameterJava}

Bestimmte Arten von Paketen erfordern eine spezielle Behandlung. Diese 
erfolgt unter anderem durch separate Skripte. Diese Behandlung wird durch 
\enquote{flags} gesteuert. Damit wird auch ein unnötiges Laden der 
Plugin-Skripte vermieden.

<<AskConfig10>>=
    # Java Flag
    # This is needed to trigger special entries
    # in debian/control and debian/rules
    if [ -z "${JavaFlag}" ]
    then
        if whiptail --title "Java" --defaultno \
        --yesno "Do you want to build a Java package?" \
        --yes-button "Yes" --no-button "No" --defaultno 15 60
<<AskConfig10-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildJavaPackage.png}
\caption{Soll ein \texttt{Java}-Paket gebaut werden?}
\end{figure}

<<AskConfig10-1>>=
        then
            JavaFlag=1
        else
            JavaFlag=0
        fi
        changeflag=1
    fi

<<AskConfig11>>
@

Abgefragt wird auch, ob das Maven-Plugin (Kapitel~\ref{chap:MavenPlugin}, 
Seite~\pageref{chap:MavenPlugin}) verwendet werden 
soll. Dieses wird dann im System lokalisiert und der Pfad zum Skript in 
der Konfigurationsdatei hinterlegt.

<<AskConfig11>>=
    # Maven Plugin
    if [ ${JavaFlag} -eq 1 ]
    then
        if [ -z "${MavenPluginFlag}" ]
        then
            if whiptail --title "Maven" --defaultno \
            --yesno "Should the (Java) package be built with maven?" \
            --yes-button "Yes" --no-button "No" --defaultno 15 60
<<AskConfig12>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildJavaMavenPackage.png}
\caption{Soll ein \texttt{Java}-Paket mit \textit{maven} gebaut werden?}
\end{figure}

<<AskConfig12>>=

            then
                MavenPluginFlag=1
            else
                MavenPluginFlag=0
            fi
            changeflag=1
        fi
    fi

<<AskConfig15>>
@

Beim Aufruf von \textit{DetectPlugins} müssen zwei Optionen übergeben 
werden. Dabei wird \textit{'Maven'} als \textit{\$1} an die Variable 
\textit{PluginName} und \textit{build-gbp-maven-plugin.sh} als 
\textit{\$2} an die Variable \textit{PluginFile} übergeben 
(s. Kapitel~\ref{subsubsec:DetectPlugins}, 
Seite~\pageref{subsubsec:DetectPlugins}).

\subsubsection{Variablenabfrage für \texttt{Mozilla}-Erweiterungen}
\label{subsubsec:ParameterWebext}

%Todo. Beschreibung fehlt noch

<<AskConfig15>>=
    # Webext Flag
    # This is needed to trigger special entries
    # in debian/control and debian/rules
    if [ -z "${WebextFlag}" ]
    then
        if whiptail --title "Mozilla AddOns" --defaultno \
        --yesno "Do you want to build a Mozilla AddOn package?" \
        --yes-button "Yes" --no-button "No" --defaultno 15 60
<<AskConfig15-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildMozillaAddOn.png}
\caption{Soll eine Erweiterung für Mozilla paketiert werden?.}
\end{figure}

<<AskConfig15-1>>=
        then
            WebextFlag=1
        else
            WebextFlag=0
        fi
        changeflag=1
    fi

<<AskConfig18>>
@

\subsubsection{Variablenabfrage für \texttt{Python3}-Pakete}
\label{subsubsec:ParameterPython}

Auch für das Paketieren von \texttt{Python-Paketen} kann auf ein 
entsprechendes Plugin zurückgegriffen werden. Dafür werden zunächst die 
benötigten Informationen abgefragt und in die Konfigurationsdatei 
eingetragen.

<<AskConfig18>>=
    # Python Flag
    # This is needed to trigger special entries
    # in debian/control and debian/rules
    if [ -z "${PythonFlag}" ]
    then
        if whiptail --title "Python3 programs" --defaultno \
        --yesno "Do you want to build a Python3 package?" \
        --yes-button "Yes" --no-button "No" --defaultno 15 60
<<AskConfig19>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildPythonPackage.png}
\caption{Soll ein \texttt{Python}3-Paket gebaut werden?.}
\end{figure}

<<AskConfig19>>=
        then
            PythonFlag=1
        else
            PythonFlag=0
        fi
        changeflag=1
    fi

<<AskConfig20>>
@

\subsection{Speichern der Konfiguration}
\label{subsec:SaveConfig}

Das (Neu-)Erstellen der Konfigurationsdatei geschieht im folgenden Teil 
der Funktion \textit{AskConfig}.

Es wird zunächst geprüft, ob bereits eine Konfigurationsdatei für das 
Projekt existiert. Sofern vorhanden wird sie gelöscht.

Die Konfigurationsdatei ist ein Shell-Skript. Sie beginnt daher mit einer
entsprechenden \textit{Shebang}.

<<AskConfig20>>=
    if [ $changeflag -eq 1 ]
    then
        if [ -f ${ConfigPath}${OrigName} ]
        then
            rm ${ConfigPath}${OrigName}
        fi
        touch ${ConfigPath}${OrigName}

        # Shebang of the config file 
        SB='#!/usr/bin/bash'

        # The config file is a shell script
        echo ${SB} >> ${ConfigPath}${OrigName}
        echo '# ConfigFile for '${OrigName} >> ${ConfigPath}${OrigName}
        echo '## General parameters' >> ${ConfigPath}${OrigName}
        echo 'SourceName='${SourceName} >> ${ConfigPath}${OrigName}
        echo 'PackName='${PackName} >> ${ConfigPath}${OrigName}
        echo 'ProjectPath='${ProjectPath} >> ${ConfigPath}${OrigName}
        echo 'SalsaName='${SalsaName} >> ${ConfigPath}${OrigName}
<<AskConfig22>>
@

Die folgenden Einträge in der Konfigurationsdatei werden nur erstellt, 
wenn entsprechende Flags gesetzt wurden. Dies gilt für \texttt{Java}-Pakete. 
Ein zusätzlicher Eintrag erfolgt, wenn sie mit \textit{maven} gebaut werden. 
Dies gilt auch für die Erweiterungen für \texttt{Firefox} und 
\texttt{Thunderbird} und Programme in der Programmiersprache \texttt{Python}.

<<AskConfig22>>=
        echo '## Parameters for Java packages'>> ${ConfigPath}${OrigName}
        echo 'JavaFlag='${JavaFlag} >> ${ConfigPath}${OrigName}
        if [ ${JavaFlag} -eq 1 ]
        then
            echo 'MavenPluginFlag='${MavenPluginFlag} >> ${ConfigPath}${OrigName}
        fi

        echo '## Parameters for Webext packages'>> ${ConfigPath}${OrigName}
        echo 'WebextFlag='${WebextFlag} >> ${ConfigPath}${OrigName}

        echo '## Parameters for Python3 packages'>> ${ConfigPath}${OrigName}
        echo 'PythonFlag='${PythonFlag} >> ${ConfigPath}${OrigName}s
        changeflag=0
    fi
}

<<ReplaceTilde>>
@

Da beim Ablauf des Skriptes die Tilde (\textasciitilde) im Pfad nicht 
automatisch durch \textit{/home/<username>} ersetzt wird, muss dies 
durch eine Funktion \textit{ReplaceTilde} im Programmskript geschehen. 
Ferner wird ein eventueller Slash (/) am Ende des Pfades entfernt.

<<ReplaceTilde>>=
function ReplaceTilde {
    # Called by ConfigFileLEC GbpConfIntegration 
    RecentUser=$(whoami)
    set +e
    tp=$(echo ${SuspectPath} | grep --count '^~')
    if [ $tp -ge 1 ]
    then
        CleanPath=$(echo ${SuspectPath} | \
        sed --expression="s/^~/\/home\/${RecentUser}/g")
    else
        CleanPath=${SuspectPath}
    fi

    # Replace / at the end
    CleanPath=$(echo ${CleanPath} | sed --expression="s/\/$//")
    set -e
}

<<SetDefaults>>
@

\subsection{Beispiel einer Konfigurationsdatei}

\begin{verbatim}
    #!/usr/bin/bash
    # ConfigFile for <OrigName>
    ## General parameters
    SourceName=<SourceName>
    PackName=<PackName>
    ProjectPath=/home/mechtilde/Projekte/Git/01_Salsa
    SalsaName=<Name of the team>/<SourceName>.git
    ## Parameters for Java packages
    JavaFlag=0
    ## Parameters for Webext packages
    WebextFlag=0
    ## Parameters for Python3 packages
    PythonFlag=0
    RecentBranch=debian/sid
    ## Maintainer and Uploaders
    Maintainer=<Name and E-Mail-Address of the Maintainer>
    Uploaders=<Name and E-Mail-Address of the Uploaders>
    ## Download from upstream
    DownloadURL=<Upstream URL for download>
    RecentUpstreamSuffix=.xpi
    # debian/sid_Dist=sid

\end{verbatim}

\section{Anlegen der Infrastruktur}

Zur Infrastruktur jedes Projektes gehören Verzeichnisse, eine Log-Datei 
und ein Git-Repositorium. Sofern diese nicht bereits vorhanden sind, 
werden die notwendigen Verzeichnisse\index{Verzeichnis} und die 
Log-Datei\index{Log-Datei} angelegt.

Zur Infrastruktur gehören auch ein \textit{Chroot}-Verzeichnis 
\textit{base.cow} oder ein \textit{Sbuild-Chroot}-Verzeichnis. Diese 
werden nur angelegt, wenn sie für die Distribution, für die das Paket 
gebaut werden soll, noch nicht existieren.
%(Kapitel~\ref{sec:ChangeRoot}, Seite~\pageref{sec:ChangeRoot})

\subsection{Anlegen der notwendigen Verzeichnisse}
\label{subsec:AnlegenVerzeichnisse}

Zunächst werden die zuvor definierten Pfade 
(Kapitel~\ref{subsec:PathDefinition}, 
Seite~\pageref{subsec:PathDefinition}) angelegt.

<<CreateDirsAndLogfile>>=
function CreateDirsAndLogFile {
    # Called by BuildApp ConfigFileLEC

    # Replace tilde if necessary
    SuspectPath=${ProjectPath}
    ReplaceTilde
    ProjectPath=${CleanPath}

<<CreateDirsAndLogfile1>>
@

\subsection{Definition der Pfade}
\label{subsec:PathDefinition}

Am Ende der Funktion \textit{ConfigFileLEC} werden noch zwei 
zusammengesetzte Pfade definiert. Die Beschreibung dieser Pfade findet
sich in Kapitel~\ref{sec:FolderStructure} (Seite~\pageref{sec:FolderStructure}). 

<<CreateDirsAndLogfile1>>=
    # Set paths
    PrjPath=${ProjectPath}/${OrigName}
    GitPath=${PrjPath}/${SourceName}

    # Create directories if necessary
    mkdir --parents ${PrjPath} # redundantly?
    mkdir --parents ${GitPath}

<<CreateLogFile>>
@

\subsection{Anlegen der Log-Datei}

In die Log-Datei werden bei jedem Programmstart zunächst Datum und 
Uhrzeit eingetragen.
 
<<CreateLogFile>>=
    # Create Log-File
    cd ${PrjPath}
    log=${PrjPath}/${OrigName}.log.txt
    touch ${log}
    echo -e "\n\n===\n=== $(date) ===\n===\n">>${log}
    echo "ConfigFile OK!" >> ${log}
}

<<InsertDebName>>
@

\section{\texttt{Git}-Repositorien}
\label{sec:GitRepos}

Für die Arbeit mit \textit{git-buildpackage} ist ein lokales 
\texttt{Git}-Repositorum mit Arbeitsverzeichnis wesentlich.

Das Programmskript geht davon, dass sowohl ein lokales Repositorium 
(Kapitel~\ref{sec:GitRepoLocal}, 
Seite~\pageref{sec:GitRepoLocal}) als auch ein Repositorium
auf \textit{salsa.debian.org} (Kapitel~\ref{chap:SalsaRepo},
Seite~\pageref{chap:SalsaRepo}) angelegt werden soll. Daneben
berücksichtigt das Programmskript auch ein \texttt{Git}-Repositorium auf einem
eigenen \texttt{Git}-Server (Kapitel~\ref{subsec:EigenerGitServer},
Seite~\pageref{subsec:EigenerGitServer}).

Die Neuanlage eines \texttt{Git}-Repositoriums ist der erste Schritt zum
Bauen eines neuen \texttt{Debian}-Paketes. Danach wird der Quellcode für
die (neue) Version heruntergeladen (Kapitel~\ref{sec:DownloadTools}, 
Seite~\pageref{sec:DownloadTools}), eine Revision gebaut 
(Kapitel~\ref{chap:NeueRevisionBauen}, 
Seite~\pageref{chap:NeueRevisionBauen}) und schließlich 
hochgeladen.(Kapitel~\ref{chap:UploadPackage}, 
Seite~\pageref{chap:UploadPackage}). Daher wird der Nutzer gefragt, ob er 
ein neues Paket bauen will.

\subsection{Gibt es bereits ein \texttt{Git}-Repositorium?}

Vorsorglich wird geprüft, ob bereits ein lokales \texttt{Git}-Repositorium für das 
anzulegende Projekt existiert. Es wird berücksichtigt, wenn in einem 
übergeordneten Verzeichnis ein \texttt{Git}-Repositorium existiert.   

Existiert ein lokales \texttt{Git}-Repositorium, geht es mit der Auswahl eines 
Git-Zweiges weiter (s. Kapitel~\ref{sec:AuswahlGitBranch}, 
Seite~\pageref{sec:AuswahlGitBranch}).

<<BuildApp7>>=
    ## Checks whether there is a git repo
    cd ${GitPath}
    set +e
    git status 1>/dev/null 2>&1

    # '==' does the same as '-eq'
    if [ $? == 0 ]
    then
        if [ -d .git ]
        then
            SelectBranch
        else
<<BuildApp8>>
@

Wenn ein Git-Repositorium in einem übergeordneten Verzeichnis existiert, 
wird ein entsprechender Hinweis gegeben.

<<BuildApp8>>=
            SupOrdMsg="Is there a git repository in a superordinate directory?"
            echo ${SupOrdMsg} >> ${log}
            whiptail --title="Attention!" --msgbox "${SupOrdMsg}" 15 60
            StartTasks
        fi
    else
        StartTasks
    fi

<<BuildApp10>>
@

\begin{figure}[h]
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/SuperordinateDir.png}
\caption{Gibt es ein übergeordnetes Git-Repositorium?}
\end{figure}

Existiert kein \texttt{Git}-Repositorium im entsprechenden Verzeichnis,
wird die Funktion \textit{StartTasks} aufgerufen.

\subsection{Auswahldialog}

Existiert noch kein Git-Repositorium, stellt das Skript vier Möglichkeiten 
bereit, ein solches Repositorium zu erstellen. Dies sind die Neuanlage 
mittels \textit{git init} und das Klonen eines bestehenden 
(Git-)Repositoriums von \textit{salsa.debian.org} 
(Kapitel~\ref{sec:SalsaDebianOrg}, Seite~\pageref{sec:SalsaDebianOrg}).
Letzteres setzt vorallem voraus, dass dort ein Zweig \textit{pristine-tar}
vorhanden ist.

Andernfalls kann ein Repositorium durch \textit{gbp import-dsc} angelegt
werden (Kapitel~\ref{sec:ImportPackage}, Seite~\pageref{sec:ImportPackage}).

Schließlich wird auch der Sonderfall des Sponsorings berücksichtigt
(Kapitel~\ref{sec:Import4Sponsoring}, Seite~\pageref{sec:Import4Sponsoring})

<<StartTasks>>=
function StartTasks {
    # Called by BuildApp

    Task=$(whiptail --title "Tasks for building a new package:" \
    --radiolist "What do you like to do to build a new package? " 17 60 9 \
      "0" "Create a git repo and download upstream code" on \
      "11" "Clone an existing repo from Salsa" off \
      "12" "Importing already existing Debian packages" off \
      "13" "Importing from mentors.debian.net for sponsoring" off \
    --cancel-button "Exit" 3>&2 2>&1 1>&3)

<<StartTasks1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/TaskNewPackage.png}
\caption{Ein neues Paket erstellen}
\end{figure}

<<StartTasks1>>=

    if [ -z "${Task}" ]
    then
        exit
    fi
    TaskSelect
}

<<DebDiffCheckList>>
@

Die Punkte des Menüs befassen sich mit verschiedenen Wegen, ein neues
Projekt aufzusetzen. Es geht vor allem um die Beschaffung des Quellcodes 
des Upstream-Projektes.

Der Aufruf der entsprechenden Funktionen erfolgt duch die Funktion
\textit{TaskSelect}.

Bei \textit{Create a git repo and download upstream code} wird durch die
Funktion \textit{BuildNewPackage} zunächst das lokale
\texttt{Git}-Repositorium angelegt (Kapitel~\ref{sec:LokalesGitRepoAnlegen}, 
Seite~\pageref{sec:LokalesGitRepoAnlegen}). Sodann wird eine neue Version
heruntergeladen (Kapitel~\ref{sec:DownloadTools},
Seite~\pageref{sec:DownloadTools}).

<<TaskSelect>>=
function TaskSelect {
    # Called by StartTasks CommonTasks

    ## The lines below serve also the sequence control. A called function
    ## changes finally the variable 'Task', so one of the following 
    ## if-clauses matches. That is why the following lines can not be 
    ## replaced by a case statement.

    NoPull=0 # Flag for PullFromSalsa

    ## Start tasks

    # Building a new package from archive
    if [ $Task -eq 0 ]
    then
        BuildNewPackage
    fi
<<TaskSelect0>>
@

Bei \textit{Clone an existing repo from Salsa} wird ein bereits vorhandenes 
Repositorium von \textit{salsa.debian.org} heruntergeladen.
Die Funktion \textit{CloneFromSalsa} klont dieses Repositorium mittels
des Befehles \textit{gbg clone}. (Kapitel~\ref{sec:SalsaDebianOrg},
Seite~\pageref{sec:SalsaDebianOrg})

<<TaskSelect0>>=

    # Clone an existing repo from Salsa
    if [ $Task -eq 11 ]
    then
        CloneFromSalsa
    fi
<<TaskSelect1>>
@

Bei \textit{Importing already existing \texttt{Debian} package} wird eine 
\textit{*.dsc}-Datei heruntergeladen und durch das Programm 
\textit{gbp import-dsc} ein \texttt{Git}-Repositorium angelegt
(Kapitel~\ref{sec:ImportPackage}, 
Seite~\pageref{sec:ImportPackage}).

<<TaskSelect1>>=

    # Importing already existing Debian package
    if [ $Task -eq 12 ]
    then
        ImportDebianPackage
    fi
<<TaskSelect2>>
@

Ein spezieller Fall für die Erstellung eines Git-Repositoriums mit
\textit{gpb import-dsc} ist das Sponsoring
(Kapitel~\ref{sec:Import4Sponsoring},
Seite~\pageref{sec:Import4Sponsoring}). Dabei unterstützt ein erfahrenes
Mitglied des \texttt{Debian}-Projektes einen Maintainer ohne Upload-Rechte,
indem das Mitglied das Paket signiert und hochlädt. 

<<TaskSelect2>>=
    # Importing from mentors.debian.net for sponsoring
    if [ $Task -eq 13 ]
    then
        Import4Sponsoring
    fi


<<TaskSelect3>>
@

\section{Neuanlage eines lokalen \texttt{Git}-Repositoriums}
\label{sec:LokalesGitRepoAnlegen}

Eine Möglichkeit der Erstellung eines \texttt{Git}-Repositoriums
\index{Git-Repositorium} ist die Neuanlage mittels
\textit{git init}. Dies erfolgt in der Funktion \textit{BuildNewPackage}.
Zuvor erfolgt noch ein entsprechender Eintrag in der Log-Datei.

<<BuildNewPackage>>=
function BuildNewPackage {
    # Called by TaskSelect
    cd ${GitPath}
    if [ -d .git ]
    then
        echo "There seems already to be a git repository in ${GitPath}." >> ${log}
        if ! whiptail --title "Warning" \
        --yesno "There seems already to be a git repository in ${GitPath}.\n \
        However continue?" --yes-button "Yes" --no-button "No" 15 60
        then
            echo "Exit" >> ${log}
            exit
        fi
<<BuildNewPackage1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/GitRepoExists.png}
\caption{Das Git-Repositorium existiert bereits.}
\end{figure}

\subsection{\texttt{Git}-Repositorium anlegen}

<<BuildNewPackage1>>=
    else
        echo "In ${GitPath} a new git repository will be created." >> ${log}
        git init
<<BuildNewPackage2>>
@

\subsection{Name und E-Mail-Adresse ins \texttt{Git}-Repositorium einfügen }
\label{subsec:DebNameAndEmail}

Der Name\index{DEBFULLNAME} und die E-Mail-Adresse\index{DEBEMAIL} des
Maintainers können in die Konfigurationsdatei des \texttt{Git}-Repositoriums
eingetragen werden, das für das Projekt angelegt worden ist. Diese Daten
werden beispielsweise jeder Commit-Mitteilung hinzugefügt.

Zunächst wird abgefragt, ob dies erwünscht ist. Diese Information kann
bereits höherrangig hinterlegt worden sein.

<<BuildNewPackage3>>=
        if whiptail --title "Name and email" \
        --yesno "Do you like to add your name and email address \n \
        to the local git config file?" --yes-button "Yes" \
        --no-button "No" 15 60
        then
            AddNameAndEmail
        fi
<<BuildNewPackage5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameAndEmail.png}
\caption{Name und E-Mail.}
\end{figure}

Die folgende Funktion wird immer dann aufgerufen, wenn bei der Anlage
eines neuen \texttt{Git}-Repositoriums die Frage nach der Eintragung in
die lokale Konfigurationsdatei bejaht wird.

<<AddNameAndEmail>>=
function AddNameAndEmail {
    # Called by BuildNewPackage CloneFromSalsa 
    # ImportDebianPackage and itself

    DEBValues
    GCName=${DEBFULLNAME}
    GCEmail=${DEBEMAIL}

<<AddNameAndEmail1>>
@

Damit der Paketierer nicht immer seinen vollen Namen und seine E-Mail-Adresse 
schreiben muss, sucht das Skript diese Daten zunächst in der 
Konfigurationsdatei und sodann in der \textit{\textasciitilde/.bashrc}. 
Gegebenenfalls wird Gefundenes oder Erfragtes in die Konfigurationsdatei 
eingetragen.

<<Bashrc>>=
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
@

<<DEBValues>>=
function DEBValues {
    # Called by DebianControlTemplate PatchHeader AddNameAndEmail
    MaintainerF=0
    set +e
    # if Maintainer is stored in config file
    if [ "${Maintainer}" ]
    then
        Maintainer=$(echo ${Maintainer} | sed --expression='s/_/ /g')
        Maintainer=$(echo ${Maintainer} | sed --expression='s/@lt@/</g')
        Maintainer=$(echo ${Maintainer} | sed --expression='s/@gt@/>/g')
        DEBFULLNAME=$(echo ${Maintainer} | sed --expression='s/<.*//')
        DEBEMAIL=$(echo ${Maintainer} | sed --expression='s/^.*<//' | sed 's/>//')
        MaintainerF=1
    fi

    # if Uploaders is stored in config file
    if [ "${Uploaders}" ]
    then
        Uploaders=$(echo ${Uploaders} | sed --expression='s/_/ /g')
        Uploaders=$(echo ${Uploaders} | sed --expression='s/@lt@/</g')
        Uploaders=$(echo ${Uploaders} | sed --expression='s/@gt@/>/g')
        DEBFULLNAME=$(echo ${Uploaders} | sed --expression='s/<.*//')
        DEBEMAIL=$(echo ${Uploaders} | sed --expression='s/^.*<//' | sed 's/>//')
    fi
    
    # Looking for a team as maintainer
    if [ ${MaintainerF} -eq 0 ]
    then
        TeamMaintainer
    fi

<<DEBValues3>>
@

Es gibt Pakete, die von einem Team\cite{DebianTeams} betreut werden. Meist
werden viele gleichartige Pakete von einem solchen Team betreut. In
diesen Fällen tritt das \texttt{Debian}-Projektmitglied als
\textit{Uploader}\index{Uploader} auf und das Team als
\textit{Maintainer}\index{Maintainer}. Dies wird entsprechend in die
Datei \textit{debian/control} (Kapitel~\ref{subsec:DebianControl},
Seite~\pageref{subsec:DebianControl}) eingetragen. Im Programmskript
werden bisher das \textit{\texttt{Java} packaging team}, das
\textit{\texttt{Mozilla} WebExtensions packaging team} und das
\textit{\texttt{Debian} \texttt{Python} Team} berücksichtigt.

<<TeamMaintainer>>=
function TeamMaintainer {
    # Called by DEBValues

    # Makes sure that variable exists
    if [ -z '${JavaFlag}' ]
    then
        JavaFlag = 0
    fi

    if [ ${JavaFlag} -eq 1 ]
    then
        Maintainer="Debian Java Maintainers \ 
        <pkg-java-maintainers@lists.alioth.debian.org>"
        MaintainerF=1
    fi

    if [ -z '${WebextFlag}' ]
    then
        WebextFlag = 0
    fi

    if [ ${WebextFlag} -eq 1 ]
    then
        Maintainer="Debian Mozilla Extension Maintainers \
        <pkg-mozext-maintainers@alioth-lists.debian.org>"
        MaintainerF=1
    fi

    if [ -z '${PythonFlag}' ]
    then
        PythonFlag = 0
    fi

    if [ ${PythonFlag} -eq 1 ]
    then
        Maintainer="Debian Python Team <team+python@tracker.debian.org>"
        MaintainerF=1
    fi
}

<<DEBValues>>
@

<<DEBValues3>>=
    # Extracts DEBFULLNAME and DEBEMAIL from ~/.bashrc (if exist)
    if [ ${MaintainerF} -eq 0 ]
    then
        if grep --quiet 'DEBFULLNAME' ~/.bashrc
        then
            dfnb=$(grep DEBFULLNAME ~/.bashrc)
            dfnb=$(echo ${dfnb} | sed --expression='s/export .*//')
            dfnb=$(echo ${dfnb} | sed --expression='s/DEBFULLNAME=//')
            dfnb=$(echo ${dfnb} | sed --expression='s/"//g')
            dfnb=$(echo ${dfnb} | sed --expression="s/'//g")
            DEBFULLNAME=${dfnb}
        fi
        if grep --quiet 'DEBEMAIL' ~/.bashrc
        then
            demb=$(grep 'DEBEMAIL' ~/.bashrc)
            demb=$(echo ${demb} | sed --expression='s/export .*//')
            demb=$(echo ${demb} | sed --expression='s/DEBEMAIL=//')
            demb=$(echo ${demb} | sed --expression='s/"//g')
            demb=$(echo ${demb} | sed --expression="s/'//g")
            DEBEMAIL=${demb}
        fi
        Maintainer=${DEBFULLNAME}" <"${DEBEMAIL}">"
        MaintainerF=1
    fi

    # Insert name and email address
    if [ ${MaintainerF} -eq 0 ]
    then
        DEBFULLNAME=$(whiptail --title "Name of the maintainer" \
        --inputbox "Please insert full name of the maintainer" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<DEBValues4-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameMaintainer.png}
\caption{Name des Maintainer}
\end{figure}

<<DEBValues4-1>>=
        DEBEMAIL=$(whiptail --title "Email of the maintainer" \
        --inputbox "Please insert email address of the maintainer" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<DEBValues4-2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EmailMaintainer.png}
\caption{E-Mail des Maintainers}
\end{figure}

<<DEBValues4-2>>=
        Maintainer=${DEBFULLNAME}" <"${DEBEMAIL}">"
        changeflag=1
        MaintainerF=1
    fi

    if ! whiptail --title "Maintainer" \
    --yesno "The full name and email address of the maintainer(s):\n \
    ${Maintainer}" --yes-button "OK" --no-button "Insert other" 15 60
<<DEBValues5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/Maintainer.png}
\caption{\texttt{Debian}-Maintainer OK?}
\end{figure}

<<DEBValues5>>=
    then
        DEBFULLNAME=$(whiptail --title "Name of the maintainer" \
        --inputbox "Please insert full name of the maintainer" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<DEBValues5-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameMaintainer.png}
\caption{Name des \texttt{Debian}-Maintainer}
\end{figure}

<<DEBValues5-1>>=
        DEBEMAIL=$(whiptail --title "Email of the maintainer"\
        --inputbox "Please insert email address of the maintainer" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<DEBValues5-2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EmailMaintainer.png}
\caption{E-Mail des \texttt{Debian}-Maintainer}
\end{figure}

<<DEBValues5-2>>=
        Maintainer=${DEBFULLNAME}" <"${DEBEMAIL}">"
        changeflag=1
        MaintainerF=1
    fi
<<DEBValues6>>
@

<<DEBValues6>>=

    # Insert maintainer data into config file if necessary
    if [ $changeflag -eq 1 ]
    then
        # Because Maintainer contains blanks
        MaintainerCF=$(echo ${Maintainer} | sed --expression='s/ /_/g')
        # Remove < and >
        MaintainerCF=$(echo ${MaintainerCF} | sed --expression='s/</@lt@/g')
        MaintainerCF=$(echo ${MaintainerCF} | sed --expression='s/>/@gt@/g')
        echo '## Maintainer and Uploaders' >> ${ConfigPath}${OrigName}
        echo 'Maintainer='${MaintainerCF} >> ${ConfigPath}${OrigName}
        changeflag=0
    fi

<<DEBValues7>>
@

<<DEBValues7>>=
     # Insert uploaders data into config file if necessary
    if [ ${JavaFlag} -eq 1 ]
    then
        if [ -z "${Uploaders}" ]
        then
            if grep --quiet 'DEBFULLNAME' ~/.bashrc
            then
                dfnb=$(grep DEBFULLNAME ~/.bashrc)
                dfnb=$(echo ${dfnb} | sed --expression='s/export .*//')
                dfnb=$(echo ${dfnb} | sed --expression='s/DEBFULLNAME=//')
                dfnb=$(echo ${dfnb} | sed --expression='s/"//g')
                dfnb=$(echo ${dfnb} | sed --expression="s/'//g")
                DEBFULLNAME=${dfnb}
            else
                DEBEMAIL=$(whiptail --title "Email of the uploader" \
                --inputbox "Please insert email address of the uploader" \
                --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
            fi
<<DEBValues8>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EmailUploader.png}
\caption{E-Mail des \texttt{Debian}-Uploaders}
\end{figure}

<<DEBValues8>>=
            if grep --quiet 'DEBEMAIL' ~/.bashrc
            then
                demb=$(grep 'DEBEMAIL' ~/.bashrc)
                demb=$(echo ${demb} | sed --expression='s/export .*//')
                demb=$(echo ${demb} | sed --expression='s/DEBEMAIL=//')
                demb=$(echo ${demb} | sed --expression='s/"//g')
                demb=$(echo ${demb} | sed --expression="s/'//g")
                DEBEMAIL=${demb}
            else
                DEBEMAIL=$(whiptail --title "Email of the uploader" \
                --inputbox "Please insert email address of the uploader" \
                --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
            fi
<<DEBValues9>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EmailUploader.png}
\caption{E-Mail des \texttt{Debian}-Uploaders}
\end{figure}

<<DEBValues9>>=
            Uploaders=${DEBFULLNAME}" <"${DEBEMAIL}">"        
            # Because Uploaders contains blanks
            UploadersCF=$(echo ${Uploaders} | sed --expression='s/ /_/g')
            # Remove < and >
            UploadersCF=$(echo ${UploadersCF} | sed --expression='s/</@lt@/g')
            UploadersCF=$(echo ${UploadersCF} | sed --expression='s/>/@gt@/g')
            echo 'Uploaders='${UploadersCF} >> ${ConfigPath}${OrigName}
            changeflag=0
        fi
     fi
     set -e
}

<<DebianControlTemplate>>
@

<<AddNameAndEmail1>>=
    if [ -z "${GCName}" ]
    then
        InsertDebName
    fi
    # if [ -n "${GCName}" ]
    # then
        git config user.name ${GCName}
    # fi
    if [ -z "${GCEmail}" ]
    then
        InsertDebEmail
    fi
    # if [ -n "${GCEmail}" ]
    # then
        git config user.email ${GCEmail}
    # fi

    set +e
    configStr=$(git config --list | grep 'user')
    set -e

    if ! whiptail --title "Result" \
    --yesno "${configStr}\nAllright?" \
    --yes-button "Yes" --no-button "No" 15 60
<<AddNameAndEmail2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ShowNameMaintainer.png}
\caption{Name und E-Mail des Maintainers korrekt?}
\end{figure}

<<AddNameAndEmail2>>=
    then
        AddNameAndEmail
    fi
}

<<AddHomeServer>>
@

Die folgende Funktion dient zur Eingabe des Vor- und Nachnamens des
Maintainers.

<<InsertDebName>>=
function InsertDebName {

    # Called by AddNameAndEmail and itself
    DEBFULLNAME=$(whiptail --title "Name of the maintainer" \
    --inputbox "Please insert full name of the maintainer" \
    --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
<<InsertDebName1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/InsertNameMaintainer.png}
\caption{Name des Maintainers eingeben}
\end{figure}

<<InsertDebName1>>=    
    if [ $? -ne 0 ]
    then
        exit
    fi
    
    # Test Name
    if [ -z "${DEBFULLNAME}" ]
    then
        whiptail --title "Your Name" \
        --msgbox "Your name is necessary." 15 60
        InsertDebName
    fi
}
<<InsertDebEmail>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameNecessary.png}
\caption{Name des Maintainers erforderlich}
\end{figure}

Die folgende Funktion dient zur Eingabe des E-Mail-Adresse des
Maintainers.

<<InsertDebEmail>>=
function InsertDebEmail {

    # Called by AddNameAndEmail and itself
    DEBEMAIL=$(whiptail --title "Email of the maintainer" \
    --inputbox "Please insert email address of the maintainer" \
    --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
<<InsertDebEmail1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/InsertEmailMaintainer.png}
\caption{E-Mail-Adresse des Maintainers eingeben}
\end{figure}

<<InsertDebEmail1>>=
    if [ $? -ne 0 ]
    then
        exit
    fi    

    # Regex string
    EmailR="\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}\b"

    # Test email address
    set +e
    if ! echo ${DEBEMAIL} | grep -E ${EmailR} > /dev/null
    then
        whiptail --title "Bad!" --msgbox "That's no email address." 15 60
        InsertDebEmail
    fi
    set -e
}
<<AddNameAndEmail>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NoEmailAddress.png}
\caption{Dies ist keine E-Mail-Adresse}
\end{figure}

\subsection{Repositorium auf \textit{salsa.debian.org}}
\label{subsec:SalsaRepoAnlegen}

Das Salsa-Repositorium wird als \enquote{Remote-Repository} vom 
Programmskript eingetragen.

<<BuildNewPackage2>>=
        git remote add salsa git@salsa.debian.org:${SalsaName}

<<BuildNewPackage3>>
@

\subsubsection{Manuell}

Das entsprechende Repositorium auf \textit{salsa.debian.org} wird dann 
manuell (Kapitel~\ref{sec:ManuelleAnlage}, 
Seite~\pageref{sec:ManuelleAnlage}) angelegt 
(s. Kapitel~\ref{sec:CreateJavaTeam}, 
Seite~\pageref{sec:CreateJavaTeam}).

Hieran erinnert das Programmskript auch den Nutzer. 

<<BuildNewPackage6>>=

    whiptail --title "If not happened yet:" \
    --msgbox "Please create a git repo ${SalsaName} \n \
    on salsa.debian.org!" 15 60
<<BuildNewPackage6-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CreateGitRepo.png}
\caption{Ein Git-Repositorium auf salsa anlegen}
\end{figure}

\subsubsection{Innerhalb des \texttt{Java}-Teams}

Innerhalb des \texttt{Java}-Teams (Kapitel~\ref{sec:JavaTeam},
Seite~\pageref{sec:JavaTeam}) sollte ein neues Repositorium mit dem vom Team 
bereitgestellten \textit{setup-salsa-repository}-Skript
(Kapitel~\ref{sec:CreateJavaTeam}, Seite~\pageref{sec:CreateJavaTeam})
angelegt werden.

%Um dies zu erleichtern, wird dies vom Programmskript
%automatisch angestoßen.

%ToDo: Zugriff auf setup-javateam-salsa-repository.sh beschreiben

%\begin{itemize}
    %\item{Skript kopiert das Setup-Skript aus \textit{.debian\_project}}
    %\item{Skript sagt, wie das Token generiert wird}
    %\item{Skript fragt Token ab (Kommandozeile)}
    %\item{Skript schreibt in Setup den Token}
    %\item{Skript ruft Setup-Skript auf, mit dem Sourcename}
%\end{itemize}

\subsection{Remoteserver anzeigen}
\label{subsec:RemoteserverAnzeigen}

Es werden die im Git-Repositorium eingetragenen Remoteserver angezeigt. 
Ein eigener Server wird nur angezeigt, wenn er zuvor eingetragen wurde.

<<BuildNewPackage5>>=
        AddHomeServer
    fi
<<BuildNewPackage6>>
@

% ToDo: Fetch AddGitServer etc from Part5

<<AddHomeServer>>=
function AddHomeServer {
    # Called by BuildNewPackage AddGitServer ImportDebianPackage
    if [ -n "$ServerName" ]
    then
        git remote add home $(whoami)@${ServerName}:/srv/git/${SourceName}.git

        whiptail --title "Remoteserver" \
        --msgbox "New server added:\n$(git remote --verbose)" 15 60
        echo -e "New server added:\n $(git remote --verbose)" >> ${log}
    fi
}

<<BuildNewPackage>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/RemoteServer.png}
\caption{Remoteserver ergänzen}
\end{figure}

Sodann wird eine neue Version heruntergeladen
(Kapitel~\ref{sec:DownloadTools},
Seite~\pageref{sec:DownloadTools}).

<<BuildNewPackage6-1>>=
    NoPull=1 # Do not ask for pulling from salsa.debian.org
    Task=2 # Go to BuildNewVersion
}

<<IdentifyBranches>>
@

\textit{NoPull=1} verhindert, dass vor dem Herunterladen der neuen Version
gefragt wird, ob zuvor eventuelle Änderungen von \textit{salsa.debian.org}
heruntergeladen werden sollen.
 
\section{Klonen von \textit{salsa.debian.org}}
\label{sec:SalsaDebianOrg}

In diesem Fall entfallen teilweise Schritte, die in den anderen Kapiteln 
genannt sind. Das Klonen erfolgt mit dem Befehl \textit{gbp clone}. Danach 
wird beim erfolgreichen Klonen das Remote-Repositorium von \textit{origin} 
nach \textit{salsa} umbenant. Damit ist eine aussagekräftigere Benamung der 
Repositorien möglich.

Andernfalls erfolgt eine Fehlermeldung und das Programm endet.

<<CloneFromSalsa>>=
function CloneFromSalsa {
    # Called by TaskSelect
    echo "Clone an existing repo from salsa.debian.org" >> ${log}
    cd ${PrjPath}
    gbp clone git@salsa.debian.org:${SalsaName} --aliases ${SourceName}
    if [ $? -eq 0 ]
    then
        cd ${GitPath}
        git remote rename origin salsa
        echo "${SalsaName} was cloned" >> ${log}
    else
        echo "${SalsaName} could not be cloned"
        exit
    fi

<<CloneFromSalsa2>>
@

Bei einem erfolgreichen Herunterladen werden mittels der Funktion 
\textit{DebianBranchName} die heuntergeladenen Zweige (Branches) angezeigt 
und der aktive Zweig gesondet angezeigt.

<<CloneFromSalsa2>>=
    # Identify branches and choose one
    DebianBranchName

<<CloneFromSalsa3>>
@

\subsection{Bestimmung der \texttt{Git}-Zweige}
\label{subsec:DebianBranchName}

Mit der Funktion \textit{DebianBranchName} werden die \texttt{Git}-Zweige
des geklonten Salsa-Repositoriums ermittelt.

Hierzu wird zunächst die Funktion \textit{IdentifyBranches} 
(Kapitel~\ref{subsec:IdentifyBranches}, 
Seite~\pageref{subsec:IdentifyBranches}) ausgeführt.

<<DebianBranchName>>=
function DebianBranchName {
    # Called by CloneFromSalsa

    ## Identify and show branches
    IdentifyBranches
    ba=($bl)

    whiptail --title "Branches in repo ${OrigName}:" --msgbox "${bl}" 15 60

<<DebianBranchName2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/BranchesList.png}
\caption{Zeigt Liste der \texttt{Git}-Zweige}
\end{figure}

Sodann wird der aktive \texttt{Git}-Zweig ermittelt.

<<DebianBranchName2>>=
    set +e
    for element in ${ba[*]}
    do
        # Find the default branch
        if echo ${element} | grep --quiet '^x_'
        then
            DefaultBranch=$(echo ${element} | sed --expression='s/^x_//')
            whiptail --title "Recent branch found" \
            --msgbox "Found: ${DefaultBranch}" 15 60
        fi
<<DebianBranchName3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/RecentBranchFound.png}
\caption{Zeigt aktuellen \texttt{Git}-Zweig}
\end{figure}

<<DebianBranchName3>>=
        # Ignore HEAD
        if echo ${element} | grep --quiet 'HEAD'
        then continue
        fi
        # Checkout all branches
        if echo ${element} | grep --quiet '^remotes/salsa/'
        then
            NewBranchName=$(echo ${element} | \
            sed --expression='s/^remotes\/salsa\///')
            git checkout ${NewBranchName}
            whiptail --title "Checkout branch" \
            --msgbox "Checkout of ${NewBranchName}" 15 60
        fi
    done
    set -e
<<DebianBranchName4>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NewBranchName.png}
\caption{Aktueller \texttt{Git}-Zweig}
\end{figure}

<<DebianBranchName4>>=

    # Finally checkout the default branch (again)
    git checkout ${DefaultBranch}
    whiptail --title "Checkout branch" \
    --msgbox "Checkout of ${DefaultBranch}" 15 60
<<DebianBranchName5>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/DefaultBranch.png}
\caption{Vorgegebener \texttt{Git}-Zweig}
\end{figure}

<<DebianBranchName5>>=
    
    # Insert default branch into the config file and write into logfile   
    echo 'DefaultBranch='${DefaultBranch} >> ${ConfigPath}${OrigName}
    echo "Branches: "${bl} >> ${log}
    echo "DefaultBranch: "${DefaultBranch} >> ${log}
    RecentBranch=${DefaultBranch}
    whiptail --title "Please check! (1)" \
    --msgbox "The branch is ${RecentBranch}" 15 60
<<DebianBranchName6>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/RecentBranch.png}
\caption{Aktueller \texttt{Git}-Zweig}
\end{figure}

<<DebianBranchName6>>=
    echo 'RecentBranch='${RecentBranch} >> ${ConfigPath}${OrigName}
    echo "RecentBranch: "${RecentBranch} >> ${log}
    Distro4Branch
}

<<FailureNotice>>
@

Durch den Aufruf der Funktion \textit{Distro4Branch} wird schließlich
dem \texttt{Git}-Zweig eine Distribution zugeordnet 
(Kapitel~\ref{subsec:Distro4Branch}, Seite~\pageref{subsec:Distro4Branch})

\subsection{\texttt{Git}-Zweige ermitteln}
\label{subsec:IdentifyBranches}

Diese Funktion ermittelt alle vorhandenen Zweige. Dies geschiet mittels 
des Befehles \textit{git branch -{}-all}. Bei der Kennzeichnung des 
aktiven Zweiges werden Sternchen (*) und Leerzeichen durch kleines X (x)
und Ubterstrich(\_) ersetzt.

Diese Funktion wird an verschiedenen Stellen im Ablauf des Programmskriptes 
aufgerufen.

<<IdentifyBranches>>=
function IdentifyBranches {
    # Called by DebianBranchName AskDist DebianBranches
    cd ${GitPath}
    # sed is used to kill the asterisk
    bl=$(git branch --all | sed --expression='s/* /x_/')
}

<<CreateNewCow>>
@

\subsection{Git-Zweig Distribution zuordnen}
\label{subsec:Distro4Branch}

An verschiedenen Stellen im Programmablauf ist es erforderlich, einem 
Git-Zweig eine Debian-Veröffentlichung zuzuordnen.

<<Distro4Branch>>=
function Distro4Branch {
    # Called by DebianBranchName CreateNewBranch AskDist BuildNewRevision

    set +e
    # Set Debian distribution for branch
    if [ ${RecentBranch} != "debian/sid" -o -z "${RecentBranchD}" ]
    then
        CowL=$(ls /var/cache/pbuilder/ | grep .cow | grep '-'| \
        sed 's/base-//' | sed 's/.cow//')
        CowA=($CowL)

        i=1; cowE="0 sid on "
        for element in ${CowA[*]}
        do
            cowE=$cowE' '$i' '${element}' off '
            i=$(expr $i + 1)
        done

        RecentBranchDNr=$(whiptail --title "Debian release" \
        --radiolist "Select pbuilder cow:" \
        --cancel-button "Other" 15 60 8 \
        $cowE 3>&2 2>&1 1>&3)
<<Distro4Branch2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/DebianRelease.png}
\caption{Auswahl des Debian Release.}
\end{figure}

<<Distro4Branch2>>=
        if [ $? -eq 1 ]
        then
            CreateNewCow
        fi

        if [ ${RecentBranchDNr} -eq 0 ]
        then
            bDist="sid"
        else
            RecentBranchDNr=$(expr ${RecentBranchDNr} - 1)
            bDist=${CowA[${RecentBranchDNr}]}
        fi
        
        echo "# "${RecentBranch}"_Dist="${bDist} >> ${ConfigPath}${OrigName}
        RecentBranchD=${bDist}
        echo "Notice from Distro4Branch: The distribution is " \
        ${RecentBranchD} >> ${log}
    fi
    set -e
}

<<DebianBranchName>>
@

\subsection{Name und E-Mail-Adresse hinzufügen}

Besonders für den Fall, dass es sich um kein \enquote{eigenes} Salsa-Repositorium
handelt, wird die Möglichkeit eröffnet, den Namen und die E-Mail-Adresse
des Maintainers in die lokale git-Konfigurationsdatei einzutragen. Dies
erfolgt mit der Funktion \textit{AddNameAndEmail} (s,~a,
Kapitel~\ref{subsec:DebNameAndEmail}, Seite~\pageref{subsec:DebNameAndEmail}

<<CloneFromSalsa3>>=
    if whiptail --title "Name and email" \
    --yesno "Do you like to add your name and email address \n \
    to the local git config file?" --yes-button "Yes" \
    --no-button "No" 15 60
<<CloneFromSalsa5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameAndEmail.png}
\caption{Name und E-Mail.}
\end{figure}

<<CloneFromSalsa5>>=
    then
        AddNameAndEmail
    fi

<<CloneFromSalsa7>>
@

<<CloneFromSalsa7>>=
    AddHomeServer
    CommonTasks
}

<<CutSuffix>>
@

\section{Import eines \texttt{Debian}-Quellcode-Paketes}
\label{sec:ImportPackage}

Nicht alle Pakete des \texttt{Debian}-Projektes liegen auf 
\textit{salsa.debian.org}, einer \texttt{Gitlab}-Instanz. Von den Paketen
auf \textit{salsa.debian.org} werden nicht alle mit
\textit{git-buildpackage} gebaut. Manchmal fehlt der Zweig
\textit{pristine-tar}.\index{pristine-tar}. In diesem Fall ist ein
Klonen nicht sinnvoll.

Auch diese Pakete können jedoch mithilfe dieses Programmskriptes gebaut
werden. In der Datei \textit{/etc/apt/sources.list} oder in einer Datei
im Verzeichnis \textit{/etc/apt/sources.list.d} muss dazu der Eintrag

\begin{verbatim}
    deb-src http://deb.debian.org/debian/ sid main
\end{verbatim}

aktiviert vorhanden sein. Dies bedeutet, dass nach der Aktivierung auch
\textit{sudo apt update} ausgeführt werden muss.

Für seltene Sonderfälle ist diese Zeile entsprechend anzupassen.

Dieser Eintrag ermöglicht das Herunterladen von Quellpaketen.

<<ImportDebianPackage>>=
function ImportDebianPackage {
    # Called by TaskSelect

    echo "Import an existing package without pristine-tar" >> ${log}
    cd ${PrjPath}
    echo "Download ${SourceName} with apt source" >> ${log}
    apt source --download-only ${SourceName} >> ${log}

<<ImportDebianPackage2>>
@

Mit \textit{apt source -{}-download-only} wird nur das Quellcodepaket
heruntergeladen.

Das Erstellen des \texttt{Git}-Verzeichnisses erfolgt mit 
\textit{gbp import-dsc} und der heruntergeladenen \textit{*.dsc}-Datei.

Da die Funktion \textit{gbp import-dsc} ein Signieren ausführt, wird
durch die Funktion \textit{GpgKeyAvailable}
(Kapitel~\ref{sec:KeyAvailable}, Seite~\pageref{sec:KeyAvailable}) zunächst
abgefragt, ob der \texttt{GnuPG}-Schlüssel verfügbar ist.

<<ImportDebianPackage2>>=
    GpgKeyAvailable

    # GitPath has to be deleted because gbp import-dsc will create it.
    rmdir --verbose ${GitPath} >> ${log}

    echo "gbp import-dsc" >> ${log}
    gbp import-dsc --verbose ${SourceName}*.dsc >> ${log}

    cd ${GitPath}
    git remote add salsa git@salsa.debian.org:${SalsaName}
<<ImportDebianPackage3>>
@

Danach erfolgt die Anzeige der vorhandenen \texttt{Git}-Zweige und die
Bestimmung des aktiven Zweiges durch Aufruf der Funktion
\textit{DebianBranchName} (Kapitel~\ref{subsec:DebianBranchName},
Seite~\pageref{subsec:DebianBranchName}).

Dann wird die Möglichkeit eröffnet, den Namen und die E-Mail-Adresse
des Maintainers in die lokale git-Konfigurationsdatei einzutragen. Dies
erfolgt mit der Funktion \textit{AddNameAndEmail} (s,~a,
Kapitel~\ref{subsec:DebNameAndEmail}, Seite~\pageref{subsec:DebNameAndEmail}

<<ImportDebianPackage3>>=   
 # Identify branches and choose one
    DebianBranchName

    if whiptail --title "Name and email" \
    --yesno "Do you like to add your name and email address \n \
    to the local git config file?" --yes-button "Yes" \
    --no-button "No" 15 60
<<ImportDebianPackage3a>>
@
  
\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NameAndEmail.png}
\caption{Name und E-Mail.}
\end{figure}

<<ImportDebianPackage3a>>=
    then
        AddNameAndEmail
    fi

<<ImportDebianPackage4>>
@

<<ImportDebianPackage4>>=
    AddHomeServer
    PQImport
    CommonTasks

}

<<Import4Sponsoring>>
@

\section{Import für das Sponsoring}
\label{sec:Import4Sponsoring}

Ein spezieller Fall für die Erstellung eines Git-Repositoriums mit
\textit{gpb import-dsc} ist das Sponsoring. Das Herunterladen der
Quellcodepakete erfolgt hier mit \textit{dget} (in der Regel von
\textit{mentors.debian.net}).

<<Import4Sponsoring>>=
function Import4Sponsoring {
    # Called by StartTasks

    cd ${PrjPath}
    
    if whiptail --title "Should the Debian sources be downloaded?" \
    --yesno "Should the Debian sources (*.orig.tar.g|xz, *.debian.tar.g|xz\n \
    and *.dsc) be downloaded?" \
    --defaultno --yes-button "Yes" --no-button "No" 15 60
<<Import4Sponsoring1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DownloadDebianSources.png}
\caption{Herunterladen der Debian Sourcen}
\end{figure}

Sollen die Quellcodepakete von \textit{mentors.debian.net} heruntergeladen
werden, hat die URL folgends Format:

\begin{verbatim}
  https://mentors.debian.net/debian/pool/main/<p> \
  /<package name>/<package name>_x.y.z.dsc
\end{verbatim}

<<Import4Sponsoring1>>=
    then
        DownloadUrl=$(whiptail --title "Insert URL for download" \
        --inputbox "Please insert the complete\n \
        URL to download ${UpstreamSourceName}\n(with ’https://’\n \
        e.g. from mentors.debian.net):" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)

<<Import4Sponsoring2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/InsertDownloadDebianSourceUrl.png}
\caption{Eingabe der Url der Debian Sourcen}
\end{figure}

<<Import4Sponsoring2>>=
        dget --download-only ${DownloadUrl}
        ls -la
        echo -e "\n Press RETURN to continue!"
        read a
    fi

    # GitPath has to be deleted because gbp import-dsc will create it.
    echo $(pwd) >> ${log}
    rmdir ${GitPath}

    GpgKeyAvailable
    gbp import-dsc --verbose $(ls *.dsc) >> ${log} &&

    ParseConfig
    cd ${SourceName}
    echo $(pwd) >> ${log}
    SBuildOrPBuilder 0
    Task=5 # Go to RunningTests
}

<<CommonTasks>>
@

Danach geht des mit dem Bauen des \texttt{Debian}"=Paketes weiter
(Kapitel~\ref{subsec:ChooseBuildSystem},
Seite~\pageref{subsec:ChooseBuildSystem}).

Nach dem Bauen des Paketes werden die Tests aufgerufen
(Kapitel~\ref{chap:Ueberpruefungen},
Seite~\pageref{chap:Ueberpruefungen}).

\section{\texttt{GnuPG}-Schlüssel verfügbar?}
\label{sec:KeyAvailable}

Die Funktion \textit{GpgKeyAvailable} fordert den Nutzer auf zu prüfen,
ob der \texttt{GnuPG}-Schlüssel zum Signieren verfügbar ist.

Sie wird an verschiedenen Stellen im Programmskript aufgerufen. Wird die
Frage nach der Verfügbarkeit des \texttt{GnuPG}-Schlüssels verneint, wird
das Programmskript beendet.

<<GpgKeyAvailable>>=
function GpgKeyAvailable {
    # Called by BuildWithUscan Import2Git CreateSignature ImportDebianPackage
    # PrepareUploading

    if ! whiptail --title "GPG-Key available?" \
    --yesno "GPG-Key must be available for signing." \
    --yes-button "Yes, is available" --no-button "Exit" 15 60
    then
        exit
    fi
    GettingFingerprint
}

<<DetectPlugins>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/GPGKeyAvailable.png}
\caption{GPG-Schlüssel verfügbar}
\end{figure}

\section{Fingerprint nutzen}
\label{sec:GettingFingerprint}

Zum Signieren wird der Fingerprint\index{Fingerprint} des
Maintainer-Schlüssels benötigt. Dies ist der Fingerprint des Schlüssels,
der auch im \texttt{Debian-Keyring}\index{Debian-Keyring} hinterlegt ist.

Befindet sich keine entsprechende Datei im Verzeichnis der 
Konfigurationsdateien\index{Konfigurationsdatei}, wird eine entsprechende 
Datei erstellt.

<<GettingFingerprint>>=
function GettingFingerprint {
    # Called by GpgKeyAvailable

    finchflag=0

    # getting the fingerprint of the key to sign
    if [ -f ${ConfigPath}/fingerprint ]
    then
        . ${ConfigPath}/fingerprint
    else
        mkdir --parents ${ConfigPath}
        finchflag=1
    fi

    if [ -z "${fipr}" ]
    then
        fipr=$(whiptail --title "Your fingerprint" \
        --inputbox "Please insert fingerprint of your key for signing!" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<GettingFingerprint1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/InsertFingerprint.png}
\caption{Fingerprint eingeben}
\end{figure}

<<GettingFingerprint1>>=
        if [ -z "${fipr}" ]
        then
            echo "Please insert fingerprint of your key for signing!"
            read fipr
        fi
        finchflag=1
    fi

    if ! whiptail --title "Fingerprint" \
    --yesno "Is ${fipr} the right fingerprint of the key for signing?" \
    --yes-button "Yes" --no-button "No" 15 60
<<GettingFingerprint2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/VerifyFingerprint.png}
\caption{Ist der Fingerprint korrekt?}
\end{figure}

<<GettingFingerprint2>>=
    then
        fipr=$(whiptail --title "Key for signing" \
        --inputbox "Real fingerprint of the key for signing:" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<GettingFingerprint3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CorrectFingerprint.png}
\caption{Korrekten Fingerprint eingeben}
\end{figure}

<<GettingFingerprint3>>=
        if [ -z "${fipr}" ]
        then
            echo "Please insert fingerprint of your key for signing!"
            read fipr
        fi
        finchflag=1
    fi

    if [ $finchflag -eq 1 ]
    then
        if [ -f ${ConfigPath}/fingerprint ]
        then
            mv ${ConfigPath}/fingerprint ${ConfigPath}/fingerprint.backup
            whiptail --title "Fingerprint file" \
            --msgbox "You can find the old fingerprint file as\n \
            ${ConfigPath}/fingerprint.backup" 15 60
        fi
<<GettingFingerprint4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/OldFingerprint.png}
\caption{Backup des Fingerprints anlegen}
\end{figure}

<<GettingFingerprint4>>=
        touch ${ConfigPath}/fingerprint
        echo "#!/usr/bin/bash" >> ${ConfigPath}/fingerprint
        echo "fipr="${fipr} >> ${ConfigPath}/fingerprint
        . ${ConfigPath}/fingerprint
    fi
}

<<CreateSignature>>
@

\section{Start des Paketierens}

Die Funktion \textit{BuildApp} ruft am Ende die Aufgabenauswahl für die 
einzelnen Schritte des Paketierens auf.

<<BuildApp10>>=
    set -e
    # Start of Packaging
    CommonTasks
}

<<MainProgram>>
@

\chapter{Arbeiten in einem angelegten Projekt}
\label{chap:ExistingProject}

\section{Konfigurationsdatei laden und editieren}
\label{sec:ConfigFileLaden}

Wird ein Projektname eingegeben, versucht das Programmskript die 
Konfigurationsdatei\index{Konfigurationsdatei} dieses Projektes zu laden 
und mit \textit{less} anzuzeigen.

Die Funktion \textit{ConfigFileLEC} zeigt die geladene Konfigurationsdatei 
an und fragt dann ab, ob sie korrekt sei. Dann kann entschieden werden, 
ob diese Datei editiert werden soll.

<<ConfigFileLEC1>>=
    set +e
    if [ -f ${ConfigPath}${OrigName} ]
    then
        . ${ConfigPath}${OrigName} # executes config script
        less --LINE-NUMBERS ${ConfigPath}${OrigName}
        if ! whiptail --title "Check config file" \
        --yesno "Is the config file OK?" \
        --yes-button "Yes" --no-button "No" 15 60
<<ConfigFileLEC2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/Checkconfigfile.png}
\caption{Abfrage - Konfigurationsdatei.}
\end{figure}

Wird die Frage, ob die Konfigurationsdatei korrekt ist, verneint, kann sie 
editiert werden. Dies kann mit dem Editor \textit{nano} geschehen oder 
durch die Beantwortung von Fragen. 

Ansonsten geht es weiter mit 
Kapitel~\ref{sec:AuswahlGitBranch}, Seite~\pageref{sec:AuswahlGitBranch}. 
Wenn jedoch nur ein oder kein Branch existiert, geht es mit 
Kapitel~\ref{subsec:OneBranch}, Seite~\pageref{subsec:OneBranch}
weiter.

<<ConfigFileLEC2>>=
        then
            Edit=$(whiptail --title "Edit Config File" \
            --radiolist "How do you like to edit the config file?" \
            15 60 2 "0" "Using Nano" on \
            "1" "Answering questions" off \
            --cancel-button "Exit" 3>&2 2>&1 1>&3)
<<ConfigFileLEC3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/Editconfigfile.png}
\caption{Abfrage - Konfigurationsdatei bearbeiten.}
\end{figure}

Wird keine Editier-Methode angegeben, beendet sich das Programm.

<<ConfigFileLEC3>>=

            if [ -z "${Edit}" ]
            then
                whiptail --title "Bye" --msgbox "Bye" 15 60
                exit
            fi
<<ConfigFileLEC3-1>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/bye.png}
\caption{Programm beendet}
\end{figure}

<<ConfigFileLEC3-1>>=
            if [ ${Edit} -eq 0 ]
            then
                nano --linenumbers --mouse \
                --softwrap ${ConfigPath}${OrigName}
                . ${ConfigPath}${OrigName}
            else
                AskConfig
            fi
        fi
        . ${ConfigPath}${OrigName} # executes config script (another time)
        SetDefaults
<<ConfigFileLEC4>>
@

Soll die Konfigurationsdatei mit dem Editor \textit{nano} bearbeitet 
werden, wird dieser aufgerufen und öffnet sich. Nach der Beendigung 
desselben (mit \textit{STRG-X}) läuft das Programmskript weiter
(Kapitel~\ref{sec:AuswahlGitBranch}, Seite~\pageref{sec:AuswahlGitBranch}).

Soll die Anpassung mittels Abfragen erfolgen, wird die Funktion 
\textit{AskConfig} (s. Kapitel~\ref{subsec:AskConfig}, 
Seite~\pageref{subsec:AskConfig}) aufgerufen, Danach wird die Datei neu 
geschrieben.

Enthält die Konfigurationsdatei hinsichtlich der Plugins keine Daten, so
werden mit der folgenden Funktion Standardwerte gesetzt.

<<SetDefaults>>=
function SetDefaults {
    # Called by ConfigfileLEC

    if [ -z "${WebextFlag}" ]
    then
        WebextFlag=0
    fi

    if [ -z "${PythonFlag}" ]
    then
        PythonFlag=0
    fi

    if [ -z "${JavaFlag}" ]
    then
        JavaFlag=0
    fi

    if [ -z "${MavenPluginFlag}" ]
    then
        MavenPluginFlag=0
    fi
}

<<ConfigFileLEC>>
@

\section{Ändern von Zeilen in der Konfigurationsdatei}
\label{sec:ChangeConfigFile}

Im Skript ist auch eine Funktion enthalten, die es ermöglicht, einzelne 
Werte in der Konfigurationsdatei zu ändern. Hierzu werden der Funktion 
zwei Parameter übergeben, nämlich als Erstes der Bezeichner der Variablen 
und zweitens der neue Wert derselben.

Diese Funktion wird von den Funktionen \textit{BuildNewVersion} 
(Kapi\-tel~\ref{subsec:DownloadSourceCode}, 
Seite~\pageref{subsec:DownloadSourceCode}), \textit{PQMigration} 
(Kapitel~\ref{sec:WorkingwithGbpPq}, Seite~\pageref{sec:WorkingwithGbpPq}), 
\textit{ChangeEntry} (Kapitel~\ref{subsec:ChangeEntry}, 
Seite~\pageref{subsec:ChangeEntry}) und \textit{OwnServer} 
(Kapitel~\ref{sec:NameEigenerGitServer}, 
Seite~\pageref{sec:NameEigenerGitServer}) genutzt.

<<ReplaceConfigLines>>=
function ReplaceConfigLines {
    # Called by BuildNewVersion PQMigration ChangeEntry OwnServer CurSuffix
    
    # This function needs two parameters:
    # First the name of the variable
    # and second it's new value
    ConfProp=$1
    ConfVal=$2

<<ReplaceConfigLines1>>
@

Die Funktion prüft, ob die zu ändernde Zeile in der Konfigurationsdatei
vorhanden ist. Andernfalls wird sie mit der Funktion
\textit{InsertConfigLines} erstellt.

Vor dem Ersetzen mit \textit{sed} sind (ebenfalls mit \textit{sed})
eventuell vorhandene Schrägstriche in der Variablen \textit{ConfVal} zu
maskieren.

<<ReplaceConfigLines1>>=
    set +e
    cprop=$(grep --count ${ConfProp} ${ConfigPath}${OrigName})
    set -e
    if [ ${cprop} -ge 1 ]
    then
        # Masquerade slasches
        ConfVal=$(echo ${ConfVal} | sed 's/\//\\\//g')

        sed --in-place --expression="s/${ConfProp}=.*/${ConfProp}=${ConfVal}/g" \
        ${ConfigPath}${OrigName}
    else
        # InsertConfigLine needs two parameters:
        # name of the variable and new value
        InsertConfigLine ${ConfProp} ${ConfVal}
    fi
}

<<GpgKeyAvailable>>
@

\section{Zeile in Konfigurationsdatei einfügen}
\label{sec:InsertConfigLine}

Die Funktion \textit{InsertConfigLine} fügt eine Zeile in die
Konfigurationsdatei ein. Ihr sind die gleichen Parameter wie der
Funktion \textit{ReplaceConfigLines} zu übergeben. 

<<InsertConfigLine>>=
function InsertConfigLine {
    # Called by ReplaceConfigLines 

    # This function needs two parameters:
    # First the name of the variable
    # and second it's value

    ConfProp=$1
    ConfVal=$2

    echo ${ConfProp}"="${ConfVal} >> ${ConfigPath}${OrigName}

}

<<ReplaceConfigLines>>
@

\section{Auswahl eines \texttt{Git}-Zweiges}
\label{sec:AuswahlGitBranch}

Damit ein Wechsel des \texttt{Git}-Zweiges möglich ist, wird geprüft, ob 
im aktuellen Zweig unversionierte Änderungen vorhanden sind. Diese 
Prüfung erfolgt mit der Funktion \textit{CheckGitStatus} 
(Kapitel~\ref{subsec:CheckGitStatus}, Seite~\pageref{subsec:CheckGitStatus})

Wenn kein Wechsel des \texttt{Git}-Zweiges erforderlich ist, müssen 
Änderungen im Verzeichnis \textit{debian/} nicht zwingend versioniert 
werden. 

Bereits erfolgte Änderungen am Upstream-Code sind mittels 
\textit{git restore} zurückzusetzen.

Existieren mehrere Branches, kann ein Branch ausgewählt werden. 
Existiert nur ein Branch, so wird dieser genannt. Anderfalls wird die Funktion 
\textit{StartTasks} aufgerufen (Kapitel~\ref{sec:GitRepos}, 
Seite~\pageref{sec:GitRepos}).

Diese Funktion kann von der Aufgabenauswahl (Kapitel~\ref{sec:Aufgabenauswahl}, 
Seite~\pageref{sec:Aufgabenauswahl}) aus aufgerufen werden. 

Die Funktion \textit{SelectBranch} wird gegebenenfalls auch beim Bauen 
einer neuen Revision aufgerufen (Kapitel~\ref{subsec:IdentifyDist}, 
Seite~\pageref{subsec:IdentifyDist}).

<<SelectBranch>>=
function SelectBranch {
    # Called by BuildApp TaskSelect BuildNewRevision

    CheckGitStatus
    DebianBranches
<<SelectBranch1>>
@

Nach der Funktion \textit{CheckGitStatus}, die im folgenden Abschnitt
beschrieben wird, wird die Funktion \textit{DebianBranches} zur Ermittlung
der lokalen \texttt{Debian}-Branches im \texttt{Git}-Repositorium aufgerufen
(Kapitel~\ref{subsec:DebianBranches}, 
Seite~\pageref{subsec:DebianBranches}).

\subsection{Prüfung mit \textit{git status}}
\label{subsec:CheckGitStatus}

Die Funktion \textit{CheckGitStatus}, die auch noch an anderen Stelle im 
Pro\-gramm-Skriptes aufgerufen wird, prüft, ob im aktuellen \texttt{Git}-Zweig 
neue oder geänderte Dateien vorhanden sind. Ist dies der Fall, können nämlich 
manche \texttt{Git}-Operationen nicht vorgenommen werden.

Wird dies mittels \textit{git status} festgestellt, wird die Funktion 
\textit{FailureNotice} aufgerufen und eine Möglichkeit 
zur Fehlerbehebung in einem weiteren Terminal eröffnet
(Kapitel~\ref{subsec:FailureNotice}, 
Seite~\pageref{subsec:FailureNotice}). 

Gibt es keine Probleme, geht es weiter mit der Anzeige der vorhandenen
\texttt{Git}-Zweige (Kapitel~\ref{subsec:DialogDebianBranches}, 
Seite~\pageref{subsec:DialogDebianBranches}).

<<CheckGitStatus>>=
function CheckGitStatus {
    # Called by Import2Git BuildWithUscan PQImport
    # PatchesTreatment SelectBranch and itself

    set +e
    # Checks git status
    echo "Notice from CheckGitStatus:" >> ${log}
    echo $(git status) >> ${log}

    if [ ! -z "$(git status --short)" ]
    then
        git status
        FailureNotice "'git status' shows problems\n\
        Please clean up 'git status'"
        if whiptail --title "Check another time?" \
        --yesno "Do you want to check the git status another time?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            CheckGitStatus
        fi
    fi
    set -e
}

<<CheckTags>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/CheckGitAnotherTime.png}
\caption{Abfrage - Weiterer Check?.}
\end{figure}

\subsection{Fehlermeldung und -behebung}
\label{subsec:FailureNotice}

Wird die Funktion \textit{FailureNotice} aufgerufen, erfolgt eine Meldung 
auf dem Terminal und es wird die Möglichkeit eröffnet, Fehler in einem 
anderen Terminal zu beheben.

Dieser Funktion kann beim Aufruf ein spezieller Text als Parameter 
mitgegeben werden. Geschieht dies nicht, wird ein Standardtext 
ausgegeben.

<<FailureNotice>>=
function FailureNotice {
    # Called by PQImport CheckGitStatus RebasePQBranch PQMigration
    # You can call this function with a text as parameter (optional)

    if [ ! "$1" ]
    then
        echo "Failure"
        echo "Something went wrong!"
    else
        for i in $*
        do
            String=${String}" "$i
        done

        echo -e ${String}
    fi
    echo
    echo "Break for fixing it in another terminal"
    echo "After fixing press RETURN to go on!"
    read a
}

<<PQImport>>
@

\subsection{Auswahl der \texttt{Debian}-Branches}
\label{subsec:DebianBranches}

Die Funktion \textit{DebianBranches} ermittelt, welche einschlägigen 
Branches im Git"=Repositorium vorhanden sind.

Hierzu wird zunächst die Funktion \textit{IdentifyBranches} aufgerufen
(Kapitel~\ref{subsec:IdentifyBranches},
Seite~\pageref{subsec:IdentifyBranches}).

<<DebianBranches>>=
function DebianBranches {
    # Called by CreateNewBranch SelectBranch
    # selects the Debian branches
    IdentifyBranches

<<DebianBranches1>>
@

Im Folgenden wird die Auswahl auf die lokalen Debian-Branches begrenzt. 

<<DebianBranches1>>=
    ## Trim branchlist
    bl=$(echo $bl | sed 's/pristine-tar/  /')
    bl=$(echo $bl | sed 's/upstream/  /')
    bl=$(echo $bl | sed 's/HEAD/  /')
    # bl=$(echo $bl | sed 's/remotes\/origin\/.*/  /g')
    # bl=$(echo $bl | sed 's/remotes\/salsa\/.*/  /g')
    # bl=$(echo $bl | sed 's/remotes\/home\/.*/  /g')
    bl=$(echo $bl | sed 's/remotes\/.*/  /g')
}

<<CreateNewBranch>>
@

\subsection{Dialog zur Auswahl eines Branches}
\label{subsec:DialogDebianBranches}

Die Anzeige dieses Dialoges erfolgt nur, wenn es mehrere
\texttt{Debian}-Branches gibt. Der aktuelle Branch wird vorausgewählt.

Existiert nur ein oder kein Branch, geht es im 
Kapitel~\ref{subsec:OneBranch} (Seite~\pageref{subsec:OneBranch}) weiter.

<<SelectBranch1>>=
    ## Create a radiolist with the branch names
    ba=($bl)
    i=1; slct=''
    set +e
    for element in ${ba[*]}
    do
        echo ${element} | grep 'x_' > /dev/null
        if [ $? -eq 0 ]
        then
            if [ "${element}" = "x_" ]
            then
                continue
            else
                ostr="on"
            fi
        else
            ostr="off"
        fi
        slct=${slct}' '"$i"' '"${element}"' '${ostr}' '
        i=$(expr $i + 1)
    done
    set -e

    if [ ${#ba[@]} -gt 1 ]
    then
        ## select branch
        branch=$(whiptail --title "Branch" --radiolist "Select:" \
        15 60 8 ${slct} --cancel-button "Task selection" 3>&2 2>&1 1>&3)
        if [ ! -z "${branch}" ]
        then
            set +e
            branch=$(expr ${branch} - 1)
            set -e
            bName=${ba[$branch]}
            bName=$(echo ${bName} | sed --expression='s/^x_//')
            ## checkout branch
            git checkout ${bName}
            ## Change config file - 
            ## make selected branch to recent one
            ChangeEntry
<<SelectBranch3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SelectBranch.png}
\caption{Auswahl des Debian Zweiges.}
\end{figure}

Statt \textit{debian-stable} wird der für diesen Git-Zweig gewählte 
Name angezeigt.

Ist dies nicht der Fall, wird mit den Klick auf den Button
\textit{Task selection} die Aufgabenauswahl ausgewählt
(Kapitel~\ref{sec:Aufgabenauswahl}, 
Seite~\pageref{sec:Aufgabenauswahl}). Dort kann mit
\textit{Exit} auch das Programm verlassen werden. Mit \textit{Create new branch}
kann dort auch ein neuer \texttt{Git}-Zweig angelegt werden.  

Mit \textit{Ok} wird die Konfigurationsdatei nochmals mit \textit{less}
angezeigt.

\subsection{Eintrag ändern}
\label{subsec:ChangeEntry}

<<ChangeEntry>>=
function ChangeEntry {
    # Called by CreateNewBranch SelectBranch
    set +e
    RecentBranchEntry=$(grep --count 'RecentBranch=' ${ConfigPath}${OrigName})
    set -e

    ## Change RecentBranch entry in config file
    if [ ${RecentBranchEntry} -eq 0 ]
    then
        echo "RecentBranch="${bName} >> ${ConfigPath}${OrigName}
    else
        # ReplaceConfigLines needs two parameters:
        # name of the variable and new value
        ReplaceConfigLines 'RecentBranch' ${bName}
        # bName1=$(echo ${bName} | sed --expression='s/\//\\\//g')
        # sed --in-place --expression=\
        # "s/RecentBranch=.*/RecentBranch=${bName1}/g" \
        # ${ConfigPath}${OrigName}
    fi
    less --LINE-NUMBERS ${ConfigPath}${OrigName}

    ## Set variable
    RecentBranch=${bName}
    echo "Notice from ChangeEntry: The branch is "${RecentBranch} >> ${log}

}

<<DebianBranches>>
@

<<SelectBranch3>>=        
            whiptail --title "This branch was selected" \
            --msgbox "${bName} was selected" 15 60
            echo "${bName} was selected" >> ${log}
            ParseConfig
        fi
<<SelectBranch4>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/SelectedBranch.png}
\caption{Ausgewählter Debian Zweig.}
\end{figure}

In der Nutzeroberfläche geht es weiter mit der Aufgabenauswahl 
(Kapitel~\ref{sec:Aufgabenauswahl}, Seite~\pageref{sec:Aufgabenauswahl}). 

\subsection{Konfiguration einlesen}

Diese Funktion ordnet dem ausgewählten Git-Zweig die 
\texttt{Debian}-Distribution zu, für die das Paket gebaut wird.
(Kapitel~\ref{subsec:DetermineDistribution}, 
Seite~\pageref{subsec:DetermineDistribution})

<<ParseConfig>>=
function ParseConfig {
    # Called by SelectBranch TaskSelect

    # Parse config file for Debian distribution of branch 
    set +e
    vc=$(grep --count ${bName}_Dist ${ConfigPath}${OrigName})
    set -e
    if [ $vc -ge 1 ]
    then
        Search4Dist
    else
        va="sid"
    fi
    RecentBranchD=${va}
    echo "Notice from ParseConfig: The distribution is "${RecentBranchD} >> ${log}

}

<<SelectBranch>>
@

\subsection{Kein oder nur ein Branch existiert}
\label{subsec:OneBranch}

<<SelectBranch4>>=
    elif [ ${#ba[@]} -eq 1 ]
    then
        whiptail --title "Only one branch" \
        --msgbox "There is only one Debian branch: ${ba[0]}" 15 60
<<SelectBranch6>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/OnlyOneBranch.png}
\caption{Es gibt nur einen Git-Zweig}
\end{figure}

Gibt es einen Git-Zweig geht es mit der Aufgabenauswahl weiter 
(Kapitel~\ref{sec:Aufgabenauswahl}, 
Seite~\pageref{sec:Aufgabenauswahl}). Andernfalls erfolgt ein Hinweis.

<<SelectBranch6>>=
    else
        whiptail --title "There is no branch" \
        --msgbox "There is no branch created.\nPlease build a new version." 15 60
    fi
}

<<AddGitServer>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NoBranchCreated.png}
\caption{Kein Zweig erstellt}
\end{figure}

\section{Aufgabenauswahl}
\label{sec:Aufgabenauswahl}

Nachdem die Konfigurationsdatei geladen und geprüft oder erstellt wurde, 
erscheint ein Menü zur Aufgabenauswahl.

Da das Programm modular aufgebaut ist, können die Aufgaben auch einzeln 
ausgewählt werden. Der Bauprozess kann abgebrochen und später wieder 
aufgenommen werden.

<<CommonTasks>>=
function CommonTasks {
    # Called by BuildApp TaskSelect

   Task=$(whiptail --title "Tasks:" \
    --radiolist "What do you like to do? " 17 60 9 \
      "2" "Build a new version of a package" off \
      "3" "Build a new debian revision" on \
      "4" "Rebuilding a revision" off \
      "5" "Running lintian and uscan" off \
      "6" "Uploading only (build again if necessary)" off \
      "7" "Create new branch" off \
      "8" "Select branch" off \
      "9" "Set name or IP of own git server" off \
     "10" "Create a debdiff" off \
    --cancel-button "Exit" 3>&2 2>&1 1>&3)

    if [ -z "${Task}" ]
    then
        exit
    fi
    TaskSelect
}

<<AskOrigName>>
@

\begin{figure}[!h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/Aufgabenauswahl.png}
\caption{Aufgabenauswahl.}
\end{figure}

Zur Auswahl stehen zunächst der Bau einer neuen Version 
(Kapitel~\ref{chap:BuildNewVersion}, 
Seite~\pageref{chap:BuildNewVersion}) und einer neuen Revision. 
Als \textit{default} geht es mit dem Bauen einer neuen 
\texttt{Debian}-Revision (Kapitel~\ref{chap:NeueRevisionBauen}, 
Seite~\pageref{chap:NeueRevisionBauen}) weiter.

Soll eine neue Version gebaut werden, wird gefragt, ob zunächst Änderungen
von \textit{salsa.debian.org} heruntergeladen werden sollen
(Kapitel~\ref{sec:PullFromSalsa}, Seite~\pageref{sec:PullFromSalsa}).

In der Funktion \textit{ClassicalOrUscan} (Kapitel~\ref{sec:DownloadTools}, 
Seite~\pageref{sec:DownloadTools}) wird abgefragt, auf welche Weise das
Herunterladen des Upstream-Quellcodes erfolgen.

Nach dem Bauen können die Pakete geprüft werden
(Kapitel~\ref{chap:Ueberpruefungen}, 
Seite~\pageref{chap:Ueberpruefungen}).

Der nächste Menüpunkt betrifft das Hochladen (Kapitel~\ref{chap:Uploading}, 
Seite~\pageref{chap:Uploading}).

Ferner kann auch ein neuer \texttt{Git}-Zweig angelegt werden,
beispielsweise auch für Backports, gearbeitet wird
(Kapitel~\ref{sec:NeuenBranchErstellen}, 
Seite~\pageref{sec:NeuenBranchErstellen}).

Sind mehrere \texttt{Git}-Zweige vorhanden, kann einer von Ihnen ausgewählt
werden (Kapitel~\ref{sec:AuswahlGitBranch},
Seite~\pageref{sec:AuswahlGitBranch}). 

Schließlich kann man auch einen eigenen Git-Server in den Arbeitsablauf
einbinden  (Kapitel~\ref{sec:NameEigenerGitServer},
Seite~\pageref{sec:NameEigenerGitServer}).

Die folgenden Zeilen des Programmskripts dienen der Ablaufsteuerung. 
Eine aufgerufene Funktion ändert an ihrem Ende die Variable \textit{Task},
so dass eine der folgenden if-Klauseln zutrifft. 
Aus diesem Grund können die folgenden Zeilen nicht durch eine Case-Anweisung 
ersetzt werden.

Die Kette von If-Anweisungen gibt die Möglichkeit, eine Bedingung nach der 
anderen abzuarbeiten, da die aufgerufene Funktion an das Ende der If-Anweisung 
zurückkehrt, von der sie aufgerufen wurde. Eine Case-Anweisung wird mit 
dem Aufruf der abzuarbeitenden Funktion beendet.

Der Aufruf der entsprechenden Funktionen erfolgt in der genannten Weise
wiederum durch die Funktion \textit{TaskSelect}.

Mit dem folgenden Aufruf wird das Bauen einer neuen Version aufgerufen
(Kapitel~\ref{sec:PullFromSalsa}, Seite~\pageref{sec:PullFromSalsa}).

<<TaskSelect3>>=
    ## Common tasks
    rcts=0 # ReCall TaskSelect flag

    # Building a new version
    if [ $Task -eq 2 ]
    then
        if [ ${NoPull} -eq 0 ]
        then
            PullFromSalsa
        fi
    ClassicalOrUscan # and then download new version
    fi

<<TaskSelect4>>
@

Oder es geht weiter mit dem Bauen einer neuen \texttt{Debian}-Revision
(Kapitel~\ref{chap:NeueRevisionBauen}, 
Seite~\pageref{chap:NeueRevisionBauen}). Dies entspricht dem
voreingestsellten Wert.

<<TaskSelect4>>=
    # Building a new revision
    if [ $Task -eq 3 ]
    then
        BuildNewRevision
    fi

    # Rebuilding a revision
    if [ $Task -eq 4 ]
    then
        ParseConfig
        AskDist
        SBuildOrPBuilder 0
        Task=5 # Running Tests
    fi

<<TaskSelect5>>
@

Nach dem Bauen einer neuen Revision ist diese zu testen.
(Kapitel~\ref{chap:Ueberpruefungen}, Seite~\pageref{chap:Ueberpruefungen})
weiter. Dies geschieht mittels \textit{lintian}
(Kapitel~\ref{sec:RunningLintian},
Seite~\pageref{sec:RunningLintian}) und \textit{uscan}
(Kapitel~\ref{sec:uscan}, Seite~\pageref{sec:uscan}).

<<TaskSelect5>>=
    # Running lintian and uscan
    if [ $Task -eq 5 ]
    then
        RunningTests
    fi
<<TaskSelect6>>
@

Mit dem nächsten Schritt wird die Funktion \textit{PrepareUploading}
aufgerufen (Kapitel~\ref{chap:Uploading}, Seite~\pageref{chap:Uploading}).
Darin wird zunächst überprüft, ob die Datei \textit{debian/changelog}
schon für eine Veröffentlichung \index{Veröffentlichung} vorbereitet ist.
Andernfalls wird dies noch durchgeführt.

<<TaskSelect6>>=
    # Uploading the package
    if [ $Task -eq 6 ]
    then
        PrepareUploading
    fi

<<TaskSelect7>>
@

Der folgende Abschnitt ist notwendig, um für eine abweichende Distribution
zu bauen. Dies bezieht sich auf Debian-Backports, Debian-Proposed-Updates 
für Stable und eventuell für Oldstable. Gegebenenfalls wird dies 
auch benötigt, um für einen Ubuntu-Zweig ein Paket bereitzustellen. (Siehe 
auch Kapitel~\ref{chap:BuildBeyondSid}, Seite~\pageref{chap:BuildBeyondSid})
 
<<TaskSelect7>>=
    # Create new branch
    # (e.g. for backports or proposed-updates)
    if [ $Task -eq 7 ]
    then
        CreateNewBranch
        rcts=1
    fi
    
    # Select branch
    if [ $Task -eq 8 ]
    then
        SelectBranch
        rcts=1
    fi

    # Set name or IP of own git server
    if [ $Task -eq 9 ]
    then
        OwnServer
        rcts=1
    fi

    # Create a debdiff
    if [ $Task -eq 10 ]
    then
        DebDiff 0
        rcts=1
    fi

<<TaskSelect9>>
@
\chapter{Bauen einer neuen Version}
\label{chap:BuildNewVersion}

In diesem Kapitel werden die Schritte beschrieben, die zur Erstellung des 
\texttt{Debian}-Quellcode-Paketes (\textit{*.orig.tar.(g|x)z})
(Kapitel~\ref{chap:DebianPackage}, Seite~\pageref{chap:DebianPackage})
führen. Dies erfolgt nach dem Start des Programmskriptes
(Kapitel~\ref{sec:Intro}, Seite~\pageref{sec:Intro}).

Das Programmskript ermöglicht auf verschiedenen Weisen, den
Upstream-Quellcode zu erlangen. Zwei Möglichkeiten wurden bereits
beschrieben, nämlich das Klonen von \textit{salsa.debian.org}
(Kapitel~\ref{sec:SalsaDebianOrg}, Seite~\pageref{sec:SalsaDebianOrg})
sowie der Import eines \texttt{Debian}-Quellcode-Paketes
(Kapitel~\ref{sec:ImportPackage}, Seite~\pageref{sec:ImportPackage})

Zwei weitere Möglichkeiten werden im Folgenden beschrieben
(Kapitel~\ref{sec:DownloadTools}, Seite~\pageref{sec:DownloadTools}).
Nach der Ausführung von \textit{mk-origtargz} zum Erstellen des
\texttt{Debian}-Quellcode-Paketes folgt die Integration des Quellcodes
in das lokale Git-Repositorium (Kapitel~\ref{subsec:GbpImportOrig}, 
Seite~\pageref{subsec:GbpImportOrig}).

Zunächst wird jedoch die Möglichkeit eröffnet, eventuelle Änderungen im
Salsa-Repositoriums des Paketes herunterzuladen, was manchmal sinnvoll
ist.

\section{Änderungen von \textit{Salsa} herunterladen}
\label{sec:PullFromSalsa}

Es kann besonders bei team"=betreuten Paketen vorkommen, dass andere 
Team"=Mitglieder Änderungen im Git-Repositorium auf \textit{salsa.debian.org} 
bereitstellen. Für die weiteren Arbeiten an diesem Repositorium ist es 
nun zwingend erforderlich, diese Änderungen auch ins lokale Repositorium 
zu übernehmen.

Dies kann erfolgen mit
\begin{verbatim}
 gbp pull --all salsa   
\end{verbatim}

Wenn dies zu Problemen führt, können die einzelnen Branches auch mit 
\begin{verbatim}
 git checkout <BranchName>
 git pull salsa <BranchName>   
\end{verbatim}

aktualisiert werden.

<<PullFromSalsa>>=
function PullFromSalsa {
    # Called by TaskSelect
    
    cd ${GitPath}
    set +e
    if git remote --verbose | grep --quiet 'salsa'
    then
        if whiptail --title "Pull from Salsa?" \
        --yesno "Do you like to pull possible changes from salsa?" \
        --yes-button "Yes" --no-button "No" 15 60
<<PullFromSalsa1>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/PullFromSalsa.png}
\caption{Herunterladen von salsa.debian.org}
\end{figure}

Dazu wird dann noch das Passwort für den SSH-Schlüssel abgefragt, mit dem
auf \textit{salsa.debian.org} zugegriffen werden kann.

<<PullFromSalsa1>>=
        then
            echo "RecentBranch: "$(git branch) >> ${log}
            gbp pull --all salsa
            if [ $? -eq 0 ]
            then
                whiptail --title "Pulled successfully!" \
                --msgbox "'gbp pull --all salsa' successfully executed" 15 60
<<PullFromSalsa2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/PullSuccessful.png}
\caption{Erfolgreich heruntergeladen von salsa.debian.org}
\end{figure}

<<PullFromSalsa2>>=
            else
                FailureNotice
            fi
        fi
    fi
    set -e
}

<<CloneFromSalsa>>
@

Danach wird die Funktion \textit{ClassicalOrUscan}
(Kapitel~\ref{sec:DownloadTools}, 
Seite~\pageref{sec:DownloadTools}) aufgerufen.

\section{Werkzeuge zum Herunterladen der Upstream-Sourcen}
\label{sec:DownloadTools}

Zum Bauen eines \texttt{Debian}-Paketes wird zunächst der Quellcode des 
Up\-stream-Pro\-jektes benötigt. Dieser kann auf verschiedene Arten erlangt 
werden. 

Das Herunterladen des Quellcodes mit \textit{wget} ist die klassische 
Methode (Kapitel~\ref{sec:BauenNeueVersion}, 
Seite~\pageref{sec:BauenNeueVersion}). Dieser Weg ist beim ersten Bauen 
eines neuen Paketes zu wählen. 

Es kommt vor, dass Upstream kein Quellcode-Archiv zur Verfügung stellt. 
Stattdessen findet man den Quellcode bei \textit{Github} oder ähnlichen 
Hostern. Dies stellt besondere Anforderungen an den Betreuer eines 
\texttt{Debian}-Paketes. 

Alleine schon, um \textit{reproducible} bauen zu können, muss ein 
Tar-Archiv des Upstream-Quellcodes bereitgestellt werden. Dies muss ohne 
Netzzugriff auf Externe Ressourcen möglich sein.

Diese Methode ist auch zu wählen, wenn ein 
bestimmter Stand des Upstream-Codes aus einem Git-Repositorium (z.B. 
Github o.ä.) verwendet werden soll. 

Existieren jedoch bereits eine Datei \textit{debian/watch} und andere 
Dateien im Verzeichnis \textit{debian/}, kann hierfür 
auch \textit{uscan} (Kapitel~\ref{sec:ImportWithUscan}, 
Seite~\pageref{sec:ImportWithUscan}) eingesetzt werden. Ein herunterladen
mit \textit{uscan} empfiehlt sich dann, wenn die Datei \textit{debian/watch}
einen Eintrag \textit{uversionmangle=} enthält.

Kann \textit{uscan} die neue Version nicht identifizieren, muss die 
neue Version manuell oder per \textit{wget} bereitgestellt werden.
Gleiches gilt, wenn \textit{uscan} die neue Version zwar identifizieren
kann, ein Herunterladen aber am Aufbau der Adresse zum Herunterladen
scheitert. 

Diese Möglichkeiten werden vom Programmskript alternativ angeboten.

Außerdem gibt es noch die Möglichkeit \textit{get-orig-source} in 
\textit{debian/rules} zu verwenden. 

<<ClassicalOrUscan>>=
function ClassicalOrUscan {
    # Called by PullFromSalsa

    if [ ! -f ${GitPath}/debian/watch ]
    then
        BuildNewVersion
        return
<<ClassicalOrUscan1-1>>
@

Es wird geprüft, ob in der Datei \textit{debian/watch}
\textit{addons.thunderbird.net} oder \textit{addons.mozilla.org} als
Quelle aufgeführt werden. Von dort ist nämlich kein Herunterladen mit
uscan möglich. Denn die Adresse zum Herunterladen enthält dort zusätzlich
zur Versionbezeichnung eine nicht vorhersehbare ID.

<<ClassicalOrUscan1-1>>=

    else
        set +e
        # Download from Mozilla repos is not possible with uscan
        if grep --quiet "addons.thunderbird.net" ${GitPath}/debian/watch
        then
            whiptail --title "Thunderbird Repository" \
            --msgbox "From addons.thunderbird.net \nyou can't download with uscan" \
            15 60
            BuildNewVersion
            set -e
            return
        fi

<<ClassicalOrUscan2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/ThunderbirdRepo.png}
\caption{Kein Herunterladen per uscan von thunderbird.net}
\end{figure}

<<ClassicalOrUscan2>>=
        if grep --quiet "addons.mozilla.org" ${GitPath}/debian/watch
        then
            whiptail --title "Mozilla Repository" \
            --msgbox "From addons.mozilla.org \nyou can't download with uscan" \
            15 60
            BuildNewVersion
            set -e
            return
        fi
        set -e

<<ClassicalOrUscan3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/MozillaRepo.png}
\caption{Kein Herunterladen per uscan von mozilla.org}
\end{figure}

Ist kein Herunterladen mit \textit{uscan} möglich, wird die Funktion
\textit{BuildNewVersion} zum Herunterladen auf klassische Weise aufgerufen
(Kapitel~\ref{subsec:DownloadSourceCode}, 
Seite~\pageref{subsec:DownloadSourceCode})

Erscheint ein Herunterladen mit \textit{uscan} möglich, wird der Benutzer
gefragt, ob er auf \enquote{klassische} Weise oder mit \textit{uscan} die neue 
Version herunterladen möchte.

<<ClassicalOrUscan3>>=
        NVTask=$(whiptail --title "Classical download or uscan" \
        --radiolist "How do you want to download the new version? " 17 60 9 \
         "0" "using the classical way" on \
         "1" "using uscan" off --cancel-button "Exit" 3>&2 2>&1 1>&3)

<<ClassicalOrUscan5>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/ClassicalOrUscan.png}
\caption{Download - klassisch oder mit uscan}
\end{figure}

<<ClassicalOrUscan5>>=
        if [ -z "${NVTask}" ]
        then
            exit
        fi
        case "$NVTask" in
            0) BuildNewVersion;;
            1) BuildWithUscan;; 
        esac
    fi
}

<<PullFromSalsa>>
@

Existiert die Datei \textit{debian/watch} nicht, muss der Benutzer die neue 
Version auf klassische Weise herunterladen.

Wird statt des klassischen Weges das Herunterladen mit \textit{uscan} 
ausgewählt, geht es mit Kapitel~\ref{sec:ImportWithUscan} 
(Seite~\pageref{sec:ImportWithUscan}) weiter.

\section{Herunterladen auf klassische Weise}
\label{sec:BauenNeueVersion}

In der Regel wird der Quellcode einer Software als Archiv bereitgestellt. 
Dazu stehen verschiedene Formate zur Verfügung. Die Verwendung derselben 
wird im Folgenden beschrieben.

\subsection{Archiv-Formate}
\label{subsec:ArchiveFormat}

Für die Nutzung mit \textit{git-buildpackage} wird zwingend ein 
Orig-Tar-Archiv als Quelle benötigt. Dieses darf nur die Formate 
\textit{*.tar.gz} 
oder \textit{*.tar.xz} haben. Das Orig-Tar-Archiv wird auch in 
das \texttt{Debian}-Archiv hochgeladen.

Zur Nutzung unter Linux wird meist ein \textit{*.tar.gz} bereitgestellt. 
Manchmal ist dies auch ein \textit{*.tar.xz}. 

Für betriebssystemübergreifende Software wird der Quellcode gerne als 
Zip-Archiv bereitgestellt. Ein Zip-Archiv wird deshalb in ein 
\textit{.tar.xz} umgepackt. Dazu gibt es das Tool 
\textit{mk-origtargz} (Kapitel~\ref{subsec:mkorigtargz}, 
Seite~\pageref{subsec:mkorigtargz}).

Zusätzlich kann in der zum Projekt gehörigen Datei 
\textit{debian/gbp.conf} angegeben werden, welches Archiv-Format 
verwendet werden soll. Wird hier als Kompression 
\textit{compression = xz} angegeben, muss auch ein \textit{*.tar.gz} in ein 
\textit{*.tar.xz} umgewandelt werden. Dies wird dann in der Datei 
Datei \textit{debian/README.source} dokumentiert 
(Kapitel~\ref{subsec:ReadmeSource}, 
Seite~\pageref{subsec:ReadmeSource}).

Mit \textit{mk-origtargz} können der Tarball der Originalautoren umbenannt, 
optional die Komprimierung geändert und unerwünschte Dateien entfernt 
werden.

\subsection{Herunterladen des Quellcodes}
\label{subsec:DownloadSourceCode}

Zunächst wird also der Quellcode heruntergeladen.

<<BuildNewVersion>>=
function BuildNewVersion {
    # Called by ClassicalOrUscan

    echo "Building a new version" >> ${log}

    UpstreamSourceName=$(whiptail --title "Name of the source" \
    --inputbox "Please insert the file name of the upstream source version\n \
    to be downloaded or copied (including version and suffix):\n" \
    --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

<<BuildNewVersion3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/EditSource.png}
\caption{Name des Quellcode-Paketes}
\end{figure}

Es ist der Name des Quellcode-Paketes einzugeben.

<<BuildNewVersion3>>=
    if [ -z "${UpstreamSourceName}" ]
    then
        exit
    fi

<<BuildNewVersion4>>
@

Das Programm erledigt das Herunterladen der Upstream-Version. 
Ist diese bereits in den Projektpfad heruntergeladen worden, kann das
Programm auch damit weiter arbeiten.

<<BuildNewVersion4>>=
    cd ${PrjPath}
    if whiptail --title "Should the source be downloaded?" \
    --yesno "Should $UpstreamSourceName\n \
    be downloaded from the upstream page?" \
    --defaultno --yes-button "Yes" --no-button "No" 15 60
<<BuildNewVersion4-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DownloadOrCopy.png}
\caption{Herunterladen (oder kopieren)?}
\end{figure}

Wird die Frage verneint, geht es mit Kopieren
(Kapitel~\ref{subsubsec:CopyingSource}, 
Seite~\pageref{subsubsec:CopyingSource}) weiter.

\subsubsection{Herunterladen}
\label{subsubsec:DownloadSource}

<<BuildNewVersion4-1>>=
    then
        if [ -z "${DownloadUrl}" ]
        then
            DownloadUrl=$(whiptail --title "Insert URL for download" \
            --inputbox "Please insert the complete\n \
            URL to download ${UpstreamSourceName}\n(with 'https://'\n \
            or so and the name of the archive):" \
            --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
        fi

<<BuildNewVersion4-2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/InsertForDownload.png}
\caption{Link für Download eingeben}
\end{figure}

<<BuildNewVersion4-2>>=
        if [ -z "${DownloadUrl}" ]
        then
            exit
        else
            changeflag=1
        fi

<<BuildNewVersion5>>
@

Vorsorglich wird nachgefragt, ob die URL zum Herunterladen des Quellcodes 
korrekt ist.

<<BuildNewVersion5>>=
        if ! whiptail --title "DownloadUrl" \
        --yesno "The complete URL to download ${UpstreamSourceName} is\n \
        ${DownloadUrl}" --yes-button "Yes" --no-button "No" 15 60
<<BuildNewVersion5-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DownloadURLCorrect.png}
\caption{Download-URL korrekt?}
\end{figure}

<<BuildNewVersion5-1>>=
        then
            DownloadUrl=$(whiptail --title "Complete URL" \
            --inputbox "Real complete URL to download ${UpstreamSourceName}\n \
            (with 'https://' or so and the name of the archive):" \
            --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)
        fi

<<BuildNewVersion5-2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CorrectDownloadURL.png}
\caption{Korrekte Download-URL}
\end{figure}

<<BuildNewVersion5-2>>=
        if [ -z "${DownloadUrl}" ]
        then
            exit
        else
            changeflag=1
        fi
<<BuildNewVersion6>>
@

Die neue URL zum Herunterladen des Quellcodes wird in die Konfigurationsdatei 
eingetragen. Danach erfolgt das Herunterladen mittels \textit{wget}. 

Dann wird die Möglichkeit eröffnet, auch die Signaturdatei 
herunterzuladen und zu prüfen (Kapitel~\ref{subsec:CheckSignature}, 
Seite~\pageref{subsec:CheckSignature}).

<<BuildNewVersion6>>=
        # Write download URL into config file
        if [ $changeflag -eq 1 ]
        then
            ReplaceConfigLines 'DownloadUrl' ${DownloadUrl} 
            changeflag=0
        fi

        # getting sources using wget
        wget --verbose $DownloadUrl &&
        echo -e "The sources were pulled from\n${DownloadUrl}\n \
        by wget." >> ${log}
        
        if whiptail --title ".asc file?" \
        --yesno "Do you want to download an .asc file, too?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            DownloadAscFile
        fi
<<BuildNewVersion6-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DownloadAscFile.png}
\caption{*asc Datei herunterladen}
\end{figure}

\subsubsection{Kopieren des Quellarchivs}
\label{subsubsec:CopyingSource}

Das Programmskript teilt mit, wohin die Upstream-Version kopiert werden
soll.

<<BuildNewVersion6-1>>=
    else
        whiptail --title "Please copy the source code now" \
        --msgbox "Please copy ${UpstreamSourceName} to ${PrjPath}!" 15 60
<<BuildNewVersion6-2>>
@
\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CopyToPrjPath.png}
\caption{Aufforderung zum Kopieren}
\end{figure}

Das Programmskript fragt, ob das Kopieren erledigt wurde. Wird diese
Frage verneint, beendet sich das Programmskript.

<<BuildNewVersion6-2>>=
        if ! whiptail --title "Copy finished?" \
        --yesno "Was ${UpstreamSourceName} copied to ${PrjPath}?" \
        --yes-button "Yes" --no-button "No" 15 60
<<BuildNewVersion6-3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CopyFinished.png}
\caption{Kopieren erledigt?}
\end{figure}


<<BuildNewVersion6-3>>=
        then
            echo "Exit" >> ${log}
            whiptail --title "Bye" --msgbox "Bye" 15 60
            exit
        fi
<<BuildNewVersion6-4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/bye.png}
\caption{Programm beenden}
\end{figure}

<<BuildNewVersion6-4>>=
    fi

    # Identify the type of the upstream archive by suffix
    CutSuffix

<<BuildNewVersion7>>
@

Nun wird die Komprimierung und die Versionsnummer
(s. Kapitel~\ref{subsec:IdentifyUpstreamVersion}
(Seite~\pageref{subsec:IdentifyUpstreamVersion}) ermittelt. Dies wird
auch insgesamt als \textit{Suffix} bezeichnet. Ist hier alles in Ordnung
geht es im Kapitel~\ref{subsec:ExcludeFiles}
(Seite~\pageref{subsec:ExcludeFiles}) weiter.

\subsection{Komprimierung ermitteln}

Welche Komprimierung \textit{mk-origtargz} automatisch wählt, hängt vom 
Dateityp des Upstream-Archivs ab. Dabei wird die Dateinamenserweiterung 
mit einer Liste sinnvoller Dateitypen verglichen.

<<CutSuffix>>=
function CutSuffix {
    # Called by BuildNewVersion

    # List of reasonable suffixes
    typea=('.tar.gz' '.tar.xz' '.tgz' '.zip' '.oxt' '.xpi'\
     '.jar' '.tar.bz2' 'tar.lzma')

<<CutSuffix1>>
@

Die Dateitypen \textit{.oxt}, \textit{.xpi} und \textit{.jar} beschreiben 
allesamt \textit{.zip}-Archive.

<<CutSuffix1>>=
    KnownTyp=0
    set +e
    for element in ${typea[*]}
    do
        if echo ${UpstreamSourceName} | grep ${element} > /dev/null
        then
            echo "Notice from CutSuffix: The suffix of the upstream \
            file is "${element} >> ${log}
            UpstreamSuffix=${element}
            RecentUpstreamSuffix=$(echo ${UpstreamSuffix} | sed --expression s/^.//)
            ReplaceConfigLines 'RecentUpstreamSuffix' ${UpstreamSuffix}
            KnownTyp=1
        fi
    done
    set -e

    if [ ${KnownTyp} -ne 1 ]
    then
        echo "Notice from CutSuffix: Unknown suffix" >> ${log}
        if ! whiptail --title "Unknown suffix" \
        --yesno "The suffix of ${UpstreamSourceName} is not listed.\n \
        Continue anyway?" --defaultno --yes-button "Yes" \
        --no-button "No" 15 60
        then
            exit
        fi
    fi
}

<<Name2Version>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/UnknownSuffix.png}
\caption{Unbekannte Endung}
\end{figure}

\subsection{Upstream-Version ermitteln}
\label{subsec:IdentifyUpstreamVersion}

<<BuildNewVersion7>>=
    # Identify the upstream version number
    Name2Version

<<BuildNewVersion8>>
@

Die Funktion \textit{Name2Version} versucht aus dem Namen des
Upstream-Paketes die Versionsbezeichnung zu extrahieren.

<<Name2Version>>=
function Name2Version {
    # Called by BuildNewVersion
    # Extracts version from uptream archive name
    Suffix=$(echo ${UpstreamSuffix} | sed --expression='s/\./\\\./g')
    Version1=$(echo ${UpstreamSourceName} | sed --expression="s/${Suffix}$//" | \
    sed --expression="s/.*${SourceName}//gI" | \
    sed --expression='s/-//' | sed --expression='s/v//')
    if [ -z ${Version1} ]
    then
        Version1="0.0.0" # Default value
    fi
}

<<GbpConfIntegration>>
@

Misslingt dies, wird die Versionsbezeichnung auf \textit{0.0.0} gesetzt.

Die ermittelte (oder nicht ermittelte) Versionsbezeichnung wird dem
Nutzer angezeigt. Der Nutzer hat zu entscheiden, ob die angezeigte
Versionsbezeichnung die korrekte ist. Zu beachten ist das
Versionierungsschema \index{Versionierungsschema}
(Kapitel~\ref{sec:schema}, Seite~\pageref{sec:schema}).

<<BuildNewVersion8>>=
    if ! whiptail --title "Version" \
    --yesno "You want to build version ${Version1}.\n\n \
    It must be a correct version number - not more!" \
    --yes-button "Yes" --no-button "No" 15 60
<<BuildNewVersion9>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CorrectVersion.png}
\caption{Ist dies die korrekte Version?}
\end{figure}

Ist die Versionsbezeichnung korrekt, wird die Funktion \textit{ExcludeFiles}
aufgerufen (s. Kapitel~\ref{subsec:ExcludeFiles}
Seite~\pageref{subsec:ExcludeFiles})

Es kann vorkommen, dass das Programmskript die korrekte Versionsbezeichnung
nicht ermitteln kann. Dann kann in der folgenden Dialogbox die
Versionsbezeichnung eingegeben werden. Damit sie auch weiterverarbeitet
werden kann, darf die Versionsbezeichnung neben den Ziffern nur Punkte
enthalten. Sie darf ferner die Angabe enthalten, ob es sich um einen
\textit{Release-Kandidaten}, eine \textit{Beta-} oder
\textit{Alpha}-Version handelt. Zulässig ist auch die Angabe, ob es sich
um einen bestimmten \textit{Commit} aus dem \texttt{Git}-Repositorium
handelt.

<<BuildNewVersion9>>=
    then
        Version1=$(whiptail --title "Version" \
        --inputbox "Name of the upstream version: ${UpstreamSourceName}\n \
        Which version (without repack identifiers and without revision)\n \
        of the package ${SourceName} should be built?" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)

<<BuildNewVersion10>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/WhichVersionBuilt.png}
\caption{Welche Version soll gebaut werden?}
\end{figure}

<<BuildNewVersion10>>=
        if ! whiptail --title "Version" \
        --yesno "Do you really want to build version ${Version1}." \
        --yes-button "Yes" --no-button "Exit" 15 60
<<BuildNewVersion11>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CorrectVersionBuilt.png}
\caption{Wird korrekte Version gebaut?}
\end{figure}

<<BuildNewVersion11>>=
        then
            echo "Exit" >> ${log}
            whiptail --title "Bye" --msgbox "Bye" 15 60
            exit
        fi
<<BuildNewVersion11-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/bye.png}
\caption{Programm beenden}
\end{figure}

Die Funktion \textit{ExcludeFiles} dient dazu, Dateien aus dem
Upstream-Archiv von der Übernahme in die Datei \textit{*.orig.tar.xz}
ausschließen.

Sollen keine Dateien ausgeschlossen werden, geht es mit
Kapitel~\ref{subsec:mkorigtargz}
(Seite~\pageref{subsec:mkorigtargz})

<<BuildNewVersion11-1>>=
    fi

    ExcludeFiles

    echo "Version "${Version1}${ESuffix}" of the package "${PackName}" \
    should be built." >> ${log}

<<BuildNewVersion12>>
@

\subsection{Dateien aus Upstream-Archiv ausschließen}
\label{subsec:ExcludeFiles}

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

<<ExcludeFiles>>=
function ExcludeFiles {
    # Called by BuildNewVersion

<<ExcludeFiles1>>
@

Anzugeben ist, dass Dateien auszuschließen sind. 
Dazu ermittelt das Programmskript, woher die Informationen zum Ausschluss von 
Dateien erfolgen sollen. Dies ist hier die Datei \textit{debian/copyright}.

Nun wird geprüft, ob eine Datei \textit{debian/copyright} existiert.

<<ExcludeFiles1>>=
    # Checks whether debian/copyright contains a section Files-Excluded
    gitflag=0
    exflag=0
    crflag=0
    if [ -f ${GitPath}/debian/copyright ]
    then
<<ExcludeFiles2>>
@

Sodann wird geprüft, ob sie den Ausdruck \textit{Files-Excluded} enthält. 
In diesem Fall wird abgefragt, ob die Datei \textit{debian/copyright} 
editiert werden soll.

<<ExcludeFiles2>>=
        crflag=1
        set +e
        grep 'Files-Excluded' ${GitPath}/debian/copyright > /dev/null
        if [ $? -eq 0 ]
        then
            exflag=1
            whiptail --title "Copyright file contains Files-Excluded" \
            --msgbox "debian/copyright contains section Files-Excluded." 15 60
            less --LINE-NUMBERS ${GitPath}/debian/copyright
        fi
        set -e
    fi

<<ExcludeFiles3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/CopyrightExcluded.png}
\caption{Datei debian/copyright enthält Abschnitt Files-Excluded}
\end{figure}

<<ExcludeFiles3>>=
    if whiptail --title "Exclude files from upstream source" \
    --yesno "Do you want to exclude files from upstream source?" \
    --defaultno --yes-button "Yes" --no-button "No" 15 60
<<ExcludeFiles3-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ExcludeFiles.png}
\caption{Dateien ausschließen}
\end{figure}

Wird kein Ausschluss von Dateien benötigt, wird im Hintergrund
\textit{mk-origtargz} ausgeführt.(Kapitel~\ref{subsec:mkorigtargz},
Seite~\pageref{subsec:mkorigtargz}). Dann geht es in 
Kapitel~\ref{subsec:Link2File}, (Seite~\pageref{subsec:Link2File}) weiter.

<<ExcludeFiles3-1>>=
    then
        if [ $crflag -eq 1 ]
        then
            if whiptail --title "Copyright file exitst" \
            --yesno "debian/copyright exists.\nDo you want to edit it?" \
            --yes-button "Yes" --no-button "No" 15 60

<<ExcludeFiles3-2>>
@


\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/EditDebianCopyright.png}
\caption{Soll debian/copyright editiert werden?}
\end{figure}

Wenn die Frage bejaht wird, wird die Datei \textit{debian/copyright} im
Editor geöffnet.

<<ExcludeFiles3-2>>=
            then
                gitflag=1
                nano --linenumbers --mouse --softwrap ${GitPath}/debian/copyright
            fi
            AddOpt="  --copyright-file "${SourceName}"/debian/copyright"

<<ExcludeFiles4>>
@

Nachdem die Datei \textit{debian/copyright} editiert wurde oder wenn sie
nicht editiert werden soll, geht es mit der Frage nach dem Suffix zur
Anzeige des Ausschlussgrundes weiter (Seite~\pageref{fig:ExcludeSuffix}).

Wenn die Datei \textit{debian/copyright} nicht existiert, wird die Funktion
\textit{SpecialExcludeFile} aufgerufen. 
In dieser Funktion wird, sofern nicht - wie im vorliegenden Fall - die 
Angaben in der Datei \textit{debian/copyright} verwandt werden, nach 
einer speziellen Datei gefragt, die die Namen der auszuschließenden 
Dateien im Format DEP-5\footnote{DEP-5\cite{DEP-5}} enthält.

<<ExcludeFiles4>>=
        else
            SpecialExcludeFile
        fi

<<ExcludeFiles5>>
@

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

Die Funktion \textit{ExcludeFiles} ruft hierfür die folgende Funktion auf. 
In dieser Funktion wird nach einer speziellen Datei gefragt, die die Namen 
der auszuschließenden Dateien im Format DEP-5 enthält.

<<SpecialExcludeFile>>=
function SpecialExcludeFile {
    # Called by ExcludeFiles
    if [ -z "${ExcludeFile}" ]
    then
        ExcludeFile=$(whiptail --title "Name of exclude file" \
        --inputbox "Please insert name of the exclude file:" \
        --cancel-button "Exit" 15 60 3>&2 2>&1 1>&3)

<<SpecialExcludeFile1>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/InsertNameExcludedFile.png}
\caption{Name der Datei mit den auszuschließenden Dateien eingeben.}
\end{figure}

<<SpecialExcludeFile1>>=
        if [ -z "${ExcludeFile}" ]
        then
            exit
        fi
        echo 'ExcludeFile='${ExcludeFile} >> ${ConfigPath}${OrigName}
    else
        whiptail --title "Exclude file name" \
        --msgbox "The name of the exlude file is ${ExcludeFile}" \
        15 60
    fi
    AddOpt=" --copyright-file "${ExcludeFile}
}

<<ExcludeFiles>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NameExcludeFile.png}
\caption{Name der Datei mit den auszuschließenden Dateien.}
\end{figure}


Dann erfragt das Programmskript den Anhang zur Ergänzung der 
Upstream"=Versionsbezeichnung\index{Versionsbezeichnung}.

Oft ist hier als Anhang \textit{+dfsg} zu wählen, um den 
Grund des Ausschlusses zu dokumentieren 
(s.a Kapitel~\ref{subsubsec:BenamungPakete}, 
Seite~\pageref{subsubsec:BenamungPakete})

\paragraph*{}%
\label{fig:ExcludeSuffix}

<<ExcludeFiles5>>=
        ESuffixN=$(whiptail --title "Suffix:" \
        --radiolist "Please choose the suffix: " \
        --cancel-button "Cancel" 15 60 4 \
        "0" "+ds" off \
        "1" "+dfsg" on \
        "2" "other" off 3>&2 2>&1 1>&3)
        if [ ${ESuffixN} -eq 1 ]
        then
            ESuffix="+dfsg"
        elif [ ${ESuffixN} -eq 0 ]
        then
            ESuffix="+ds"
<<ExcludeFile6>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/ExcludeSuffix.png}
\caption{Suffix für den Ausschluss von Dateien}
\end{figure}

Wenn ein anderes Suffix als die beiden vorgeschlagenen verwendet werden 
soll, ist dies manuell hinzuzufügen. Dieser Eintrag muss auch entsprechend 
in der Datei \textit{debian/watch} ergänzt werden. 
(s.a Kapitel~\ref{subsec:DebianWatch}, 
Seite~\pageref{subsec:DebianWatch})

<<ExcludeFile6>>=
        else
            ESuffix=$(whiptail --title "Enter suffix" \
            --inputbox "Please insert the suffix:" \
            --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
        fi
<<ExcludeFile7>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/InputRepackSuffix.png}
\caption{Eigener Suffix für den Ausschluss von Dateien}
\end{figure}

<<ExcludeFile7>>=
        if [ -z "${ESuffix}" ]
        then
            whiptail --title "Warning!" \
            --msgbox "You repacked the upstream source and\n\
            do not want to use a repack suffix." 15 60
            if [ -n "${RecentRepackSuffix}" ]
            then
                # Remove suffix from config file
                sed --in-place \
                --expression="s/RecentRepackSuffix=.*//g" \
                ${ConfigPath}${OrigName}
            fi    
        else
<<ExcludeFile8>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/WarningNoRepackSuffix.png}
\caption{Warnung! - Kein Suffix angegeben}
\end{figure}

In manchen Fällen kann ein Pluszeichen (+) Probleme vor allem beim Bauen 
von Java-Paketen verursachen. Manchmal ist es auch notwenig, dass 
kein Suffix hinzugefügt werden kann. Die Dokumentation solcher Vorgänge 
kann dann in der Datei \textit{README.source} 
(Kapitel~\ref{subsec:ReadmeSource}, 
Seite~\pageref{subsec:ReadmeSource}) erfolgen.

<<ExcludeFile8>>=
            # Insert suffix into config file
            if [ -z "${RecentRepackSuffix}" ]
            then
                echo "RecentRepackSuffix="${ESuffix} >> ${ConfigPath}${OrigName}
            else
                sed --in-place \
                --expression="s/RecentRepackSuffix=.*/RecentRepackSuffix=${ESuffix}/g" \
                ${ConfigPath}${OrigName}
            fi

            RecentRepackSuffix=${ESuffix}
            AddOpt=${AddOpt}" --repack-suffix "${ESuffix}
        fi    
<<ExcludeFiles10>>
@

Die Kompression des \textit{*.orig.tar.*}-Archives wird in der Variable 
\textit{suffix} hinterlegt. Er wird auf \textit{.tar.xz} festgelegt. 

<<ExcludeFiles10>>=
        whiptail --title "Option(s) for mk-origtargz:" \
        --msgbox "\n${AddOpt}" 15 60
    else
        AddOpt=""
        ESuffix=""
<<ExcludeFiles12>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/MKOrigAddition.png}
\caption{Zusätzliche Optionen für \textit{mk-origtargz}}
\end{figure}

Sollen keine Dateien ausgeschlossen werden, enthält aber die Datei 
\textit{debian/copyright} einen Abschnitt \textit{Files-Excluded:}, so 
ist dieser (manuell) zu entfernen.

<<ExcludeFiles12>>=
        if [ $exflag -eq 1 ]
        then
            gitflag=1
            whiptail --title "Copyright file contains Files-Excluded" \
            --msgbox "debian/copyright contains Files-Excluded section.\n \
            Please delete it" 15 60
            nano --linenumbers --mouse \
            --softwrap ${GitPath}/debian/copyright
        fi
    fi

<<ExcludeFiles15>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/CopyrightFilesExcluded.png}
\caption{\textit{debian/copyright} enthält auszuschließende Dateien}
\end{figure}

Wurde im Zusammenhang mit dem Ausschluss von Dateien die Datei 
\textit{debian/copyright} bearbeitet, erfolgt ein entsprechender \textit{commit}.

<<ExcludeFiles15>>=
    if [ $gitflag -eq 1 ]
    then
        set +e
        git add debian/copyright
        git commit -am "Changed debian/copyright"
        set -e
    fi
}

<<CheckSignature>>
@

\subsection{\texttt{Debian}-Quellcode-Datei erzeugen}
\label{subsec:mkorigtargz}

Das Skript führt dann die Funktion \textit{BuildNewVersion} weiter aus 
und übergibt dem Programm \textit{mk-origtargz} die zum Ausschluss 
notwendigen Parameter. (Referenz auf diese Stelle in der anderen Funktion)

Auf diese Weise wird ein neuer Orig-Tarball mit \textit{mk-origtargz} 
ohne die auszuschließenden Dateien aus dem bisherige *.tar.gz erstellt 
und dessen Inhalt mit \textit{gbp import-orig} in das vorhandene 
Git-Repositorium eingefügt.

<<BuildNewVersion12>>=
    # Creating orig file using mk-origtargz
    if [ -z ${Version1} ]
    then
        whiptail --title "No version number!" \
        --msgbox "No version - no *.orig.tar.gz! Bye!" \
        --ok-button "Exit" 15 60
        exit
    fi
    echo "mk-origtargz --package "${SourceName}" \
    --version "${Version1}${AddOpt}" "${UpstreamSourceName} >> ${log}
    mk-origtargz --package ${SourceName} \
    --version ${Version1}${AddOpt} ${UpstreamSourceName} 2>> ${log}
<<BuildNewVersion13>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/Exit4NoVersion.png}
\caption{Keine Versionsnummer -- kein \textit{mk-origtargx}}
\end{figure}

<<BuildNewVersion13>>=
    if [ $? -eq 0 ]
    then
        echo "orig file was created by mk-origtargz" >> ${log}
        Version1=${Version1}${ESuffix}
    else
        echo "mk-origtargz failed" >> ${log}
        whiptail --title "Fatal error" \
        --msgbox "mk-origtargz failed" 15 60
        exit
    fi

<<BuildNewVersion14>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/MKOrigFailed.png}
\caption{mk-origtargz gescheitert}
\end{figure}

<<BuildNewVersion14>>=
    Link2File
    SearchGbpConf

    cd ${GitPath}
    
    DebianBranch4Import
<<BuildNewVersion15>>
@

Wenn die Variable \textit{RecentBranch} nicht existiert oder leer ist, 
wird ihr der Wert \textit{debian/sid} zugeordnet und ein entsprechender 
Eintrag in der Konfigurationsdatei vorgenommen.

<<DebianBranch4Import>>=
function DebianBranch4Import {
    # Called by BuildNewVersion # Makes sure RecentBranch contains value
    set +e
    RecentBranch=$(grep 'RecentBranch=' ${ConfigPath}${OrigName})
    RecentBranch=$(echo ${RecentBranch} | sed --expression='s/RecentBranch=//')
    set -e
    if [ -z "${RecentBranch}" ]
    then
        RecentBranch="debian/sid"
        changeflag=1
        whiptail --title "Set RecentBranch" \
        --msgbox "Set RecentBranch to ${RecentBranch}" 15 60
    fi

    if [ $changeflag -eq 1 ]
    then
        echo 'RecentBranch='${RecentBranch} >> ${ConfigPath}${OrigName}
    fi
    echo "Notice from DebianBranch4Import: \
    The branch is "${RecentBranch} >> ${log}
    changeflag=0
}

<<SpecialExcludeFile>>
@

\subsection{Signatur prüfen}
\label{subsec:CheckSignature}

Manche Projekte veröffentlichen neben dem Quellcodepaket auch eine Signaturdatei.
Das Skript kann diese herunterladen und eine kryptografische Prüfung durchführen. 
Erwartet wird eine Signaturdatei im \textit{asc}-Format.

\subsubsection{Signatur-Datei herunterladen}

<<DownloadAscFile>>=
function DownloadAscFile {
    # Called by BuildNewVersion and itself

    cd ${PrjPath}
    
    AscFileURL=$(whiptail --title "URL of .asc file" \
    --inputbox "URL and name (with suffix)\nof the .asc file:" \
    --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)

    if [ $? -eq 1 ]
    then
        return 1
    fi
    
    if [ -z "${AscFileURL}" ]
    then
        echo -e "URL and name (with suffix)\nof the .asc file:"
        read AscFileURL
    fi
    
    if [ -n  "${AscFileURL}" ]
    then    
        # getting -asc file using wget
        wget --version ${AscFileURL} &>> ${log}
        if [ $? -eq 0 ]
        then
            echo -e "The .asc file was pulled from\n${AscFileURL}\n \
            by wget." >> ${log}
            whiptail --title "Download successful" \
            --msgbox "${AscFileURL} was downloaded." 15 60
            if [ -r ${UpstreamSourceName}.asc ]
            then
                CheckSignature
            else
                whiptail --title "There is something wrong!" \
                --msgbox "Maybe you has downloaded the wrong .asc file." 15 60
                DownloadAscFile
            fi
        else
            DownloadAscFile
        fi
    fi
}

<<Link2File>>
@

\subsubsection{Prüfung der Signatur}

<<CheckSignature>>=
function CheckSignature {
    # Called by DownloadAscFile
    gpg --verify ${UpstreamSourceName}.asc >> ${log}

    if [ $? -ne 0 ]
    then
        tail --lines=5 ${log}
        read x
    else
        whiptail --title "Check successfull!" --msgbox "gpg \
        --verify has been successfull" 15 60
    fi
}

<<DownloadAscFile>>
@

\subsection{Link durch Kopie ersetzen}
\label{subsec:Link2File}

Das Standardverhalten von \textit{mk-origtargz} (Kapitel~\ref{subsec:mkorigtargz},
Seite~\pageref{subsec:mkorigtargz}) ist einen symbolischen Verweis auf
die Originaldatei zu erzeugen, wenn diese unverändert übernommen wird.

Das Programmskript ersetzt diesen Verweis gegebenenfalls durch eine
entsprechende Datei.

<<Link2File>>=
function Link2File {
    # Called by BuildNewVersion
    echo "Version: "${Version1} >> ${log}
    set +e
    OrigLinkNr=$(ls -la ${PrjPath} | grep ${Version1} | \
    grep --count -e '.orig.tar.[gx]z -> ')
    if [ $OrigLinkNr -ge 1 ]
    then
        OrigLink=$(ls -la ${PrjPath} | grep --regexp='.orig.tar.[gx]z -> ')
        OrigLink=$(echo ${OrigLink} | \
        sed --expression='s/^.*:.. //' | sed --expression='s/ //g')
        echo ${OrigLink}" will be transformed into a file" >> ${log}

        LinkTarget=$(echo $OrigLink | sed --expression='s/^.*->//')
        LinkName=$(echo $OrigLink | sed --expression='s/->.*$//')
        rm ${PrjPath}/${LinkName}
        cp -a ${PrjPath}/${LinkTarget} ${PrjPath}/${LinkName}
        whiptail --title "Result of transformation link to file:" \
        --msgbox "$(ls -la ${PrjPath})" --scrolltext 15 60
        echo "Result of transformation link to file: \
        "$(ls -la ${PrjPath}) >> ${log}
    fi
    set -e
}

<<CheckGitStatus>>
@

%\begin{figure}[h] 
%\centering 
%\includegraphics[width=25em,height=30ex]{Pictures/MKOrigFailed.png}
%\caption{mk-origtargz gescheitert}
%\end{figure}

\subsection{\textit{gbp}-Konfigurationsdatei}
\label{subsec:GbpConf}

\textit{gbp import-orig} (Kapitel~\ref{subsec:GbpImportOrig}, Seite~\pageref
{subsec:GbpImportOrig}) fügt den heruntergeladenen Quellcode dem 
Git-Repositorium hinzu.

Zur Steuerung dieses Prozesses wird die Einfügung einer vorbereiteten 
Datei \textit{gbp.conf} in das Verzeichnis \textit{.git} ermöglicht 
(Kapitel~\ref{subsec:GbpImportOrig}, Seite~\pageref{subsec:GbpImportOrig})

<<SearchGbpConf>>=
function SearchGbpConf {
    # Called by BuildNewVersion BuildWithUscan

    # Neither .git/gbp.conf nor debian/gbp.conf exist
    if [ ! -f ${GitPath}/.git/gbp.conf -a ! -f ${GitPath}/debian/gbp.conf ]
    then
        if whiptail --title "gbp.conf needed?" \
        --yesno "Do you want to integrate a special gbp.conf for this project?" \
        --defaultno --yes-button "Yes" --no-button "No" 15 60
<<SearchGbpConf1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=30em,height=30ex]{Pictures/GbpConf.png}
\caption{Spezielle gbp.conf}
\end{figure}

Wird diese Frage verneint, geht es mit mit dem Import in das
\texttt{Git}-Repositorium (Kapitel~\ref{subsec:GbpImportOrig},
Seite~\pageref{subsec:GbpImportOrig}) weiter.

<<SearchGbpConf1>>=
        then
            GbpConfIntegration
        fi
    fi
<<SearchGbpConf2>>
@

<<GbpConfIntegration>>=
function GbpConfIntegration {
    # Called by SearchGbpConf and itself
    GbpConfPath=$(whiptail --title "gbp.conf" \
    --inputbox "Please insert the path to the your special\n \
     gbp.conf for this project:" \
    --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
<<GbpConfIntegration1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=30em,height=30ex]{Pictures/GbpConfPath.png}
\caption{Abfrage: Pfad zur gbp.conf}
\end{figure}

<<GbpConfIntegration1>>=
    if [ -z "${GbpConfPath}" ]
    then
        echo "Please insert the path to the your special gbp.conf for this project:"
        read GbpConfPath
    fi
    
    # Replace tilde if necessary
    SuspectPath=${GbpConfPath}
    ReplaceTilde
    GbpConfPath=${CleanPath}
    
    if [ -f ${GbpConfPath}/gbp.conf ]
    then
        cp -av ${GbpConfPath}/gbp.conf ${GitPath}/.git/
    else
        if whiptail --title "File not found!" \
        --yesno "There was no gbp.conf found at ${GbpConfPath}! Retry?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            GbpConfIntegration
        fi
    fi
}

<<TwoConfFilesFound>>
@

\begin{figure}[h]
\centering
\includegraphics[width=30em,height=30ex]{Pictures/GbpConfNoPath.png}
\caption{gbp.conf nicht gefunden}
\end{figure}


Wird eine Datei \textit{gbp.conf} gefunden, wird diese zwecks Überprüfung 
und gegebenenfalls Anpassung im Editor angezeigt. Zu prüfen ist besonders 
der Wert der Variablen \textit{compression} -- vor allem dann, wenn ein 
entsprechender Wechsel des Archivformats erfolgen soll. 

<<SearchGbpConf2>>=
    # debian/gbp.conf exists, but not .git/gbp.conf
    if [ ! -f ${GitPath}/.git/gbp.conf -a -f ${GitPath}/debian/gbp.conf ]
    then
        whiptail --title "Found gbp.conf" \
        --msgbox "Please check and edit your gbp.conf (if necessary)" 15 60

<<SearchGbpConf3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=30em,height=30ex]{Pictures/FoundGbpConf.png}
\caption{Check gbp.conf}
\end{figure}

<<SearchGbpConf3>>=

        nano --linenumbers --mouse --softwrap ${GitPath}/debian/gbp.conf
    fi
    # .git/gbp.conf exists, but not debian/gbp.conf
    if [ -f ${GitPath}/.git/gbp.conf -a ! -f ${GitPath}/debian/gbp.conf ]
    then
        whiptail --title "Found gbp.conf" \
        --msgbox "Please check and edit your gbp.conf (if necessary)" 15 60

<<SearchGbpConf4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=30em,height=30ex]{Pictures/FoundGbpConf.png}
\caption{Check gbp.conf}
\end{figure}

<<SearchGbpConf4>>=

        nano --linenumbers --mouse --softwrap ${GitPath}/.git/gbp.conf
    fi
    # There is a gbp.conf in both directories
    if [ -f ${GitPath}/.git/gbp.conf -a -f ${GitPath}/debian/gbp.conf ]
    then
        TwoConfFilesFound
    fi
}

<<MovingGbpConfFile>>
@

Im folgenden wird die Datei mit den Informationen abgebildet, die 
für viele \texttt{Debian}-Pakete verwendet werden können.

<<debian/gbp.conf>>=
# Configuration file for git-buildpackage and friends

[DEFAULT]
# use pristine-tar:
pristine-tar = True
# generate xz compressed orig file
compression = xz
debian-branch = debian/experimental
upstream-branch = upstream

[pq]
patch-numbers = False

[dch]
id-length = 7
debian-branch = debian/experimental

[import-orig]
# filter out unwanted files/dirs from upstream
filter = [ '.cvsignore', '.gitignore', '.hgtags', '.hgignore', '*.orig', *.rej' ]
# filter the files out of the tarball passed to pristine-tar
filter-pristine-tar = True
@

Nach der Überprüfung und eventuellen Verbesserung der Datei
\textit{gbp.conf} geht es mit weiteren  Vorbereitungen für den Import ins
lokale \texttt{Git}-Repositorium weiter (Kapitel~\ref{subsec:CheckGitRepo},
Seite~\pageref{subsec:CheckGitRepo}). Verläuft die Überprüfung des
\texttt{Git}-Repositoriums befundlos, geht es direkt mit dem Import ins
lokale \texttt{Git}-Repositorium weiter (Kapitel~\ref{subsec:GbpImportOrig},
Seite~\pageref{subsec:GbpImportOrig}). 

Die Funktion \textit{TwoConfFilesFound} behandelt den Fall, dass jeweils 
eine Datei \textit{gbp.conf} sowohl im Verzeichnis \textit{.git/} als
auch im Verzeichnis \textit{debian/} vorkommt.

<<TwoConfFilesFound>>=
function TwoConfFilesFound {
    # Called by SearchGbpConf MovingGbpConfFile

    whiptail --title "Information" \
    --msgbox "There are a gbp.conf in debian/ and a gbp.conf in .git/" 15 60
<<TwoConfFilesFound0-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/TwoConfFilesFound.png}
\caption{\textit{gbp.conf} zweimal gefunden.}
\end{figure}

<<TwoConfFilesFound0-1>>=
    # Are they different?
    GitConfFile=$(cat ${GitPath}/.git/gbp.conf)
    DebianConfFile=$(cat ${GitPath}/debian/gbp.conf)
    if [ "${GitConfFile}" != "${DebianConfFile}" ]
    then
        whiptail --title "Warning!" \
        --msgbox "There are a gbp.conf in debian/ and a gbp.conf in .git/\n \
        But they are different!\n\nThe left column is ${GitPath}/.git/gbp.conf\n \
        The right column is ${GitPath}/debian/gbp.conf\n \
        After studying the diff press RETURN!" 15 60

<<TwoConfFilesFound1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DifferentConfigFile.png}
\caption{Unterschiedliche Konfigurationsdateien}
\end{figure}

Mit \textit{diff -{}-side-by-side} (-y) wird die Differenz in zwei
Spalten angezeigt.

<<TwoConfFilesFound1>>=
        diff --side-by-side ${GitPath}/.git/gbp.conf ${GitPath}/debian/gbp.conf
        read a
    fi
    # Editing
    if whiptail --title "debian/gbp.conf" \
    --yesno "Do you want to edit ${GitPath}/debian/gbp.conf?" \
    --yes-button "Yes" --no-button "No" 15 60
<<TwoConfFilesFound2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EditDebianConf.png}
\caption{\textit{gbp.conf} im Verzeichnis \textit{debian/} bearbeiten?}
\end{figure}

<<TwoConfFilesFound2>>=
    then
        nano --linenumbers --mouse --softwrap ${GitPath}/debian/gbp.conf
    fi
    if whiptail --title ".git/gbp.conf" \
    --yesno "Do you want to edit  ${GitPath}/.git/gbp.conf (too)?" \
    --yes-button "Yes" --no-button "No" 15 60
    then
        nano --linenumbers --mouse --softwrap ${GitPath}/.git/gbp.conf
    fi
}

<<SearchGbpConf>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EditGitConf.png}
\caption{\textit{gbp.conf} im Verzeichnis \textit{.git/} bearbeiten?}
\end{figure}

\subsection{Prüfung des \texttt{Git}-Repositoriums}
\label{subsec:CheckGitRepo}

Zur weiteren Vorbereitung des Importes in das lokale
\texttt{Git}-Repositoriums finden noch Prüfungen desselben statt.

<<Import2Git>>=
function Import2Git {
    # Called by BuildNewVersion and itself

    CheckGitStatus # to exercise caution
    CheckTags

<<Import2Git1>>
@

Es wird geprüft, ob noch eine lokale Änderung nicht zum Commit vorgemerkt
wurde. Dies erfolgt mit der Funktion \textit{CheckGitStatus}
(Kapitel~\ref{subsec:CheckGitStatus}, Seite~\pageref{subsec:CheckGitStatus}).
Solche Änderungen müssen vor dem Import einer neuen Version abgearbeitet
werden.

Eine weitere Prüfung erfolgt mit der Funktion \textit{CheckTags}. Diese
listet die vorhandenen \textit{Tags} auf. Für den nachfolgenden Commit
mit \textit{gbp import-orig} darf der Tag der zu importierenden Version
noch nicht existieren (Tag-Kollision).

Bleiben die Überprüfungen befundlos, erfolgt der Import der neuen Version
in das \texttt{Git}-Repositorium (Kapitel~\ref{subsec:GbpImportOrig},
Seite~\pageref{subsec:GbpImportOrig}). 

<<CheckTags>>=
function CheckTags {
    # Called by BuildWithUscan Import2Git and itself
    # checks git tags before executing gbp import-orig
    echo $(git tag) >> ${log}
    set +e
    cTags=$(git tag | grep --fixed-strings ${Version1})
    set -e
    if [ ${#cTags} -gt 0 ]
    then
        cTags1=$(echo ${cTags} | sed --expression='s/ /\\n/g')
        if ! whiptail --title "List of dubious tags:" \
        --yesno "${cTags1}\n\nDo you want to continue regardless?" --defaultno \
        --yes-button "Yes" --no-button "No" 15 60
<<CheckTags2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DubiousTag.png}
\caption{Zweifelhafter Git-Tag}
\end{figure}

Wird hier ein \texttt{Git}-Tag aufgeführt, der vor dem Import einer
neuen Version noch entfernt werden soll, lautet hier die Antwort \enquote{No}.
Dann erfolgt im nächsten Dialog die Aufforderung, diesen \texttt{Git}-Tag
zu entfernen.

<<CheckTags2>>=
        then
            whiptail --title "Delete tags!" \
            --msgbox "Please delete tags in another terminal\n \
            and then press ok" 15 60
<<CheckTags3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DeleteTags.png}
\caption{Git Tags entfernen}
\end{figure}

<<CheckTags3>>=
            # git tag -d
            CheckTags
        fi
    fi
}

<<Import2Git>>
@

\subsection{Import nach \texttt{Git}}
\label{subsec:GbpImportOrig}

Hier wird zum ersten Mal \textit{gbp} eingesetzt. 
Als erster Schritt wird mit \textit{gbp import-orig} der heruntergeladene 
Quellcode dem Git-Repositorium hinzugefügt. 
Der Option \textit{--debian-branch} wird der Inhalt der Variable 
\textit{RecentBranch} zugewiesen.

Existieren mehrere mögliche Branches, kann der \texttt{Debian}-Branch, 
in den importiert werden soll, zuvor ausgewählt werden 
(Kapitel~\ref{sec:AuswahlGitBranch}, Seite~\pageref{sec:AuswahlGitBranch}).

<<BuildNewVersion15>>=
    Import2Git # Contains import to the git repo using gbp import
    Task=3 # Go to BuildNewRevision
}

<<DebianFormatTemplate>>
@

Die Funktion \textit{Import2Git} (s. Kapitel~\ref{subsec:CheckGitRepo},
Seite~\pageref{subsec:CheckGitRepo}) wird von der Funktion
\textit{BuildNewVersion} aufgerufen. Nach der Überprüfung des
\texttt{Git}-Repositoriums wird der Zweig ermittelt, in den importiert
werden soll.

<<Import2Git1>>=    
    # Check branch for import
    bl=$(git branch --list | sed --expression='s/* /x_/')
    ba=($bl)
    set +e
    for element in ${ba[*]}
    do
        if echo ${element} | grep --quiet '^x_'
        then
            ActiveBranch=$(echo ${element} | sed --expression 's/\x_//')
        fi
    done
    set -e

    # After git init $ActiveBranch is always empty 
    if [ ${ActiveBranch} ] && [ "${ActiveBranch}" != "${RecentBranch}" ]
    then
        whiptail --title "Check Branch!" \
        --msgbox "The active branch is ${ActiveBranch}.\n\
        In ${ConfigPath}${OrigName} 'RecentBranch' is ${RecentBranch}." \
        15 60
        echo -e "The active branch is "${ActiveBranch}".\n"\
        "In "${ConfigPath}${OrigName}" 'RecentBranch' is "${RecentBranch}"."
        FailureNotice
    fi

    # Import to the git repo using gbp import

    echo "Notice from BuildNewVersion: The branch is \
    ${RecentBranch}" >> ${log}
    whiptail --title "Notice from BuildNewVersion:" \
    --msgbox "The branch is ${RecentBranch}" 15 60
<<Import2Git2>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/BranchIs.png}
\caption{Der Zweig is ...}
\end{figure}

<<Import2Git2>>=
    # The asterix (*) is for .bz2 and for lzma
    OrigFile=$(ls ${PrjPath}/${SourceName}_${Version1}.orig.tar.?z*)
    whiptail --title "Notice from BuildNewVersion:" \
    --msgbox "The orig file to be imported is ${OrigFile}" 15 60
<<Import2Git3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/ImportedOrigFile.png}
\caption{Importiert wurde der Upstream-Code}
\end{figure}

Hier wird nun die Eingabe der Passphrase für den GPG-Schlüssel 
\index{GPG-Schlüssel} angefordert.
Wird er nicht zeitnah eingegeben, wird der Import zurückgerollt. Es wird
daher zunächst abgefragt, ob der \texttt{GnuPG}-Schlüssel zur Verfügung
steht (Kapitel~\ref{sec:KeyAvailable}, Seite~\pageref{sec:KeyAvailable}).
Wird die Frage verneint, wird das Programm beendet.

Damit wird der zu erzeugende Git-Tag signiert. Dies entspricht guter Praxis.
Nach \textit{salsa.debian.org} sollten nur signierte Tags hochgeladen werden.

Das Signieren der Tags ist das Standardverhalten von \textit{gbp import-orig}. 
Diese Option wurde gleichwohl in die Befehlszeile aufgenommen, denn 
\enquote{explizit ist besser als implizit}. 

Will man ausnahmnsweise mal nicht signieren, ist die Option 
\textit{--no-sign-tags} zu verwenden.

<<Import2Git3>>=

    GpgKeyAvailable
    echo -e "\n Starting gbp import-orig - Please wait"'!'"\n"
    # Signing tags is default
    gbp import-orig --verbose --debian-branch=${RecentBranch} \
    --sign-tags ${OrigFile}

<<Import2Git4>>
@

Nun zeigt \textit{gbp buildpackage} ausführlich alle Schritte, die nun 
ausgeführt werden. Dabei muss die ermittelte Paket-Version bestätigt oder 
angepasst werden. 

<<Import2Git4>>=
    if [ $? -eq 0 ]
    then
        echo ${OrigFile}" was imported by gbp import-orig"  >> ${log}
    else
        whiptail --title "Something went wrong!" \
        --msgbox "gbp import-orig -v --debian-branch=${RecentBranch} \
        --sign-tags ${OrigFile} failed!" 15 60
        echo "gbp import-orig -v --debian-branch="${RecentBranch}" \
        --sign-tags "${OrigFile}" failed!" >> ${log}
        FailureNotice
        Import2Git
    fi
}

<<BuildNewVersion>>
@

Am Ende ruft die Funktion \textit{BuildNewVersion} die Funktion 
\textit{BuildNewRevision} auf (Kapitel~\ref{chap:NeueRevisionBauen}, 
Seite~\pageref{chap:NeueRevisionBauen})

\section{Herunterladen und Importieren mit \textit{uscan}}
\label{sec:ImportWithUscan}

Die folgenden Schritte werden durch den Befehl 
\textit{gbp import-orig -{}-uscan ...} ausgeführt.

Anhand des ersten Eintrages in der Datei \textit{debian/changelog} 
(Kapitel~\ref{sec:DebianChangelog}, 
Seite~\pageref{sec:DebianChangelog}) ermittelt \textit{uscan} die 
Versionsbezeichnung des zuletzt gebauten Paketes.
\textit{uscan}\index{uscan} lädt dann die Web-Seite von der in der Datei
\textit{debian/watch}\index{debian/watch} 
(Kapitel~\ref{subsec:DebianWatch}, Seite~\pageref{subsec:DebianWatch})
angegebenen \textit{URL}. Dann sucht \textit{uscan} unter Verwendung des 
in \textit{debian/watch} angegebenen Suchmusters nach Hyperlinks 
(\textit{href}), die auf Upstream-Archive verweisen.

\textit{uscan} lädt das Upstream-Archiv mit der neuesten Version 
herunter, wenn diese neuer als die in \textit{debian/changelog} zuletzt 
angegebene Version ist. Das heruntergeladene Archiv wird im 
übergeordnete Verzeichnis gespeichert. Schließlich wird 
\textit{mk-origtargz} (s. Kapitel~\ref{desc:mkorigtargz}, 
Seite~\pageref{desc:mkorigtargz}) aufgerufen.

Im Programmskript wird zunächst geprüft, ob ein Herunterladen mit 
\textit{uscan} möglich und sinnvoll ist.

Ferner wird eine vorhandene Datei \textit{gbp.conf}\index{gbp.conf} (mit 
der Funktion \textit{SearchGbpConf} (Kapitel~\ref{subsec:GbpConf}, 
Seite~\pageref{subsec:GbpConf})) zum Zwecke der Prüfung im Editor geöffnet.
Es ist besonders auf die angegebene Kompression (\textit{compression}) 
zu achten.

%ToDo: gbp import-orig --uscan doesn't work with exclude suffix

<<BuildWithUscan>>=
function BuildWithUscan {
    # Called by ClassicalOrUscan

    cd ${GitPath}

    echo "Try gbp import-orig --uscan" >> ${log}
    set +e
    uscaninfo=$(uscan --no-download --verbose)
    if [ ${#uscaninfo} -gt 0 ]
    then
        SearchGbpConf
        whiptail --title "uscan" --msgbox "${uscaninfo}" \
        --scrolltext 15 60
        echo -e "Result of uscan:\n"${uscaninfo} >> ${log}
        set +e
        echo ${uscaninfo} | grep '=> Package is up to date' > /dev/null
        if [ $? -eq 0 ]
        then 
            whiptail --title "uscan" \
            --msgbox "Package seems to be up to date.\n \
            Nothing to do!" 15 60
            echo "Package seems to be up to date. Nothing to do!" \
            >> ${log}
<<BuildWithUscan4>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/Uscan.png}
\caption{Up to date}
\end{figure}

<<BuildWithUscan4>>=
        fi
        echo ${uscaninfo} | grep '=> Newer package available from' \
        > /dev/null
        if [ $? -eq 0 ]
        then
            if ! whiptail --title "Newer package available" \
            --yesno "All well? Continue?" --yes-button "Yes" \
            --no-button "Exit" 15 60
            then
                exit
            fi
<<BuildWithUscan5>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NewerPackage.png}
\caption{Neue Version verfügbar}
\end{figure}

Es wird nun die Funktion \textit{CheckRepackSuffix} ausgeführt.

<<BuildWithUscan5>>=
            set -e
            CheckRepackSuffix
            set +e
<<BuildWithUscan5-1>>
@

Hier wird geprüft, ob in der Konfigurationsdatei der Eintrag 
\textit{RecentRepackSuffix} vorhanden ist, aber kein entsprechender
Eintrag in \textit{debian/watch}.

In diesem Fall erfolgt ein Hinweis und die Datei \textit{debian/watch}
wird zum Editieren präsentiert.

<<CheckRepackSuffix>>=
function CheckRepackSuffix {
    # Called by BuildWithUscan
    if [ -n "${RecentRepackSuffix}" ]
    then
        if ! cat ${GitPath}/debian/watch | grep "repacksuffix=" > /dev/null
        then
            whiptail --title "debian/watch!" \
            --msgbox "No repacksuffix in debian/watch." 15 60
            nano --linenumbers --mouse --softwrap ${GitPath}/debian/watch
        fi
    fi
}

<<BuildWithUscan>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NoRepackSuffix.png}
\caption{Kein Repack Suffix in debian/watch}
\end{figure}

Die Versionsbezeichnung der neuen Version wird durch einen Testlauf von
\textit{uscan} ermittelt.

Sodann wird die Funktion \textit{CheckGitStatus} aufgerufen
(Kapitel~\ref{subsec:CheckGitStatus}, Seite~\pageref{subsec:CheckGitStatus}),
um sicherzustellen, dass alle lokalen Änderungen committet wurden.

<<BuildWithUscan5-1>>=
            Version1=$(uscan --no-download --verbose | \
            grep newversion | sed --expression 's/    $newversion  = //')
            set -e
            CheckGitStatus
<<BuildWithUscan6>>
@

Zum Signieren des Archivs des heruntergeladenen Quellcodes wird der 
GPG-Schlüssel \index{GPG-Schlüssel} des Maintainers benötigt. Dieser
muss daher zur Verfügung stehen. Sonst kann es nicht weitergehen.
(Kapitel~\ref{sec:KeyAvailable}, Seite~\pageref{sec:KeyAvailable}

<<BuildWithUscan6>>=
            GpgKeyAvailable
<<BuildWithUscan7>>
@

Die eingangs beschriebenen Schritte werden durch 
\textit{gbp import-orig -{}-uscan} ausgeführt. Für Einzelheiten kann
auf die Handbuchseite von \textit{gbp import-orig}
\cite{GBP-ImportOrig2022} verwiesen werden.

<<BuildWithUscan7>>=
            CheckTags
            set +e
            # Downloads with uscan and imports with gbp import-orig
            gbp import-orig --uscan --verbose \
            --debian-branch=${RecentBranch} --sign-tags ${OrigFile}
            if [ $? -ne 0 ]
            then
                echo "Import with gbp import-orig --uscan failed!" \
                >> ${log}
                exit
            fi
            echo "Imported with gbp import-orig --uscan" >> ${log}
        else
            exit
        fi
        set -e
    else
        whiptail --title "Uscan failed!" \
        --msgbox "Please check the watch file with uscan." 15 60
        echo "Uscan failed! Please check the watch file with uscan." >> ${log}
        exit
    fi

    Task=3 # Go to BuildNewRevision
}

<<PrepareUploading>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/UscanWatchFailed.png}
\caption{Uscan kann Watch-Datei nicht parsen}
\end{figure}

Am Ende ruft die Funktion \textit{BuildWithUscan} die Funktion 
\textit{BuildNewRevision} auf.

\chapter{Bauen einer neuen Revision}
\label{chap:NeueRevisionBauen}

Die Funktion \textit{BuildNewRevison} wird automatisch von den Funktionen 
\textit{BuildNewVersion} und \textit{BuildWithUscan} aufgerufen.

Um das Bauen einer neuen Revision auf einen späteren Zeitpunkt verschieben 
zu können, wird die Möglichkeit gegeben, das Programm zuvor abzubrechen.

<<BuildNewRevision2>>=
    # Intro
    if ! whiptail --title "New Debian revision" \
    --yesno "A new Debian revision will be built." --yes-button "Yes" \
    --no-button "Exit" 15 60
<<BuildNewRevision3>>
@

\begin{figure}[!h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildNewRevision.png} 
\caption{Neue Revision bauen}
\end{figure}

<<BuildNewRevision3>>=
    then
        exit
    fi

    echo "A new Debian revision will be built." >> ${log}
<<BuildNewRevision4>>
@

Existiert das Verzeichnis \textit{debian/source} und handelt es sich 
nicht um ein \texttt{Maven}-Paket geht es mit der Frage weiter, ob die 
Dateien im Verzeichnis \textit{debian/} zum Editieren angezeigt werden
sollen (Kapitel~\ref{sec:DisplayDebianFiles}, 
Seite~\pageref{sec:DisplayDebianFiles})

\section{Anlegen des \texttt{Debian}-Verzeichnisses}
\label{sec:AnlegenDebianVerzeichnis}

Sofern das Verzeichnis \textit{debian/source} (noch) nicht existiert, 
wird es vom Programmskript angelegt. Damit wird zugleich sichergestellt,
dass auch das Verzeichnis \textit{debian/} existiert
(Kapitel~\ref{sec:DateienInDebian}, 
Seite~\pageref{sec:DateienInDebian}).

Dies ist in der Regel nur dann relevant, wenn ein neues Paket für 
\texttt{Debian} gepackt werden soll. 

<<BuildNewRevision>>=
function BuildNewRevision {
    # Called by TaskSelect
    cd ${GitPath}

    ## Generate directory if necessary
    echo $(pwd) >> ${log}
    if [ -d debian/source ]
    then
        echo "The directory debian/source in ${GitPath} \
        already exists." >> ${log}
        dfe=1
    else
        mkdir --parents debian/source
        echo "Directory debian/source was created" >> ${log}
        dfe=0
    fi

<<BuildNewRevision2>>
@

Das Ergebnis der Ausführung des Programmskriptes wird in der Log-Datei 
vermerkt.

\section{Abfrage: Bauen mit \textit{mh-make}?}
\label{sec:RequestBuildWithMaven}

Sofern das \texttt{Maven}-Plugin (Kapitel~\ref{chap:MavenPlugin}, 
Seite~\pageref{chap:MavenPlugin}) installiert ist und \texttt{Maven} als
Build-System ausgewählt wurde, wird gefragt, ob bestimmte Dateien für
dieses Build-System erstellt werden sollen. In der Regel kann diese 
Frage verneint werden.

<<BuildNewRevision4>>=

    # For building java packages with maven

    # To avoid an error, if 'MavenPluginFlag' is empty 
    if [ ! -z ${MavenPluginFlag} ] && [ ${MavenPluginFlag} -eq 1 ]
    then
        . build-gbp-maven-plugin
        if whiptail --title "Maven" \
        --yesno "Should mh_make create the ${PackName}.poms\n \
        file and some maven.* files?\n\n \
        Normally you only need it at the first run" --yes-button "Yes" \
        --no-button "No" --defaultno 15 60
        then
            MakeMaven
        fi
    fi

<<BuildNewRevision5>>
@

\begin{figure}[!h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CreateMavenFiles.png} 
\caption{Daten für Maven erstellen?}
\end{figure}

Wird sie bejaht, wird das \texttt{Maven}-Plugin geladen
(Kapitel~\ref{chap:MavenPlugin}, Seite~\pageref{chap:MavenPlugin}) und
die Funktion \textit{MakeMaven} aufgerufen. In
Kapitel~\ref{sec:BuildWithMaven} (Seite~\pageref{sec:BuildWithMaven}) 
werden die weiteren Schritte beschrieben.

\section{Sollen die \texttt{Debian}-Dateien angezeigt werden?}
\label{sec:DisplayDebianFiles}

Hier wird nun die Möglichkeit eröffnet, die Dateien im Verzeichnis 
\textit{debian/} zu erstellen und zu editieren. 

<<BuildNewRevision5>>=
    # Displaying files in debian/ for editing
    if [ ${dfe} -ne 1 ]
    then
        DisplayDebianFiles
    else
        if whiptail --title "Showing debian files for editing" \
        --yesno "Should the files of debian/ be displayed\n \
        to check, edit or create them?" --yes-button "Yes" \
        --no-button "No" 15 60
        then
            DisplayDebianFiles
        fi
    fi
    dfe=0

<<BuildNewRevision5-1>>
@

\begin{figure}[!h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ShowDebianFiles.png} 
\caption{Debian-Dateien anzeigen}
\end{figure}

Wird die Frage, ob die Dateien im Verzeichnis \textit{debian/} angezeigt 
werden sollen, bejaht, werden diese Dateien, soweit notwendig, erstellt 
und zum möglichen Editieren angezeigt.

Andernfalls geht es mit Änderungen am Upstream-Code weiter
(Kapitel~\ref{chap:Aenderungen_am_Upstream_Code_vornehmen},
Seite~\pageref{chap:Aenderungen_am_Upstream_Code_vornehmen}) und es wird
lediglich noch die Datei \textit{debian/changelog} angezeigt 
(Kapitel~\ref{sec:DebianChangelog}, Seite~\pageref{sec:DebianChangelog}).

\section{Dateien im Verzeichnis debian/}
\label{sec:DateienInDebian}

Die Dateien im Verzeichnis \textit{debian/} dienen der Steuerung und der 
Dokumentation des Build-Prozesses. Die Dateien in diesem Verzeichnis
werden in der Archiv-Datei mit der Endung \textit{<Paketname>.debian.tar.xz}
veröffentlicht (s. Kapitel~\ref{chap:DebianPackage},
Seite~\pageref{chap:DebianPackage}).

Das Verzeichnis \textit{debian/} wird, wenn nötig, vom Programmskript
erstellt (Kapitel~\ref{sec:AnlegenDebianVerzeichnis},
Seite~\pageref{sec:AnlegenDebianVerzeichnis}).

Das Skript hat die Aufgabe, die notwendigen oder häufiger verwendeten 
Dateien im Verzeichnis \textit{debian/} zu erstellen und - soweit möglich - 
Vorschläge für ihren Inhalt zu machen.

Existieren die \texttt{Debian}-Dateien bereits, kann der Nutzer sie
prüfen und verbessern.

\subsection{Anzeigen der \texttt{Debian}-Dateien}
\label{subsec:DebianDateienAnzeigen}

Sollen die Dateien im Verzeichnis \textit{debian/} angezeigt werden, um 
sie zu prüfen, zu editieren oder auch zu erzeugen, wird die folgende 
Funktion ausgeführt:

<<DisplayDebianFiles>>=
function DisplayDebianFiles {
    # Called by BuildNewRevision

    # Add Debian files

    # If the Debian files already exists, you can review and improve them now
    # If not, you have to write them

    ## There is default content for Debian files
    ## Change the default values, if you know, what you are doing

<<DisplayDebianFiles0>>
@

Ist in der Konfigurationsdatei ein entsprechender Eintrag vorhanden, wird
das Plugin-Script für \textit{Webext}-Pakete geladen 
(Kapitel~\ref{chap:WebextPlugin}, Seite~\pageref{chap:WebextPlugin})

Das Plugin-Skript zeigt an, dass es geladen wurde
(s. Kapitel~\ref{subsec:WebextPluginLoaded},
Seite~\pageref{subsec:WebextPluginLoaded}).

<<DisplayDebianFiles0>>=
    # Loading Webext plugin or Python3 Plugin if needed

    if [ ${WebextFlag} -eq 1 ]
    then
        . build-gbp-webext-plugin
    fi

<<DisplayDebianFiles01>>
@

Ist in der Konfigurationsdatei ein entsprechender Eintrag vorhanden, wird
das Plugin-Script für \textit{Python}-Pakete geladen 
(Kapitel~\ref{chap:WebextPlugin}, Seite~\pageref{chap:WebextPlugin})

Das Plugin-Skript zeigt an, dass es geladen wurde
(s. Kapitel~\ref{subsec:PythonPluginLoaded},
Seite~\pageref{subsec:PythonPluginLoaded}).

<<DisplayDebianFiles01>>=
    if [ ${PythonFlag} -eq 1 ]
    then
        . build-gbp-python-plugin
    fi
<<DisplayDebianFiles02>>
@

Es werden dann Funktionen aufgerufen, die gegebenenfalls Vorlagen für
Dateien im Verzeichnis \textit{debian/} erstellen.

<<DisplayDebianFiles02>>=

    DebianFormatTemplate
<<DisplayDebianFiles1>>
@

Die Funktion \textit{DebianFormatTemplate} erstellt eine Vorlage für die
Datei \textit{debian/source/format} (Kapitel~\ref{subsec:d/source/format}, 
Seite~\pageref{subsec:d/source/format}).

<<DisplayDebianFiles1>>=
    DebianUpstreamMetadataTemplate
<<DisplayDebianFiles2>>
@

Kapitel~\ref{subsec:d/upstream/metadata}, 
Seite~\pageref{subsec:d/upstream/metadata}

<<DisplayDebianFiles2>>=
    DebianCopyrightTemplate
<<DisplayDebianFiles3>>
@

<<DisplayDebianFiles3>>=
    DebianControlTemplate
<<DisplayDebianFiles4>>
@

<<DisplayDebianFiles4>>=
    DebianWatchTemplate
<<DisplayDebianFiles4-1>>
@

<<DisplayDebianFiles4-1>>=
    DebianRulesTemplate
<<DisplayDebianFiles4-2>>
@
<<DisplayDebianFiles4-2>>=
    DebianSalsaCiTemplate

<<DisplayDebianFiles5>>
@

Wenn ein Java-Paket ohne Build-System gebaut werden soll, kann es notwendig 
sein, eine Datei \textit{debian/javabuild} zu erstellen.

Wenn das Maven-Plugin verwendet wird, werden die Maven-Dateien zum 
Editieren angezeigt (Kapitel~\ref{sec:MavenDateienBearbeiten}, 
Seite~\pageref{sec:MavenDateienBearbeiten}).

<<DisplayDebianFiles10>>=

    if [ ${JavaFlag} -eq 1 ]
    then
        if [ ${MavenPluginFlag} -eq 0 ]
        then
            DebianJavabuildTemplate
        else
            ls debian/ | grep 'maven'
            if [ $? -eq 0 ]
            then
                ShowMaven
            fi
        fi
    fi
    CmeFix
}

<<ForceOrig>>
@

\subsection{debian/source/format}
\label{subsec:d/source/format}

Diese Datei enthält das Format des Quellpaketes. In der Datei
\textit{debian/source/format} wird der Eintrag \textit{3.0 (quilt)} erstellt. 
Dies bedeutet, dass es sich um \emph{kein} natives Paket handelt. Bei
einem nativen Paket muss \textit{3.0 (native)} eingetragen werden. 

Was ein natives Paket ist, wird in Kapitel~\ref{sec:DebianDoc}
(Seite~\pageref{sec:DebianDoc}) und in Kapitel~4 der \texttt{Debian-Policy}
\cite{DebianPolicy} beschrieben.

Eine ausführliche Beschreibung zur Datei \textit{debian/source/format}
gibt es im \textit{Debian-Leitfaden für Neue Paketbetreuer}\cite{maint-guide}
in Kapitel 5.22
\footnote{\url{https://3ws.debian.org/doc/manuals/maint-guide/dother.de.html\#sourcef}}

<<DebianFormatTemplate>>=
function DebianFormatTemplate { 
    # Called by DisplayDebianFiles

    if ! [ -f ${GitPath}/debian/source/format ]
    then
        # String for debian/source/format
        if whiptail --title "Kind of package" \
            --defaultno --yesno "Is it a native debian package?" \
            --yes-button "Yes" --no-button "No" 15 60

<<DebianFormatTemplate1>>
@

\begin{figure}[!h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/KindPackage.png} 
\caption{Art des Quellpaketes (Nativ? J/N)}
\end{figure}

<<DebianFormatTemplate1>>=
        then
            str4format="3.0 (native)"
        else
            str4format="3.0 (quilt)"
        fi

        touch ${GitPath}/debian/source/format
        echo ${str4format} >> ${GitPath}/debian/source/format
        echo "/debian/source/format was created." >> ${log}
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/source/format
}

<<DebianUpstreamMetadataTemplate>>
@

\subsection{debian/source/include.binaries}

Grundsätzlich sollen Binär-Dateien keine Aufnahme in das 
\texttt{Debian}-Paket finden. Sie sind daher regelmäßig von der Aufnahme 
in das *.orig-Archiv auszuschließen 
(Kapitel~\ref{subsec:ExcludeFiles}, 
Seite~\pageref{subsec:ExcludeFiles}).

Es gibt jedoch Ausnahmen. Hierzu können Medien-Dateien und komprimierte 
Dokumentationen zählen. Diese Dateien sind zwecks Dokumentation in der 
Datei \textit{debian/source/include-binaries} unter Angabe ihres Pfades 
aufzuführen.

\subsection{debian/upstream/metadata}
\label{subsec:d/upstream/metadata}

Es gibt eine ausführliche Beschreibung\cite{Wiki-DEP-12} dieser 
\textit{YAML}-Datei in englischer Sprache. Dort wird auch auf 
DEP-12\footnote{Quelle:\cite{DEP-12}} hingewiesen.

Dort wird auch erläutert, welche Informationen in den einzelnen Zeilen 
vom Maintainer eingetragen werden sollen, sofern diese Informationen 
vorhanden sind. 

Es wird empfohlen, beim Editieren der Datei die Kommentare zu entfernen.

<<DebianUpstreamMetadataTemplate>>=
function DebianUpstreamMetadataTemplate {
    # Called by DisplayDebianFiles

    # Treatment for native packages
    set +e
    cat debian/source/format | grep "native" > /dev/null
    if [ $? -eq 0 ]
    then
        set -e
        return
    fi
    set -e

    # Strings for debian/upstream/metadata
    if ! [ -f ${GitPath}/debian/upstream/metadata ]
    then
        mkdir --parents debian/upstream
        # creating a template for debian/upstream/metadata
        echo -e "# You can find a description at\n#\
        https://wiki.debian.org/UpstreamMetadata" \
        >> debian/upstream/metadata
        echo "# Archive: " >> debian/upstream/metadata
        echo "# ASCL-id: " >> debian/upstream/metadata
        echo "Bug-Database: " >> debian/upstream/metadata
        echo "Bug-Submit: " >> debian/upstream/metadata
        echo "# Cite-As: " >> debian/upstream/metadata
        echo "Changelog: " >> debian/upstream/metadata
        echo "# CPE: " >> debian/upstream/metadata
        echo "Documentation: " >> debian/upstream/metadata
        echo "# Donation: " >> debian/upstream/metadata
        echo "# FAQ: " >> debian/upstream/metadata
        echo "# Funding: " >> debian/upstream/metadata
        echo "# Gallery: " >> debian/upstream/metadata
        echo "# Other-References: " >> debian/upstream/metadata
        echo "# Reference: " >> debian/upstream/metadata
        echo "#     Author: " >> debian/upstream/metadata
        echo "#     Booktitle: " >> debian/upstream/metadata
        echo "#     DOI: " >> debian/upstream/metadata
        echo "#     Editor: " >> debian/upstream/metadata
        echo "#     Eprint: " >> debian/upstream/metadata
        echo "#     ISBN: " >> debian/upstream/metadata
        echo "#     ISSN: " >> debian/upstream/metadata
        echo "#     Journal: " >> debian/upstream/metadata
        echo "#     Number: " >> debian/upstream/metadata
        echo "#     Pages: " >> debian/upstream/metadata
        echo "#     PMID: " >> debian/upstream/metadata
        echo "#     Publisher: " >> debian/upstream/metadata
        echo "#     Title: " >> debian/upstream/metadata
        echo "#     Type: " >> debian/upstream/metadata
        echo "#     URL: " >> debian/upstream/metadata
        echo "#     Volume: " >> debian/upstream/metadata
        echo "#     Year: " >> debian/upstream/metadata
        echo "#     Debian-package: " >> debian/upstream/metadata
        echo "# Registration: " >> debian/upstream/metadata
        echo "# Registry: " >> debian/upstream/metadata
        echo "Repository: " >> debian/upstream/metadata
        echo "Repository-Browse: " >> debian/upstream/metadata
        echo "# Screenshots: " >> debian/upstream/metadata
        echo "# Security-Contact: " >> debian/upstream/metadata
        echo "# Webservice: " >> debian/upstream/metadata
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/upstream/metadata
}

<<DebianCopyrightTemplate>>
@

Folgende Felder sind für viele Pakete relevant. Ihr Vorhandensein wird 
teilweise von \textit{lintian} geprüft.

\begin{description}
  \item[Bug-Database] URL zur Liste der bekannten Fehler
  \item[Bug-Submit] Adresse, an die Fehlermeldungen gesandt werden können.
  \item[Changelog] URL des Upstream Changelogs
  \item[Documentation] Upstream Dokumentation
  \item[Repository] URL zum Upstream-Repositorium
  \item[Repository-Browse] Durchsuchbares Repositorium von Upstream
\end{description}

\subsection{debian/copyright}
\label{subsec:d/copyright}

Diese Datei enthält Informationen über das Copyright und die Lizenzen der 
Quellen der Originalautoren.

Diese Datei kann mit \textit{debmake --cc} erzeugt werden und im 
DEP-5-Format \cite{DEP-5} abgelegt

<<DebianCopyrightTemplate>>=
function DebianCopyrightTemplate {
    # Called by DisplayDebianFiles

    if ! [ -f ${GitPath}/debian/copyright ]
    then
    # creating debian/copyright using debmake
        debmake -cc > debian/copyright
<<DebianCopyrightTemplate2>>
@

Auszug aus der Manpage für \textit{debmake}
\begin{verbatim}
     -c, --copyright
           scan source for copyright+license text and exit.

           •   -c: simple output style

           •   -cc: normal output style (similar to 
                    the debian/copyright file)

           •   -ccc: debug output style
\end{verbatim}

Danach muss die Datei noch bearbeitet werden. Dateien mit gleichem Autor 
und gleicher Lizenz können zusammengefasst werden. Stehen Dateien unter 
mehreren Lizenzen, werden diese Lizenzen mit\textit{or} verbunden.
 
<<DebianCopyrightTemplate2>>=
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/copyright
}

<<TeamMaintainer>>
@

Jeder Abschnitt \textit{Files} in der maschinenlesbaren Copyright-Datei 
muss auf eine Lizenz verweisen, für die jeweils ein eigenständiger 
Lizenzabsatz existiert. Diese Absätze müssen \textbf{nach} allen 
\textit{Files}-Absätzen erscheinen.

Eigenständige Lizenzabsätze können verwendet werden, um den 
vollständigen Lizenztext für eine bestimmte Lizenz nur einmal bereitzustellen, 
anstatt ihn in jedem \textit{Files}-Abschnitt zu wiederholen, der auf 
sie verweist.\cite{Copyright2020}

Steht der Lizenztext unter \url{/usr/share/common-licenses/} zur Verfügung, 
ist statt des kompletten Lizenztextes eine Kurzfassung und der Dateiname 
nebst Pfad der Datei, die den Lizenztext enthält, (beispielsweise
\textit{/usr/share/common-licenses/GPL-3}) aufzuführen.

\subsection{\textit{debian/control}}
\label{subsec:DebianControl}

Diese Datei enthält essentielle Werte, die durch die Paketverwaltungswerkzeuge 
\index{Paketverwaltungswerkzeug} verwendet werden.

Das Paketverwaltungssystem verarbeitet Daten, die in einem gemeinsamen 
Format, den sogenannten Kontrolldaten, in der \textit{control}-Datei 
gespeichert ist. Diese Daten werden für Quellpakete, Binärpakete und
die \textit{*.changes}-Dateien verwendet, die die Installation der 
hochgeladenen Dateien steuern.

Einzelheiten werden in der \texttt{Debian}-Policy\cite{DebianPolicy} 
beschrieben.

\subsubsection{Grundlegender Aufbau}

Das Programmskript erzeugt ein \enquote{Grundgerüst} der 
\textit{control}-Datei für das Quellpaket. Die \textit{control}-Datei 
des Binärpaketes und der \textit{.changes}-Datei werden durch den 
Build-Prozess aus den Informationen des Abschnittes für die 
Binär-Datei(en) erstellt.

<<DebianControlTemplate>>=
function DebianControlTemplate {
    # Called by DisplayDebianFiles

    # Strings for debian/control
    str4versiondebhelpers="(=13)"
<<DebianControlTemplate1>>
@

Ab der Version \textit{debhelper >= 12}\index{debhelper} wird die 
\textit{Kompatibilitätsversion} 
nicht mehr in der Datei \textit{debian/compat} zusätzlich gepflegt. 
Stattdessen wird in der Datei \textit{debian/control} der Eintrag 
\textit{debhelper} durch \textit{debhelper-compat} mit der Version \textit{(= 13)} 
ersetzt.\footnote{\url{https://release.debian.org/bookworm/freeze_policy.html} (2023)} 
Dies gilt auch für alle darauf folgenden Versionen.

Von der Verwendung der Version 11 wird bereits abgeraten.

<<DebianControlTemplate1>>=
    str4standardsversion="4.7.2"

<<DebianControlTemplate2>>
@

In der Datei \textit{debian/control} muss es einen Eintrag 
\enquote{Standard-Version: } geben\index{Standard-Version}, der die 
Konformität zur Version der Debian-Policy (s. Kapitel~\ref{sec:PolicyHandbuch}, 
Seite~\pageref{sec:PolicyHandbuch}) angibt. 
Hier wird die jeweils aktuelle Version (\textit{jetzt: 4.7.2}) vorgegeben.

An dieser Stelle im Programmskript wird eine Vorlage für die Datei 
\textit{debian/control} erstellt, wenn die Datei noch nicht existiert.

<<DebianControlTemplate2>>=
    if ! [ -f ${GitPath}/debian/control ]
    then
        # creating a template for debian/control
        echo -e "Source: "${SourceName} > debian/control
        echo -e "Priority: optional" >> debian/control

<<DebianControlTemplate3>>
@

Name und E-Mail-Adresse von \texttt{Maintainer} und gegebenenfalls 
\texttt{Uploa\-ders} werden durch die Funktion \textit{DEBValues} ermittelt.
(Kapitel~\ref{subsec:DebNameAndEmail}, 
Seite~\pageref{subsec:DebNameAndEmail})

<<DebianControlTemplate4>>=
        DEBValues

        if [ -n "${Maintainer}" ]
        then
            echo -e "Maintainer: "${Maintainer} >> debian/control
        else
            echo "Maintainer: " >> debian/control
        fi
        
        if [ -n "${Uploaders}" ]
        then
            echo -e "Uploaders: "${Uploaders} >> debian/control
        fi

<<DebianControlTemplate5>>
@

<<DebianControlTemplate5>>=
        echo -e "Build-Depends: debhelper-compat" \
        ${str4versiondebhelpers} >> debian/control
<<DebianControlTemplate6>>
@

<<DebianControlTemplate7>>=
        echo -e "Standards-Version: "${str4standardsversion} \
        >> debian/control
        echo -e "Rules-Requires-Root: no" >> debian/control
        echo -e "Vcs-Git: https://salsa.debian.org/"${SalsaName} \
        >> debian/control
        BrowserName=$(echo ${SalsaName} | sed --expression='s/.git$//g')
        echo -e "Vcs-Browser: https://salsa.debian.org/"${BrowserName} \
        >> debian/control
        echo -e "Homepage: \n" >> debian/control
<<DebianControlTemplate8>>
@

Nun folgt in der Datei \textit{debian/control} die Informationen über 
das Binär-Paket.

<<DebianControlTemplate8>>=
        echo -e "Package: "${PackName} >> debian/control
        echo -e "Architecture: all" >> debian/control
        echo -e "Depends: \${misc:Depends}" >> debian/control
        echo -e "Description: " >> debian/control
        echo "A template for debian/control was created." >> ${log}
<<DebianControlTemplate9>>
@

\subsubsection{Anpassungen für \texttt{Java}-Pakete}

Informationen aus dieser Datei werden bei der Erstellung der 
\textit{control}-Datei des Binär-Paketes verwendet.

Für das Paketieren von \texttt{Java}-Paketen können schon folgende 
Einträge vorgenommen werden.

<<DebianControlTemplate3>>=
        if [ ${JavaFlag} -eq 1 ]
        then
            echo -e "Section: java" >> debian/control
        else
            echo -e "Section:" >> debian/control
        fi
<<DebianControlTemplate4>>
@

Bei Paketen, die im Team betreut werden, wird hier die Adresse des Teams 
angegeben. 
Dies ist in der Regel die E-Mail-Adresse der Mailingliste. 
In diesen Fällen ist auch das Feld \texttt{Uploaders} mit den Namen der 
Paketbetreuer zu füllen.

\textit{Maintainer} für das Java-Team ist beispielsweise 
\textit{Debian Java maintainers <pkg-java-maintainers@lists.alioth.debian.org>}.

Damit der Paketierer nicht immer seinen vollen Namen und seine E-Mail-Adresse 
schreiben muss, sucht das Skript diese Daten zunächst in der 
Konfigurationsdatei (Kapitel~\ref{subsec:DebNameAndEmail}, 
Seite~\pageref{subsec:DebNameAndEmail}).

<<DebianControlTemplate6>>=
        if [ ${JavaFlag} -eq 1 ]
        then
            echo " , default-jdk" >> debian/control

            if [ ${MavenPluginFlag} -eq 1 ]
            then
                echo " , maven-debian-helper" >> debian/control
            fi
        fi
<<DebianControlTemplate7>>
@

\subsubsection{Web-Extension-Plugin}

Aufruf der Funktion zur Anpassung der Datei \textit{debian/control} für 
\texttt{Mozilla}-AddOns. Diese Funktion befindet sich im 
\texttt{Webext}-Plugin (Kapitel~\ref{subsec:WebextControl}, 
Seite~\pageref{subsec:WebextControl})

<<DebianControlTemplate9>>=
        if [ ${WebextFlag} -eq 1 ]
        then
            WebextControl
        fi
<<DebianControlTemplate10>>
@

\subsubsection{Python-Plugin}

Aufruf der Funktion zur Anpassung der Datei \textit{debian/control} für 
\texttt{Python}-Pakete und -Bibliotheken. Diese Funktion befindet sich im 
\texttt{Python}-Plugin (Kapitel~\ref{sec:PythonControl}, 
Seite~\pageref{sec:PythonControl})

<<DebianControlTemplate10>>=
        if [ ${PythonFlag} -eq 1 ]
        then
            PythonControl
        fi
<<DebianControlTemplate11>>
@

<<DebianControlTemplate11>>=
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/control
}

<<OptionsWatchFile>>
@

\subsection{debian/watch}
\label{subsec:DebianWatch}

Die Datei \textit{watch}\index{Watch (Datei)} im \texttt{Debian}-Verzeichnis 
enthält Daten für das Programm \textit{uscan}\index{uscan} 
(Kapitel~\ref{sec:ImportWithUscan}, Seite~\pageref{sec:ImportWithUscan} und 
Kapitel~\ref{sec:uscan}, Seite~\pageref{sec:uscan}). 

Zur Bestimmung des Namens des Quellcodepaketes liest \textit{uscan} den 
ersten Eintrag in der Datei \textit{debian/changelog} 
(Kapitel~\ref{sec:DebianChangelog}, 
Seite~\pageref{sec:DebianChangelog}). Anhand dieses 
Eintrages ermittelt \textit{uscan} auch die Versionsbezeichnung des 
zuletzt gebauten Paketes \cite{ManUscan2019}.

Dann verarbeitet \textit{uscan} die Zeilen der Datei 
\textit{debian/watch} in einem Zuge von oben nach unten. Einzelheiten 
zur Datei \textit{debian/watch}\index{debian/watch} werden 
im entsprechenden Artikel im Debian-Wiki 
beschrieben\footnote{\url{https://wiki.debian.org/debian/watch}}. 

In dieser Datei können reguläre Ausdrücke \index{reguläre Ausdrücke} 
im \index{Perl-Format} Perl-Format\footnote{siehe hierzu:
\begin{itemize}
\item{\url{https://de.wikibooks.org/wiki/Perl-Programmierung:_Reguläre_Ausdrücke}} 
\item{\url{http://www.mathe2.uni-bayreuth.de/perl/GK/regExp.htm}} 
\item{\url{http://perl-seiten.privat.t-online.de/html/perl_reg.html}}
\end{itemize}}
verwendet werden. Zeilen, die mit einem \textit{\#} beginnen, werden als 
Kommentarzeilen ignoriert.

Eingangs dieser Datei steht die Version des verwendeten Formats. Diese 
Angabe ist erforderlich. Die empfohlene Versionsnummer ist die \textit{4} 
und wird vom Skript schon bei der Erstellung der Datei eingetragen.

<<DebianWatchTemplate>>=
function DebianWatchTemplate {
    # Called by DisplayDebianFiles

    # Treatment for native packages
    set +e
    cat debian/source/format | grep "native" > /dev/null
    if [ $? -eq 0 ]
    then
        set -e
        return
    fi
    set -e
<<DebianWatchTemplate1>>
@

In der ersten Zeile der Datei \textit{debian/watch} steht die Version des
Programmes \textit{uscan}.

<<DebianWatchTemplate1>>=
    # String for debian/watch
    str4watch="version=4"

    if ! [ -f ${GitPath}/debian/watch ]
    then
    # creating a template for debian/watch
        echo ${str4watch} > debian/watch
        OptionsWatchFile
<<DebianWatchTemplate3>>
@

Nun werden die Optionen\index{Optionen (uscan)} definiert, wie 
\textit{uscan} überprüfen kann, ob auch die aktuelle Version gebaut wird. 

Die Auswertung der Versionierung folgt der Darstellung in  
Kapitel~\ref{chap:VersioningPackage}
(Seite~\pageref{chap:VersioningPackage}).

Die Optionen geben Regeln für die Auswahl möglicher Upstream.Archive 
vor. Sie werden in der Handbuchseite (Manpage) von \textit{uscan} erläutert
\footnote{\url{https://people.debian.org/~osamu/uscan.html\#WATCH-FILE-OPTIONS}}.

Das Programmskript stellt die Optionen auf der Basis der bisher 
vorhandenen Informationen in die Datei \textit{debian/watch} ein.

Das Programmskript vermeidet Leerzeichen in der Liste der Optionen.
Andernfalls muss die Optionenliste von doppelten Anführungszeichen 
(”) eingerahmt werden.

<<OptionsWatchFile>>=
function OptionsWatchFile {
    # Called by DebianWatchfile

    olf='\\\n'
    WOpt='opts='

<<OptionsWatchFile1>>
@

Bei die Erstellung der \textit{*.orig.tar.*}-Datei 
(Kapitel~\ref{subsec:ArchiveFormat}, 
Seite~\pageref{subsec:ArchiveFormat}) wurde bereits das ursprüngliche 
Archiv-Format festgestellt. Diese Information wird nun für die Datei 
\textit{debian/watch} verwendet.

Die folgende Option legt beim Bauen einer neuen Version mittels 
\textit{uscan} fest, dass die \textit{*.orig.tar.*}-Datei in einem anderen 
Kompressionsformat archiviert wird, als das herunterzuladende 
Upstream-Archiv. Angegeben wird hier als  Kompressionsformat des 
orig-Archives \textit{xz}.

Wenn das Upstream-Archiv in einem Zip-Format (einschließlich .xpi, .jar 
oder .oxt) vorliegt, muss nämlich eine Neupaketierung vorgenommen werden. 
Die Option \textit{compression=xz} legt fest, dass ein 
\textit{*.orig.tar.xz} gebildet wird. Die Option \textit{repack} ist in 
diesem Fall entbehrlich; aber explizit ist besser als implizit.

<<OptionsWatchFile1>>=
    # Repacked <UpstreamPackage>.zip
    RepackFlag=0
    ZipSuffix=(.zip .oxt .xpi .jar)
    if [[ ${ZipSuffix} =~ ${RecentUpstreamSuffix} ]]
    then
        WOpt=${WOpt}${olf}'repack,compression=xz,'
        RepackFlag=1
    fi

<<OptionsWatchFile2>>
@

Muss eine Neupaketierung vorgenommen werden, weil aus dem 
Quellco\-de-Archiv Dateien zu entfernen sind, sollte dies im Namen der 
\textit{*.orig.tar.*}-Datei ersichtlich sein. Hierzu dient die Option 
\textit{repacksuffix}. Die auszuschließenden Dateien ergeben sich aus 
der entsprechenden Liste (\textit{Files-Exluded}) in der Datei 
\textit{debian/copyright}.

<<OptionsWatchFile2>>=
    # Excluded files
    if [ -z ${RecentRepackSuffix} ]
    then
        if [ ${RepackFlag} -eq 1 ]
        then
            WOpt=${WOpt}${olf}'repacksuffix='${RecentRepackSuffix}',\\\n'
        else
            WOpt=${WOpt}${olf}'repack,compression=xz,\\\n\
            repacksuffix='${RecentRepackSuffix}',\\\n'
        fi

<<OptionsWatchFile3>>
@

Als Nächstes folgt die Option \textit{dversionmangle}\index{dversionmangle}. 
Hiermit wird die letzte gefundene Upstream-Versionsbezeichnung in der Datei 
\textit{debian/changelog} normalisiert, um sie mit der Version des 
verfügbaren Upstream-Archivs zu vergleichen. Dazu werden die 
\texttt{Debian}-spezifischen Suffixes wie \textit{+dfsg} oder \textit{+ds} 
im Wege der Ersetzung entfernt. 

<<OptionsWatchFile3>>=
        WOpt=${WOpt}${olf}'dversionmangle=s/'${RecentRepackSuffix}'//,'
    fi
 
<<OptionsWatchFile4>>
@

Mit der Option \textit{uversionmangle}\index{uversionmangle} werden die 
Zeichenketten der Dateien der Upstream-Versionen normalisiert, die aus 
den Links auf diese Dateien im Quellcode der Webseite extrahiert werden.
In der Versionsbezeichnung werden die nicht-numerischen Zeichen (außer 
dem Punkt) zwecks Vereinheitlichung sinnvoll ersetzt. Damit wird die 
Versionsbezeichnung des Upstream-Archives versionierungsschemakonform 
(Kapitel~\ref{sec:schema}, Seite~\pageref{sec:schema}) gestaltet.
Dies wird als Versionssortierungsindex\index{Versionierungsindex} bei 
der Auswahl der neuesten Upstream-Version verwendet.

<<OptionsWatchFile4>>=

    # For beta-, rc- etc. releases

    WOpt=${WOpt}${olf}'uversionmangle=s/-?([^\d.]+)/~$1/;tr/A-Z/a-z/,'
<<OptionsWatchFile5>>
@

\textit{filenamemangle}\index{filenamemangle} generiert den 
Upstream-Tarball-Dateinamen aus der ausgewählten 
\textit{href}-Zeichenkette, wenn die Vergleichsmuster die neueste 
Up\-stream-Version aus der ausgewählten \textit{href}-Zeichenkette 
extrahieren können. Andernfalls wird der Upstream-Tarball-Dateiname aus 
seiner vollständigen URL-Zei\-chenkette erzeugt und die fehlende 
Upstream-Version aus dem erzeugten Upstream-Tarball-Da\-teinamen eingesetzt.

Ohne diese Option wird der standardmäßige Upstream-Tarball-Dateina\-me 
generiert, indem die letzte Komponente der URL genommen und alles nach 
einem '?' oder '\#' entfernt wird.

<<OptionsWatchFile5>>=
    # For packages from Github
    set +e
    if echo ${DownloadUrl} | grep "github" > /dev/null
    then
        WOpt=${WOpt}${olf}'filenamemangle=s/.+\/v?(\d\S+)\.*/$1/,'
    fi
    set -e

<<OptionsWatchFile8>>
@

<<OptionsWatchFile8>>=
    # If there are no options
    if [ ${#WOpt} -eq 6 ]
    then
        WOpt='# '${WOpt}
        WOpt=$(echo ${WOpt} | sed 's/\\/\"\" \\/')
    fi

    echo -e ${WOpt} >> debian/watch
}


<<DebianWatchTemplate>>
@

\textit{uscan} lädt die Web-Seite von der in \textit{debian/watch} 
angegebenen \textit{URL}. Dann sucht \textit{uscan} unter Verwendung des 
in \textit{debian/watch} angegebenen Suchmusters nach Hyperlinks 
(\textit{hrefs}), die auf Upstream-Archive verweisen.

Ausgehend von der URL, mit der der Quellcode heruntergeladen wurde, wird 
im Programmskript definiert, wie nach einer neuen Version gesucht 
werden kann. Die URL wurde der Variablen \textit{DownladURL} als Wert 
zugewiesen  
(Kapitel~\ref{subsec:ArchiveFormat}, Seite~\pageref{subsec:ArchiveFormat}). 

<<DebianWatchTemplate3>>=
        set +e
        if echo ${DownloadUrl} | grep "github" > /dev/null
        then
            DownloadUrl=$(echo ${DownloadUrl} | \
            sed --expression 's/archive.*$/releases/')
            DownloadUrl=${DownloadUrl}' .*/v?(\d\S+)\.tar\.gz'
            echo -e ${DownloadUrl} >> debian/watch
        fi
        set -e
        echo "A template for debian/watch was created." >> ${log}
        whiptail --title "Edit debian/watch!" \
        --msgbox "Please insert reasonable regular expressions\n \
         into debian/watch!" 15 60
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/watch
}

<<DebianRulesTemplate>>
@

Ein Beispiel:

\begin{verbatim}
opts=repack,compression=xz,dversionmangle=s/\+dfsg$//,\
uversionmangle=s/-Beta/~beta/;s/-rc/~rc/,\
filenamemangle=s/.*\/v?(\d+\.\d+\.\d+(?:-(Beta|rc)\d+)?)\.tar\
.gz/jax-maven-plugin-$1.tar.gz/ \
https://github.com/davidmoten/jax-maven-plugin/releases \
.*/v?(\d\S+)\.tar\.gz
\end{verbatim}

Die Datei \textit{debian/watch} kann, wenn man in dem Verzeichnis ist, 
in dem sich das Git-Repositorium befindet, mit dem Befehl 
\textit{uscan --no-download --debug} geprüft werden. Die Option 
\textit{--no-download} bewirkt, dass ein gefundenes, neueres 
Upstream-Archiv nicht heruntergeleaden wird. Die Option 
\textit{--debug} erzeugt einen für Menschen lesbaren Bericht, der auch 
den Status der internen Variablen anzeigt.

\subsection{\textit{debian/rules} - Grundlegender Aufbau}
\label{subsec:rules}

Diese Datei steuert den Ablauf des Buildprozesses. 

Im Unterschied zu den anderen Dateien im Verzeichnis \textit{debian} ist 
die Datei \textit{debian/rules} als ausführbar zu kennzeichnen.

Wie jedes andere \textit{Makefile} ist die Datei \textit{debian/rules} 
aus mehreren Regeln zusammengesetzt, welche das Ziel definieren und wie 
diese Regeln ausgeführt werden. In der Debian-Policy, 
Kapitel 4.9\cite{DebianPolicy} \textit{Main building script: debian/rules} 
werden die Details erklärt.

\subsubsection{Erstellen der Datei}

Existiert die Datei \textit{debian/rules} noch nicht, wird sie angelegt. 

Sie ist ein Makefile und hat daher eine entsprechende \textit{Shebang} 
(\textit{\#!/usr/bin/make -f}).

<<DebianRulesTemplate>>=
function DebianRulesTemplate {
    # Called by DisplayDebianFiles

    # Strings for debian/rules
    str4rules="#!/usr/bin/make -f\n# -*- makefile -*-\n"\
    str4rulesdh="%:\n\tdh \$@\n\n"

    if ! [ -f ${GitPath}/debian/rules ]
    then
        touch ${GitPath}/debian/rules
        echo -e ${str4rules} >> ${GitPath}/debian/rules
<<DebianRulesTemplate1>>
@

\subsubsection{Export von Variablen}

Es wird durch den Export der Variablen \textit{DH\_VERBOSE} und 
\textit{DH\_OPTIONS}, sowie der Zuweisung entsprechender Werte die 
umfassendere Ausgabe der Meldungen eingeschaltet. 

<<DebianRulesTemplate1>>=
        echo -e "# Uncomment this to turn on verbose mode.\n" \
        >> ${GitPath}/debian/rules        
        echo -e "export DH_VERBOSE=1\nexport DH_OPTIONS=-v\n" \
        >> ${GitPath}/debian/rules

<<DebianRulesTemplate2>>
@

Zusätzlich werden für verschiedene Pakettypen ergänzende Variablen 
exportiert. Diese werden in den jeweiligen Plugins definiert. Die 
Beschreibung für \texttt{Java}-Pakete findet sich in 
Kapitel~\ref{sec:JavaAdaption} (Seite~\pageref{sec:JavaAdaption}). Die 
Anpassung für \texttt{Java}-Pakete erfolgt durch die Funktion
\textit{Rules4Java}.

<<DebianRulesTemplate2>>=
        if [ ${JavaFlag} -eq 1 ]
        then
            . build-gbp-java-plugin
            Rules4Java
        fi    

<<DebianRulesTemplate3>>
@

Für das Bauen der \texttt{Mozilla}-Erweiterungen werden auch zusätzliche 
Einträge benötigt. Die Beschreibung der Besonderheiten für die 
\texttt{Mozilla}-AddOns findet sich in Kapitel~\ref{subsec:webextrules} 
(Seite~\pageref{subsec:webextrules}).

Die Anpassung für \textit{Webext}-Pakete erfolgt durch die Funktion 
\textit{WebextRules} im entsprechenden Plugin 
(Kapitel~\ref{chap:WebextPlugin} Seite~\pageref{chap:WebextPlugin}).

<<DebianRulesTemplate3>>=
        if [ ${WebextFlag} -eq 1 ]
        then
            WebextRules
        fi

<<DebianRulesTemplate4>>
@

Entsprechendes Gilt auch für die \texttt{Python}-Pakete 
(Kapitel~\ref{sec:PythonRules} Seite~\pageref{sec:PythonRules}).

<<DebianRulesTemplate4>>=
        if [ ${PythonFlag} -eq 1 ]
        then
            PythonRules
        fi

<<DebianRulesTemplate5>>
@

\subsubsection{Aufruf der Debhelper}
% Add %:\n\tdh \$@\n\n to the translable string

<<DebianRulesTemplate5>>=
        echo -e ${str4rulesdh} >> ${GitPath}/debian/rules

<<DebianRulesTemplate6>>
@

Für \texttt{Maven}-Pakete muss der Aufruf der \textit{debhelper} ergänzt 
werden. Dies erfolgt duch die Funktion \textit{Rules3MavenDH} des 
Maven-Plugins (Kapitel~\ref{sec:Rules4MavenDH} Seite~\pageref{sec:Rules4MavenDH}). 

<<DebianRulesTemplate6>>=
        if [ ${MavenPluginFlag} -eq 1 ]
        then
            Rules4MavenDH
        fi

<<DebianRulesTemplate7>>
@

Auch für die \texttt{Mozilla}-Erweiterungen muss der Aufruf der 
\textit{debhelper} ergänzt werden. Dies erfolgt durch das 
\textit{Web-Extension-Plugin} (Kapitel~\ref{chap:WebextPlugin}, 
Seite~\pageref{chap:WebextPlugin}).

<<DebianRulesTemplate7>>=
        if [ ${WebextFlag} -eq 1 ]
        then
            WebextRulesDH
        fi

<<DebianRulesTemplate10>>
@

Auch beim Paketieren von Python-Paketen ist der Aufruf der Debhelper in 
der Datei \textit{debian/rules} zu ergänzen.

<<DebianRulesTemplate10>>=
        if [ ${PythonFlag} -eq 1 ]
        then
            PythonRulesDH
        fi

<<DebianRulesTemplate11>>
@

\subsubsection{\textit{debian/rules} - overrides}

Manchmal ist es notwendig, vor oder nach der Asuführung der jeweiligen 
\textit{debhelper}-Skripte, weitere Schritte auszuführen. Dazu wird das 
jeweilige Skript übersteuert.

Beispiel:

\begin{verbatim}
override_dh_auto_build:
        dh_auto_build -- -f org/xmlunit/pom.xml package -DskipTests
\end{verbatim}

In der ersten Zeile des Beispiels wird das Ziel genannt, welches 
modifiziert werden soll. 
Die zweite Zeile muss mit einem \textit{Tabulatorzeichen} in einer Breite 
von 8 Zeichen beginnen.

Das doppelte Minuszeichen bedeutet, dass zunächst die Parameter 
ausgeführt werden, die \textit{dh\_auto\_build} normalerweise übergibt.
Danach können weitere Parameter aufgeführt werden, die an das Programm 
übergeben werden.

\textit{package} bezeichnet das sogenannte \textit{goal}. 

\subsubsection{Schluss der Funktion}

Am Ende der Funktion erfolgt ein Eintrag in die Log-Datei. Die Datei 
\textit{debian/rules} wird zum Editieren angezeigt. Schließlich wird sie 
als \textit{Make}-Datei ausführbar gemacht.

<<DebianRulesTemplate11>>=
        echo "debian/rules was created " >${log}

    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/rules

    if ! [ -x ${GitPath}/debian/rules ]
    then
        chmod ugo+x ${GitPath}/debian/rules
        echo ${GitPath}"/debian/rules is now executable" >> ${log}
    fi
}

<<DebianSalsaCiTemplate>>
@

\subsection{salsa-ci.yml}
\label{subsec:SalsaCi}

Auf \textit{salsa.debian.org} wird im jeweiligen Projekt unter 
\textit{Einstellungen - CI/CD - Allgemeine Pipelines - CI/CD configuration 
file} \textit{debian/salsa-ci.yml} eingetragen, oder der 
entsprechende Dateiname, der sich im Verzeichnis \textit{debian/} befindet.

Damit wird der automatische Bauprozess auch für die 
\textit{Reproducible Builds} ausgelöst. 

<<DebianSalsaCiTemplate>>=
function DebianSalsaCiTemplate {
    # Called by DisplayDebianFiles

    # String for debian/salsa-ci.yml
    str4salsa="include:\n\
    - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/salsa-ci.yml\n\
    - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/pipeline-jobs.yml"

    if ! [ -f ${GitPath}/debian/salsa-ci.yml ]
    then
        touch ${GitPath}/debian/salsa-ci.yml
        echo -e ${str4salsa} >> ${GitPath}/debian/salsa-ci.yml
        echo "debian/salsa-ci.yml was created." >> ${log}
    fi
    nano --linenumbers --mouse --softwrap ${GitPath}/debian/salsa-ci.yml
}

<<SelectChangesFile>>
@

\subsection{debian/javabuild}
\label{subsec:javabuild}

Die folgende Funktion ermöglicht die Erstellung einer Datei 
\textit{debian/javabuild}, welche zum Bauen eines Java-Paketes ohne 
Build-System dienen kann.

Die Datei \textit{debian/javabuild} enthält in jeder Zeile den Namen einer 
\textit{.jar}-Datei gefolgt von einer Liste von Quellcode-Dateien oder 
-Verzeichnissen. Diese Datei wird von dem \textit{javahelper}-Programm 
\textit{jh\_build} eingelesen.

<<DebianJavabuildTemplate>>=
function DebianJavabuildTemplate {
    # Called by DisplayDebianFiles
    # For building a java package without build system (like maven)
    if [ -f debian/javabuild ]
    then
        if whiptail --title "Creating debian/javabuild?" \
        --defaultno --yesno "Should debian/javabuild be created?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            echo "# NameOfJarFile SourceDirToPackage" >>debian/javabuild
            echo "debian/javabuild was created" >> ${log}
            nano --linenumbers --mouse --softwrap debian/javabuild
        fi
    fi
}

<<DisplayDebianChangelog>>
@

\subsection{<Paketname>.install}
\label{subsec:install}

Diese Datei wird benötigt, um anzugeben, wohin Dateien installiert 
werden sollen. Dabei ist zwingend darauf zu achten, dass als Paketname
wirklich der Name des zu bauenden Binary verwendet wird.

<<DisplayDebianFiles5>>=
    if [ ${WebextFlag} -eq 1 ] && [ ! -f ${GitPath}/debian/${PackName}.install ]
    then
        WebextInstall
    fi

    nano --linenumbers --mouse \
    --softwrap ${GitPath}/debian/${PackName}.install
<<DisplayDebianFiles6>>
@

Beispiel:
\begin{verbatim}
nc.jar usr/share/java
\end{verbatim}

Damit werden die jeweiligen Dateien in das zukünftige Verzeichnis kopiert. 
Standardmäßig ist es nicht möglich, eine Datei umzubenennen, damit der 
Dateiname zum Beispiel der Benamung von Java-Bibliotheken in der 
\textit{Debian Policy für Java} \cite{JavaPolicy} entspricht. 

Wie im Handbuch zu \textit{dh\_install}
\footnote{\url{https://manpages.debian.org/unstable/debhelper/dh_install.1.de.html}} 
beschrieben. Dazu sind dann auch weitere Schritte notwendig.

\begin{itemize}
    \item{Das Paket muss eine Bauabhängigkeit zu \textit{dh-exec} haben.
           Das Paket, das in der Datei \textit{debian/control} angegeben 
           werden muss, ist \textit{dh-exec}}
    \item{Die Installationsdatei muss als ausführbar markiert sein.}
\end{itemize}

\subsection{<Paketname>.dirs}

Diese Datei muss nicht zwingend den Namen des Binaries führen. Der Paketname 
kann auch komplett weggelassen werden.

<<DisplayDebianFiles6>>=
    nano --linenumbers --mouse \
    --softwrap ${GitPath}/debian/${PackName}.dirs
<<DisplayDebianFiles7>>
@

Beispiel:
\begin{verbatim}
usr/share/java
\end{verbatim}

\subsection{<Paketname>.docs}

Die hier aufgeführten Dateien werden im Buildprozess vom entsprechenden 
\textit{debhelper} \textit{dh\_installdocs} in ein dazu erstelltes Verzeichnis 
\textit{/usr/share/docs/<Paketname>} installiert.

Die Datei \textit{LICENSE} muss nicht aufgenommen werden. 
Diese wird automatischisch nach \textit{/usr/share/docs/<Paketname>} 
installiert.

<<DisplayDebianFiles7>>=
    nano --linenumbers --mouse \
    --softwrap ${GitPath}/debian/${PackName}.docs
<<DisplayDebianFiles8>>
@

\subsection{<Paketname>.links}
\label{subsec:links}

Diese Datei wird vom \textit{dh\_link} aufgerufen.

<<DisplayDebianFiles8>>=
    if [ ${WebextFlag} -eq 1 ] && [ ! -f ${GitPath}/debian/${PackName}.links ]
    then
        WebextLinksTB
    fi

    nano --linenumbers --mouse \
    --softwrap ${GitPath}/debian/${PackName}.links
<<DisplayDebianFiles9>>
@

\subsection{<Paketname>.desktop}

Dies ist erst einmal ein Beispiel:

<<PaketnameDesktop>>=
[Desktop Entry]
X-AppInstall-Package=JVerein
X-AppInstall-Popcon=1
X-AppInstall-Section=main

Version=1.0
Name=JVerein
Comment=Administration of an Association
Comment[de]=Vereinssoftware
 
Exec=jameica
Icon=jameica-icon
Terminal=false
Type=Application
Categories=Office
Keywords=Association;Verein
StartupNotify=true

@

% TODO: Wenn es eine Desktop-Datei gibt muss der folgende Eintrag auch 
% in die Datei d/<Paketname.install>

% debian/source/include-binaries ist eine Datei. Sie enthält zu Dokumentationszwecke 
% den Namen der Icon Datei, wenn diese nicht von Upstream bereitgestellt wird.
% https://lists.debian.org/debian-mentors/2020/10/msg00018.html

\subsection{<Paketname>.manpages}

Nach der \texttt{Debian}-Policy\cite{DebianPolicy} sollte jedes Programm
und jede Funktion eine entsprechende Handbuchseite haben. Diese sollte
im selben Paket oder zumindest in einer Abhängigkeit enthalten sein.

Gibt es im Quellcode keine solchen Handbuchseiten, muss diese vom
Maintainer erstellt und im Verzeichnis \textit{debian/man} abgelegt werden.

Dieser Ort wird dann in die Datei \textit{<Paketname>.manpages}
eingetragen. Damit kann sie von \textit{dh\_installman} aufgerufen werden.

Beispiel:

\begin{verbatim}
    debian/man/build-gbp.1
\end{verbatim}

\subsection{<Paketname>.examples}

Diese Datei wird vom \textit{dh\_installexamples} aufgerufen.

<<DisplayDebianFiles9>>=
    nano --linenumbers --mouse \
    --softwrap ${GitPath}/debian/${PackName}.examples

<<DisplayDebianFiles10>>
@

\subsection{README.Debian}

\subsection{README.source}
\label{subsec:ReadmeSource}

In dieser Datei können die Ausschlüsse (Kapitel~\ref{subsubsec:BenamungPakete}, 
Seite~\pageref{subsubsec:BenamungPakete}) und ihre Begründungen dokumentiert 
werden\footnote{Debian-Policy, Kapitel 4.14 \cite{DebianPolicy}}. Diese
Datei erhält auf jeden Fall einen Eintrag, wenn mit \textit{maven} gebaut
wird. (Kapitel~\ref{subsec:MavenReadmeSource}, 
Seite~\pageref{subsec:MavenReadmeSource})

\subsection{source/lintian-overrides}
\label{subsec:LintianOverrides}

Manchmal erlauben die \texttt{Debian}-Richtlinien\cite{DebianPolicy}
Ausnahmen von einer Regel. Dann erzeugt \texttt{lintian} eine falsche
Meldung. Gleiches gilt in den seltenen Fällen, in denen \textit{lintian}
selbst fehlerhaft ist.

In diesen Fällen kann die Datei \textit{debian/source/lintian-overrides}
genutzet werden, um eine solche Fehlermeldung zu unterdrücken. Damit wird dann
das Programm fehlerfrei beendet.

Beispiel für eine solche Datei:

\begin{verbatim}
    #/usr/share/lintian/overrides/<PackageName>
    <PackageName>: <Lintian message>
\end{verbatim}

Näheres zu den Lintian-Meldungen findet sich in
Kapitel~\ref{chap:LintianMessages}, (Seite~\pageref{chap:LintianMessages}).

\section{Überprüfung der Dateien in \textit{debian/} mit CmeFix}
\label{sec:cmefix}

Der Befehl \textit{cme fix dpkg} prüft die \textit{dpkg}-Dateien, 
aktualisiert veraltete Parameter und wendet alle Korrekturen an.

Mit dem Parameter \textit{-verbose} erhält man mehr Informationen darüber, 
was passiert. Der Parameter \textit{-backup} erzeugt vor der Speicherung der 
Änderungen Backup-Dateien. Diese werden durch die Endung \textit{.old} 
gekennzeichnet. Zu beachten ist, dass in diesem Fall die Langform der 
Optionen wirklich nur mit einem Bindestrich eingeleitet werden
\footnote{\url{https://manpages.debian.org/unstable/cme/cme.1p.en.html}}.

<<CmeFix>>=

function CmeFix {
    # Called by DisplayDebianFiles

    if whiptail --title "Check and fix with cme?" \
    --yesno "Should debian files be checked and fixed using 'cme fix'?" \
    --yes-button "Yes" --no-button "No" 15 60
    then
        set +e
        if whiptail --title "Backup?" \
        --yesno "Should the recent files be backuped (recommended)?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            cme fix --verbose --backup dpkg
        else
            cme fix --verbose dpkg
        fi
        set -e
<<cmefix1>>
@

Die Ausführung des Programmskriptes wird hier angehalten, damit die 
Ausgaben des Befehls \textit{cme fix dpkg} analysiert werden können.
In einem anderen Terminal können -- sofern die Backupoption gewählt wurde --
die ursprünglichen Dateien mit den neu erstellen Dateien verglichen, 
Backupdateien gelöscht und gegebenenfalls Korrekturen vorgenommen werden.

<<cmefix1>>=
        echo "Please check the result of cme fix!"
        echo "You can check and fix it in another terminal."
        echo "Please press RETURN to go on."
        read a
    fi
}

<<DisplayDebianFiles>>
@

\chapter{Änderungen am Upstream-Code vornehmen}
\label{chap:Aenderungen_am_Upstream_Code_vornehmen}

Weiter geht es mit möglichen Änderungen am Quellcode 
(s.~Kapitel~\ref{subsec:AenderungQuellcodeDateien},
(Seite~\pageref{subsec:AenderungQuellcodeDateien}). Sollen keine 
Änderungen am Quellcode vorgenommen werden, folgt direkt die Behandlung der Datei
\textit{debian/changelog} (Kapitel~\ref{sec:DebianChangelog}, 
Seite~\pageref{sec:DebianChangelog}).

<<BuildNewRevision5-1>>=
    # Patches treatment
    PatchesTreatment

<<BuildNewRevision6>>
@

\section{Sollen Änderungen am Upstream-Code vorgenommen werden?}

Wenn eine neue Revision erstellt wird, wird der Nutzer gefragt, ob 
Veränderungen am Quellcode vorgenommen werden sollen. Dazu prüft das 
Programm zunächst, ob ein Verzeichnis \textit{debian/patches} bereits 
vorhanden ist, und teilt dem Nutzer zuvor das Ergebnis dieser Prüfung mit.

Ist das Verzeichnis \textit{debian/patches} vorhanden, erhält der Nutzer
die Gelegenheit, die Anwendbarkeit der in diesem Verzeichnis vorhandenen
Patches zu prüfen.

<<PatchesTreatment>>=
function PatchesTreatment {
    # Called by BuildNewRevision

    # Patches treatment
    cd ${GitPath}
    if [ ! -d debian/patches ]
    then
        whiptail --title "Info" \
        --msgbox "There is no directory debian/patches" 15 60
<<PatchesTreatment1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ThereIsNoPatchDir.png} 
\caption{Es gibt kein Verzeichnis debian/patches.}
\end{figure}

Nun kann noch entschieden werden, ob für dieses Paket Patches erstellt
werden sollen (Seite~\pageref{par:patches}).

<<PatchesTreatment1>>=
    else
        whiptail --title "Info" \
        --msgbox "There is a directory debian/patches" 15 60

<<PatchesTreatment2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ThereIsPatchDir.png} 
\caption{Es gibt ein Verzeichnis debian/patches.}
\end{figure}

<<PatchesTreatment2>>=
        if whiptail --title "Applicability check"'!' \
        --yesno "Do you want to check the applicability of the patches?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            ApplyCheck
        fi
    fi

<<PatchesTreatment2-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ApplicabilityPatches.png} 
\caption{Anwendbarkeit der Patches prüfen?}
\end{figure}

\paragraph*{}
\label{par:ApplyCheck}

Die Funktion \textit{ApplyCheck} prüft alle im Verzeichnis
\textit{debian/patches} vorhandenen Patches, unabhängig davon, ob sie in
der Datei \textit{debian/patches/series} aufgeführt sind, auf ihre
Anwendbarkeit.

Die Ergebnisse werden nicht nur im Terminal ausgegeben, sondern auch zum
späteren Nachlesen in die Log"=Datei des jeweiligen Projektes geschrieben.

Die Ergebnisse dieses \enquote{Probelaufes} sind vor allem dann nicht
aussagekräftig, wenn mehrere Patches dieselbe Datei verändern sollen.

<<ApplyCheck>>=
function ApplyCheck {
    # Called by PQMigration

    echo -e "\nResults will also be written in "${log}"\n"
    echo -e "\nResults of tests of applicability of patches\n" >> ${log}
    patchfilesa=$(ls debian/patches/)
    set +e
    for element in ${patchfilesa[*]}
    do
        if [ ${element} != 'series' ]
        then
            echo "Check "${element}
            echo "Check "${element} >> ${log}
            acmessage=$(patch --dry-run -p1 --verbose < debian/patches/${element})
            echo ${acmessage}
            echo -e "\n"
            echo ${acmessage} >> ${log}
        fi
    done
    set -e
    # For reading whether the patches are applicable
    echo
    echo "-- Look whether the patches are applicable --"
    echo
    echo "After reading press RETURN to go on!"
    read a
}

<<RebasePQBranch>>
@

Nun erfolgt die Abfrage, ob Patches erstellt, bearbeitet oder 
gelöscht werden sollen. Außerdem kann zwischen den beiden Methoden 
\textit{quilt} (Kapitel~\ref{sec:NutzungQuilt}, 
Seite~\pageref{sec:NutzungQuilt}) und \textit{gbp pq} 
(Kapitel~\ref{sec:WorkingwithGbpPq}, Seite~\pageref{sec:WorkingwithGbpPq}) 
gewählt werden.

\paragraph*{}
\label{par:patches}

<<PatchesTreatment2-1>>=
    PMTask=$(whiptail --title "Tasks:" \
    --radiolist "Do you want to create, edit or delete patches?" 15 60 4 \
    "0" "By using quilt" off \
    "1" "By using gbp pq" off \
    "2" "No" on --cancel-button "Exit" 3>&2 2>&1 1>&3)

<<PatchesTreatment3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchesTasks.png} 
\caption{Patches für Debian erstellen}
\end{figure}

Natürlich kann der Bauprozess auch ohne \textit{patchen} fortgesetzt
werden. Wird die Option \enquote{No} ausgewählt, geht es mit dem Editieren
der Datei\textit{debian/changelog} weiter (Kapitel~\ref{sec:DebianChangelog},
Seite~\pageref{sec:DebianChangelog}).

Das Patchen mit \textit{quilt} ist die \enquote{klassische} Methode und
führt direkt zu den in das \texttt{Debian}"=Paket (unter \textit{debian/patches})
aufzunehmenden Dateien. Das Vorgehen mit \textit{gbp pq} ist für alle,
die gut und gerne mit \texttt{Git} arbeiten. Diese Methode sollte bei der
Nutzung von \textit{git-buildpackage} bevorzugt werden.

Mit \textit{Exit} wird das Programmskript verlassen.

<<PatchesTreatment3>>=
    if [ -z "${PMTask}" ]
    then
        exit
    fi

<<PatchesTreatment4>>
@

Hat man sich zum Patchen und zu einer Methode entschieden, ruft das 
Programmskript nun die jweils weiterführenden Funktionen auf.

<<PatchesTreatment4>>=
    if [ ${PMTask} -eq 0 ]
    then
        PatchRunNr=0
        set +e
        PatchTasks
        set -e

<<PatchesTreatment5>>
@

Entweder man arbeitet mit \textit{gbp pq} oder mit \textit{quilt}.
Hat man sich für die Arbeit mit \textit{quilt} entschieden, wird die 
Variable \textit{PatchRunNr} auf \textit{0} gesetzt und die Funktion 
\textit{PatchTasks} (Kapitel~\ref{sec:NutzungQuilt}, 
Seite~\pageref{sec:NutzungQuilt}) aufgerufen.

Arbeitet man mit \textit{gbp pq} erfolgt der Warnhinweis, dass alles
committet sein muss.

<<PatchesTreatment5>>=
    elif [ $PMTask -eq 1 ]
    then
        # Message in upper case and red
        echo -e "\n\n\033[31mEVERYTHING MUST BE COMMITTED! \033[0m \n"
        CheckGitStatus
        PQMigration
    fi
}

<<LastQuestionsBeforeBuild>>
@

Die Funktion \textit{PQMigration} des Programmskriptes wird aufgerufen.

Vor dem Aufruf der Funktion \textit{PQMigration} (und vorsichtshalber 
später nochmals) wird zur Prüfung die Funktion \textit{CheckGitStatus}
(Kapitel~\ref{subsec:CheckGitStatus}, 
Seite~\pageref{subsec:CheckGitStatus}) aufgerufen.

\section{Arbeiten mit \textit{gbp pq}}
\label{sec:WorkingwithGbpPq}

Um Patches zu verwalten, kann \textit{gbp pq} verwandt werden. Dies ist
hauptsächlich für Quellpakete im Format \textit{3.0 (quilt)} 
gedacht (s. Kapitel~\ref{subsec:d/source/format}, 
Seite~\pageref{subsec:d/source/format}).
Die Änderung des Upstream-Quellcodes erfolgt durch Dateien im Verzeichnis
\textit{debian/patches/}. 

Die Funktion \textit{PQMigration} kann unter Verwendung dieser Patches
einen Patch-Queue-Zweig erstellen, falls er noch nicht existiert. Ferner
kann diese Funktion einen existierenden Patch-Queue-Zweig aktualisieren.


<<PQMigration>>=
function PQMigration {
    # Called by PatchesTreatment and itself
    # Transfers patches into patch-queue branch
    npqf=0
    cd ${GitPath}
    
<<PQMigration0>>
@

Das Programmskript unterscheidet vier Fälle.

\subsection{Fallunterscheidung}

Es wird geprüft, ob es eine Datei \textit{debian/patches/series}
gibt oder nicht. Gibt es diese Datei, ermöglicht das Programmskript eine
Prüfung der Situation (Kapitel~\ref{subsubsec:CheckSituation},
Seite~\pageref{subsubsec:CheckSituation}).

Auch wird geprüft, ob es einen passenden \textit{Patch-Queue-Branch} gibt.

Es sind vier Fälle zu unterscheiden: 

\begin{enumerate}
    \item Es gibt weder eine Datei \textit{debian/patches/series} noch
        einen passenden \textit{Patch-Queue Branch}. Dann wird mit
        \textit{git checkout -b} ein neuer \textit{Patch-Queue Branch}
        erzeugt und in diesen gewechselt (Seite~\pageref{par:case1}).
    \item Die Datei \textit{debian/patches/series} existiert nicht, aber
        schon ein passender \textit{Patch-Queue Branch}. Dann wird
        auf dessen Vorhandensein hingewiesen und in diesen gewechselt
        (Seite~\pageref{par:case2}).
    \item Die Datei \textit{debian/patches/series} existiert, aber kein
        passender \textit{Patch-Queue Branch}. Dann wird mit
        \textit{gbp pq import} ein passender \textit{Patch-Queue Branch}
        erzeugt (Seite~\pageref{subsubsec:case3}). Dies scheitert, wenn
        nicht alle Patches der Queue anwendbar sind. Daher wird 
        \textbf{dringend} empfohlen, die vom Programmskript ermöglichte 
        Prüfung der Situation durchzuführen
        (Kapitel~\ref{subsubsec:CheckSituation},
        Seite~\pageref{subsubsec:CheckSituation}).
    \item Sowohl die Datei \textit{debian/patches/series} als auch der
        passende \textit{Patch-Queue Branch} existieren
        (Seite~\pageref{subsubsec:UpdatePQBranch}). Dann wird
        \textit{gbp pq rebase} angewandt.Daher wird \textbf{dringend} 
        empfohlen, die vom Programmskript ermöglichte Prüfung der
        Situation durchzuführen (Kapitel~\ref{subsubsec:CheckSituation},
        Seite~\pageref{subsubsec:CheckSituation}).
\end{enumerate}

Ein \textit{Patch-Queue}-Zweig wird lediglich in den Fällen 1 und 3
erstellt. Andernfalls wird der schon vorhandene \textit{Patch-Queue-Zweig}
auf die neue Version aktualisiert.

\subsection{Die \enquote{einfachen} Fälle}
\label{subsec:CreatePQMigration}

Gibt es die Datei \textit{debian/patches/series} nicht, ist der Wechsel
in den \textit{Patch"=Queue}"=Zweig unkompliziert, da sich das Problem der
Anwendbarkeit der Patches nicht stellt.

<<PQMigration0>>=
    if [ ! -f debian/patches/series ] # debian/patches/series does not exists
    then
        # Case 2
        # Anything is easy
        npqf=1
        set +e
        if echo $(git branch) | grep --quiet 'patch-queue/'${RecentBranch}
        then
            whiptail --title "PQ-branch exists" \
            --msgbox "Branch 'patch-queue/${RecentBranch}' exists." 15 60
            git checkout patch-queue/${RecentBranch}
<<PQMigration0-1>>
@

\paragraph*{}
\label{par:case2}

Wenn die Datei \textit{debian/patches/series} nicht existiert, aber schon
ein passender \textit{Patch-Queue-Zweig} (\textbf{Fall 2}), erscheint als
Hinweis folgende Nachricht.

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PQBranchExists.png}
\caption{Es existiert ein PQ-Zweig.}
\end{figure}

In diesen Zweig wird dann gewechselt.

\paragraph*{}
\label{par:case1}

Existiert die Datei \textit{debian/patches/series} nicht und auch kein 
passender Patch-Queue-Zweig (\textbf{Fall 1}), wird er neu erstellt
und in diesen gewechselt.

<<PQMigration0-1>>=
        # Case 1
        else # creating a new patch-queue branch
            git checkout -b patch-queue/${RecentBranch}
        fi
        set -e
<<PQMigration1>>
@

Es kann dann sofort mit der Bearbeitung des Quellcodes begonnen werden
(Kapitel~\ref{subsec:EditSourceCode}, 
Seite~\pageref{subsec:EditSourceCode}).

\subsection{Die \enquote{schwierigeren} Fälle}

Beim Import in den Patch-Queue-Zweig und bei der Aktualisierung desselben
werden die Patches auf den Upstream-Quellcode angewandt.

Voraussetzung dafür ist, dass sich alle in der Datei 
\textit{debian/patches/series} aufgeführten Patches anwenden lassen.
Andernfalls schlagen \textit{gbp pq import} oder \textit{gbp pq rebase}
fehl. Dann wird kein \textit{Patch-Queue-Zweig} erzeugt.

Sowohl \textit{gbp pq rebase} als auch \textit{gbp pq import}
(\textbf{Fälle 3 und 4)} setzen also voraus, dass es im aktuellen Git-Zweig
keine unversionierten Dateien gibt \textbf{und} sich alle bisherigen Patches
anwenden lassen. Andernfalls sind Merge-Konflikte zu lösen. Hierauf wird
der Nutzer hingewiesen.

<<PQMigration1>>=
    else # debian/patches/series exists
        Notice="All patches listed in 'debian/patches/series' \n\
        have to be applicable"'!'"\n\
        Otherwise you have to solve 'merge conflicts'"'!'
        if whiptail --title "Attention please"'!' \
        --yesno "${Notice} Do you want to check the situation?" \
        --yes-button "Yes" --no-button "No" 15 60
<<PQMigration1-0>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchesAppliable.png}
\caption{Alle Patches müssen anwendbar sein.}
\end{figure}

\subsubsection{Prüfen der Situation}
\label{subsubsec:CheckSituation}

Wird die Frage, ob die Situation geprüft werden soll, bejaht, wird -- wenn
gewünscht -- die Funktion \textit{ApplyCheck} aufgerufen
(Seite~\pageref{par:ApplyCheck}). Diese prüft mit \enquote{Probeläufen}, 
ob die im Verzeichnis \textit{debian/patches} vorhandenen Patch-Dateien 
auf den neuen Upstream"=Quellcode anwendbar sind und teilt das Ergebnis mit.

Die Ergebnisse sind vor allem dann nicht aussagekräftig, wenn mehrere 
Patches dieselbe Datei verändern sollen.

Der Nutzer wird gefragt, ob diese Prüfung (noch einmal) erfolgen soll.

<<PQMigration1-0>>=

        then
            if whiptail --title "Applicability check"'!' \
            --yesno "Do you want to check the applicability of the patches\n\
            (another time)?" \
            --yes-button "Yes" --no-button "No" 15 60
            then
                ApplyCheck
            fi
            ShowPatches "check"
<<PQMigration1-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ApplicabilityPatchesAgain.png}
\caption{(Nochmalige) Prüfung der Anwendbarkeit der Patches?}
\end{figure}

Das Programm verbleibt zunächst im ursprünglichen Zweig.

Es können Änderungen an Patch-Dateien vorgenommen werden. Dies sollte
in einfachen und eindeutigen Fällen -- wie folgt -- geschehen. Die
Funktion \textit{ShowPatches} (Kapitel~\ref{sec:ChoosePatches},
Seite~\pageref{sec:ChoosePatches}) zeigt die vorhandenen Patch"=Dateien
zur Auswahl an. Ausgewählte Patch"=Dateien können dann editiert werden.
In der Regel kann dies durch \textit{Cancel} übergegangen werden,

In der Datei \textit{debian/patches/series} werden alle Patches in der
Reihenfolge aufgelistet, in der diese bisher angewandt wurden.

Wenn vorhandene Patches nicht anwendbar sind, müssen diese vor dem
Wechsel in den \textit{Patch"=Queue}"=Zweig in der Datei 
\textit{debian/patches/series} deaktiviert (auskommentiert) werden.

Dafür wird gefragt, ob die Datei \textit{debian/patches/series} editiert
werden soll.

<<PQMigration1-1>>=
            if whiptail --title "Attention please"'!' \
            --yesno "Do you want to edit 'debian/patches/series'?" \
            --yes-button "Yes" --no-button "No" 15 60
            then
                nano --linenumbers --mouse --softwrap debian/patches/series
            fi
        fi

        echo -e ${Notice}
        CheckGitStatus
    fi
<<PQMigration2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/EditPatchesSeries.png}
\caption{Soll \textit{debian/patches/series} editiert werden?.}
\end{figure}

Nicht-anwendbare Patches sollten bereits hier darauf geprüft werden, ob
die Probleme durch Upstream bereits behoben wurden und diese Patches
damit entfallen.

Dann können diese Patches aus der Datei \textit{debian/patches/series}
entfernt werden.

Werden Patches oder die Datei \textit{debian/patches/series} verändert,
müssen diese Änderungen committet werden. Daher wird auch nochmals der
\texttt{Git}-Status geprüft.

\subsubsection{\textit{gbp pq import}}
\label{subsubsec:case3}

Existiert die Datei \textit{debian/patches/series}, aber noch kein 
entsprechender Patch-Queue-Zweig, wird \textit{gbp pq import} ausgeführt.
Dies geschieht in der Funktion \textit{PQImport} (\textbf{Fall 3}).

<<PQMigration3>>=
        else # patch-queue branch does not exist
            # Case 3
            if whiptail --title "Attention"'!' \
            --yesno "Do you really want to use 'gbp pq import'?" \
            --yes-button "Yes" --no-button "Working with Quilt" 15 60
            then
                PQImport 0
<<PQMigration3-1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/GbpPqImportUse.png}
\caption{Soll \textit{gbp pq} genutzt werden?}
\end{figure}

\textit{gbp pq import} erzeugt einen neuen Patch-Queue-Zweig aus den 
\textit{quilt patches} im Verzeichnis \textit{debian/patches}, die in der
Datei \textit{debian/patches/series} aufgeführt sind. Diese Patches müssen
ohne Unschärfe anwendbar sein.

<<PQImport>>=
function PQImport {
    # Called by PQMigration and itself
    # returnflag=$1
    # if [ ! ${returnflag} ]
    # then
    #     returnflag=1
    # fi
    cd ${GitPath}
    set +e
    if echo $(git branch) | grep --quiet 'patch-queue/'${RecentBranch}
    # patch-queue branch already exists
    then
        set -e
        return
    fi
    set -e

    if [ -f debian/patches/series ]
    # debian/patches/series exists   
    then
        if whiptail --title "There are patches" \
        --yesno "Do you like to import the current patches\n\
         onto the patch-queue branch? (recommended)" \
        --yes-button "Yes" --no-button "No" 15 60
<<PQImport1>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/ThereArePatches.png}
\caption{Es gibt Patches}
\end{figure}

<<PQImport1>>=
        then
            CheckGitStatus
            set +e
            echo "Notice from gbp pq import: " >> ${log}
            gbp pq --verbose import >> ${log} 2>&1
            if [ $? -eq 1 ]
            then
                Notice="\n\nAll patches listed in debian/patches/series\n\
                have to be applicable"'!'"\n\
                For Details, look into the log file of the project.\n"
                FailureNotice ${Notice}
<<PQImport2>>
@

\begin{figure}[!h] 
\centering 
\includegraphics[width=25em]{Pictures/GbpPqImportFailed.png}
\caption{PQ-Import fehlgeschlagen}
\end{figure}

Schlägt der Import fehl, wird eine Möglichkeit zur Fehlerbehebung eröffnet
(Kapitel~\ref{subsec:FailureNotice}, Seite~\pageref{subsec:FailureNotice}). 

Zur Fehlerbehebung nach einem Fehlschlag können nur allgemeine Hinweise 
gegeben werden.

In einem weiteren Terminal können folgende Schritte ausgeführt werden.

\begin{itemize}
    \item In der Log-Datei den fehlgeschlagenen Patch identifizieren.
    \item Einfache Fehler direkt im Patch-File anpassen;
    \item Patch-File committen.
    \item Alternativ Patch in der Datei \textit{debian/patches/series}
     deaktivieren;
    \item dann \textit{debian/patches/series} committen.
    \item Zurück in das ursprünglichen Terminal;
    \item dort mit <RETURN> weiter.
\end{itemize}

Nach der Fehlerbehebung kann ein erneuter Importversuch unternommen werden.
Dieser Vorgang kann wiederholt werden, um sich Schritt für Schritt dem
erfolgreichen Import zu nähern.

Wird der Versuch der Fehlerbebung endgültig für misslungen erachtet,
kann der Import abgebrochen werden.

<<PQImport2>>=
                if whiptail --title "Fixed?" --yesno "Retry?" \
                --yes-button "Yes" --no-button "No import" 15 60
<<PQImport3>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/FixedRetry.png}
\caption{Fixed? Retry?}
\end{figure}

<<PQImport3>>=
                then
                    PQImport ${returnflag}
                else
                    whiptail --title "No import onto a patch-queue branch" \
                    --msgbox "Let's go on without the import\n\
                    of the current patches onto a patch-queue branch" \
                    15 60
                fi
            fi
            set -e
        fi
    fi
}

<<ClassicalOrUscan>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/NoPQImport.png}
\caption{Kein Import in Patch-Queue}
\end{figure}

\paragraph*{}
\label{par:ImportExistingPatches}

Ziel ist es, durch \textit{gbp pq import} einen \textit{Patch"=Queue}"=Zweig
zu erstellen, in dem dann gearbeitet werden kann. 

<<PQImport4>>=
            else
                whiptail --title "Done" \
                --msgbox "Imported the current patches onto the patch-queue branch" \
                15 60
<<PQImport5>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/PQImport.png}
\caption{PQ-Import erfolgreich}
\end{figure}

Der erfolgreiche Import in den PQ-Branch wird mit einem Dialog angezeigt.

Der Inhalt von \textit{debian/patches} wird
mit \textit{gbp pq} in den Patch-Queue-Branch importiert und in diesen 
gewechselt\footnote{s. Abschnitt \textit{gbp.patches.html} und 
\textit{man.gbp.pq.html}\cite{Guenther2006-2017}}.

Nach erfolgreichem Import in den \textit{Patch-Queue}-Zweig kann mit der
Bearbeitung des Quellcodes begonnen werden (Kapitel~\ref{subsec:EditSourceCode},
Seite~\pageref{subsec:EditSourceCode}).

Beim Import wird eine Ausgabe wie folgt erzeugt:
\begin{verbatim}
    gbp:info: Versuchen, Patches \
    unter'aaa1011bfd5aa74fea43620aae94709de05f80be' \
    anzuwenden.

    gbp:info: 18 Patches, die in 'debian/patches/series' \
    aufgelistet sind, importiert unter 'patch-queue/debian/sid'.
\end{verbatim}

Es wurde mit \textit{gbp pq} jede Patchdatei importiert und in den neu 
erstellten Patch-Queue-Zweig \textit{patch-queue/debian/sid} gewechselt. 

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/pq-applied.png}
\caption{Der Patch-Queue-Zweig mit Patches von debian/patches wurde 
angewandt.\cite{Guenther2006-2017}}
\end{figure}

\subsubsection{Aktualisieren des Patch-Queue-Zweiges}
\label{subsubsec:UpdatePQBranch}

Das Programmskript prüft, ob bereits ein entsprechender Patch-Queue-Zweig 
existert.

Existiert ein passender Patch-Queue-Zweig ruft das Programmskript 
zunächst die Funktion \textit{RebasePQBranch} auf (\textbf{Fall 4}).

Andernfalls wird Patch-Queue-Zweig durch \textit{gbp pq import} aus 
dem aktuellen \textit{Git}-Zweig erstellt (Kapitel~\ref{par:ImportExistingPatches}, 
Seite~\pageref{par:ImportExistingPatches}).

<<PQMigration2>>=

    if [ ${npqf} -eq 0 ]
    then
        set +e
        if echo $(git branch) | grep --quiet 'patch-queue/'${RecentBranch}
        # patch-queue  branch exists
        then
            # Case 4
            RebaseCounter=0
            RebasePQBranch
<<PQMigration3>>
@

Die Funktion \textit{RebasePQBranch} führt ein \textit{gbp pq rebase} aus.
Die Commits des \textit{debian/}-Zweiges werden auf den Patch-Queue-Zweig 
angewandt.

Mit \textit{gbp pq rebase} wird in den Patch-Queue-Zweig gewechselt, der 
mit dem aktuellen Zweig verbunden ist. Alle Neuerungen des aktuellen 
Zweiges werden durch ein \textit{rebase} in den Patch-Queue-Zweig 
übernommen.\cite{GBP-PQ2020} 

<<RebasePQBranch>>=
function RebasePQBranch {
    # Called by PQMigration and itself
    if [ ${RebaseCounter} == 0 ]
    then
        gbp pq rebase --verbose
    else
        git rebase --continue
    fi

<<RebasePQBranch1>>
@

Misslingt die Ausführung von \textit{gbp pq rebase}, kann und muss händisch 
eingegriffen werden, um die Situation zu bereinigen

Hierzu werden von \texttt{Git} dem Nutzer Hinweise gegeben, die sorgfältig
studiertt und meist befolgt werden sollten.

<<RebasePQBranch1>>=        
    if [ $? -ne 0 ]
    then
        git rebase --show-current-patch | cat
<<RebasePQBranch2>>
@

An dieser Stelle wird der Patch angezeigt, der nicht (komplett) angewandt
werden kann. Mit dieser Hilfe ist es dann möglich, nach der Unterbrechung
manuell die Merge-Konflikte aufzulösen. 

<<RebasePQBranch2>>=
        Notice="gbp pq rebase failed"'!'"\n\
        All changes must be committed"'!'"\n\
        All patches have to be applicable"'!'"\n"
        FailureNotice ${Notice}
        RebaseCounter=$(expr ${RebaseCounter} + 1)
        RebasePQBranch
    fi
}

<<PQMigration>>
@
Wie die Konflikte aufgelöst werden können, wird im Folgenden beschrieben. 

Das Programmskript gibt in solchen Fällen den Hinweis, auf ein weiteres
Terminal zu wechseln. Dort kann mit \textit{git status} überprüft werden,
dass ein unvollständiger Rebase vorliegt. 

Mit dem nachstehenden Befehl wird in dem weiteren Terminal der
fehlgeschlagene Patch angezeigt.

\begin{verbatim}
    git rebase --show-current-patch
\end{verbatim}

In noch einem weiteren Terminal kann das (noch) Vorhandensein der zu patchenden
Datei mit folgendem Befehl geprüft werden.

\begin{verbatim}
    tar --list --file ../<UpstreamPackageName>.orig.tar.xz | \
    grep <Filename>
\end{verbatim}

Ist die Datei nicht (mehr) vorhanden, kann der Patch mit

\begin{verbatim}
    git rebase --skip 
\end{verbatim}

entfernt werden. Sodann ist im (ursprünglichen) Terminal, in dem das
Programmskript läuft, mit \textit{RETURN} fortzufahren. Damit wird
zunächst ein \textit{git rebase --continue --verbose} ausgeführt.

Wenn die zu patchende Datei existiert, muss sie in einem Editor
bearbeitet werden. Die Patches sind so zu verändern, dass sie auf die
neue Version angewandt werden können.

Die Datei ist dann zu speichern und ein \textit{git add <Dateiname>}
auszuführen. Im ursprüngliche Terminal ist mit \textit{RETURN} fortzufahren.

Der Vorgang ist gegebenenfalls sooft zu wiederholen, bis das Programmskript
mit seiner Ausführung fortfährt.

Eine Möglichkeit ist es auch, durch den Befehl

\begin{verbatim}
    gbp pq import --time-maschine=<n>
\end{verbatim}

solange Commit für Commit durchzugehen, bis die Patch-Queue angewandt
werden kann.

\textit{n} gibt dabei die maximale Anzahl der Rückschritte an.

Danach kann ein erneuter Versuch erfolgen.

Notfalls kann der Prozess mit 

\begin{verbatim}
    git rebase --abort
\end{verbatim}

abgebrochen werden.

Im Erfolgsfalle geht es mit der Bearbeiten des Quellcodes weiter.

\subsection{Bearbeiten des Quellcodes}
\label{subsec:EditSourceCode}

Dass mit der Bearbeitung des Quellcodes im \textit{Patch"=Queue}"=Zweig
begonnen werden kann, zeigt das Programmskript im Terminal an.

<<PQMigration4>>=

    # Starting the work in the patch-queue branch
    echo
    echo "\033[32m-- Starting the work in the patch-queue branch --/033[0m"
    echo
    echo "Break for patching in another terminal"
    echo "Do not forget to commit the changes!"
    echo
    echo "After finishing press RETURN to go on!"
    read a

<<PQMigration5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em]{Pictures/Break4Patching.png}
\caption{Unterbrechung zum Patchen}
\end{figure}

Nach der Bearbeitung des Quellcodes kann das Programmskript mit einem
\textit{RETURN} fortgesetzt werden. Dann erfolgt der Export der Patches
(Kapitel~\ref{subsec:PatchExport}, Seite~\pageref{subsec:PatchExport}).

Im separaten Terminal sollte mit \textit{git branch -v} festgestellt 
werden, dass der richtige Git-Zweig (\textit{patch-queue/}-Zweig) 
aktiv ist und dass dessen Stand dem des bisherigen Git-Zweiges entspricht. 
Sodann können Dateien im Patch-Queue-Zweig bearbeitet werden.

Code kann hinzugefügt, verändert oder entfernt werden. So können die
Patches erstellt oder \enquote{in Form gebracht} werden.

Dabei sind die Änderungen möglichst kleinteilig zu committen. Was später 
ein einzelner Patch in \textit{debian/patches/} werden wird, wird einfach 
durch einen Commit hinzugefügt. 

Die erste Zeile der Commit-Nachricht wird später Teil des Patch-Na\-mens. 
Die folgenden Zeilen enthalten die Details zu den Funktionen des Patches.
Daher ist es sinnvoll mehrzeilige Commit-Nachrichten zu schreiben.

Die mehrzeilige Commit-Nachricht sollte dann im Patch der 
\textit{Patch tagging guideline} 
entsprechen\footnote{\url{https://dep-team.pages.debian.net/deps/dep3/}\cite{DEP-3}}
Der Header der Patch-Datei sieht dann wie folgt aus:

Der Autor und das Datum werden automatisch gesetzt. Der unter
\textit{Gbp-PQ} anzugebene Name darf keine Leerzeichen enthalten. Diese
sind gegebenenfalls durch \textit{Unterstriche (\_)} zu ersetzen. Dies
wird der Name der Patch-Datei im Verzeichnis \textit{debian/patches}.

\begin{verbatim}
From: Autor <E-Mail-Adresse>
Date: <Erstellungsdatum und -zeit>
Subject: <Commit-Nachricht>

Gbp-Pq: Name <name of the patch>
Forwarded: Yes/No <if necessary>
Last Update: <dateof the last version of the patch>

* posix/regcomp.c (re_compile_fastmap_iter): Rewrite COMPLEX_BRACKET
  handling.

Origin: upstream, http://sourceware.org/git/?p=glibc.git;\
a=commitdiff;h=bdb56bac
Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697
Bug-Debian: http://bugs.debian.org/510219
\end{verbatim}

Diese kann mit \textit{git commit -{}-amend} korrigiert werden. Es öffnet
sich der Editor zur Eingabe der neuen Commit-Message.

Die Bearbeitung des Quellcodes sollte damit beginnen, die in der Datei
\textit{debian/patches/series} deaktivierten Patches anwendbar zu machen.
Hierzu sind die Patch"=Datei und die zu patchende Datei zu vergleichen.

Stellt sich dabei heraus, dass die Probleme durch die Upstream-Entwickler
bereits behoben worden sind, ist (an dieser Stelle) nichts mehr zu tun.

\subsection{Export der Patches}
\label{subsec:PatchExport}

Sobald wir mit den Commits zufrieden sind, können die Patches in 
\textit{debian/patches/} unter Verwendung von \textit{gbp pq} neu generiert
werden.
Dadurch wechseln wir zurück zum Zweig debian/sid und regenerieren die Patches 
mit einer Methode ähnlich dem git-format-patch:

Das Ergebnis könnte nun wie folgt hinzugefügt werden:

\begin{verbatim}
  gbp pq export
  git add debian/patches 
  git commit
\end{verbatim}

\textit{gbp pq export} bedeutet:

Exportiert die Patches auf dem Patch-Queue-Branch, der mit dem 
aktuellen Zweig verbunden ist, in eine Quilt-Reihe von Patches nach 
\textit{debian/patches/} und aktualisierte die Datei \textit{series} 
im aktuellen Zweig (z.B. \textit{debian/sid})\footnote{\url{https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.patches.html}}\cite{Guenther2006-2017}.

Damit das Ergebnis nicht jedes Mal von Hand übertragen werden muss, kann 
auch \textit{--commit} an den gbp-Exportbefehl übergeben werden.

<<PQMigration5>>=
    # Export
    if whiptail --title "Use gbp pq export?" \
    --yesno "Do you like to use 'gbp pq export --commit'?" \
    --yes-button "Yes" --no-button "No" 15 60
<<PQMigration7>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/GbpPqExport.png}
\caption{Soll \textit{gbp pq export} angewandt werden?}
\end{figure}


<<PQMigration7>>=
    then
        CheckGitStatus
        gbp pq export --commit --verbose >> ${log} 2>&1
        echo "Check branch."
        git branch --verbose
        echo "Press RETURN to continue!"
        read a
<<PQMigration8>>
@

Nach dem \textit{RETURN} kann die Datei \textit{debian/changelog}
aktualisiert werden (z.~B. durch Ausführen von \textit{gbp dch -S -a},
was dasselbe ist wie \textit{gbp dch -{}-snapshot -{}-auto}.
(Kapitel~\ref{sec:DebianChangelog}, Seite~\pageref{sec:DebianChangelog})

Das Paket kann dann -- wie gewohnt -- erstellt werden.

Wird die Frage verneint, kann manuell eingegriffen werden.

<<PQMigration8>>=
    else
        git log
        git checkout ${HistoricBranch}
        ReplaceConfigLines 'RecentBranch' ${HistoricBranch}
        git branch
        echo "-- You have cancelled the export from patch-queue branch --"
        echo
        echo "You are still in the patch-queue branch!"
        echo "Break for fixing in another terminal"
        echo "After finishing press RETURN to go on!"
        read a
    fi
}

<<PatchTasks>>
@

\section{Bauen schlägt fehl}
\label{sec:MorePatchesNeeded}

Wenn das Bauen fehlschlägt und weitere Patches benötigt werden oder
Patches zu korrigieren sind, muss das Programmskript neugestartet werden.

Vor einem Neustart muss gegebenenfalls das Bau"=Verzeichnis bereinitgt
werden. Dazu wird es auf den Stand nach dem Export gesetzt.

Im \textit{Patch"=Queue}"=Zweig können dann Änderungen an den
Quellcode"=Dateien vorgenommen werden. Der danach notwendige Export der
Patches wird in Kapitel~\ref{subsec:PatchExport}
(Seite~\pageref{subsec:PatchExport}) beschrieben.

Es kann die Patch-Queue geprüft und eventuell auch mittels \textit{dquilt}
bearbeitet werden.

Dann kann im Hauptzweig ein erneuter Bau-Versuch unternommen werden.

\section{Auswahl der Patches}
\label{sec:ChoosePatches}

Die folgende Funktion \textit{ShowPatches} kann sowohl beim Arbeiten mit
\textit{gbp pq} als auch beim Arbeiten mit \textit{quilt} Anwendung finden.

Beim Aufruf durch die Funktion \textit{PQMigration} wird die Funktion 
\textit{ShowPatches} mit dem Parameter \textit{check} aufgerufen.

Die einzelnen Patches können angepasst werden. Wenn benötigt, kann man
sich die Ausgaben des \enquote{Probelaufes} in der Log"=Datei ansehen.

<<ShowPatches>>=
function ShowPatches {
    # Called by EditPatch DeletePatch PQMigration and itself
    actionstr=${1}

    patchfilesa=$(ls debian/patches)
    i=0; slct=''
    for element in ${patchfilesa[*]}
    do
        if [ ${element} != 'series' ]
        then
            slct=$slct' '$i' '${element}' off '
            newPFA[$i]=${element}
            i=$(expr $i + 1)
        fi
    done

    set +e
    PatchFileNo=$(whiptail --title "Select patch" \
    --radiolist "Select one of these patches for editing.\
    In doubt press Cancel." \
    --cancel-button "Cancel" 15 80 8 \
    $slct 3>&2 2>&1 1>&3)

<<ShowPatches1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SelectPatches.png}
\caption{Dateiauswahl bestätigen}
\end{figure}

<<ShowPatches1>>=
    if [ $? -eq 1 ]
    then
        return
    fi
    set -e

    if [ "${actionstr}" = "check" ]
    then
        # Code for PQMigation
        if [ -z "${PatchFileNo}" ]
        then
            return
        fi
        PatchFileName=${newPFA[$PatchFileNo]}
        nano --linenumbers --mouse --softwrap debian/patches/${PatchFileName}
        ShowPatches "check"
<<ShowPatches2>>
@

Der ausgewählte Patch wird zum Editieren angezeigt. Alle Änderung sind
zu committen.

<<ShowPatches2>>=
    else
        if [ -z "${PatchFileNo}" ]
        then
            PatchFileName=""
        else
            PatchFileName=${newPFA[$PatchFileNo]}
            if ! whiptail --title "${PatchFileNo}" \
            --yesno "Do you want to ${actionstr} ${PatchFileName}?" \
            --yes-button "Yes" --no-button "No" 15 60
            then
                ShowPatches
            fi
        fi
    fi
}

<<EditPatch>>
@

\section{Nutzung von Quilt}
\label{sec:NutzungQuilt}

Die Änderungen am Upstream können auch mittels Quilt erfolgen. 

<<PQMigration3-1>>=
            else
                PatchTasks # Working with Quilt
            fi
        fi
        set -e
    fi
<<PQMigration4>>
@

Wie zuvor beschrieben, ist \textit{dquilt} zunächst einzurichten 
(Kapitel~\ref{sec:QuiltEinrichtung}, Seite~\pageref{sec:QuiltEinrichtung}).

Die Einrichtung in der \textit{.bashrc} lässt sich bei der Ausführung 
dieses Programms nicht nutzen (Kapitel~\ref{sec:QuiltEinrichtung}, 
Seite~\pageref{sec:QuiltEinrichtung}). 

Das Programm prüft daher zunächst, ob \textit{quilt} zur Verfügung steht. 
Da das Skript den Alias der \textit{.bashrc} unbeachtet lässt, wird 
\textit{dquilt} in einer Variablen definiert.

<<CreateDquilt>>=
function CreateDquilt {
    # Called by PatchTasks

    # Check whether quilt is available
    if [ ${PatchRunNr} -eq 0 ]
    then
        if [ ! -f ~/.quiltrc-dpkg ]
<<CreateDquilt1>>
@

Die Zeile prüft, ob es im Home-Verzeichnis des Nutzers eine Datei 
\textit{.quiltrc-dpkg} existiert. 
Wenn diese Datei nicht existiert, erfolgt die Meldung, dass 
\textit{dquilt} nicht konfiguriert ist, weil dann der entsprechende Alias 
für \textit{quilt --quiltrc=\${HOME}/.quiltrc-dpkg} nicht erstellbar ist.

<<CreateDquilt1>>=
        then
            whiptail --title "No dquilt!" \
            --msgbox "Dquilt seems not to be configured.\n \
            See: https://www.debian.org/doc/manuals/maint-guide/modify.html" \
            15 62
            exit
        fi

<<CreateDquilt2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NoDQuilt.png}
\caption{\textit{dquilt} ist nicht konfiguriert.}
\end{figure}

Wenn die Datei \textit{.quiltrc-dpkg} nicht gefunden wird, gibt das Skript 
eine entsprechende Meldung aus und wird beendet.

Nur wenn die Datei \textit{~/.quiltrc-dpkg} existiert, kann die folgende 
Definition erfolgen.

<<CreateDquilt2>>=
    # Definition of dquilt
        dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
    fi   
}

<<MakePatches>>
@

\subsection{Bisher kein Patch vorhanden}

Zunächst prüft das Programmskript, ob das Verzeichnis \textit{debian/patches}
vorhanden ist.

<<PatchTasks>>=
function PatchTasks {
    # Called by PatchesTreatment and itself

    cd ${GitPath}
    if [ ! -d debian/patches ]
    then
        # Create patch
        if whiptail --title "Patches" --yesno "Is a patch necessary?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            CreateDquilt
            MakePatches
        else
            return
        fi

<<PatchTasks0>>
@        

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchNecessary.png}
\caption{Wird ein Patch benötigt?}
\end{figure}

Gibt es bisher keinen Patch, kann nur ein neuer Patch estellt werden. Dies
erfolgt mit der Funktion \textit{CreateNewPatch}.
(Kapitel~\ref{subsec:CreateNewPatch}, Seite~\pageref{subsec:CreateNewPatch}). 

<<MakePatches>>=
function MakePatches {
    # Called by PatchTasks and itself

    cd ${GitPath}
    cnpr=0
    CreateNewPatch
    if [ $cnpr -ne 0 ]
    then
        return
    fi

    PatchRunNr=1

    if whiptail --title "Another patch?" \
    --yesno "Do you want to apply another patch?" --yes-button "Yes" \
    --no-button "No" 15 60
    then
        MakePatches
    fi
}

<<ShowPatches>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/AnotherPatch.png}
\caption{Ein weiterer Patch?}
\end{figure}

\subsection{Was soll getan werden?}
Sind bereits Patches vorhanden, wird zur Auswahl gestellt, ob weitere
Patches erzeugt, editiert oder entfernt werden sollen. Diese Aufgaben
können in beliebiger Reihenfolge und auch mehrmals ausgeführt werden.

<<PatchTasks0>>=
    else
        CreateDquilt
        PTask=$(whiptail --title "Tasks:" \
        --radiolist "What do you like to do? " 15 60 8 \
          "0" "Display patch files to check or edit them" off \
          "1" "Create additional patch" off \
          "2" "Add another patch to existing patch file" off \
          "3" "Show patch files for deleting" off \
          "4" "Edit debian/patches/series" off \
          "5" "Exit to go on" on --cancel-button "Cancel" 3>&2 2>&1 1>&3)
<<PatchTasks1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DQuiltTasks.png}
\caption{Aufgaben für \texttt{Quilt}}
\end{figure}

Wird der Button \textit{Cancel} gedrückt, so wird ebenfalls die Aufgabe 
\textit{Exit to go on} ausgeführt. Es wird der Ausgangszustand
wieder hergesellt. (Kapitel~\ref{subsec:CreateInitialStatus}, 
Seite~\pageref{subsec:CreateInitialStatus}) 

<<PatchTasks1>>=

        if [ $? -eq 1 ]
        then
            PTask=5
        fi

<<PatchTasks2>>
@

Im folgenden Abschnitt wird den einzelnen Aufgaben Befehle zugeordnet. 
Dabei enthält die Variable \textit{PTask}  eine Ziffer von 0 bis 4.

Wenn beispielsweise dieser Variablen der Wert \textit{0 = Display patch 
files to check or edit them} zugewiesen wurde, dann wird die Funktion 
\textit{ChangePatches} ausgeführt.

In der folgenden \textit{case-Anweisung} ist \textit{0)} ein Wert aus der 
Liste von 0 bis 4, gegen den der Inhalt der Variable \textit{PTask} 
verglichen wird.

<<PatchTasks3>>=
            1) MakePatches;; # If (more) patches are necessary
<<PatchTasks4>>
@

\subsection{Neuen Patch erstellen}
\label{subsec:CreateNewPatch}

Beim Erstellen eines neuen Patches wird zunächst der Name der Patch"=Datei
erfragt.

<<CreateNewPatch>>=
function CreateNewPatch {
    # Called by MakePatches

    PatchFileName=$(whiptail --title "Patch name" \
    --inputbox "Name of the patchfile:" \
    --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
    if [ $? -ne 0 ]
    then
        cnpr=1
        return 1
    fi

<<CreateNewPatch0>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchName.png}
\caption{Name des Patches}
\end{figure}

<<CreateNewPatch0>>=

    # Because a user might use blanks in a filename
    PatchFileName=$(echo ${PatchFileName} | sed --expression='s/ /-/g')
    if [ -z "${PatchFileName}" ]
    then
        cnpr=1
        return 1
    fi

<<CreateNewPatch1>>
@

Es wird geprüft, ob ein gleichnamiger Patch bereits existiert.

<<CreateNewPatch1>>=
    if [ -f debian/patches/${PatchFileName} ]
    then
        if ! whiptail --title "Patch exists" \
        --yesno "${PatchFileName} exists already.\nContinue?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            return 1
        fi
    fi

<<CreateNewPatch2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchExits.png}
\caption{Patch existiert bereits!}
\end{figure}

Der Befehl \textit{dquilt new} mit dem Parameter des Patch-Namens erzeugt 
die erste "Patch-Datei".
 
Hierbei werden folgende Dateien erzeugt (Patch-Name exemplarisch): 
\begin{verbatim}
    debian/patches/series
        enthält den Namen des Patches DescriptionNoRegistration.patch 
    .pc/applied-patches
        enthält den Namen des Patches DescriptionNoRegistration.patch 
    .pc/DescriptionNoRegistration.patch/
    .pc/.quilt_patches
        enhält debian/patches 
    .pc/.quilt_series
        enthält series 
    .pc/.version
        enthält 2 
\end{verbatim}

Wenn schon Patches existieren, ist darauf zu achten, dass diese in der 
Datei \textit{debian/patches/series} in der korrekten Reihenfolge genannt 
werden.

<<CreateNewPatch2>>=
    # Create a new patch file
    $dquilt new ${PatchFileName}

    # Patch
    FileToPatch
<<CreateNewPatch4>>
@

\subsection{Datei zum Patchen auswählen}

<<PatchTasks4>>=
            2) FileToPatch # Add patch to patch file
               PatchRunNr=1
               $dquilt refresh;;
<<PatchTasks6>>
@

Wird ein neuer Patch erstellt oder soll ein weiterer Patch einer
existierenden Patch"=Datei hinzugefügt werden, ist die Quellcode"=Datei
auszuwählen, die verändert werden soll.

<<FileToPatch>>=
function FileToPatch {
    # Called by CreateNewPatch PatchTasks and itself

    FileSelector ${GitPath} # Select the file to be patched
    File2Patch=${selected}

    echo "Patch ${PatchFileName} because of ${File2Patch}" >> ${log}

    # quilt add must get only the filename without 
    # the path of the file to be patched
    File2pName=$(basename ${File2Patch})
    $dquilt add -P ${PatchFileName} ${File2pName}

    nano --linenumbers --mouse --softwrap ${File2Patch}

    $dquilt refresh ${PatchFileName}

    if whiptail --title "Patch another" \
    --yesno "Do you want to patch another file in ${PatchFileName}?" \
    --yes-button "Yes" --no-button "No" --defaultno 15 60
    then
        FileToPatch
    fi
}

<<CreateNewPatch>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PatchAnotherFile.png}
\caption{Eine weitere Datei patchen?}
\end{figure}

Die Auswahl der zu korrigierenden Datei erfolgt in einem Dateiauswahldialog.

<<FileSelector>>=
function FileSelector {
    # Called by CreateNewPatch and itself
    # Dialog to select a file using whiptail
    
    StartPath=$1
    cd $StartPath
    txta=($(ls -a))

    i=0
    flist=''
    for element in ${txta[*]}
    do
        if [ $element == '.' ]
        then
            i=$(expr $i + 1)
            continue
        fi
        flist=$flist' '$i' '${element} 
        i=$(expr $i + 1)
    done

    sel=$(whiptail --title "Filepicker" \
    --menu "Select:" 15 60 6 $flist 3>&2 2>&1 1>&3)

<<FileSelector1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/FilePicker.png}
\caption{Dateiauswahldialog}
\end{figure}

<<FileSelector1>>=
    if [ $? -ne 0 ]
    then
        return
    fi

    # Go back
    if [ ${txta[$sel]} = '..' ]
    then
        cd ..
        StartPath=$(pwd)
        selected=${StartPath}
    else
        selected=${StartPath}"/"${txta[$sel]}
    fi

    # The order of the following if-clauses is important
    if [ -f ${selected} ]
    then    
        if ! whiptail --title "Your choice;" \
        --yesno "${selected}\nContinue?" --yes-button "Yes" \
        --no-button "No" 15 60
        then
            FileSelector ${StartPath}
        fi
    fi

<<FileSelector2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ConfirmedChoose.png}
\caption{Dateiauswahl bestätigen}
\end{figure}

<<FileSelector2>>=
    if [ -d ${selected} ]
    then
        FileSelector ${selected}
    fi
}

<<FileToPatch>>
@

Sind in diesem Verzeichnis alle Dateien vorhanden, wird mit 
\textit{dquilt add} mit dem Parameter der zu bearbeitenden Datei diese 
in \textit{quilt} eingebunden.
 
Damit wird in \textit{.pc/DescriptionNoRegistration.patch/} die genannte 
Datei hinzugefügt. 
Dort steht sie dann für den ersten Abgleich zur Verfügung.

<<CreateNewPatch4>>=
    PatchHeader
}

<<CreateDquilt>>
@

\subsection{Patch löschen}

Mit der folgenden Auswahl werden bestehende Patches gelöscht. 
Dies ist notwendig, wenn ein bisheriger Patch nicht mehr benötigt wird, 
weil die Korrekturen inzwischen vom Upstream eingebaut wurden.

<<PatchTasks6>>=
            3) DeletePatches;; # Delete patches
<<PatchTasks7>>
@

Es kann aber auch sein, dass der bisherige Patch für die aktuelle 
Up\-stream-Version angepasst werden muss. 
Ein Weg hierzu ist, den alten Patch zu löschen und einen neuen zu erstellen.

<<DeletePatches>>=
function DeletePatches {
    # Called by PatchTasks and itself
    
    cd ${GitPath}
    DeletePatch
    PatchRunNr=1

    if whiptail --title "Another patch?" \
    --yesno "Do you want to delete another patch?" --yes-button "Yes" \
    --no-button "No" 15 60
    then
        DeletePatches
    fi
}

<<ApplyCheck>>
@

Wird die Frage mit \textit{No} beantwortet, springt das Programm zur 
Auswahl der Patchaufgaben (Kapitel~\ref{sec:NutzungQuilt}, 
Seite~\pageref{sec:NutzungQuilt}) zurück.

<<DeletePatch>>=
function DeletePatch {
    # Called by DeletePatches

    ShowPatches "delete" # String will be found in ${1}

    if [ -z "${PatchFileName}" ]
    then
        PatchTasks
    fi

    less --LINE-NUMBERS ${GitPath}/debian/patches/${PatchFileName}
    
    if whiptail --title "Delete this patch?" \
    --yesno "Do you really want to delete ${PatchFileName}?" \
    --yes-button "Yes" --no-button "No" 15 60
    then    
        $dquilt delete -r --backup ${PatchFileName}

        if whiptail --title "Delete backup file?" \
        --yesno "Do you want to delete the backup file, too" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            rm ${GitPath}/debian/patches/${PatchFileName}~
        fi
    fi
}

<<DeletePatches>>
@

\subsection{\textit{debian/patches/series} editieren}

Ein Grund, die Datei \textit{debian/patches/series} zu bearbeiten ist zu
gewährleiten, dass in dieser Datei die Patches in der korrekten Reihenfolge
aufgeführt werden.

<<PatchTasks7>>=
               # Edit series
            4) nano --linenumbers --mouse --softwrap debian/patches/series;;
<<PatchTasks8>>
@

\subsection{Ausgangszustand wiederherstellen}
\label{subsec:CreateInitialStatus}

Wenn ein Patch mit \textit{quilt} erstellt, bearbeitet oder gelöscht wurde, 
werden beim Verlassen der Funktion die Patches aus dem Upstream-Code 
entfernt und dieser in den ursprünglichen Zustand zurückversetzt. Dies 
geschieht mit \textit{quilt pop -a}. Dies bedeutet, dass alle angewandten 
Patches entfernt werden.

<<PatchTasks8>>=
            5) if [ ${PatchRunNr} -eq 1 ]
               then
                   # remove all patches and return the source
                   # to its original state
                   ${dquilt} pop -a
                   PatchRunNr=0
               fi
               # If debian/patches/series is empty,
               # delete directory debian/patches
               if ! [ -s debian/patches/series ]
               then
                   rm debian/patches/series
                   rmdir debian/patches
               fi
               return;;
        esac
    fi

    PatchTasks  
}

<<GitBranch2RecentBranch>>
@

So ist es für Quilt möglich immer das Diff zwischen der Vorversion und 
der aktuellen Version zu erstellen. 
Danach erfolgt die Änderung. 
Die Informationen zur Registrierung werden entfernt. 
Mit \textit{dquilt refresh} erzeugt man das Diff zur Dokumentation der 
Änderung. 
Mit \textit{dquilt header -e} wird nun die Beschreibung der Änderung im 
\$EDITOR erstellt.

<<PatchHeader>>=
function PatchHeader {
    # Called by CreateNewPatch EditPatch

    PatchDescription=$(whiptail --title "Describe patch!" \
    --inputbox "Description:\n\n" \
    --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
    if [ -z "${PatchDescription}" ]
    then
        echo "Please insert the description of the patch!"
        read PatchDescription
    fi
    if whiptail --title "Describe patch!" --yesno "Forwarded:?" \
    --yes-button "Yes" --no-button "No" 15 60
    then
        PatchForwarded="Yes"
    else
        PatchForwarded="No"
    fi

    DEBValues
    if [ -z ${Uploaders} ]
    then
        PatchAuthor=${Maintainer}
    else
        PatchAuthor=${Uploaders}
    fi

    PatchUpdate=$(date +%Y'-'%m'-'%d)

    touch ${PatchFileName}.header
    echo "Description: "${PatchDescription} >> ${PatchFileName}.header
    echo "Forwarded:   "${PatchForwarded} >> ${PatchFileName}.header
    echo "Author:      "${PatchAuthor} >> ${PatchFileName}.header
    echo "Last-Update: "${PatchUpdate} >> ${PatchFileName}.header
    
    $dquilt header -a < ${PatchFileName}.header
    rm ${PatchFileName}.header
}

<<FileSelector>>
@

Hier ein Beispiel dazu:

\begin{verbatim}
Description: removed registration of license 
Forwarded: No 
Author: Mechtilde Stehmann <ooo@mechtilde.de> 
Last-Update: 2014-05-18 
\end{verbatim}

\subsection{Patch bearbeiten}

<<PatchTasks2>>=
        # Patches treatment
        case "$PTask" in
            0) ChangePatches;; # Edit patches
<<PatchTasks3>>
@

Zum Bearbeiten eines Patches wird die Funktion \textit{EditPatch}
aufgerufen.

<<ChangePatches>>=
function ChangePatches {
    # Called by PatchTasks and itself

    cd ${GitPath}
    EditPatch

    if whiptail --title "Another patch?" \
    --yesno "Do you want to edit another patch?" --yes-button "Yes" \
    --no-button "No" 15 60
    then
        ChangePatches
    fi
}

<<DeletePatch>>
@

Diese ruft die Funktion \textit{ShowPatches} mit dem Parameter 
\textit{edit} auf.

<<EditPatch>>=
function EditPatch {
    # Called by ChangePatches

    ShowPatches "edit" # String will be found in ${1}
    
    if [ -z "${PatchFileName}" ]
    then
        return 1
    else
        PatchRunNr=1
    fi

    $dquilt pop ${PatchFileName}
    nano --linenumbers --mouse --softwrap debian/patches/${PatchFileName}
    $dquilt refresh
    
    if whiptail --title "New Patch Header" \
    --yesno "Do you want to create a new patch header?" --yes-button "Yes" \
    --no-button "No" 15 60
    then
        PatchHeader
    fi
    
    while $dquilt push
    do
       $dquilt refresh
    done
}

<<ChangePatches>>
@

\chapter{Bauen}
\label{chap:Bauen}

Das eigentliche Bauen der Binärpakete erfolgt in einer \textit{chroot}. 
Hierbei wird hauptsächlich geprüft, ob alle benötigten Buildabhängigkeiten 
in der Datei \textit{debian/control} (Kapitel~\ref{subsec:DebianControl}, 
Seite~\pageref{subsec:DebianControl}) aufgeführt sind und bereits als 
\texttt{Debian}-Pakete zur Verfügung stehen.

Damit wird gewährleistet, dass das Paket auch von den FTP-Mastern 
reproduzierbar ohne Zugriff auf weitere Netzressourcen gebaut werden kann.

\section{debian/changelog}
\label{sec:DebianChangelog}

Vor dem eigentlichen Bauen wird die Datei \textit{debian/changelog} zur 
Anpassung angezeigt.

<<BuildNewRevision6>>=
    # Check debian/changelog
    # - includes creating changelog using gbp dch
    DisplayDebianChangelog

<<MovingGbpConf>>
@

Zunächst wird im Skript geprüft, ob eine Datei \textit{debian/changelog} 
bereits existiert. Wenn dies der Fall ist, wird diese Datei angezeigt und 
abgefragt, ob sie korrekt ist.

Andernfalls wird sie mit \textit{gbp dch} erzeugt.

<<DisplayDebianChangelog>>=
function DisplayDebianChangelog {
    # Called by BuildNewRevision

    newChangelog=0
    if [ -f debian/changelog ]
    then
        less --LINE-NUMBERS debian/changelog
        if ! whiptail --title "Changelog ok?" --defaultno \
        --yesno "Is debian/changelog ok?" --yes-button "Yes" \
        --no-button "No" 15 60
        then
            newChangelog=1
        fi
    else
        newChangelog=1
    fi

<<DisplayDebianChangelog1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ChangelogOK.png}
\caption{Debian-Changelog OK?}
\end{figure}

Wird die Frage nach der Korrektheit des Changelogs bejaht, geht es mit 
einem eventuellen Verschieben der \textit{gbp}-Konfigurationsdatei weiter
(Kapitel~\ref{sec:MovingGbpconfFile}, 
Seite~\pageref{sec:MovingGbpconfFile}).

Ist ein solches Verschieben der \textit{gbp}-Konfigurationsdatei nicht
erforderlich, werden die Parameter für \textit{gbp buildpackage} festgelegt
(Kapitel~\ref{sec:preparations}, 
Seite~\pageref{sec:preparations}).

Andernfalls wird diese Datei im Editor angezeigt.

%Als Nächstes können Sie die Datei \textit{debian/changelog} aktualisieren
%(z.~B. durch Ausführen von \textit{gbp dch -S -a}, was dasselbe ist wie 
%\textit{gbp dch -{}-snapshot -{}-auto)} und das Paket -- wie gewohnt -- erstellen.

Zu achten ist besonders auf die Versions- und Revisionsbezeichnung in der 
ersten Zeile der Datei \textit{debian/changelog}. Dies gilt hauptsächlich, 
wenn Dateien aus dem Upstream-Quellcode ausgeschlossen wurden 
(Kapitel~\ref{subsubsec:BenamungPakete}, 
Seite~\pageref{subsubsec:BenamungPakete}).

Für einen Non-Maintainer-Upload (NMU) wird als erster Eintrag nach den 
Informationen zu der Version der Eintrag

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

erwartet.

Existiert die Datei \textit{debian/changelog} noch nicht, wird sie mit 
\textit{gbp dch} erzeugt.

<<DisplayDebianChangelog1>>=
    # Check whether d/control exists without a comment in line 1
    if [ ${newChangelog} -eq 1 ]
    then
        if ! [ -f debian/control ]
        then
            DebianControlTemplate
        else
            set +e
            cat --number debian/control | grep '^1 ' | grep '#' > /dev/null
            if [ $? -eq 0 ]
            then
                set -e
                DebianControlTemplate
            fi
            set -e
        fi
        # creating changelog using gbp dch

        AddVersionNumber
<<DisplayDebianChangelog3>>
@

\subsection{Versionsbezeichnung einfügen}
\label{subsec:Versionsbezeichnung}

\textit{gbp dch} benötigt die Angabe der aktuellen Versionsbezeichnung. 
Enthält die entsprechende Variable nicht diesen Wert, wird zur 
(manuellen) Eingabe dieser Versionsbezeichnung aufgefordert.

Dagegen kann \textit{dch} die nächsthöhere Versionsbezeichnung mit 
\textit{dch --increment} erstellen. 
Dies kann auch explizit mit \textit{dch -{}-newversion <Version>} erfolgen.
\footnote{New Maintainer Guide, Kap. 8.1\cite{maint-guide}}

Das Programmskript nutzt die zweite Möglichkeit.
 
<<AddVersionNumber>>=
function AddVersionNumber {
    # Called by DisplayDebianChangelog
    if [ -z "${Version1}" ]
    then
        RecentIdentifier
    fi

<<AddVersionNumber1>>
@

Zunächst wird geprüft, welche Versionsbezeichnung in der ersten 
Zeile der Datei \textit{debian/changelog} eingetragen ist. 
Es wird abgefragt, ob eine dort gefundene Versionsbezeichnung übernommen 
werden soll. Exisiert die Datei \textit{debian/changelog} nicht, wird
die Versionsnummer abgefragt (s.~Seite~\pageref{par:InsertIdentifier}).

<<RecentIdentifier>>=
function RecentIdentifier {
    # Called by AddVersionNumber ForceOrig
    # Takes version number from debian/changelog, if it exists

    if [ -f ${GitPath}/debian/changelog ]
    then
        set +e
        firstLine=$(grep --line-number 'urgency=' ${GitPath}/debian/changelog | grep '^1:')
        set -e
        whiptail --title "First line:" \
        --msgbox "First line of debian/changelog;\n${firstLine}" 15 60
        recentId=$(echo ${firstLine} | sed --expression='s/^.*(//' | \
        sed --expression='s/).*//')
<<RecentIdentifier2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/FirstLineChangelog.png}
\caption{Anzeige der ersten Zeile der Datei \textit{debian/changelog}}
\end{figure}

<<RecentIdentifier2>>=
        whiptail --title "Recent identifier" \
        --msgbox "Recent identifier is ${recentId}" 15 60

<<RecentIdentifier3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RecentId.png} 
\caption{Aktuelle Version}
\end{figure}

<<RecentIdentifier3>>=
        if [ -n "${recentId}" ]
        then
            Version1=${recentId}
        fi
    else
        InsertIdentifier
    fi
}

<<AddVersionNumber>>
@

Danach geht es mit Kontrollfragen weiter.

<<AddVersionNumber1>>=
    set +e
    revisionflag=$(echo ${Version1} | grep --count '\-[0-9]')
    set -e
    if [ ${revisionflag} -eq 0 ]
    then
        if ! whiptail --title "Identifier of the version:" \
        --defaultno --yesno "${Version1} contains no revision number.\n \
        Is it a native package?" --yes-button "Yes" --no-button "No" 15 60

<<AddVersionNumber2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/NoRevisionNumber.png}
\caption{Keine Revisionsnummer angegeben}
\end{figure}

<<AddVersionNumber2>>=
        then
            InsertIdentifier
            if ! whiptail --title "Identifier of the version:" \
            --defaultno --yesno "Is ${Version1} the right identifier?" \
             --yes-button "Yes" --no-button "No" 15 60

<<AddVersionNumber3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RightIdentifier.png}
\caption{Korrekte Versionsbezeichnung angegeben?}
\end{figure}

<<AddVersionNumber3>>=
            then
                InsertIdentifier
            fi
        fi
    else
        if ! whiptail --title "Identifier of the version:" \
        --defaultno --yesno "Is ${Version1} the right identifier?" \
        --yes-button "Yes" --no-button "No" 15 60
        then
            InsertIdentifier
        fi
    fi
    echo "Message from AddVersionNumber: identifier="${Version1} >> ${log}
}

<<DebianJavabuildTemplate>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RightIdentifier.png}
\caption{Korrekte Versionsbezeichnung angegeben?}
\end{figure}

\paragraph*{}
\label{par:InsertIdentifier}

In der Funktion \textit{InsertIdentifier} wird zunächst der komplette 
Bezeichner des Paketes einschließlich der Verionsbezeichnung der Revision 
abgefragt.

<<InsertIdentifier>>=
function InsertIdentifier {
    # Called by AddVersionNumber Recentidentifier
    RIdentifier=${Version1}
    set +e
    cat debian/source/format | grep "native" > /dev/null
    if [ $? -eq 0 ]
    then
        Version1=$(whiptail --title "Identifier" \
        --inputbox "Recent identifier: ${RIdentifier}\n \
        Please insert the identifier of the package\n \
        (without revision version because it is a native package):" \
        --nocancel 15 60 3>&2 2>&1 1>&3)

<<InsertIdentifier1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/IdentifierVersionNative.png} 
\caption{Abfrage des Bezeichners eines nativen Paketes}
\end{figure}

<<InsertIdentifier1>>=
    else
        Version1=$(whiptail --title "Identifier" \
        --inputbox "Recent identifier: ${RIdentifier}\n \
        Please insert the whole identifier of the package\n \
        (including revision version):" \
        --nocancel 15 60 3>&2 2>&1 1>&3)
    fi
    set -e
}

<<RecentIdentifier>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/IdentifierVersion.png} 
\caption{Abfrage des Bezeichners}
\end{figure}

Anhand des Vorhandenseins einer Tilde wird geprüft, ob es sich 
um eine Schnappschuss"=Version handelt. Ist dies der Fall, wird dem Befehl 
\textit{gbp dch} auch die Option \textit{-{}-dch-opt=-{}-force-bad-version}
mitgegeben und dies angezeigt. 

Dies bewirkt, dass das Programm \textit{debchange} nicht stoppen wird, falls 
die neue Version kleiner als die aktuelle ist. Dies ist vor allem beim 
Rückportieren sinnvoll

<<DisplayDebianChangelog3>>=
        set +e
        SnapshotFlag=$(echo ${Version1} | grep --count '~')
        if [ ${SnapshotFlag} -eq 0 ]
        then
            DchAdd=''
        else
            DchAdd=' --dch-opt=--force-bad-version'
            whiptail --title "Additional option to gbp dch:" \
            --msgbox "Option: ${DchAdd}" 15 60
        fi
<<DisplayDebianChangelog4>>
@
\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/AdditionalOption.png} 
\caption{Weitere Optionen für \textit{dch}}
\end{figure}

Die Datei \textit{debian/changelog} wird vom Programmskript mittels des 
Programms \textit{gbp dch} erstellt. Immer wird \textit{gbp dch} mit den 
Optionen \textit{-{}-verbose}, \textit{-{}-debian-branch=} und
\textit{-{}-new-version=} aufgerufen.

Im Falle eines Fehlschlages von \textit{gbp dch} wird eine Fehlermeldung 
ausgegeben. Andernfalls wird die Datei \textit{debian/changelog} zum 
Editieren angezeigt.

<<DisplayDebianChangelog4>>=
        gbp dch --verbose --debian-branch=${RecentBranch} \
        --new-version=${Version1}${DchAdd}
        if [ $? -ne 0 ]
        then
            set -e
            FailureNotice
        fi
        set -e
        nano --linenumbers --mouse --softwrap debian/changelog
    fi
}

<<CmeFix>>
@

Für das Paket \textit{tbsync} ergab sich folgende Befehlszeile zum Bauen 
einer Fehlerkorrektur für Buster, das seinerzeit das stabile Release war.

\begin{verbatim}
 gbp dch --verbose --debian-branch=debian/buster \
 --new-version=1.16-1~deb10u1 --dch-opt=--force-bad-version   
\end{verbatim}

Zum Hintergrund ist folgendes auszuführen:

Mit \textit{-{}-dch-opt=\textless{}dch-option\textgreater{}} können dem 
Befehl \textit{gbp dch} Optionen für \textit{debchange} (\textit{dch})
mitgegeben werden. Dabei ist zu beachten, dass
\textit{dbp dch} das Programm \textit{dch} mehrfach aufruft und die 
Option jeweils bei allen Aufrufen übergibt. Daher sind an dieser Stelle 
nicht alle \textit{dch}-Optionen sinnvoll. Außerdem kann es passieren, 
dass Optionen im Widerspruch stehen zu Optionen, die von \textit{gbp dch} 
selbstständig übergeben werden.

Nach dem Schließen des Editors wird regelmäßig der Dialog zur Prüfung des
\texttt{Git}-Zweiges angezeigt (Kapitel~\ref{subsec:CheckGitBranch},
Seite~\pageref{subsec:CheckGitBranch}).

\section{Verschieben der \textit{gbp}-Konfigurationsdatei}
\label{sec:MovingGbpconfFile}

Wenn für das zu bauende Paket eine spezielle Konfigurationsdatei für 
\textit{git-buildpackage} verwandt werden soll (Kapitel~\ref{sec:GbpConf}, 
Seite~\pageref{sec:GbpConf}), wird diese im Verzeichnis \textit{debian/}
mitveröffentlicht.

Wurde für \textit{gbp import-orig} beim (erstmaligen) Herunterladen des 
Quellcodes eine solche Konfigurationsdatei erstellt 
(Kapitel~\ref{subsec:GbpConf}, Seite~\pageref{subsec:GbpConf}), ist diese
gegebenenfalls in das Verzeichnis \textit{debian/} zu verscheiben. Dies
geschieht durch die Funktion \textit{MovingGbpConfFile}.

<<MovingGbpConf>>=
    MovingGbpConfFile
<<Preparations>>
@

Existiert eine Datei \textit{gbp.conf} im Verzeichnis \textit{.git/}, 
aber keine im \textit{debian/}-Verzeichnis, so wird diese Datei nach 
\textit{debian/} verschoben.

Sind in beiden Verzeichnissen entsprechende Dateien vorhanden, kann die 
zu veröffentlichende Datei ausgewählt werden.

<<MovingGbpConfFile>>=
function MovingGbpConfFile {
    # Called by BuildNewRevision

    # .git/gbp.conf exists, but not debian/gbp.conf
    # Move gbp.conf from .git/ to debian/
    if [ -f ${GitPath}/.git/gbp.conf -a ! -f ${GitPath}/debian/gbp.conf ]
    then
        mv -iv ${GitPath}/.git/gbp.conf ${GitPath}/debian
    fi
    # There is a gbp.conf in both directories
    if [ -f ${GitPath}/.git/gbp.conf -a -f ${GitPath}/debian/gbp.conf ]
    then
        TwoConfFilesFound
    fi
}

<<DebianBranch4Import>>
@

Die Funktion \textit{TwoConfFilesFound}, welche diese Auswahl ermöglicht,
wird in (Kapitel~\ref{subsec:GbpConf}, Seite~\pageref{subsec:GbpConf})
beschrieben.

\section{Parameter für \textit{gbp buildpackage} festlegen}
\label{sec:preparations}

Bevor das Bauen der Pakete beginnen kann, müssen zunächst Parameter für 
\textit{gbp buildpackage} ermittelt und festgelegt werden.


<<Preparations>>=
    # Preparations for gbp buildpackage
    AskDist # Ensure that RecentBranch has a value
<<Preparations1>>
@

\subsection{Git-Zweig und Distribution ermitteln}
\label{subsec:IdentifyDist}

Damit im richtigen Git-Zweig und mit der richtigen Distribution gebaut wird, 
werden diese Parameter ermittelt und angezeigt. Sie können auch noch vom
Benutzer angepasst werden.

Zunächst werden mit der Funktion \textit{IdentifyBranches} die vorhandenen
\texttt{Git}-Zweige ermittelt (Kapitel~\ref{subsec:IdentifyBranches},
Seite~\pageref{subsec:IdentifyBranches}).

<<AskDist>>=
function AskDist {
    # Called by BuildNewRevision PrepareUploading LastQuestionsBeforeBuild

    IdentifyBranches
    ba=($bl)
    set +e
    for element in ${ba[*]}
    do
        # rb=$(echo ${element} | grep --count '^x_')
        # if [ $rb -ge 1 ]
        if echo ${element} | grep --quiet '^x_'
        then
            CurrentBranch=$(echo ${element} | sed --expression='s/^x_//')
        fi
    done
    set -e

<<AskDist0>>
@

Zunächst wird mit \textit{-z} geprüft, ob die Variable \textit{RecentBranch}
leer ist. In diesem Fall wird die Funktion \textit{GitBranch2RecentBranch}
(Kapitel~\ref{subsec:GitBranch2RecentBranch},
Seite~\pageref{subsec:GitBranch2RecentBranch}) aufgerufen.

Andernfalls wird geprüft, ob der Name des aktuellen Zweiges dem Wert der
Variablen \textit{RecentBranch} entspricht.Sollte dies nicht de rFall sein,
erfolgt ein Hinweis und der Nutzer kann einen der beiden Zweige auswählen.

<<AskDist0>>=
    if [ -z "${RecentBranch}" ]
    then
        GitBranch2RecentBranch
    else    
        if [ "${RecentBranch}" != "${CurrentBranch}" ]
        then
            Msg="Branch according to git: "${CurrentBranch}",\n \
            branch according to "${ConfigPath}${OrigName}": "${RecentBranch}
            whiptail --title "There is something wrong!" --msgbox "${Msg}" 15 60
<<AskDist1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SomethingWrong.png}
\caption{Da läuft was falsch!}
\end{figure}

<<AskDist1>>=
            WishedBranch=$(whiptail --title "Choose branch:" \
            --radiolist "Which branch do you want to work with? " \
            --cancel-button "Cancel" 15 60 2 \
            "0" "${RecentBranch}" off \
            "1" "${CurrentBranch}" off 3>&2 2>&1 1>&3)
<<AskDist2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ChooseBranch.png}
\caption{Auswahl des Branches}
\end{figure}

<<AskDist2>>=
            if [ ${WishedBranch} -eq 0 ]
            then
                git checkout ${RecentBranch}
            else
                GitBranch2RecentBranch
            fi
        fi
    fi

    echo "Notice from AskDist: The branch is "${RecentBranch} >> ${log}
    set +e
    va=$(grep --count ${RecentBranch}_Dist ${ConfigPath}${OrigName})
    if [ $va -eq 1 ]
    then
        bName=${RecentBranch}
        set -e
        Search4Dist
        RecentBranchD=${va}
    elif [ $va -gt 1 ]
    then
        nano ${ConfigPath}${OrigName}
        AskDist

<<AskDist5>>
@

<<AskDist5>>=
    else
        set -e
        Distro4Branch
    fi
    set -e

    if [ -z "${RecentBranchD}" ]
    then
        RecentBranchD="sid"
    fi
    echo "Notice from AskDist: The distribution is "${RecentBranchD} >> ${log}
}

<<InsertIdentifier>>
@

\subsection{\texttt{Git}-Zweig und Distribution prüfen}
\label{subsec:CheckGitBranch}

Der \texttt{Git}-Zweig wird angezeigt, damit der nutzer prüfen kann, ob
es der richtige ist.

<<Preparations1>>=
    echo "Notice from BuildNewRevision: Branch is "${RecentBranch} >> ${log}
    whiptail --title "Please check!" \
    --yesno "The git branch is ${RecentBranch}" --yes-button "Yes" \
    --no-button "No" 15 60
    rbq=$?
<<Preparations2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ReleaseBranch.png}
\caption{Anzeige des \texttt{Git}-Zweiges}
\end{figure}

Wird die Frage, ob der angezeigte Git-Zweig der richtige ist, verneint, 
kann der zutreffende Zweig ausgewählt werden 
(Kapitel~\ref{sec:AuswahlGitBranch}, Seite~\pageref{sec:AuswahlGitBranch}).

<<Preparations2>>=
    if [ $rbq -ne 0 ]
    then
        SelectBranch
    fi
<<Preparations3>>
@

Wird die Frage, ob die angezeigte Distribution die richtige ist, verneint, 
kann die zutreffende Distribution ausgewählt werden 
(Kapitel~\ref{subsec:Distro4Branch}, Seite~\pageref{subsec:Distro4Branch}).

<<Preparations3>>=
     if ! whiptail --title "Please check!" \
    --yesno "The distribution is ${RecentBranchD}" --yes-button "Yes" \
    --no-button "No" 15 60
<<Preparation4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RecentBranchDistribution.png}
\caption{Release-Branch der Distribution}
\end{figure}

<<Preparation4>>=

    then
        RecentBranchD=""
        Distro4Branch
    fi

    echo "Notice from BuildNewRevision: Distribution is "${RecentBranchD} >> ${log}

    SBuildOrPBuilder 0

<<BuildNewRevision8>>
@

Zur Auswahl des Build-Systems wird die Funktion \textit{SBuildOrPBuilder}
aufgerufen (Kapitel~\ref{subsec:ChooseBuildSystem},
Seite~\pageref{subsec:ChooseBuildSystem}).

\subsection{\texttt{Git}-Zweig anpassen}
\label{subsec:GitBranch2RecentBranch}

Zunächst wird im Wert der Variablen \textit{CurrentBranch} (welcher der
Name des aktuellen Zweiges ist) ein ''\slash'' durch
''\textbackslash\slash''  ersetzt, also ein Schrägstrich maskiert.

Dann wird der so veränderte Wert der Variablen als \textit{RecentBranch}
in die Konfigurationsdatei eingefügt.

Schließlich wird dieser Wert der Variablen \textit{RecentBranch}
zugewiesen.

<<GitBranch2RecentBranch>>=
function GitBranch2RecentBranch {
    # Called by AskDist

    bName1=$(echo ${CurrentBranch} | sed --expression='s/\//\\\//g')
    sed --in-place --expression="s/RecentBranch=.*/RecentBranch=${bName1}/g" \
    ${ConfigPath}${OrigName}
    RecentBranch=${CurrentBranch}
}

<<Search4Dist>>
@

\subsection{Distribution ermitteln}
\label{subsec:DetermineDistribution}

<<Search4Dist>>=
function Search4Dist {
    # Called by AskDist ParseConfig
    set +e
    va=$(grep ${bName}_Dist ${ConfigPath}${OrigName})
    bName1=$(echo ${bName} | sed --expression='s/\//\\\//g')
    va=$(echo $va | sed --expression="s/# ${bName1}_Dist=//g")
    va=$(echo $va | sed --expression='s/"//g')
    set -e
}

<<AskDist>>
@

\subsection{Auswahl des Build-Systems}
\label{subsec:ChooseBuildSystem}

Nun kann noch die Auswahl getroffen werden, ob mit \textit{pbuilder} oder 
\textit{sbuild} gebaut werden soll.

<<SBuildOrPBuilder>>=
function SBuildOrPBuilder {
    # Called by BuildNewRevision TaskSelect PrepareUploading Import4Sponsoring 
    # Flag for tagging and signing
    tsf=$1
    
    Builder=$(whiptail --title "Which builder do you want to use?" \
    --radiolist "Which builder do you want to use? " 15 60 6 \
    "0" "PBuilder" off \
    "1" "SBuild" on \
    --cancel-button "Exit" 3>&2 2>&1 1>&3)
<<SBuildOrPbuilder1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/AuswahlBuildSystem.png}
\caption{Auswahl des Build-Systems}
\end{figure}

Voreingestellt ist die Auswahl von \textit{sbuild}.

<<SBuildOrPbuilder1>>=
    if [ -z "${Builder}" ]
    then
        exit
    fi
    if [ ${Builder} -eq  1 ]
    then
        echo "Using SBuild." >>${log}
        UsingSBuild
    else
        echo "Using PBuilder." >>${log}
        UsingPBuilder
    fi
}
<<BuildNewRevision>>
@

Wird \textit{SBuild} ausgewählt, ruft das Programmskript die Funktion 
\textit{UsingSBuild} auf. Wird \textit{PBuilder} ausgewählt, wird die 
Funktion \textit{UsingPBuilder} aufgerufen. 

Eine Beschreibung des \textit{PBuilders} finden Sie im 
Kapitel~\ref{sec:pbuilderdoes} (Seite~\pageref{sec:pbuilderdoes}).

Was \textit{sbuild} macht, erfährt man in Kapitel~\ref{sec:sbuild}
(Seite~\pageref{sec:sbuild}).

Zuvor erhält der Nutzer jedoch die Gelegenheit vor dem Bau des
Paketes die Parameter letztmalig zu prüfen. Außerdem wird ihm eine letzte
Ausstiegsmöglichkeit gewährt (Kapitel~\ref{subsec:LastExit},
Seite~\pageref{subsec:LastExit}).

\subsection{Überprüfung der Parameter}
\label{subsec:CheckParameter}

Bevor der Paketbau endgültig beginnt, werden die Parameter letztmalig
zur Prüfung angezeigt.

<<LastQuestionsBeforeBuild>>=
function LastQuestionsBeforeBuild {
    # Called by UsingSBuild UsingPBuilder

    if ! whiptail --title "Please check!" \
    --yesno "The release you want to build for in ${BuildEnv} is ${RecentBranchD}" \
    --yes-button "Yes" --no-button "No" 15 60
    then
        AskDist
    fi

<<LastQuestionsBeforeBuild1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ReleaseDistribution.png}
\caption{Parameterüberprüfung}
\end{figure}

\subsection{Letzte Ausstiegsmöglichkeit}
\label{subsec:LastExit}

Vor dem Paketbau wird schließlich eine letzte Gelegenheit zum Ausstieg
gegeben.

<<LastQuestionsBeforeBuild1>>=
    whiptail --title "Last opportunity to exit before building" \
    --yesno "Do you want to start the build process?" --yes-button "Yes" \
    --no-button "Exit" 15 60
<<LastQuestionsBeforeBuild2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/StartBuildProcess.png}
\caption{Bau des Paketes starten}
\end{figure}

<<LastQuestionsBeforeBuild2>>=
    if [ $? -ne 0 ]
    then
        whiptail --title "Bye" --msgbox "Exit" 15 60
<<LastQuestionsBeforeBuild3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/Bye.png}
\caption{Beenden}
\end{figure}

<<LastQuestionsBeforeBuild3>>=
        exit
    else
        if [ "${BuildEnv}" = "pbuilder" ]
        then
            whiptail --title "Start building" \
            --msgbox "${BuildEnv} will be updated first\n \
            This need sudo and/or root rights" 15 60
        fi
    fi
}

<<UsingSBuild>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildEnvUpdateInfo.png}
\caption{Information zur Aktualisierung der Build-Umgebung}
\end{figure}

\section{Was macht \textit{sbuild}?}
\label{sec:sbuild}

\textit{Sbuild} wird im offiziellen \textit{buildd}-Netzwerk verwendet, 
um Binär- und Quellpakete für alle unterstützten Architekturen zu 
erstellen\cite{SBuild2024}.

Es wird dafür jeweils eine eigene Buildumgebung erstellt.

<<UsingSBuild>>=
function UsingSBuild {
    # Called by BuildNewRevision

    BuildEnv="sbuild"
<<UsingSBuild1>>
@

Zunächst erfolgt der Aufruf der Funktion \textit{LastQuestionsBeforeBuild} 
zur Festlegung der Parameter \textit{release} und des dazugehörigen 
Git-Zweiges für \textit{gbp buildpackage} (Kapitel~\ref{subsec:LastExit},
Seite~\pageref{subsec:LastExit}).

Dann besteht die Gelegenheit, die Datei \textit{\textasciitilde/.sbuildrc}
zu prüfen und gegebenenfalls anzupassen.

<<UsingSBuild1>>=
    LastQuestionsBeforeBuild

    if whiptail --title ".sbuildrc." \
    --yesno "Do you want to check (and edit) ~/.sbuildrc?" \
    --defaultno --yes-button "Yes" --no-button "No" 15 60
    then
        nano ~/.sbuildrc
    fi
<<UsingSbuild2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/CheckSbuilRC.png}
\caption{.sbuildrc prüfen}
\end{figure}

Wenn die Datei \textit{\textasciitilde/.sbuildrc} leer ist, ist diese mit
dem beschriebenen Inhalt zu füllen (s.~Kapitel~\ref{sec:confFileSBuild},
Seite~\pageref{sec:confFileSBuild})

Abhängig davon, zu welchem Zwecke der Paketbau erfolgen soll, wird
\textit{gbp buildpackage} mit einer unterschiedlichen Parameterkonfiguration
aufgerufen.

<<UsingSbuild2>>=

    # Check whether chroot directory exits  

    if ! [ -d  ~/.cache/sbuild ]
    then
        mkdir -p ~/.cache/sbuild
    fi

    # Create/Update tarballed chroot

    if [ $tsf -eq 0 ]
    # Called by TaskSelect via SBuildOrPbuilder 0
    then
        ChrootName='UNRELEASED'
    else
        ChrootName=${RecentBranchD}
    fi

    mmdebstrap --variant=buildd ${RecentBranchD} \
    ~/.cache/sbuild/${ChrootName}-amd64.tar.xz
    
    set +e
    if [ $tsf -eq 0 ]
    # Called by TaskSelect via SBuildOrPbuilder 0
    then
        gbp buildpackage --git-builder=sbuild --no-clean-source \
        --dist=UNRELEASED --build-failed-commands=%SBUILD_SHELL \
        --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD} --git-ignore-new
        # Setting flag for success
        gbpq=$?
    elif [ $tsf -eq 1 ]
    # Called by PrepareUploading via SBuildOrPBuilder 1
    then
        gbp buildpackage --git-builder=sbuild --no-clean-source \
        --dist=${RecantBranchD} --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD} --git-verbose --git-tag \
        --git-sign-tags
        # Setting flag for success
        gbpq=$?
    else
        # Called by PrepareUploading via SBuildOrPBuilder 2
        gbp buildpackage --git-builder=sbuild --no-clean-source\
        --dist=${RecentBranchD} --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD}
        # Setting flag for success
        gbpq=$?
    fi
    set -e
}
<<UsingPBuilder>>
@

\section{In der \textit{Pbuilder-Chroot} bauen}
\label{sec:pbuilderdoes}

Mit \textit{PBuilder} wird eine Umgebung geschaffen, in der
\texttt{Debian}-Pakete erstellt werden können
(s.~a.~Kapitel~\ref{sec:configurepbuilder},
Seite~\pageref{sec:configurepbuilder}).

Die Pakete werden in einer \textit{chroot} gebaut, die von 
\textit{pbuilder} bereitgestellt wird.
Zur besseren Kontrolle des Prozesses können an vordefinierten Stellen 
sogenannte \textit{hooks} eingebaut werden 
(Kapitel~\ref{subsec:HooksEinrichten}, Seite~\pageref{subsec:HooksEinrichten}).

Da \textit{git pbuilder} zur Aktualisierung der Basisinstallation
\textit{root}-Rechte benötigt, erfolgt eine Passwortabfrage.

\subsection{\textit{base.cow} erstellen}
\label{subsec:CreateCow}

Ist die erforderliche \textit{base-cow} noch nicht vorhanden, wird sie 
mit \textit{git-pbuilder create} angelegt. Damit kann 
auch eine \textit{chroot} für eine abweichende Architektur wie zum 
Beispiel \textit{i386 (32-bit)} auf einem \textit{64-bit}-Rechner 
angelegt werden.
Dazu wird eine \textit{base-sid-i386.cow} mit 

\begin{verbatim}
 DIST=sid ARCH=i386 git-pbuilder create
\end{verbatim}

erstellt.

<<CreateNewCow>>=
function CreateNewCow {
    # Called by Distro4Branch UsingPBuilder

    bDist="sid"
    set +e
    bDist=$(whiptail --title "Create new cow for ${RecentBranch}" \
    --inputbox  "Debian distribution\n \
    for this branch ${RecentBranch}:" \
    --cancel-button "Use Sid" 15 60 3>&2 2>&1 1>&3)
<<CreateNewCow1>>
@

\begin{figure}[h] 
\centering 
\includegraphics[width=25em,height=30ex]{Pictures/SelectCow.png}
\caption{Auswahl der zu erstellenden Cow.}
\end{figure}

<<CreateNewCow1>>=
    if [ -z "${bDist}" ]
    then
        bDist="sid"
    fi
    # You must be root to create a cow
    echo -e "\nPlease enter Password for creating pbuilder cow.\n"
    sudo DIST=${bDist} git-pbuilder create
    echo "Cow for "${bDist}" created." >> ${log}
    set -e
}

<<Distro4Branch>>
@

\subsection{git-pbuilder update}
\label{subsec:GitPBuilderUpdate}

Vor dem Start von \textit{gbp buildpackage} sind Vorkehrungen zu treffen, 
damit die Einrichtung in der \textit{chroot} aktuell ist. 
Dies geschieht mittels \textit{git-pbuilder update}. 
Zuvor wird noch geprüft, ob die notwendige \textit{base-cow} (des 
entsprechenden Branches/Releases) vorhanden ist.

Während die \textit{cow}-Verzeichnisse für die übrigen 
Veröffentlichungen die Release-Bezeich\-nun\-gen im Namen tragen, heißt das 
entsprechende Verzeichnis für \textit{sid} schlicht \textit{base.cow}.

Daher wird anhand zweier Bedingungen geprüft, ob das entsprechende 
Verzeichnis vorhanden ist.

Fehlt das entsprechende Verzeichnis wird es mittels der Funktion 
\textit{CreateNewCow} (Kapitel~\ref{subsec:CreateCow}, 
Seite~\pageref{subsec:CreateCow}) erstellt.

<<UsingPBuilder>>=
 
function UsingPBuilder {
    # Called by BuildNewRevision

    BuildEnv="pbuilder"
    LastQuestionsBeforeBuild

    # Building package using git-pbuilder and gbp buildpackage

    # check, whether cow exists
    # if exists update cow
    # else create cow
    if [ -d /var/cache/pbuilder/base-${RecentBranchD}.cow ]
    then
        echo -e "\nPlease enter Password for updating pbuilder cow.\n"
        DIST=${RecentBranchD} git-pbuilder update
        echo "Notice from BuildNewRevision: Pbuilder was updated." >> ${log}
    elif [ -d /var/cache/pbuilder/base.cow -a ${RecentBranchD} = "sid" ]
    then
        echo -e "\nPlease enter Password for updating pbuilder cow.\n"
        DIST=${RecentBranchD} git-pbuilder update
        echo "Notice from BuildNewRevision: Pbuilder was updated." >> ${log}
    else
        CreateNewCow
    fi
    
    if [ ${OptFlag} -ne 1 ]
    then
        ForceOrig
<<UsingPBuilder3>>
@

Für die Anzeige der bereits gesetzten Optionen für \textit{gbp buildpackage}
in der Funktion \textit{MoreOptions} werden diese mit der Variablen
\textit{normalOpts} übergeben.

<<UsingPBuilder3>>=

        if [ $tsf -eq 0 ]
        then
            normalOpts="--git-debian-branch="${RecentBranch}" \
            --git-dist="${RecentBranchD}" --git-verbose \
            --git-ignore-new"${pbuilderOpt}
        elif [ $tsf -eq 1 ]
        then
            normalOpts="--git-debian-branch="${RecentBranch}" \
            --git-dist="${RecentBranchD}" --git-verbose --git-tag \
            --git-sign-tags"${pbuilderOpt}
        else
            normalOpts="--git-debian-branch="${RecentBranch}" \
            --git-dist="${RecentBranchD}" --git-verbose"${pbuilderOpt}
        fi
        MoreOptions
    fi
<<UsingPBuilder4>>
@

\subsection{Aufnahme des *.orig-Archives in *.changes}
\label{subsec:Orig2changes}

Grundsätzlich wird das *.orig-Archiv (\textit{*.orig.tar.gz} oder 
\textit{*.orig.tar.xz}) 
nur dann in die *.changes-Datei eingebunden und damit auch hochgeladen, 
wenn die Revisionsnummer 1 nicht übersteigt.

Zunächst wird also die Versionsbezeichnung durch Aufruf der Funktion 
\textit{RecentIdentifier} (Kapitel~\ref{subsec:Versionsbezeichnung}, 
Seite~\pageref{subsec:Versionsbezeichnung}) ermittelt und angezeigt.

<<ForceOrig>>=
function ForceOrig {
    # Called by BuildNewRevision PrepareUploading
    OptFlag=1
    if [ -z "${Version1}" ]
    then
        RecentIdentifier
    fi
    whiptail --title "Version" --msgbox "Version: ${Version1}" 15 60

<<ForceOrig2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/Version.png}
\caption{Anzeige der Version mit Revisionsnummer}
\end{figure}

Es wird geprüft, ob es sich um ein \textit{natives} Paket
(Kapitel~\ref{sec:DebianDoc}, Seite~\pageref{sec:DebianDoc}) handelt.

<<ForceOrig2>>=
    set +e
    cat debian/source/format | grep "native" > /dev/null
    if [ $? -ne 0 ]
<<ForceOrig3>>
@

Handelt es sich um ein natives Paket, so enthält die Versionsbezeichnung
keine Revisionsbezeichnung.

<<ForceOrig7>>=
    else
        pbuilderOpt=" --git-pbuilder"
    fi
    set -e
}

<<MoreOptions>>
@

Bei nicht-nativen \texttt{Debian}-Paketen wird die Revisionsnummer
extrahiert und angezeigt.

<<ForceOrig3>>=
    then
        RevNr=$(echo ${Version1} | sed --expression='s/[^0-9]/#/g' | \
        sed --expression='s/^.*#//')
        whiptail --title "Revision number" \
        --msgbox "The number of the revision is ${RevNr}." 15 60
        pbuilderOpt=" --git-builder=git-pbuilder \
        --git-pbuilder-options='--source-only-changes'"

<<ForceOrig5>>
@

%     --git-pbuilder-options='--hookdir ${HOME}/.pbuilder/'


\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/RevisionNumber.png}
\caption{Anzeige der Revisionsnummer}
\end{figure}

Man kann jedoch bei einer Revisionsnummer größer als 1 erzwingen, dass 
das *.orig-Archiv in die *.changes-Datei eingebunden und damit auch 
hochgeladen wird, indem \textit{git-pbuilder} die Option \textit{-sa} 
mitgegeben wird.
 
Dies ist dann sinnvoll, wenn das *orig-Archiv bislang noch nicht hochgeladen 
wurde oder in der \textit{New Queue} erneut bereitgestellt werden muss.

Bei der Verwendung von \textit{gbp buildpackage}, wie im Skript, lautet 
die entsprechende Option \textit{--git-builder=git-pbuilder -sa}.

<<ForceOrig5>>=
        if [ ${RevNr} -gt 1 ]
        then
            if whiptail --title "orig in changes file" \
            --yesno "Do you want to insert the orig archive into the changes file?\n \
            That makes sense, if the orig archive has not been uploaded before." \
            --defaultno --yes-button "Yes" --no-button "No" 15 60
<<ForceOrig6>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ChangesFile.png}
\caption{Soll der Upstream-Tarball auch hochgeladen werden}
\end{figure}

Die Option \textit{-sa} bedeutet, dass laut 
\textit{dpkg-buildpackage --help} die Quelle immer \textit{Orig} enthält.

<<ForceOrig6>>=
            then
                pbuilderOpt=" --git-builder=git-pbuilder -sa"
            fi
        fi
<<ForceOrig7>>
@

Nun wird in der folgenden Funktion die Möglichkeit eröffnet, weitere Optionen 
für den \textit{pbuilder} in \textit{gbp buildpackage} mitzugeben. Zuvor 
werden die bisherigen Optionen angezeigt.

<<MoreOptions>>=
function MoreOptions {
    # Called by UsingPBuilder PrepareUploading
    # Adds options to specify pbuilder in gpb buildpackage
    moreOpts=''
    intText="The options for gbp buildpackage are:\n"
    intText=${intText}${normalOpts}
    if whiptail --title "Options for gbp buildpackage" \
    --yesno "${intText}\nDo you want to add some more?" --yes-button "Yes" \
    --no-button "No" --defaultno 15 60
<<MoreOptions2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ShowBuildPackageOptions.png}
\caption{Anzeige der Optionen von \textit{gbp buildbackage}}
\end{figure}

<<MoreOptions2>>=
    then
        moreOpts=$(whiptail --title "Options for gbp buildpackage" \
        --inputbox "${intText}\nPlease insert options to be added:" \
        --cancel-button "Cancel" 15 60 3>&2 2>&1 1>&3)
        moreOpts=" "${moreOpts}
    fi
}

<<PatchesTreatment>>
@

%\begin{figure}[h]
%\centering
%\includegraphics[width=25em,height=30ex]{Pictures/MoreGBPOptions.png}
%\caption{Mehr Optionen von \textit{gbp buildbackage}}
%\end{figure}

Die Informationen zu \textit{pbuilderOpt} wurden aus verschiedenen 
Manpages zusammengetragen. 

In der Manpage zu \textit{gbp buildbackage} enrhält man die Information, 
dass mit \textit{--git-pbuilder-options= PBUILDER\_OPTIONS} weitere Optionen 
des \textit{pbuilder}s hinzugefügt werden können. Welche Optionen dies 
sind, findet man in der Manpage von \textit{pbuilder}

\subsection{Bauen mit \textit{gbp buildpackage}}
\label{subsec:buildwithgbp}

Nach den Vorbereitungen erfolgt nun das Bauen des jeweiligen Paketes mit 
\textit{gbp buildpackage}. 
Misslingt dies, beendet sich das Programm. 
Andernfalls geht es weiter zur Überprüfung der gebauten Pakete 
(Kapitel~\ref{chap:Ueberpruefungen}, Seite~\pageref{chap:Ueberpruefungen}). 
Good luck!

Hier beginnt nun mit dem Herunterladen der Build-Abhängigkeiten das 
eigentliche Bauen des Debian-Paketes.

<<UsingPBuilder4>>=
    echo "== Options for gbp buildpackage ==" >> ${log}
    echo -e "RecentBranch contains ${RecentBranch}" >> ${log}
    echo -e "RecentBranchD contains ${RecentBranchD}" >> ${log}
    echo -e "PBuilderOpt contains ${pbuilderOpt}" >> ${log}
    echo -e "MoreOpts contains ${moreOpt} \n" >> ${log}    
    echo "Starting gbp buildpackage" >> ${log}
    set +e

    if [ $tsf -eq 0 ]
    then
        gbp buildpackage --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD} --git-verbose \
        --git-ignore-new${pbuilderOpt}${moreOpts}
        # Setting flag for success
        gbpq=$?
    elif [ $tsf -eq 1 ]
    then
        gbp buildpackage --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD} --git-verbose --git-tag \
        --git-sign-tags${pbuilderOpt}${moreOpts}
        # Setting flag for success
        gbpq=$?
    else
        gbp buildpackage --git-debian-branch=${RecentBranch} \
        --git-dist=${RecentBranchD} --git-verbose${pbuilderOpt}${moreOpts}
        # Setting flag for success
        gbpq=$?
    fi
    set -e
}

<<SBuildOrPBuilder>>
@

<<BuildNewRevision8>>=
    if [ $gbpq -eq 0 ]
    then
        echo -e "The package ${SourceName} was built with gbp buildpackage\n \
        without creating and signing tags." >> ${log}
    else
        whiptail --title "Build failed!" \
        --msgbox "Gbp buildpackage failed!" 15 60
        echo
        echo "-- Gbp buildpackage failed! --"
        echo
        echo "Please fix the problem in another terminal!"
        echo "After fixing, press RETURN to continue."
        read a
        if [ "${BuildEnv}" = "sbuild" ]
        then
            UsingSBuild
        else
            UsingPBuilder
        fi        
    fi

    Task=5 # Go to RunningTests
}

<<RunningLintian>>
@

\begin{figure}[h!]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/BuildFailed.png}
\caption{Erfolgloser Bauversuch!}
\end{figure}

\chapter{Wenn das Bauen fehlschlägt}
\label{chap:BuildFails}

Wenn das Bauen fehlschlägt oder die nachfolgenden Tests
(Kapitel~\ref{chap:Ueberpruefungen}, Seite~\pageref{chap:Ueberpruefungen})
nicht zufriedenstellend ausfallen, kann das verschiedenartige Ursachen
haben.

Erster Ansatzpunkt für die Ursachenforschung ist das Studium der Datei\\
\textit{$<SourceName>$\_$<Version>$-$<Revision>$\_$<Arch>$.build}.

Eine Ursache, warum das Bauen fehlgeschlagen ist, kann ein unzureichendes
Ermitteln der Build-Abhängigkeiten sein. Die Ermittlung, ob benötigte
Abhängigkeiten bereits paketiert sind, ist in
Kapitel~\ref{sec:CheckDependencies} (Seite~\pageref{sec:CheckDependencies})
beschrieben.

Was zu tun ist, wenn das Fehlschlagen auf fehlenden oder fehlerhaften
Patches beruht, wird in Kapitel~\ref{sec:MorePatchesNeeded}
(Seite~\pageref{sec:MorePatchesNeeded}) erörtert.

\chapter{Bauen jenseits von \textit{Unstable (sid)}}
\label{chap:BuildBeyondSid}

\section{Bauen für bereits offiziell freigegebene Distributionen}

Zum Bauen für \textit{Backports}- und \textit{Proposed-Updates}-Paketen
(Kapitel~\ref{chap:JenseitsUnstable},
Seite~\pageref{chap:JenseitsUnstable}) hat sich für uns die folgende
Vorgehensweise bewährt. Die folgenden Ausführungen gelten für \textit{}
{Oldstable} und \textit{Oldoldstable} entsprechend.

Zunächst ist von der Aufgabenauswahl aus (Kapitel~\ref{sec:Aufgabenauswahl},
Seite~\pageref{sec:Aufgabenauswahl}) ein neuer Git-Branch anzulegen (Kapitel~
\ref{sec:NeuenBranchErstellen}, Seite~\pageref{sec:NeuenBranchErstellen}). 
Dieser geht in der Regel vom Git-Zweig \textit{debian/sid} bzw. 
\textit{master} oder \textit{main} aus.

Der Name dieses neuen Zweiges sollte das Ziel-Repositorium des Paketes angeben (z.B. 
debian/bookworm-bpo).

Gibt es diesen Git-Zweig schon, kann dieser genutzt werden. Hierzu kann
man folgende Befehle verwenden.

<<Merge2Stable>>=
git branch -vv
git checkout <OlderBranch>
git merge debian/sid # or master or main
# Solve merge conflicts esp. d/changelog
nano debian/changelog
git add debian/changelog
git commit
# This is the merge commit
@

Die Behebung des Merge-Konfliktes erfordert in der Regel zumindest die 
Bearbeitung der Datei \textit{debian/changelog}. Es wird ein neuer
Eintrag in \textit{debian/changelog} erstellt. 
(Kapitel~\ref{sec:DebianChangelog}, Seite~\pageref{sec:DebianChangelog})

Für den Versionseintrag in \textit{debian/changelog} ist zwingend die in 
Kapitel~\ref{sec:Versioning} (Seite~\pageref{sec:Versioning}) 
beschriebene Nomenklatur zu verwenden. Diese hängt davon ab, für welchen
Zweig nun gebaut wird.

Diese lauten:
\begin{description}
    \item[stable-proposed-updates] Es soll die bereits im Stable-Zweig
    vorhandene Paketversion bei der nächsten Zwischenveröffentlichung
    ersetzt werden.
    \item[stable-updates] Es soll die bereits im Stable-Zweig
    vorhandene Paketversion dringend ersetzt werden.
    \item[stable-backports] Zusätzlich zur älteren Paketversion soll
    eine neuere Version verfügbar gemacht werden.
\end{description}

\section{Proposed-Updates -- Besonderheiten}

Der Changelog \textbf{darf nicht} die Nummer des Fehlerberichtes enthalten,
der gegen \textit{release.debian.org} erstellt wurde. Er sollte aber die
Nummer des Fehlerberichtes enthalten, der gegen dieses \texttt{Debian}-Paket
erstellt wurde und weswegen diese Version gebaut wird.

Danach wird das Paket für \textit{proposed-updates} gebaut. Es ist eine
neue Revision zu bauen (Kapitel~\ref{chap:NeueRevisionBauen}, 
Seite~\pageref{chap:NeueRevisionBauen}). Hierzu müssen gegebenenfalls in
der Datei \textit{debian/contol} die Versionen für die Abhängigkeiten
angepasst werden.

Nach dem Bauen für die Veröffentlichung (Kapitel~\ref{chap:Uploading},  
Seite~\pageref{chap:Uploading}) und \textbf{vor} dem tatsächlichen
Hochladen mit \textit{dput} (Kapitel~\ref{chap:UploadPackage},
Seite~\pageref{chap:UploadPackage}) wird mit \textit{debdiff}
(Kapitel~\ref{subsec:debdiff}, Seite~\pageref{subsec:debdiff}) noch die
Differenz zwischen der bisherigen Version im angestrebten Zweig und der
neuen Version erstellt (Kapitel~\ref{subsec:debdiff},
Seite~\pageref{subsec:debdiff}).

Wenn das Release-Team dem Antrag zustimmt, kann das Paket gebaut und 
hochgeladen werden. (Kapitel~\ref{sec:SalsaHochladen}, 
Seite~\pageref{sec:SalsaHochladen} bzw. Kapitel~\ref{sec:DputHochladen}, 
Seite~\pageref{sec:DputHochladen}). Das Paket landet dann in der
entsprechenden \textit{New-Queue}.

Der Fehlerbericht an \textit{release.debian.org} wird geschlossen,
sobald das Paket dem nächsten Pointrelease der stabilen Version
hinzugefügt wurde. Dies ist dann das Ende dieses Prozesses.

\chapter{Überprüfungen}
\label{chap:Ueberpruefungen}

Eine erste Qualitätskontrolle erfolgt bereits während des Bauvorganges im 
\textit{pbuilder} mit \textit{lintian}.

Die nachfolgende Qualitätskontrolle erfolgt erneut mit \textit{lintian} 
im \textit{pedantic}-Modus (Kapitel~\ref{sec:RunningLintian}, 
Seite~\pageref{sec:RunningLintian}).

<<RunningTests>>=
function RunningTests {
    # Called by TaskSelect BuildNewRevision

    # QA using lintian and uscan

    # lintian
    RunningLintian
<<RunningTests1>>
@

und mit \textit{uscan} hinsichtlich des Inhaltes 
der Datei \textit{debian/watch} (Kapitel~\ref{sec:uscan}, 
Seite~\pageref{sec:uscan}).

<<RunningTests1>>=
    # uscan
    if [ $linq -eq 0 ]
    then
        RunningUscan
    else
        usq=1
    fi

<<RunningTests3>>
@

Wird mindestens eines der beiden Testergebnisse als mangelhaft qualifiziert, 
beendet sich das Programmskript nach einem entsprechenden Eintrag in die 
Log-Datei. 

Andernfalls erfolgt die Frage, ob das Hochladen des Paketes vorbereitet 
werden soll.

<<RunningTests3>>=
    if [ $usq -ne 0 ] || [ $linq -ne 0 ]
    then
        echo "At least one test failed!" >> ${log}
        exit
    else
        if whiptail --title "Upload?" \
        --yesno "Should the package be prepared to be uploaded now?" \
        --yes-button "Yes" --no-button "Exit" 15 60
        then
<<RunningTests4>>
@

\begin{figure}[h!]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PreparedUpload.png}
\caption{Upload des Release vorbereiten}
\end{figure}

Wird die Frage bejaht, wird das Hochladen vorbereitet
(Kapitel~\ref{chap:Uploading}, 
Seite~\pageref{chap:Uploading}).

<<RunningTests4>>=
            Task=6 # Go to PrepareUploading
        else
            exit
        fi
    fi
}

<<CheckRepackSuffix>>
@

Später folgen noch weitere Überprüfungen mit \textit{debdiff}
(Kapitel~\ref{subsec:debdiff}, Seite~\pageref{subsec:debdiff}).und 
\textit{diffoscope}. Schließlich wird auch noch
\textit{piuparts} beschrieben.

\section{Auswahl der Changes-Datei}
\label{sec:SelectChangesFile}

Diese Funktion dient der Auswahl der Changes-Datei (\textit{*.changes}), 
die zur Prüfung des Paket-Bauergebnisses und zur Bestimmung der 
hochzuladenen Dateien genutzt wird.

<<SelectChangesFile>>=
function SelectChangesFile {
    # Called by RunningLintian SelectUploadTarget

    titlestr=${1}
    cd ${PrjPath}
    changesa=($(ls ${SourceName}_${Version1}*_*.changes))

    if [ -z "${changesa}" ]
    then
        echo "File *"${SourceName}"*_"${Version1}"*_*.changes not found!"
        exit
    fi

    i=0; slct=''
    for element in ${changesa[*]}
    do
        slct=$slct' '$i' '${element}' off '
        i=$(expr $i + 1)
    done

    paket=$(whiptail --title "${titlestr}" --radiolist "Select:" \
    --cancel-button "Exit" 15 60 8 $slct 3>&2 2>&1 1>&3)

<<SelectChangesFile1>>
@

\begin{figure}[h!]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/SelectChangesFile.png}
\caption{\textit{*.changes}-Datei auswählen}
\end{figure}

Erfolgt keine Auswahl beendet sich das Programmskript.

<<SelectChangesFile1>>=

    if [ -z "${paket}" ]
    then
        exit
    fi
}

<<PatchHeader>>
@

\section{Yamllint}

Mit dem Kommandozeilentool \textit{yamllint} kann die Syntax der
\textit{.yml}-Dateien geprüft werden. 

\section{Prüfung mit Lintian}
\label{sec:RunningLintian}

Das Ergebnis des Bauens wird mit \textit{lintian} überprüft. Hierzu ist 
zunächst die \textit{*.changes}-Datei auszuwählen, auf die sich die Prüfung 
beziehen soll. Es wird daher die Funktion \textit{SelectChangesFile} aufgerufen 
(Kapitel~\ref{sec:SelectChangesFile}, 
Seite~\pageref{sec:SelectChangesFile}).

<<RunningLintian>>=
function RunningLintian {
    # Called by RunningTests

    SelectChangesFile "lintian_check" # String will be found in ${1}
    linfile=${changesa[$paket]}
<<RunningLintian1>>
@

\textit{Lintian} wird mit Optionen aufgerufen, die eine ausführliche 
Prüfung bewirken.

<<RunningLintian1>>=

    set +e
    lininfo=$(lintian --check --display-experimental --display-info \
    --info --verbose --show-overrides --pedantic --tag-display-limit 0 \
    --color auto ${linfile})
    lx=$?


<<RunningLintian3>>
@

Wenn \textit{Lintian} nichts meldet, soll der Nutzer dieses erfreuliche
Ergebnis erfahren.

<<RunningLintian3>>=
    if [ ${lx} -eq 0 ]
    then
        lininfo="Lintian does not find any Errors \
        \n\n Congratulations \n\n"${lininfo}
    fi

<<RunningLintian4>>
@

Die Variable \textit{lininfo} muss noch mit \textit{sed} bearbeitet 
werden, damit die Lintian-Meldungen in einzelnen Zeilen erscheinen.

<<RunningLintian4>>=
    # Make lininfo better readable
    lininfo=$(echo ${lininfo} | sed --expression='s/ [EWIPNX]:/\\n&/g')

    set -e
    echo -e "lintian("${lx}"): "${lininfo}
    whiptail --title "Lintian" --msgbox "${lininfo}" --scrolltext 15 60
    echo -e "Result of Lintian:\n"${lininfo} >> ${log}
        
<<RunningLintian5>>
@

Nach der Anzeige des Ergebnisses der Prüfung ist das Ergebnis vom Nutzer 
zu bewerten.

<<RunningLintian5>>=
    whiptail --title "All well?" \
    --yesno "All well? Continue?" --yes-button "Yes" \
    --no-button "Exit" 15 60
    linq=$?
}

<<RunningUscan>>
@

\begin{figure}[!h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/AllWell.png}
\caption{Lintian: All Well?}
\end{figure}

Ist das Ergebnis in Ordnung, folgt die nächste Prüfung. Hinweise zur
Fehlerbehebung sind im Kapitel~\ref{chap:LintianMessages} 
(Seite~\pageref{chap:LintianMessages}) zu finden.

\section{Uscan}
\label{sec:uscan}

Mit der Option \textit{--verbose} erstellt \textit{uscan} einen für 
Menschen lesbaren Bericht über die Programmausführung. Mit der Option 
\textit{--debug} wird zusätzlich der Status der internen Variablen 
angezeigt.

<<RunningUscan>>=
function RunningUscan {
    # Called by RunningTests BuildWithUscan

    cd ${GitPath}

    # Check whether debian/watch exists
    if [ ! -e debian/watch ]
    then
        whiptail --title "No debian/watch file found" \
        --yesno "Is there a good reason for having no debian/watch file?" \
        --defaultno --yes-button "Yes" --no-button "No" 15 60
        if [ $? -eq 0 ]
        then
            usq=0
        else
            usq=1
        fi
        return
    fi

    set +e
    uscaninfo=$(uscan --no-download --verbose)
    if [ ${#uscaninfo} -gt 0 ]
    then
        whiptail --title "uscan" --msgbox "${uscaninfo}" --scrolltext 15 60
        echo -e "Result of uscan:\n"${uscaninfo} >> ${log}
<<RunningUscan1>>
@

Hier wird aus \textit{uscaninfo} ausgelesen, ob die gebaute Version auch 
die aktuelle ist. Dies gilt für alle Builds, die in \textit{experimental} 
oder \textit{sid} veröffentlicht werden sollen.
Die dazugehörige Meldung lautet: "=> Package is up to date \dots".

<<RunningUscan1>>=
        echo ${uscaninfo} | grep '=> Package is up to date' > /dev/null
        usc1=$?
        echo ${uscaninfo} | grep '=> Only older package available' > /dev/null
        usc2=$?
        if [ ${usc1} -eq 0 ]
        then 
            whiptail --title "uscan" --msgbox "Package seems to be up to date." 15 60
            usq=0
<<RunningUscan2>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/PackageUptodate.png}
\caption{Paket ist aktuell}
\end{figure}

<<RunningUscan2>>=
        elif [ ${usc2} -eq 0 ]
        then
            whiptail --title "uscan" --msgbox "Only older package available." 15 60
            usq=0
<<RunningUscan3>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/OldPackage.png}
\caption{Älteres Paket verfügbar}
\end{figure}

<<RunningUscan3>>=
        else
            whiptail --title "No up to date message" \
            --yesno "No up to date message.\nRegardless all well? Continue?" \
            --defaultno --yes-button "Yes" --no-button "Exit" 15 60
            usq=$?
        fi
<<RunningUscan4>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/AllWellContinue.png}
\caption{Uscan - OK?}
\end{figure}

<<RunningUscan4>>=
    else
        echo "uscan failed" >> ${log}
        whiptail --title "uscan failed" --msgbox "uscan failed" 15 60
        usq=1
    fi
    set -e
}

<<RunningTests>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/UscanFailed.png}
\caption{Uscan schlägt fehl}
\end{figure}

\section{Überprüfen der Datei \textit{debian/copyright}}

An dieser Stelle wird überprüft, ob auch wirklich \textbf{alle} Angaben 
zu den Lizenzen\index{Lizenzprüfung} in der Datei \textit{debian/copyright}
erfolgt sind. Dazu gibt es mehrere Werkzeuge. Diese werden in 
Kapitel~\ref{sec:LicenseCheck} (Seite~\pageref{sec:LicenseCheck}) beschrieben.

Derzeit muss diese Prüfung noch manuell erfolgen, denn der Gebrauch dieser
Werkzeuge ist manchmal nicht ausreichend.

\section{Überprüfen mit \textit{debdiff} und \textit{diffoscope}}

Beide Programme dienen dazu, die Differenz zwischen dem aktuellen Paket und 
der Vorversion darzustellen. 

\textit{debdiff} wird mit dem Paket \textit{devscripts} installiert. 
\textit{diffoscope} dagegen muss mit dem gleichnamigen Paket zusätzlich 
installiert werden.

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

Mit \textit{debdiff} können zwei \texttt{Debian}-Quellcodepaketen verglichen
werden.

\textit{debdiff} dient in diesem Falle dazu zu belegen, dass zwischen zwei
Quellpaketen keine oder nur geringe Differenzen vorhanden sind.

<<DebDiff>>=
function DebDiff {
    # Called by TaskSelect Ask4DebDiff
    debdiffFlag=$1

    if [ ${debdiffFlag} -gt 0 ]
    then
        whiptail --title "debdiff" \
        --msgbox "Now you can detect the differences between two Debian packages.\n" \
        15 60
    fi

<<DebDiff1>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/DebDiff.png}
\caption{Unterschiede feststellen}
\end{figure}

Der Nutzer kann zwei von ihm ausgewählte Quellcodepakete miteinander
vergleichen, Hierzu werden \textit{debdiff} die beiden Pakete in Form von
\textit{.dsc}-Dateien übergeben. Anhand dieser Dateien wird der Inhalt
der Quellcodepakete verglichen.

<<DebDiff1>>=
    cd ${PrjPath}
    set +e
    PackageList=$(ls ${PrjPath} | grep \.dsc$ | sort --reverse --version-sort)
    set -e
    PackageArray=(${PackageList})

    i=0
    for element in ${PackageArray[*]}
    do
        packageE=${packageE}' '$i' '${element}' off '
        i=$(expr $i + 1)
    done

<<DebDiff4>>
@

Für diese Auswahlmöglichkeit werden alle lokal verfügbaren
\textit{.dsc-Dateien} geordnet angezeigt. Davon können dann genau die
zwei Dateien zum Vergleich ausgewählt werden.

<<DebDiffCheckList>>=
function DebDiffCheckList {
    # Called by DebDiff

    PackageNrL=$(whiptail --title "debdiff" \
    --checklist "Which two versions should be compared?" \
    15 60 8 \
    ${packageE} --cancel-button "Cancel" 3>&2 2>&1 1>&3)

    PackageNrA=(${PackageNrL})
}

<<DebDiff>>
@

%\begin{figure}[h]
%\centering
%\includegraphics[width=25em,height=30ex]{Pictures/DebDiffSelectVersion.png}
%\caption{Welche Versionen vergleichen}
%\end{figure}

Das Programmskript prüft nun, ob genau zwei Einträge (\textit{.dsc}-Dateien)
ausgewählt wurden.

<<DebDiff4>>=
    DebDiffCheckList
    
    if [ ${#PackageNrA[@]} -gt 2 ]
    then
        whiptail --title "Too much selections" \
        --msgbox "Please select only two versions" 15 60
        DebDiffCheckList

<<DebDiff5>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/TooMuchSelections.png}
\caption{Zu viele Versionen ausgewählt}
\end{figure}

<<DebDiff5>>=
    elif [ ${#PackageNrA[@]} -lt 2 ]
    then
        whiptail --title "Less selections" \
        --msgbox "Please select two versions" 15 60
        DebDiffCheckList
    fi

<<DebDiff6>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/LessSelection.png}
\caption{Zu wenig ausgewählt}
\end{figure}

Wurden genau zwei \textit{.dsc}-Dateien ausgewählt, erfolgt der Vergleich
der Quellcodepakete mit \textit{debdiff}.

<<DebDiff6>>=
    if [ -z "${PackageNrL}" ]
    then
        cd ${GitPath}
        CommonTasks
    fi

    if whiptail --title "Reverse order?" \
        --yesno "Should the order of the packages be reversed?" \
        --yes-button "Yes" --no-button "No" --defaultno 15 60
    then
        sn=${PackageNrA[1]}
        fn=${PackageNrA[0]}
    else
        fn=${PackageNrA[1]}
        sn=${PackageNrA[0]}
    fi

<<DebDiff7>>
@

\begin{figure}[h]
\centering
\includegraphics[width=25em,height=30ex]{Pictures/ReverseDiffOrder.png}
\caption{Umkehr der Reihenfolge der zu vergleichenden Pakete}
\end{figure}

In bestimmten Fällen ist es sinnvoll, die Vergleichsreihenfolge umzukehren.

Regelmäßig ist das Resultat dann richtig, wenn im Dateinamen die ältere
Version vor der neueren erscheint.

<<DebDiff7>>=

    # Killing toxic quotationmarks
    fn=$(echo $fn | sed --expression="s/\"//g")
    sn=$(echo $sn | sed --expression="s/\"//g")

<<DebDiff8>>
@

Die Ausgabe von \textit{debdiff} erfolgt in eine entsprechend benamten
Datei im Projektverzeichnis. Der Inhalt dieser Datei wird mit \textit{less}
angezeigt.

<<DebDiff8>>=
    echo -e "Compare with debdiff: \n" \
    ${PackageArray[fn]}" and "${PackageArray[sn]}"\n" >> \
    ${log}
    echo -e "The result can be found in\n" \
    debdiff_${PackageArray[fn]}-${PackageArray[sn]}.diff >> ${log}
    set +e
    debdiff --diffstat ${PackageArray[fn]} ${PackageArray[sn]} > \
    debdiff_${PackageArray[fn]}-${PackageArray[sn]}.diff
    set -e
    less debdiff_${PackageArray[fn]}-${PackageArray[sn]}.diff

    if [ ${debdiffFlag} -eq 0 ]
    then
        cd ${GitPath}
        CommonTasks
    fi
    cd ${GitPath}
}

<<ImportDebianPackage>>
@