% !TEX root = BuildWithGBP.nw% ===> this file was generated automatically by noweave --- better not edit it
\part{Preparation} 

This part of the book starts with a little theory. Then the setup of the system including the Git repository, which is essential for \textit{git-buildpackage}, is described. 

\chapter{Literature} 

Some people ask what they should have to read before starting building \texttt{Debian} packages. Others want to know where they can find helpful information. So here are recommended readings for those who (want to) build \texttt{Debian} packages. 

A short introduction to the topic "`Packaging for Debian"' contains the \texttt{Simple Packaging Tutorial}\cite{SimplePackagingTutorial2019}.. 

The following three documents are ``must-reads'' for any package maintainer. 

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

All who want to contribute to \texttt{Debian} are recommended to read the social contract\index{Social Contract}. The \texttt{Debian Free Software Guidelines (DFSG)}\cite{DFSG} are an essential part of the social contract. They contain the conditions that a license must meet in order to be considered "`free'". These conditions are already significant in the selection of the software to be packaged (chapter \ref{sec:SourceVerification}, page \pageref{sec:SourceVerification}). 

The \texttt{Debian Free Software Guidelines (DFSG)} apply not only to software licenses, but according to clause 1 of version 1.1 of the social contract ("`all components'") also to the licenses of images, sounds, texts etc.. 

\section{\texttt{Debian} Policy Manual} \label{sec:PolicyHandbuch} 

The \texttt{Debian} Policy Manual\cite{DebianPolicy} \index{Debian Policy} describes the policies for the \texttt{Debian GNU/Linux} distribution. It describes the structure and contents of the \texttt{Debian} archive, various operating system design decisions, and technical requirements that each package must meet to be included in the distribution. This document is available in English only. 

It is also available as \texttt{Debian} package \textit{debian-policy}. 

The \index{FHS} \texttt{Filesystem Hierarchy Standard}\cite{fhs} is an important addition to the Policy Manual. 

There are also other supplementary sets of rules.\footnote{\url{https://www.debian.org/devel/index.en.html}} 

\section{\texttt{Debian} Developer Reference} 

The \index{Developer Reference} Developer Reference\cite{Debian-Entwicklerreferenz} \index{Debian Developer Reference} lists the procedures and resources for  \texttt{De\-bian}-developers. The document describes how to become a new developer for the \texttt{Debian} project, the upload procedure, how to operate the bug database (bug tracking system), the mailing lists, Internet servers, etc. 

This document is intended as a reference manual for all \texttt{Debian} developers. It is available as \texttt{Debian} package \textit{developers-reference-en}. \cite{Debian-Entwicklerreferenz} 

\section{Reference for \textit{Git-Buildpackage}} 

There are various procedures and tools for building \texttt{Debian} packages. In this book, \textit{git-buildpackage} \index{git-buildpackage} is used. 

In addition, we therefore still recommend the \textit{git-buildpackage}\cite{Guenther2006-2017} reference for the build system we have chosen. 

\section{Manual for \texttt{Debian} Maintainer} 

This manual \index{Manual} for the \texttt{Debian} Maintainer\cite{Leitfaden_Debian-Betreuer} describes how to build a \texttt{Debian} package using the \textit{debmake} command. It is intended for normal users and aspiring package maintainers. 

The focus is on the modern packaging style. Many simple examples are included. 

This ``Manual for \texttt{Debian} maintainers'' should consider as a legacy of the ``\texttt{Debian} Guide for New Package Maintainers''. 

It is available as \texttt{Debian} package  \textit{debmake-doc}. \cite{Leitfaden_Debian-Betreuer} 

\section{\texttt{Debian} New Maintianer Guide} 

This mature \index{New Maintianer Guide}work\cite{maint-guide} attempts to describe building \texttt{Debian} packages in a way that is understandable to ordinary users and future developers, with working examples. 

Unlike previous documents, this one builds on \textit{debhelper} and other tools available to a developer. \cite{maint-guide} 

This document is also available in other languages and as \texttt{Debian} packages. 

\section{More Information} 

Other useful \index{Literature} literature can be found at \url{https://www.debian.org/doc}. 

On the subject of building \texttt{Debian} packages, one can find documents in other places on the Internet. However, it is important to note: ``The internet does not forget anything, and somewhere there is always still an outdated documentation linked, whose obsolescence is also not recognizable due to the lack of an expiration date.'' \footnote{About this book, chapter 2.9 in the book Debian Package Management}\cite{DPMB2021} 

\chapter{What is a \texttt{Debian} Package?} \label{chap:DebianPackage} 

To understand the way, you should know the goal. The goal of packaging is a \texttt{Debian} package\index{Debian Package}\cite{SimplePackagingTutorial2019}. 

But what is a \texttt{Debian} package? 

A formal answer is: A \texttt{Debian} package is a software package released by the \texttt{Debian} project\index{Debian Project}. 

For a package to be released by the \texttt{Debian} project, it must meet requirements established, written, and published for transparency by the \texttt{Debian} project. 

A \texttt{Debian} package is a software package that primarily satisfies the requirements described in the \texttt{Debian} policy\cite{DebianPolicy}. It is part of the transparency maintained by the \texttt{Debian} project  that the exact version of the \texttt{Debian} policy followed in building the package is specified in the \textit{debian/control} file. (Chapter \ref{subsec:DebianControl}, page \pageref{subsec:DebianControl}) 

A \texttt{Debian} packages is a collection of files that allows applications or libraries to be distributed through the \texttt{Debian} package management system. The goal of packaging is to allow the automation of installing, updating, configuring, and removing software for \texttt{Debian} in a consistent manner.is\cite{SimplePackagingTutorial2019} 

A \texttt{Debian} package is more than just an archive file containing executable code with the extension \textit{.deb}. A \texttt{Debian} package consists of \textbf{four} files; three of them are archives. 

\begin{itemize}\itemsep2pt \item An archive file with the extension \textit{.orig.tar.gz} resp. \textit{.orig.tar.xz} contains the source code from which the package is built. \item Another archive file with the extension \textit{.debian.tar.xz} contains the debian-specific files that control the build process and installation or contain additional information. \item A file contains the signatures of the archive files. This file has the extension \textit{.dsc}. This file is signed, too. \item Finally, the executable code is in the archive with the extension \textit{.deb}. \end{itemize} 

The \texttt{Debian} package system enables traceability of the path from the upstream source code to the binary \texttt{Debian} package. Aimed at and often achieved is a bit-accurate reproducibility \index{Reproducibility}of the build process\cite{Team2020}. 

How this can be checked is described in chapter \ref{chap:ReproducibleBuilds} (page~\pageref{chap:ReproducibleBuilds}). 

This transparency gives the user confidence that the binary package was also comprehensibly built from the published source code. 

If you save software from your build system to an archive in deb format without caring about standards and rules, you don't pack a  \texttt{Debian} package. 

Several variants (releases) are offered by the  \texttt{Debian} project at any time, namely \textit{stable}\index{stable}, \textit{testing}\index{testing} and \textit{unstable}\index{unstable}. After the release of each new \textit{Stable} version, the previous  \textit{Stable} version is maintained for some time as \textit{Oldstable} \index{oldstable}. Furthermore, there is still \textit{oldoldstable} \index{oldoldstable} and a branch \textit{experimental}\index{experimental}. There, changes are tried out that could have serious effects on the overall system. 

However, the \textit{experimental} branch is not a complete distribution, but works only as an extension of \textit{unstable} \cite{DebianExperimental2020}. 

The branch \textit{unstable} (\textit{Sid}) is the first port of call for new programs and new versions of programs before they are integrated into \textit{testing}. 

The development of a \texttt{Debian} package usually starts in the \textit{unstable} branch.\footnote{I.Concepts, chapter 2.10.1\cite{DPMB2021}} 

Each \texttt{Debian} package belongs to a defined development stage of the \texttt{Debian} distribution, i.e. to a specific, released version\footnote{Chapter 2.10 in \cite{DPMB2021}}. 

Each package must be aligned with its release. It must not have any dependencies on another release. Libraries may only exist in one version in a release, so that security updates are easy for the user. A \texttt{Debian} package must therefore not contain its own version of such a library. \footnote{Chapter 7.1 \cite{DebianFAQ2019}} 

\chapter{How to select the software to be packaged} 

Often the question is asked to the project, which package is suitable for starting. To learn packaging, there is no specially created ``training'' package. Rather, one learns packaging by packaging \texttt{Debian} packages (``learning by doing''). 

It is emphasized from the beginning that the motivation is brought along to work step by step into the subject of packaging. A good condition for it is also that it is a software, which one would like to use gladly as \texttt{Debian} package and make available to others.. 

Often there are also packages for which the maintainers need help or which are orphaned. This can also apply to packages that are used by themselves. To find out if and which of the installed packages are affected, there is a tool that you can install additionally as package \textit{how-can-i-help} \cite{HowCanIHelp2021}. 

This installation causes \textit{apt} to call \textit{how-can-i-help -{}-apt} at the end. This will then list help needing packages that have just been updated. 

With \textit{how-can-i-help -{}-old} you can see which of the installed packages need help. 

With \textit{how-can-i-help -{}-all} all packages are displayed for which help is needed\footnote{More details about \textit{how-can-i-help} are described in Debian Package Management\cite{DPMB2021} in chapter 37.3.6.}. 

This information can also be found at \url{https://www.debian.org/devel/wnpp/}. The acronym \textit{wnpp} abbreviates \textit{Work-Needing and Prospective Packages} and stands, mutatis mutandis, for packages on which work is needed and which are in the process of being created (prospective packages). 

It is also motivating and helpful if one is active in the upstream project. In these cases, a certain sustainability of the package support is guaranteed. 

For many categories of packages support teams have been formed \footnote{Lists can be found at \url{https://wiki.debian.org/Teams.}}. If you choose a package that fits into the portfolio of such a team, you have a better chance to find support and sponsors. Support can also be found on the mailing lists of the respective teams. 

Before you start packaging, you should of course check if the software is already packaged. With \textit{apt search <name>} it can be determined whether there is already a corresponding \texttt{Debian} package. At \textit{salsa.debian.org} you can check if there are already packaging attempts in progress. 

For all questions about packaging for \texttt{Debian} there is also a special mailing list\footnote{\url{https://lists.debian.org/debian-mentors/}}. Just reading along this list is useful. 

\chapter{Checking the sources} \label{sec:SourceVerification} 

Having selected the software to be packaged for \texttt{Debian}, the source code must now be examined in more detail. The goal of this examination is to determine that the selected software can be packaged by the package maintainer for \texttt{Debian main}. To do this, it must be verified that \textbf{all} parts of the source code conform to the \texttt{Debian Free Software Guidelines} (\texttt{DFSG})\cite{DFSG} \index{DFSG} and are consistent with the \texttt{Debian} policy\cite{DebianPolicy} \index{Debian Policy}. 

This requires an intensive examination of \textbf{all} source code files. 

\section{License verification}\index{License verification} \label{sec:LicenseCheck} 

In \texttt{Debian}, only Free Software\index{Free Software} as defined in the \texttt{Debian Free Software Guidelines} may be published in the \texttt{main}\index{main} branch. You have to note the \texttt{Debian Free Software Guidelines (DFSG)} apply not only to software licenses, but according to clause 1 of version 1.1 of the social contract ("`all components'") also to licenses of images, sounds, texts, etc. 

Checking this requirement has a big part in the work of a package maintainer, especially to release a new package in \texttt{Debian}. 

When creating and maintaining the \textit{debian/copyright} file, this work is then used. Thus this file is also one of the most important files of a \texttt{Debian} package. It describes the copyright situation. 

This file must accurately describe the copyright and licenses of all files in a source package using a specific syntax (DEP-5).\cite{DEP-5} 

The \textit{debian/copyright} file is checked by the FTP masters\cite{FTPMaster2020} when a new package is to be accepted in the \texttt{Debian} project. 

To avoid overlooking entries for this purpose, at least a four-eyes-principle \index{Copyright-Review} (peer-review)\cite{CopyrightReviewTools2021} applies. 

The contents of the copyright file must therefore accurately reflect the licenses \index{Licenses} of all files. The license \index{License} is often specified in the comments of a source file.  

The entire source code must be tested from this point of view. There are some tools that help the package maintainer to perform these tests. \footnote{\url{https://wiki.debian.org/CopyrightReviewTools}} 

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

The \textit{debmake -cc} \index{debmake} command is also used by the program script to create the \textit{debian/copyright} file (Chapter \ref{subsec:d/copyright}, page \pageref{subsec:d/copyright}). 

In practice, it turns out that this is sometimes not sufficient. This is because the information about the licenses and the authors is not stored following a standard. Therefore the program \textit{debmake} does not find all entries concerning the required \textit{copyrights}. So further tests are needed . 

\subsection{\textit{licensecheck}} 

The \textit{licensecheck} program (from the package of the same name) is able to scan source files and reports the copyright and licenses specified in them. However, it does not summarize this information: A copyright line is generated for each file in a package. 

The test was performed with the command line 

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

as detailed in the wiki\footnote{\url{https://wiki.debian.org/CopyrightReviewTools\#licensecheck}}. 

Unfortunately, the manual page (man page) of \textit{licensecheck} is rather unproductive. More information is provided by the command: 

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

The output must be evaluated manually, since \textit{licensecheck} also tries to display the copyright for so-called binary files (e.g. images, fonts). 

\subsection{\textit{scan-copyrights}} 

The \textit{scan-copyrights} program from the \textit{libconfig-model-dpkg-perl} package can update an existing copyright file by rescanning the source. 

The command line for this is: 

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

The program can also create such a file from scratch. This is done in DEP-5 format. \cite{DEP-5} 

This program is written in \texttt{Perl} and uses \textit{licensecheck}.  

\subsection{\textit{licensing}} 

The \textit{licensing} command from the \textit{licenseutils} package can scan the source code and return found licenses with the command. 

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

It can also add license templates to new code. 

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

Another tool is \index{cme}\textit{cme}. \textit{cme} checks and/or edits the data in the configuration files. Among other things, this can be used to check whether the copyright file provided by the original author \index{Original author} contains all the necessary information.  

The \textit{cme fix dpkg} command checks the \textit{dpkg} files, updates obsolete parameters, and applies any fixes (Chapter \ref{sec:cmefix}, page \pageref{sec:cmefix}). 

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

the licenses listed in the headers of the source code files are checked and listed. 

With \begin{verbatim} cme check dpkg-copyright -file <path/file name> \end{verbatim} 

data can be read from any file. 

There is also a graphical user interface for this package with \textit{libcomcnfig-model-tkui-perl}. 

\subsection{Manually} 

The use of these tools is sometimes not sufficient. It may happen that further authors are named somewhere in the code. This can be searched for with the following commands: 

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

\subsection{Stumbling blocks} 

There are the following stumbling blocks: \begin{enumerate} \item {co-delivered build dependencies} \item {microcode} \item {co-delivered non-free documents} \item {licenses incompletely observed by the upstream author}. \end{enumerate} 

Such files must be excluded from the \textit{*.orig.tar.xz} to be published, if this is reasonably possible. An appropriate version designation must also be chosen. \cite{debian-mentorsFAQ}. In this program script, it is intended to exclude the files using the \textit{debian/copyright} file (chapter \ref{subsec:ExcludeFiles}, page \pageref{subsec:ExcludeFiles}) 

If the source code package contains differently licensed files, the source code package as a whole must be examined in addition to checking the licenses\index{Licenses} of the individual source code files. It must be checked whether the licenses used are compatible with each other. The \textit{FINOS Open Source License Compliance Handbook}\cite{OpenSourceLicenceCompliance2019} is helpful here. 

\section{Identifying the Programming Language} 

Software is written in different programming languages. There are also programs written in several programming languages. Depending on the programming language, different compiler and build systems must be used. 

There are several build systems for building \texttt{Java} packages. This is described in detail in a separate chapter (chapter \ref{chap:JavaPaketeBauen}, page \pageref{chap:JavaPaketeBauen}). 

\section{Checking the Dependencies} \label{sec:CheckDependencies} 

In order to release a package in \texttt{Debian main}, \textbf{all} dependencies \index{dependency} (including build dependencies) must already be available in \texttt{Debian main}\cite{DebianPolicy}. This means that dependencies that are not yet available must be packaged first.  

How the dependencies can be determined depends on the programming language. Hints on unfulfilled build dependencies can also be found in the build error messages. 

For \texttt{Java} programs, there are several places where this information can be found. This is described in the corresponding chapter (chapter \ref{chap:JavaPaketeBauen}, page \pageref{chap:JavaPaketeBauen}). 

\subsection{Identify dependencies with \textit{packages.debian.org}} 

To determine if the required dependency is already packaged, you can start with the website \textit{packages.debian.org}. 

In the \textit{Search package directories} section, the options \textit{Package names only} and \textit{Source package names} are interesting. 

In the \textit{Search the contents of packages} section, it is then the option \textit{packages that contain files whose names contain the keyword}. 

As distribution should then \textit{all} or \textit{Unstable} be selected. 

\subsection{Identify dependencies at \textit{codesearch.debian.net}}  

Sometimes it can be helpful to look for source code in which a similar problem has been solved before. 

An example is that in a package built with \texttt{Maven}, a certain entry in the file \textit{debian/maven.rules} has been done before. 

Such a search can be done -- as follows: 

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

\subsection{Search for Dependencies at the Console} 

% II.Werkzeuge, Kapitel 8.20\cite{DPMB2021}
With \textit{apt-file find} \footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}} it can be determined if needed dependencies are already packaged in Debian. 

\section{Modifications of the Source Code } 

The source code must be carefully checked to see if any changes need to be made to it for the \texttt{Debian} package. Such a need can have various causes. 

The upstream release may contain parts that do not comply with the \texttt{Debian} policy\cite{DebianPolicy} \index{Debian Policy} or the \texttt{Debian} Free Software Guidelines\cite{DFSG} \index{DFSG}. 

Changes to the source code specifically for the \texttt{Debian} package can be made as follows: 

\begin{itemize} \item Whole files can be excluded. This is done when building a new version (chapter \ref{subsec:ExcludeFiles}, page \pageref{subsec:ExcludeFiles}). \item Changes can be made to upstream files by \textit{patching} (chapter \ref{subsec:AenderungQuellcodeDateien}, page \pageref {subsec:AenderungQuellcodeDateien}). This is done by the program script when building a new revision (chapter \ref{chap:Aenderungen_am_Upstream_Code_vornehmen}, page \pageref{chap:Aenderungen_am_Upstream_Code_vornehmen}). \end{itemize} 

\subsection{Exclude complete files} \label{subsec:Dateien_ausschliessen} 

If entire files need to be excluded, a source code package must be created that no longer contains these files. 

Before \textit{mk-origtargz} is called, the program script allows individual source code files to be excluded from inclusion in the \textit{orig} archive. 

The files that do not comply with the \texttt{Debian} policy\cite{DebianPolicy} or the \texttt{Debian} Free Software Guidelines (\texttt{DFSG})\cite{DFSG} must be removed. 

A new version must always be built, even if no new upstream source code archive is used. 

The exclusions should be documented with their rationale in the \textit{debian/README.source} file (chapter \ref{subsec:ReadmeSource}, page \pageref {subsec:ReadmeSource}). 

\subsubsection{Listing of files to be excluded} 

The files to be excluded can be listed either in a separate file or in the \textit{debian/copyright} file in \textit{DEP-5 format} \cite{DEP-5}. 

Example: \scriptsize

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

In the enumeration, the files to be excluded are separated by one character using spaces or line breaks with indentation.Case distinctions 

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

Often it is already known before the package is submitted to the \textit{New Queue} that files are to be excluded. Since there is no \textit{debian/copyright} file at this point, it is a good idea to list the files to be excluded in a separate file. 

In response to the corresponding question in the program script, specify that files are to be excluded. Then the program script determines where to store the information to exclude files. This is a separate file before submitting the first package of a new project.. 

This is done by creating a file \textit{<SourceName>-excluded} in the directory \textit{PrjPath} (chapter \ref{subsec:PathDefinition}, page \pageref{subsec:PathDefinition}). 

The information in this file is to be transferred there when the debian/copyright file is created (chapter , page ).\textit{}\ref{subsec:d/copyright}\pageref{subsec:d/copyright} 

After a rejection from the \texttt{New Queue}, the package must be re-provisioned for release. Again, files whose license is not \texttt{DFSG} compliant may have to be excluded. The exclusion of the files already applies to the *.orig.tar.(gz | bz2 | xz) to be published. Usually, however, no other (newer) upstream version is available at this time. However, the version to be created must be larger than the previous version but smaller than the next expected upstream version.. 

In the case of removing files that are not DFSG compliant, this is the \textit{+dfsg} attachment that directly follows the upstream version. If this attachment already exists, it is incremented after \textit{+dfsg1} (see chapter \ref{subsubsec:BenamungPakete}, page \pageref{subsubsec:BenamungPakete}). Thus, a new tarball with a larger version label can be created with \textit{mk-origtargz}. (Chapter \ref{sec:schema}, page \pageref{sec:schema}) 

The names of the files to be excluded are added to the then already existing file \textit{debian/copyright} in DEP-5 format\cite{DEP-5}. After committing these adjustments in the \textit{debian/} directory, a new version can be built. For this the previous upstream archive is used. 

In this way, a new orig tarball is created with \textit{mk-origtargz} without the files to be excluded from the previous *.tar.gz and its contents are inserted into the existing Git repository with \textit{gbp import-orig} (chapter \ref{subsec:GbpImportOrig}, page \pageref{subsec:GbpImportOrig}). 

If a new upstream version requires files to be excluded, or if the files to be excluded change, proceed in the same way as just explained. The copyright file must be changed and a corresponding commit must be executed. Again, when building the new version, specify that files are to be excluded. 

\subsubsection{Naming of packages when excluding files} \label{subsubsec:BenamungPakete} 

So that the version designation of this new version is larger than that of the previous version, but smaller than the expected next upstream version, the previous version designation is provided with an appendix. This makes clear at the same time that and why the upstream code was changed. 

Common additions to the version string are \textit{+dfsg} and \textit{+ds}\footnote{\url{https://wiki.debian.org/DebianMentorsFaq} in section \textit{What does "'dfsg"' or "'ds"' in the version string mean}}. 

If licenses of individual files of the upstream source code do not satisfy the \texttt{Debian Free Software Guildelines (DFSG)} and therefore should not be published as sources by \texttt{Debian}, the supplement\textit{+dfsg} is used. If other reasons require the exclusion, one takes \textit{+ds} ("{}Debian Source"{}). \cite{debian-mentorsFAQ} 

This is because it is possible that initially only files that do not comply with the \texttt{Debian} policy were excluded. 

If it is later determined that the uploaded original archive still contains non-free documents, this then leads to a version designation according to the pattern \textit{<version number>+ds+dfsg.}\footnote{s. Mentors-FAQ 2.6\cite{ debian-mentorsFAQ}} 

In some cases, a plus sign (+) can cause problems especially when building Java packages. 

The naming of the \texttt{Debian} packages shown also has consequences for the contents of the \textit{debian/watch} file (chapter \ref{sec:uscanwatch} page \pageref{sec:uscanwatch} and chapter \ref{sec:uscan} page \pageref{sec:uscan}). 

\subsection{Changes in individual source code files (patching)} \label{subsec:AenderungQuellcodeDateien} 

Changes to source code files\index{Patching}are necessary when adjustments \index{Build environments}have to be made due to different build environments. Other cases are bug fixes\index{Troubleshooting}, especially \textit{security patches}\index{Security Patches}. 

The classical method is described below with \textit{quilt}. 

Besides, this can also be done in a \textit{patch queue} branch with \textit{gbp pq} (chapter \ref{subsubsec:BeschreibungPQ}, page \pageref{subsubsec:BeschreibungPQ}) 

\subsubsection{Patching with \textit{Quilt}} 

Changes to source code files are made by so-called patch files. These document the original source code and the respective changes. Another file (\textit{debian/patches/series}) controls the sequence of application of patches. This usually happens with \textit{quilt}. \textit{Dquilt} is a \texttt{debian}-specific adjustment for \textit{quilt}.. 

For this, there is a description in the \textit{Debian Guide for New Package Maintainers}\footnote{\url{https://www.debian.org/doc/manuals/maint-guide/modify.en.html}} and in the \textit{Debian Wiki}\cite{UsingQuilt2020}. In addition, there is a general introduction to the use of Quilt \cite{Gruenbacher2012}. 

Chapter \ref{sec:QuiltEinrichtung} (page \pageref{sec:QuiltEinrichtung}) describes how to generate the \texttt{debian}-specific customization. 

\subsubsection{Patching in a \textit{Patch-Queue}-Branh} \label{subsubsec:BeschreibungPQ} 

Since a workflow with \texttt{Git} or \textit{git-buildpackage} \cite{Guenther2006-2017} is used to build the Debian packages, it makes sense to use \textit{gbp pq}\index{gbp pq} instead of \index{quilt} \textit{quilt}\footnote{section gbp.patches.html \cite{Guenther2006-2017}}. 

The changes are then made in a separate \texttt{Git} branch. 

When using \textit{gbp pq}, \emph{all} code changes then occur in this branch. These changes should be thematic and small-scale. Then the patches can flow more easily to upstream or be adopted from other distributions. This also makes it easier to adapt to a new upstream version. 

The basic idea is that patches are imported from the \texttt{Debian} branch to the patch queue branch in such a way that one patch file in \textit{debian/patches} corresponds to one commit on the patch queue branch at a time. 

The patch queue branch is created with \textit{gbp pq import}. (s. a. Chapter \ref{sec:ImportPatchQueue} Page \pageref{sec:ImportPatchQueue}) 

The created branch is named after the branch from which it was imported. It is prefixed with \textit{patch-queue/} to distinguish it. So, if the \texttt{Debian} packaging is done on \textit{debian/sid} and a \textit{gbp pq import} is done, the newly created branch is named \textit{patch-queue/debian/sid}. 

The program script allows this import before downloading a new upstream version (chapter \ref{sec:ImportPatchQueue}, page \pageref{sec:ImportPatchQueue}) and as a selection option for patching (chapter \ref{sec:WorkingwithGbpPq}, page \pageref{sec:WorkingwithGbpPq}). 

In the patch queue branch, the familiar \texttt{Git} commands (\textit{rebase}, \textit{commit} and \textit{-{}-amend}, etc.) can be used to work on the commits. When this is done, \textit{gbp pq export} is used to convert the commits on the \textit{patch queue branch} back to patches in \textit{debian/patches/} files. 

%toDo: Hier muss noch der Verweis angepasst werden
(Chapter~\ref{sec:WorkingwithGbpPq}, page~\pageref{sec:WorkingwithGbpPq}). 

This described workflow facilitates, for example, cherry-picking patches for stable releases, forwarding patches to new upstream releases by using \textit{git rebase} on the patch queue branch (already applied patches are automatically detected), and reordering, dropping, and renaming patches without resorting to \textit{quilt}. The generated patches in \textit{debian/patches/} have all the necessary information to be forwarded to upstream, since they use a format similar to \textit{git-format-patch}. 

The main disadvantage of this workflow is the lack of history on the patch queue branch, since it is often dropped and recreated. But there is of course a full history on the \texttt{Debian} branch in the \textit{debian/patches/} directory. 

Note that \textit{gbp pq} does not currently provide full support for DEP3 headers\cite{DEP-3}. 

First, it will try to parse with git-mailinfo\cite{GitMailinfo2020}, which only supports the \textit{From} and Subject fields. If neither of these are present, \textit{gbp pq} will attempt to convert the patch from DEP3 format to a git-mailinfo(1) compatible format. This is done by first loading from the ``author'' and ``subject'' fields via the first line of the Description field. Then any additional fields (such as ``Origin'' and ``Forwarded'') and the rest of the description (if any) are appended to the \textit{mail body}. 

\chapter{Versioning of the packages} \label{chap:VersioningPackage} 

Both the software to be built for Debian and \texttt{Debian} packages have version names. Here, the version designation of the upstream software should be included in that of the Debian package. 

The names of all Debian binary package files are structured as follows: 

\small \textless{}foo\textless{}\textgreater\textless{}Version number\textgreater{}-\textless{}Debian revision number\textgreater{}\_\textless{}Debian architecture\textgreater{}.deb. \normalsize

\footnote{DebianFAQ2019, Chapter 7.3\cite{DebianFAQ2019}} 

\section{Package Name} 

The version name is preceded by the package name. 

This must be written entirely in lowercase. The version name may also contain digits. Additionally, +, -, \textasciitilde can be included. 

The version designation must begin with a digit. 

\section{Version Scheme} \label{sec:schema} 

The versioning \index{Versioning} of the packages follows a firmly defined scheme. This ensures that all tools that use this versioning can access the same scheme. It must be ensured that the system recognizes the new version designation \index{Version Name} also as larger than the previous version designation. (s.a chapter \ref{subsec:IdentifyUpstreamVersion}, page \pageref{subsec:IdentifyUpstreamVersion}) 

So how must the version designation of the future package be composed? After the version designation of the upstream package, debian-specific additions can be made. These may indicate if and why parts of the upstream sortware have been removed, or if the package has been backported to an older package. In addition, the package version name includes a \texttt{Debian} revision number. This \index{Revision Number} revision number is incremented especially if the package was rebuilt because of fixes in files in the \textit{debian/} directory. 

Possible variants can be checked for their suitability with the following command:\index{compare-version} 

\begin{verbatim} dpkg --compare-versions Version1 Operant Version2 && \
 &&\echo "OK" \end{verbatim} As operands these are to be used: lt le eq ne gt 

\begin{description} \item[lt] less than (<) \item[le] less than or equal to (<=) \item[eq] equal to (=) \item[ne] not equal to (!=) \item[ge] greater than or equal to (>=) \item[gt] greater than (>). \end{description} 

The version comparison rules \index{Rules of comparison} can be summarized as follows:\footnote{New Maintainer Guide, chapter 2.6 \cite[Kapitel 2.6]{maint-guide} s.a. Debmake-doc, chapter 5.2} 

\begin{itemize}\itemsep2pt \item Strings are compared from beginning to end. \item Letters are larger than digits. \item Digits are compared as integers. \item Letters are compared in ASCII sort order. \item There are special rules for dot (.), plus (+), and tilde (\textasciitilde) characters, as follows: \emph{Example:} 0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0\textasciitilde rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0. \end{itemize} 

In some cases, a plus sign (+) can cause problems especially when building Java packages. 

The ``correct'' versioning plays a role if this is to be read and used by programs. These are mainly the programs \textit{dpkg}\index{dpkg}, \textit{apt}\index{apt} and \textit{uscan}. 

\section{\textit{apt} and \textit{dpkg}} 

The correct versioning of the \texttt{Debian} package is then not quite easy if not built for \texttt{Debian}-Sid (chapter \ref{sec:Versioning}, page \pageref{sec:Versioning}). 

\textit{dpkg} or \textit{apt} must be able to correctly identify if a newer package is available in the respective release branch. 

\section{\textit{uscan} and the file \textit{debian/watch}} \label{sec:uscanwatch} 

\textit{uscan}\index{uscan} is a useful tool in the \texttt{Debian} project. By means of \textit{uscan} it can be checked if there is an upstream version which is more recent (i.e. higher versioned) than the current \texttt{Debian} package. 

The \textit{uscan} program is provided with the \textit{devscripts}\index{devscripts} package. 

Using the data contained in \textit{debian/watch}, \textit{uscan} checks whether newer versions are available in the original source\index{Original source} (chapter \ref{sec:uscan}, page \pageref{sec:uscan}), and can download them if necessary (chapter \ref{sec:ImportWithUscan}, page \pageref{sec:ImportWithUscan}). 

The information obtained by \textit{uscan} is also displayed on the page of the respective maintainer \\ \url{https://qa.debian.org/developer.php?<Maintainer>@debian.org} \\. 

For this, \textit{uscan} needs first of all a suitable \textit{debian/watch}\index{Watch (File)} file. The creation of this file, which is also needed when downloading the source code with \textit{uscan} (chapter \ref{sec:ImportWithUscan}, page \pageref{sec:ImportWithUscan}), is supported by the program script (chapter \ref{subsec:DebianWatch}, page \pageref{subsec:DebianWatch}). 

If files are excluded and the \textit{*.orig.tar.xz} file has been named accordingly (chapter \ref{subsubsec:BenamungPakete}, page \pageref{subsubsec:BenamungPakete}), appropriate options must be added to the \textit{debian/watch} file. These options are \textit{repack}, \textit{compression}, \textit{repacksuffix} and \textit{dversionmangle}. Then, on the next new upstream version, the download can be performed using \textit{uscan}. This is also true for checking with \textit{uscan} if there is a new upstream version. 

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

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

Fortunately, there are many useful programs (utilities)\index{Utilities} that make building \texttt{Debian} packages easier and more uniform. Anyone involved in building \texttt{Debian} packages will always come across the \textit{dh\_make} tool. The package is called \textit{dh-make} (with hyphen). 

\textit{dh\_make} shows how a \texttt{Debian} package can potentially look like. This makes it possible to learn how to package using concrete examples. Especially instructive are the templates included in the program package. 

\textit{dh\_make} creates many files in the \textit{debian/} directory. For most packages, only a subset of them is needed. 

The Practice shows that each time it is necessary to check which files are not needed for the specific package. Also, the generated files are incomplete and require some manual work. 

To be able to use \textit{dh\_make}, some preparations have to be made. For this purpose a corresponding "`working directory"' is created. The downloaded source code archive is stored in it. Preferably a tar archive intended for this is used. 

This tar archive is unpacked there. This can be done on the console with  

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

\textit{dh\_make} must be called in the directory containing the source code. In doing so, the name of the directory containing the source code may contain characters other than lowercase letters. However, \textit{dh\_make} requires a constrained name that conforms to the <package name>-<version> scheme. \textit{dh\_make} accepts only lowercase letters for package names. 

To allow \textit{dh\_make} to fill the templates correctly, the additional option \textit{-{}-package name} is added to \textit{dh\_make} in such cases. This can be used to force the use of the following name as the source package name. This package name must contain the version name. There must be a hyphen between package name and version name. 

Thus after the change into this directory there with 

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

the source tarball in the form desired by \texttt{Debian} \textit{<SourceName>.orig.tar.gz|xz} can be generated. Besides this, a draft of the files in the \textit{debian/} directory is created. 

The following information is requested. \begin{description} \item[Type of package = package classes] single, indep, library, python with the following meaning \begin{description} \item[single] A single binary package (*.deb) is created. This is the normal case \item[indep] A binary package is created that is independent of the architecture. \item[library] At least two binaries are created. A library package containing only the lib in /usr/lib, and another *-dev\_*.deb package containing the documentation and C headers. \item[python] \end{description} \item[details about package] The determined values for \textit{Maintainer Name}, \textit{Email-Address}, \textit{Date}, \textit{Package Name}, \textit{Version}, \textit{License} and \textit{Package Type} are displayed for confirmation. \end{description} 

The following files are created. First the files are listed, which are needed in any case, in each case in alphabetical order. The files \textit{README.Debian} and \textit{README.source} can be used for information purposes. At the end follow such templates, which are used only in very few packages. 

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

The unneeded files are removed from the \textit{debian/} directory. 

The fact that the directory name must contain the respective version designation is unfavorable when using \textit{git}. It is refrained so far from using this utility in the program script. 

\chapter{\texttt{}Building \texttt{Java} Packages} \label{chap:JavaPaketeBauen} 

Building \texttt{Java} packages has special challenges. These special features are described in detail below. 

For packaging \texttt{Java} packages, there is a special policy called\index{Java-Policy} \texttt{Debian}-\texttt{Java} policy\cite{JavaPolicy}. 

Furthermore there is a description about packaging with the \texttt{Java}tools\cite{Koschany}. In it the\index{javahelper} \texttt{Java} helpers are described. This tutorial is also part of the \texttt{Debian} package \textit{javahelper}. 

More information can also be obtained from the\index{Java-FAQ} \texttt{Java} FAQ\cite{Werner2014}, especially section 2.4\footnote{\url{https://www.debian.org/doc/manuals/debian-java-faq/ch2.en.html\#s2.4}}. 

\section{Challenges} 

In a blog article\cite{Steiner2019} Hans-Christoph Steiner aptly describes the challenges for a \texttt{Debian} package with respect to \texttt{Java} software. 

Accordingly, the \texttt{Debian}-\textit{Java} team must consistently fight the \textit{Java} standard practice of bundling all dependencies into a single \textit{*.jar} file. This means that there are no common security updates. In this model each developer must update each dependency\index{dependency}. This works great for large organizations with staff dedicated to this task. 

For the majority of \texttt{Debian} use cases, this works poorly. \texttt{Debian} delivers on the promise that people can just install \textit{foo} appropriately to make it work, and get security updates. The user doesn't even have to know what language the program is written in, it just works. 

The hope that the \textit{Java} developer community will embrace the value of these use cases and help \texttt{Debian} by making it easier to package \textit{Java} projects in the standard distribution method, with common dependencies that are updated independently, has so far been only rudimentarily fulfilled. 

\section{Applications and Libraries} 

There are two categories of \texttt{Java} packages: Applications\index{Java Application} and Libraries\index{Java Library}. Both \texttt{Java} applications and \texttt{Java} libraries may contain (additional) libraries in the source code which are precompiled. 

If applications written in \texttt{Java} are to be packaged, usually \texttt{Java} libraries must also be provided as \texttt{Debian} packages. 

Both applications and libraries are provided in \textit{*.jar} files as \textit{Zip} archive. 

Both types must basically be written as \texttt{Java} bytecode (*.class files, packaged in a *.jar archive) and with a "`\textit{Architecture: all}"' (chapter \ref{subsec:rules}, page \pageref{subsec:rules}). 

If you have only one (compiled) \textit{*.jar} archive of an application or library to be packaged, a look into the \textit{MANIFEST.MF} file of the respective \textit{ .jar} archive can help to determine the \textit{URL} under which the source code has been published. 

\subsection{Packaging \texttt{Java} programs} 

\texttt{Java} programs\index{Java Application} are intended to be executed by end users. These also require a man page, as far as they are independently executable programs. \footnote{Chapter 2.3 of the \texttt{Java} Policy\cite{JavaPolicy}} 

The package must also ensure that the correct class is used as the main class. 

Additional classes in the package must be packaged into one or more \texttt{Java} archive(s) (\textit{*.jar} file(s)), which can be placed in \textit{/usr/share/java} (if intended for use by other programs) or in a ``private'' directory in \textit{/usr/share/<package>}. 

\subsection{Packaging \texttt{Java} libraries} 

\texttt{Java} libraries\index{Java Library} are used to fulfill dependencies of programs. These can be build and/or runtime dependencies. 

\subsection{Name of the \texttt{Java} package} \label{subsec:Paketname} 

A special challenge is the formation of the correct name of the \texttt{Java} package. 

\section{Dependencies for \texttt{Java} packages} 

\texttt{Java} applications always depend on \texttt{Java} libraries as well. In addition, \texttt{Java} packages always require \textit{default-jdk} as a dependency. Behind this is usually the currently available OpenJDK version, a free \texttt{Java} implementation with long-term support (JDK = \texttt{Java} Development Kit). 

In addition, there are special dependencies that result from the build system. These are discussed below for the individual build systems. 

\subsection{Identify other dependencies} \label{subsec:DetectDependencies} 

\texttt{Java} developers add the required build dependencies - including third-party libraries - to their source code packages in compiled form as *.jar archives. 

Especially among \texttt{Java} developers it is unfortunately very common to fall back on libraries published somewhere in the \texttt{World Wide Web} and then ship them precompiled. These libraries must be replaced by packages published in \texttt{Debian}. 

So, to find dependencies, search for \textit{*.jar} archives in the source code. 

In this case, repacking is necessary for the \texttt{Debian} maintainer to remove these files from the upstream tarball. (Chapter \ref{chap:Aenderungen_am_Upstream_Code_vornehmen}, page \pageref{chap:Aenderungen_am_Upstream_Code_vornehmen}). 

The excluded libraries must be made available through standalone packages. 

\subsection{Identify dependencies} \label{VerifyDependencies} 

If one has determined dependencies, then one must determine how these dependencies can be fulfilled. The first thing to do is to check if corresponding \texttt{Debian} packages already exist. To determine if a dependency has already been packaged in \texttt{Debian}, there are several ways to do this. 

\texttt{Debian}-Wiki (for Maven-Packages): 

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

\section{Build systems for \texttt{Java} packages} 

For building \texttt{Java} packages different build systems \index{Java build system} are used. These are \textit{maven}, \textit{ant} and \textit{gradle}. This results in peculiarities that must be considered when packaging for \texttt{Debian}. There are also \texttt{Java} packages that are built without one of these build systems. The following descriptions are based on the experiences made by the authors. 

\subsection{The build system \textit{maven}} \label{subsec:JavaPaketMaven} 

\texttt{Apache Maven}\index{Maven} is a tool for managing and understanding software projects. 

A key identifying feature for the \textit{Maven} build system is the \textit{pom.xml}\index{pom.xml} file. This contains all information about the respective software project and follows a standardized \texttt{XML} format. 

Also essential is the default \index{Directory structure of Maven}directory structure of a \texttt{Maven} project, shown below.\cite{ASF-Maven2020} 

\begin{description}\itemsep0pt \item[src/main/java] Application / library sources \item[src/main/resources] Application. / library resources \item[src/main/filters] Resource filter files \item[src/main/webapp] Web application sources \item[src/test/java] Test sources \item[src/test/resources] Test resources \item[src/test/filters] Test resource filter files \item[src/it] Integration tests (mainly for plugins) \item[src/assembly] Assembly- Descriptors \item[src/site] Website \item[LICENSE. txt] License of the project \item[NOTICE.txt] Notes and mappings for libraries on which the project depends \item[README.txt] Readme of the project \item[pom.xml] Description of the project and configuration. \end{description} 

In most cases, it is sufficient to build the \textit{src/main/} branch as a \texttt{Debian} package. This is especially true when building libraries that are needed as dependencies for applications. 

The upstream package must meet certain requirements to be built with the \texttt{Maven} build system. 

In any case, this includes at least one \textit{pom.xml} file. This file can be located in various places within the source code. Sometimes it is provided - especially in the \texttt{Maven} repository (\url{https://mvnrepository.com/}.) - only additionally. 

However, if available, it is often better to choose \texttt{Github} or other Git repositories as source. In doing so, pay attention to the version! For some packages the source code is also published under the domain \url{https://gitbox.apache.org/repos/asf}. 

\subsection{Packaging with \textit{maven}} 

For \textit{maven}-based packages, the use of \textit{maven-debian-helper}\footnote{\url{https://manpages.debian.org/unstable/maven-debian-helper/index.html}} is recommended\index{Maven}. 

In the file \textit{debian/rules} (chapter \ref{chap:MavenPlugin}, page \pageref{chap:MavenPlugin}) is written. 

To support building with \textit{maven} it contains the following commands: 

\begin{description}\itemsep0pt \item[mh\_genrules(1)] generates, at least partially, the \textit{debian/rules} file \item[mh\_lspoms(1)] looks for all POM files specified in the project source code. \item[mh\_make(1)] generates the \texttt{Debian} package by reading the information from the Maven POM \item[mh\_resolve\_dependencies(1)] resolves the dependencies and generates the \textit{<package name>.substvars} file containing the list of dependent packages for use by \textit{debian/control}. \end{description} 

There are also corresponding \textit{man pages} for these commands. 

Of these, only the mh\textit{\_}make\footnote{url{https://manpages.debian.org/unstable/maven-debian-helper/mh\_make.1.en.html}} command in the \textit{build-gbp-maven-plugin.sh} plugin is used at first. (Chapter \ref{chap:MavenPlugin}, page \pageref{chap:MavenPlugin}) 

When using mh\textit{\_}make\index{mh\_make}\textit{\_, note that the environment in which mhmake} is started should have all dependencies of the package to be built. Otherwise, any entries in the relevant files (e.g. \textit{debian/control}) must be made up manually. (Chapter \ref{sec:MavenDateienBearbeiten}, page \pageref{sec:MavenDateienBearbeiten})  

For this purpose, it is recommended to perform these operations in a dedicated \textit{chroot}\index{Chroot (maven)} where all dependencies can be installed without burdening the actual host system. The setup of the same is described in chapter \ref{sec:MoreChrootSystems} (page \pageref{sec:MoreChrootSystems}).  

From mh\textit{\_}make the following files are created in the \textit{debian/} directory: 

\begin{itemize}\itemsep2pt \item maven.cleanIgnoreRules \item maven.rules \item maven.ignoreRules \item maven.properties \item <Paketname>.poms \item maven.publishedRules \end{itemize} 

In addition, \textit{mh\_make} also creates the (default) files. 

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

created. This must be taken into account during further work on these files (chapter \ref{sec:DateienInDebian}, page \pageref{sec:DateienInDebian}). 

With \textit{apt-file find}\footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}} it can be determined whether there is a \texttt{Debian} package for an \textit{artifactID}. This function is also used by \textit{mh\_make}. The \textit{artifactID} is located in the \textit{pom.xml} file from the upstream code. 

See \url{wiki.debian.org/Java/MavenPkgs/Unstable} for a list of all \textit{Maven} packages already packaged in \texttt{Debian}. \footnote{ Thanks to Thorsten Glaser and the company Tarent \url{https://www.tarent.de/}for this support} 

\textit{mh\_make} also creates the file \textit{debian/<package name>.poms} from the \textit{pom.xml}. 

In this file all \textit{pom.xml} files occurring in the package are listed with their relative path. These can then be provided there with the listed options. 

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

A commonly used line is \textit{pom.xml --no-parent --has-package-version}. This means that the <parent> tag is removed from the POM when building. The \textit{--has-package-version} option specifies that the original version of the POM is the same as the upstream part of the package version. 

This file can be customized within the build process of a new \texttt{Debian} revision. (Chapter \ref{sec:MavenDateienBearbeiten}, page \pageref{sec:MavenDateienBearbeiten}). 

If the \textit{pom.xml} is in the root directory of the source code, \textit{mh\_make} creates the other files for the \textit{debian/} directory. 

In the \texttt{Maven} repository, the \textit{pom.xml} file is often only provided separately. This file is then placed in the \textit{debian/} directory. 

Therefore, some entries in \textit{debian/rules} (chapter \ref{subsec:rules}, page \pageref{subsec:rules} are required here. 

After calling all \textit{debhelper} (\textit{dh \$@}), the \textit{dh\_auto\_build} is first overridden in a \textit{override} to perform some more preparatory configurations. 

This includes copying files to the location where the build system needs them to build the desired program. 

\nwenddocs{}\nwbegincode{3}\sublabel{NW4L0rPZ-2txdMG-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-2txdMG-1}}}\moddef{maven-build~{\nwtagstyle{}\subpageref{NW4L0rPZ-2txdMG-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
 override_dh_auto_build: 
         cp debian/pom.xml .
         dh_auto_build
\nwnotused{maven-build}\nwendcode{}\nwbegindocs{4}\nwdocspar 

\textbf{More Literature} 

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

With \textit{apt-file find}\footnote{\url{https://manpages.debian.org/unstable/apt-file/apt-file.1.en.html}} it can be determined whether there is a \texttt{Debian} package for an \textit{artifactID}. This function is also used by \textit{mh\_make}. The \textit{artifactID} is located in the \textit{pom.xml} file from the upstream code. 

See \url{wiki.debian.org/Java/MavenPkgs/Unstable} for a list of all \textit{Maven} packages already packaged in \texttt{Debian}. \footnote{Thanks to Thorsten Glaser and the company Tarent \url{https://www.tarent.de/}for this support} 

\subsection{Packaging with \textit{ant}} \label{subsec:JavaPaketAnt} 

The \textit{ant} build system can be recognized by the fact that there is a \textit{build.xml} file. \footnote{\url{https://wiki.debian.org/Java/Packaging/Ant}} 

\subsection{Packaging with \textit{gradle}} 

\section{\texttt{Building Java} Packages without build system} 

It is also possible to simply build a \texttt{Java} library from a directory of *.java files. This is useful when only one or a few individual Java classes are needed from a larger program package to satisfy build dependencies of other packages. 

Thereby there is no build system for such a Java directory like the still to be described \textit{ant} \index{ant}(chapter \ref{subsec:JavaPaketAnt}, page \pageref{subsec:JavaPaketAnt} or \textit{maven} \index{maven} (chapter \ref{subsec:JavaPaketMaven}, page \pageref{subsec:JavaPaketMaven}. 

\nwenddocs{}\nwbegincode{5}\sublabel{NW4L0rPZ-3WCS5x-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-3WCS5x-1}}}\moddef{java-builds~{\nwtagstyle{}\subpageref{NW4L0rPZ-3WCS5x-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
export DH_VERBOSE=1
export DH_OPTIONS=-v 

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

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

override_jh_build: 

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

        javac -encoding UTF-8 src/net/numericalchameleon/util/spokennumbers/*
        jh_build \nwnotused{java-builds}\nwendcode{}\nwbegindocs{6}\nwdocspar 

The \textit{javahelper} package provides assistance for building with \textit{dh}. This is highly recommended for Java packaging. 

Furthermore, the file \textit{debian/javabuild} is required. This contains two columns. 

Specify the \textit{*.jar} file to be built in the first column and the source code directory where the \textit{*.java} files are located in the second column. 

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

The script allows to create this file (chapter \ref{subsec:javabuild}, page \pageref{subsec:javabuild}. 

\chapter{\texttt{Building Mozilla} extensions} \label{chap:WebextBauen} 

Packaging \texttt{Mozilla} extensions as \texttt{Debian} packages has the advantage for users and administrators that extensions can be updated together with the main application. 

\texttt{Debian} packages are installed centrally for all system users\index{System user}. The updates\index{Updating} are also done with the distribution's package management system\index{Package management system}. It requires then only a tool for this purpose. 

These aspects are particularly relevant for security updates or new versions of the applications. 

This has the further advantage that all users work with the same version levels. 

\section{Sources of extensions} \label{sec:SourcesMozillaAddOns} 

At \url{addons.mozilla.org} you can find extensions for \texttt{Firefox} published by Mozilla. 

For the \texttt{Thunderbird} the extensions are published under \url{addons.thunderbird.net}. 

These are there as \textit{.xpi} archives. Provided these are source code packages, there are not necessarily also separate source code archives. To build the \textit{.orig.tar.xz} package from source code archives of file type \textit{.xpi}, the \textit{mozilla-devscripts} package is required (chapter \ref{subsec:DependencyMozilla}, page \pageref{subsec:DependencyMozilla}). 

In the case of an \textit{.xpi} file, special entries are required in the \textit{debian/watch} file for repackaging. The \textit{.xpi} format is a specially specified \textit{.zip} archive. Below is the \textit{debian/watch} file for the \texttt{Thunderbird} extension \texttt{Mailmindr}. 

\nwenddocs{}\nwbegincode{7}\sublabel{NW4L0rPZ-2sH2Wp-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-2sH2Wp-1}}}\moddef{watch4xpi~{\nwtagstyle{}\subpageref{NW4L0rPZ-2sH2Wp-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
version=4
opts=\\ 
repack,compression=xz,\\ 
uversionmangle=s/-?([^\\d.]+)/~$1/;tr/A-Z/a-z/,\\ 
filenamemangle=s/.+\\/v?(\\d\\S+)\\
.*/$1/, https://addons.thunderbird.net/en-US/thunderbird/addon/mailmindr/versions/ \\ (\\d.\\d.\\d) \nwnotused{watch4xpi}\nwendcode{}\nwbegindocs{8}\nwdocspar 

Sometimes you can also find source code releases from people and projects on, for example, Github (\url{github.com}) or self-hosted sites. These can also be available as \textit{.tar.gz} or \textit{.zip} archives. 

From experience, the versions that have already been published in the \textit{addons} archive are not always promptly marked as new versions there. 

\section{Integration into file system} \label{sec:IntegrationFileSystem} 

In order to build all desired \texttt{Mozilla} extensions in a uniform way, the required parts of the script are realized as \textit{Webext plugin} (chapter \ref{chap:WebextPlugin}, page \pageref{chap:WebextPlugin}). This also ensures a uniform integration into the system. 

From the version (>=78.2) of \texttt{Thunderbird}s\index{Thunderbird} can be used exclusively \textit{Mail"=Extensions}\index{Mail-Extension}. This is a break in the deployment of the respective extensions. The old (for TB <= 68.x) extensions do not work anymore. 

The extension must now be added to the \textit{/usr/share/webext} directory with the name (id) from the \textit{manifest.json} file and stored as a zip archive with the extension (.xpi) (chapter \ref{subsec:webext.install}, page \pageref{subsec:webext.install}). 

For this the file \textit{debian/rules} is extended accordingly (chapter \ref{subsec:webextrules}, page \pageref{subsec:webextrules}). In addition, the files \textit{<packageName>.install} (chapter \ref{subsec:webext.install}, page \pageref{subsec:webext.install}) and \textit{<package name>.links} (chapter \ref{subsec:webext.links-tb}, page \pageref{subsec:webext.links-tb}) must always be created so that \texttt{Thunderbird}. 

\chapter{\texttt{Building Python} Packages} \label{chap:PythonBauen} 

\chapter{Building metapackages} 

\textit{Metapackages} are those \texttt{Debian} packages that depends on a group of packages. This groups packages together where it makes sense to install them together. 

Metapackages have some specific features. 

\section{No upstream source} Since there is no upstream source code, a metapackage does not need a file \textit{debian/watch.} 

\section{Native \texttt{Debian} package} \subsection{\textit{debian/source/format}} 

\subsection{\textit{debian/control}} 

\subsection{\textit{debian/rules}} 

\subsection{\textit{debian/changelog}} 

\chapter{Configuration for installation} 

\section{\textit{debconf}} 

\textit{Debconf} is a configuration management system for \texttt{Debian}. This is used to retrieve information for the installation from the user and then take it into account during the installation. \footnote{\url{https://wiki.debian.org/debconf}} 

With \textit{sudo dpkg-reconfigure debconf} \textit{debconf} can be configured itself. This also includes the graphical user interface. 

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

\section{\textit{dbconfig-common}} 

\textit{Dbconfig-common} provides a simple, reliable and consistent method for managing databases used by \texttt{Debian} packages. 

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

It is assumed that an installed and running \texttt{Debian} system already exists. It does not matter which branch (unstable, testing or stable) is running on it. 

To sign the products of the program script, a \textit{GPG} key \index{GPG-Key} of the user must be available on the system. This should usefully be the key intended for the \texttt{Debian} repository. 

This also applies when a virtual machine is set up and used for building. 

\section{Dependencies for the program script} \label{sec:ScriptDependencies} 

The packages required to run the program script are listed in the headers of the same (chapter \ref{sec:scriptdependency}, page \pageref{sec:scriptdependency}). 

Some of the included programs are described below: 

\subsection{General dependencies} 

The helpful programs listed below are regularly used by the script to build a \texttt{Debian} package: 

\begin{description} \item[mk-origtargz] \label{desc:mkorigtargz} from the \textbf{devsripts} \index{devscripts} package renames the original authors' tarball, optionally changes the compression and removes unwanted files. Different options are available for this\cite {Devscripts2020} (see usage in chapter \ref{subsec:mkorigtargz}, page \pageref{subsec:mkorigtargz}). 

\item[gbp import-orig] from package \textbf{git-buildpackage} \index{git-buildpackage} imports a new upstream version into a Git repository (see usage in chapter \ref{subsec:GbpImportOrig}, page \pageref{subsec:GbpImportOrig}). 

\item[dh\_make] from the \textbf{dh-make} \index{dh\_make} package can create the required \textit{Debian} files. Practice shows that this is very incomplete and requires some manual work. Therefore, so far we refrain from using this utility in the program script. (see chapter \ref{chap:DhMake}, page \pageref{chap:DhMake}). 

\item[debmake -cc] from the \textbf{debmake} package of the same name searches the source files for copyright and license texts (see chapter \ref{subsec:debmake}, page \pageref{subsec:debmake}). This command is used by the program script to create the \textit{debian/copyright} file. (see usage in chapter \ref{subsec:d/copyright}, page \pageref{subsec:d/copyright}). 

\item[gbp dch] is also included in the \textbf{git-buildpackage} package. In the program script, \textit{dch} is related via \textit{gbp dch}(see usage in chapter \ref{sec:DebianChangelog}, page \pageref{sec:DebianChangelog}). Further options for \textit{dch} can be passed to \textit{gbp dch} by \textit{-{}-dch-opt=<dch-options>}. 

\item[gbp import-orig] from package \textbf{git-buildpackage} <p0> imports a new upstream version into a Git repository (see usage in chapter <n0>, page <n1>). 

\item[lintian] in  \textbf{\textit{lintian}} and dh\_lintian in \textbf{\textit{devscripts}} 

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

\item[debsign] in \textbf{\textit{devscripts}} also for signing at sponsoring 

\item[dput] in \textbf{\textit{dputt}} resp. \textbf{\textit{dput-ng}} 

\item[mh\_make (Plugin)] 

\end{description} 

\subsection{Dependencies for building \texttt{Java} packages} \label{subsec:DependencyJava} 

The following dependency is required for building with build systems for \texttt{Java} packages. 

\nwenddocs{}\nwbegincode{9}\sublabel{NW4L0rPZ-32PlLN-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-32PlLN-1}}}\moddef{Dependencies1~{\nwtagstyle{}\subpageref{NW4L0rPZ-32PlLN-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
# gradle-debian-helper, maven-debian-helper, libmaven-bundle-plugin-java,
 \LA{}Dependencies5~{\nwtagstyle{}\subpageref{NW4L0rPZ-2nN1Rx-1}}\RA{} \nwnotused{Dependencies1}\nwendcode{}\nwbegindocs{10}\nwdocspar 

\subsection{Dependencies for the \texttt{Mozilla} extensions} \label{subsec:DependencyMozilla} 

If the Mozilla extensions source code is provided only as an \textit{*.xpi} file, the following package must be available on the machine for use by \textit{mk-origtargz}. 

\nwenddocs{}\nwbegincode{11}\sublabel{NW4L0rPZ-2nN1Rx-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-2nN1Rx-1}}}\moddef{Dependencies5~{\nwtagstyle{}\subpageref{NW4L0rPZ-2nN1Rx-1}}}\endmoddef\nwstartdeflinemarkup\nwusesondefline{\\{NW4L0rPZ-32PlLN-1}}\nwenddeflinemarkup 
# mozilla-devscripts, zip \nwused{\\{NW4L0rPZ-32PlLN-1}}\nwendcode{}\nwbegindocs{12}\nwdocspar 

\begin{description} \item[mozilla-devscripts] \item[zip\label{item:zip}] Description like zip for the \texttt{Mozilla} extension. \end{description} 

\section{{Create the file}} \label{sec:FolderStructure} 

\subsection{Path to the projects} \label{subsec:ProjectPath} 

It makes sense to create the packaging projects each as subdirectories of a project directory. An example of this project directory is: 

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

This path is deposited in each configuration file in the variable \textit{ProjectPath}. Furthermore, this can be included in the variable \textit{DefaultProjectPath} for many projects as a default value in the file \textit{\textasciitilde/.debian\_project/DefaultValues} (chapter \ref{subsubsec:DefaultValues}, page \pageref{subsubsec:DefaultValues}).. 

\subsection{Configuration files} \label{subsec:ConfigurationFiles} 

\subsubsection{For every project} \label{subsubsec:KonfigProjekt} 

For each project an own configuration file\index{Configuration file} is created. This is stored in the home directory of the user in the directory \textit{.debian\_project/} as file \textit{<project name>}. Project-specific\index{project specific} information is stored in it. 

The configuration file\index{Configuration file} is technically a shell script, which is created and loaded by the program script. This Shell script contains variables, to which there values are assigned. The variables provided with values in the configuration file can be used by loading from the program script. 

Furthermore, the file contains comments. These can be created by the user as desired. However, some of the comments are created by the program script. These contain a property-value pair, which is structured like the assignment of a value to a variable. The technical background is that the property name contains characters that are not allowed to be used in the identifier of a variable. 

If the configuration file\index{Configuration file} exists, it is loaded first. (Chapter \ref{sec:ConfigFileLaden}, page \pageref{sec:ConfigFileLaden}. One can edit it then, if necessary. OtherwiseExists the configuration file\index{Configuration file}, so it is loaded first. (Chapter ls, this file is created by the script. (Chapter \ref{sec:ConfigFileCreate}, page \pageref{sec:ConfigFileCreate}) 

The following information is stored there: \\ 

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

\subsubsection{For many projects} \label{subsubsec:DefaultValues} 

In the \textit{\textasciitilde/.debian\_project/DefaultValues} file, variables are assigned values that apply to many projects. 

\nwenddocs{}\nwbegincode{13}\sublabel{NW4L0rPZ-3rG2Ni-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-3rG2Ni-1}}}\moddef{DefaultValues~{\nwtagstyle{}\subpageref{NW4L0rPZ-3rG2Ni-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 

HOME=/home/<user>/ DefaultProjectPath=$\{HOME\}/Projekte/Git/01_Salsa \nwnotused{DefaultValues}\nwendcode{}\nwbegindocs{14}\nwdocspar 

\subsubsection{Fingerprint of the Maintainer-Key} 

In the directory \textit{\textasciitilde/.debian\_project/} there is also a file \textit{fingerprint} which contains the fingerprint\index{Fingerprint} of the maintainer key\index{Maintainer-Key}. This key is used to sign the packets\index{sign}. (Chapter \ref{sec:GettingFingerprint}, page \pageref{sec:GettingFingerprint}) 

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

The following entries must be included in the \textit{.bashrc} file: 

\begin{verbatim} DEBFULLNAME="<Fullname of the Maintainer>" 
DEBEMAIL="<Email addressof the  Maintainers>" 
export DEBEMAIL DEBFULLNAME \end{verbatim} 

Various Debian tools recognize your email address and name using the shell environment variables \$DEBEMAIL\index{DEBEMAIL} and \$DEBFULLNAME\index{DEBFULLNAME}. \footnote{Chapter 3.1 in \cite{maint-guide}} 

These entries are read by the \textit{DEBValues} function. (Kapitel~\ref{subsec:DebNameAndEmail}, Seite~\pageref{subsec:DebNameAndEmail}) 

Also for \textit{dquilt} the file \textit{.bashrc} has to be added. (Chapter \ref{sec:QuiltEinrichtung}, page \pageref{sec:QuiltEinrichtung}) 

\section{Set up PBuilder} \label{sec:configurepbuilder} 

\textit{Gbp buildpackage} \index{gbp buildpackage} uses \textit{cowbuilder} \index{cowbuilder}. The \textit{cowbuilder} command is a wrapper for \textit{pbuilder}, which allows the use of a \textit{pbuilder}-like interface in a \textit{cowdancer} environment \index{cowdancer}. 

\subsection{\textit{Chroot}} 

The \textit{pbuilder} \index{pbuilder} package contains programs to build and maintain a \index{Chroot} \textit{chroot} environment. 

\textit{Chroot} means \textit{Change root} 

It is good practice to build \texttt{Debian} packages in a \textit{Chroot}. This is to ensure that the package can be built with the resources of the respective distribution. 

When building a \texttt{Debian} package in this \textit{Chroot} environment, the build dependencies are checked to see if they can be met. This can also avoid \index{FTBFS} FTBFS (Failed To Build From Source) errors. Under certain circumstances, however, the following error messages may still occur. 

\subsection{Configuration of the \texttt{Pbuilder}} \label{subsec:PbuilderConfiguration} 

First, the directory \textit{/var/cache/pbuilder/result} must be created. This directory must be writable for the user. After that the configuration of the \textit{pbuilder} is done. 

The configuration of \textit{pbuilder} is not completely trivial, which may make troubleshooting difficult. Therefore, we go into it in great detail here. 

The default configuration is taken from the \textit{/usr/share/pbuilder/pbuilderrc} file. 

\scriptsize

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

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

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

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

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

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

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

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

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

# Arguments for $PBUILDERSATISFYDEPENDSCMD. 
# PBUILDERSATISFYDEPENDSOPT=() 

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

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

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

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

#APT configuration files directory 
APTCONFDIR="" 

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

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

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

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

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

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

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

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

# default PKGNAME_LOGFILE 
PKGNAME_LOGFILE="" 

# default AUTOCLEANAPTCACHE 
AUTOCLEANAPTCACHE="" 

#default COMPRESSPROG 
COMPRESSPROG="gzip" 

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

These values may be overridden by values in the \textit{/etc/pbuilderrc} file if necessary. 

After a fresh install, the \textit{/etc/pbuilderrc} looks like this: 

\scriptsize

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

\end{verbatim} \normalsize

I have set these up as follows: 

\scriptsize

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

In addition to the global configuration file \textit{/etc/puilderrc}, a user-specific file \textit{\textasciitilde/.pbuilderrc} can also be created. The contents of this file override the system-wide settings. 

\scriptsize

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

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

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

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

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

\end{verbatim} \normalsize

In addition to the system-wide and user-specific configurations, package-specific configurations of the pbuilder are also required. These files can be stored in the project directory and read in with \textit{-{}-configfile <configuration file>}. This configuration will overwrite any existing values. Here then the information to the projects can be stored, if for these publications in the Backports branch are needed. This file is read after all other configuration files. 

See also page  

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

the section \textit{\#Advanced:\_Building\_multi-dependency\_packages} 

This can also be added to the \textit{\textasciitilde/.pbuilderrc} file if it exists. As MIRROR a common well accessible \texttt{Debian} mirror is specified. If available, the address of an existing local mirror can also be entered here. 

For the \textit{hook} scripts, create a directory \textit{\textasciitilde/.pbuilder/}. 

\subsection{Set up Hooks} \label{subsec:HooksEinrichten} 

\textit{Hooks} are scripts that do things at certain predefined points during the build process. With the so-called \textit{hooks} (hooks), the process in the build chroot can also be interrupted at predefined positions to still be able to manually intervene in the process. 

The \textit{Hook} scripts are located in the \textit{\textasciitilde/.pbuilder/ directory.} 

The name of the hook script determines at which point in the build process the \textit{hook} is executed. 

The following conversation applies:  

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

Here it is important to specify the path and the file name used under <i0>CI/CD</i0>. 

Unfortunately, the order in which the classes are executed in the build process does not correspond to the alphabetical order. 

\begin{description} \item[A] Is for the --build target. It is executed before the build starts. I.e. after unpacking the build system, the source code and after the build dependency has been satisfied. \item[B] Executed after the build system has successfully completed the build, before the build result is copied back. - Interrupt after successful build \item[C]Executed after a build failure, before cleanup. - Interrupt after failed build \item[D]Runs before unpacking the source inside the chroot environment, after the chroot environment is set up. Creates \$TMP and \$TMPDIR if necessary. This is called before the build dependency is satisfied. Also useful for calling apt update. - Ability to edit sources.list. <u4>[E] Runs after <i0>pbuilder --update</i0> and <i1>pbuilder --create</i1> finishes apt-get's work with the chroot, before the kernel filesystem (/proc) is umounted and the tarball is created from the chroot. <u5>[F] Is executed just before user logs in, or program starts executing, after chroot is created in --login or --execute target. <u6>[G] Is executed just after debootstrap finishes, and configuration is loaded, and pbuilder starts mounting /proc and invoking apt install in --create target. <u7>[H] Is executed just after chroot unpacks, mounting proc and any bind mount specified in BINDMOUNTS. It is run for each target that needs the unpacked chroot. It is useful if you want to dynamically change the chroot mount before anything starts using it. <u8>[I] Runs after the build system has successfully a bcompleted the build, after copying back the build results. 

\item[A] Is for the -{}-build target. It is executed before the build starts. I.e. after unpacking the build system, the source code and after the build dependency has been satisfied. \item[B] Executed after the build system has successfully completed the build, before the build result is copied back. - Interrupt after successful build \item[C]Executed after a build failure, before cleanup. - Interrupt after failed build \item[D]Runs before unpacking the source inside the chroot environment, after the chroot environment is set up. Creates \$TMP and \$TMPDIR if necessary. This is called before the build dependency is satisfied. Also useful for calling apt update. - Ability to edit sources.list. \item[E] Runs after \textit{pbuilder -{}-update} and \textit{pbuilder -{}-create} finishes apt-get's work with the chroot, before the kernel filesystem (/proc) is umounted and the tarball is created from the chroot. <u5>[F] Is executed just before user logs in, or program starts executing, after chroot is created in -{}-login or -{}-execute target. <u6>[G] Is executed just after debootstrap finishes, and configuration is loaded, and pbuilder starts mounting /proc and invoking apt install in -{}-create target. <u7>[H] Is executed just after chroot unpacks, mounting proc and any bind mount specified in BINDMOUNTS. It is run for each target that needs the unpacked chroot. It is useful if you want to dynamically change the chroot mount before anything starts using it. <u8>[I] Runs after the build system has successfully a bcompleted the build, after copying back the build results. 

\end{description} 

\subsection{Hooks - Examples} These are all in the directory: \textit{\textasciitilde/.pbuilder/} 

\subsubsection{Hook A} 

This hook could be named \textit{C10shell} for example. 

\nwenddocs{}\nwbegincode{15}\sublabel{NW4L0rPZ-3YzWY4-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-3YzWY4-1}}}\moddef{Hook-A~{\nwtagstyle{}\subpageref{NW4L0rPZ-3YzWY4-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell before build starts.  

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

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

\subsubsection{Hook B} 

This hook could be named \textit{C10shell} for example. 

\nwenddocs{}\nwbegincode{17}\sublabel{NW4L0rPZ-1Pa3Pk-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-1Pa3Pk-1}}}\moddef{Hook-B~{\nwtagstyle{}\subpageref{NW4L0rPZ-1Pa3Pk-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell if build fails. 

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

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

\subsubsection{Hook C} 

Here you can install packages that are required if the build fails. 

This hook could be named \textit{C10shell} for example. 

\nwenddocs{}\nwbegincode{19}\sublabel{NW4L0rPZ-3N4N5M-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-3N4N5M-1}}}\moddef{Hook-C~{\nwtagstyle{}\subpageref{NW4L0rPZ-3N4N5M-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell if build fails. 

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

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

\subsubsection{Hook D}  

\nwenddocs{}\nwbegincode{21}\sublabel{NW4L0rPZ-CMLwe-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-CMLwe-1}}}\moddef{Hook-D~{\nwtagstyle{}\subpageref{NW4L0rPZ-CMLwe-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell before unpacking the source 
# inside the chroot 
 

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

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

\nwnotused{Hook-D}\nwendcode{}\nwbegindocs{22}\nwdocspar 

\subsubsection{Hook E}  

\nwenddocs{}\nwbegincode{23}\sublabel{NW4L0rPZ-4gXFPs-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-4gXFPs-1}}}\moddef{Hook-E~{\nwtagstyle{}\subpageref{NW4L0rPZ-4gXFPs-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
echo "Hook E" 
echo "Please use CTRL-D to continue" 
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty 
\nwnotused{Hook-E}\nwendcode{}\nwbegindocs{24}
\nwdocspar 

\subsubsection{Hook F}  

\nwenddocs{}\nwbegincode{25}\sublabel{NW4L0rPZ-23bUkq-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-23bUkq-1}}}\moddef{Hook-F~{\nwtagstyle{}\subpageref{NW4L0rPZ-23bUkq-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
echo "Hook F" 
echo "Please use CTRL-D to continue" 
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty 
\nwnotused{Hook-F}\nwendcode{}\nwbegindocs{26}
\nwdocspar 

\subsubsection{Hook G}  

\nwenddocs{}\nwbegincode{27}\sublabel{NW4L0rPZ-2RRngG-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-2RRngG-1}}}\moddef{Hook-G~{\nwtagstyle{}\subpageref{NW4L0rPZ-2RRngG-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
echo "Hook G" 
echo "Please use CTRL-D to continue" 
/usr/bin/bash < /dev/tty > /dev/tty 2> /dev/tty 
\nwnotused{Hook-G}\nwendcode{}\nwbegindocs{28}
\nwdocspar 

\subsubsection{Hook H}  

\nwenddocs{}\nwbegincode{29}\sublabel{NW4L0rPZ-kZ17Q-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-kZ17Q-1}}}\moddef{Hook-H~{\nwtagstyle{}\subpageref{NW4L0rPZ-kZ17Q-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell if build fails. 
 

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

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

\subsubsection{Hook I}  

\nwenddocs{}\nwbegincode{31}\sublabel{NW4L0rPZ-41noFc-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-41noFc-1}}}\moddef{Hook-I~{\nwtagstyle{}\subpageref{NW4L0rPZ-41noFc-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
#!/usr/bin/bash 
# example file to be used with --hookdir 
# 
# invoke shell if build fails. 
 

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

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

\nwnotused{Hook-I}\nwendcode{}\nwbegindocs{32}\nwdocspar 

\subsection{Alternative \textit{Chroot} environment}  

It has proven useful to provide separate \textit{chroot} environments for the different \texttt{Debian} branches. 

For this a copy of the directory \textit{/var/cache/pbuilder/base.cow} is created. The file \textit{/etc/apt/sources.lists} can then be adapted accordingly. 

When updating packages, it may be necessary to update dependencies of these packages first. However, these are only available in the repo with a time delay. Here it can help for the further tests already once the line 

\small

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

in the \textit{/etc/apt/sources.lists} chroot. This makes the packages there available for building in the \textit{pbuilder} chroot. 

\section{More chroot systems} \label{sec:MoreChrootSystems} 

Besides building in an \textit{pbuilder} chroot, there are other situations where using a separate system can be useful. This is especially true for running \textit{mh\_make}. (Chapter \ref{sec:BuildWithMaven}, page \pageref{sec:BuildWithMaven}) 

This setup of a \textit{Maven chroot} is described as an example: 

First, install the \textit{debootstrap} package if it is not already present. 

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

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

After that, the \textit{root} user can start a new root directory with the \textit{chroot} command. 

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

This user \textit{root} can then no longer access files outside the new root directory. 

The chroot environment can be removed again as follows: 

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

\section{\texttt{Set up quilt} for patching} \label{sec:QuiltEinrichtung} 

With this script, \textit{dquilt} \index{dquilt} is used for patching, among other things. This is a \texttt{debian} specific customization for \textit{quilt} \index{quilt}. 

To create this customization, the file \textit{.quiltrc-dpkg} with the following content \footnote{\url{https://www.debian.org/doc/manuals/maint-guide/modify.html}} is needed: 

\nwenddocs{}\nwbegincode{33}\sublabel{NW4L0rPZ-4PTXHR-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-4PTXHR-1}}}\moddef{DQuilt~{\nwtagstyle{}\subpageref{NW4L0rPZ-4PTXHR-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
d=. ; while [ ! -d $d/debian -a `readlink -ev $d` != / ]; do d=$d/..; done 
if [ -d $d/debian ] &&[ -z $QUILT_PATCHES ]; then 
    # if in Debian package tree with unset $QUILT_PATCHES 
    QUILT_PATCHES="debian/patches" 
    QUILT_PATCH_OPTS="--reject-format=unified" 
    QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto" 
    QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
    QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;\\ 
    31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33" 
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi 
fi 
\nwnotused{DQuilt}\nwendcode{}\nwbegindocs{34}\nwdocspar 

For manual operation, this also includes the entry in the \textit{\textasciitilde/.bashrc} \index{\textasciitilde/.bashrc} file. This entry looks like this: 

\begin{verbatim} # is needed for patch tracking with Quilt 
alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg" 
complete -F -quilt-completion $_quilt_complete_opt dquilt \end{verbatim} 

Note that settings in the \textit{\textasciitilde/.bashrc} \index{\textasciitilde/.bashrc} file are ignored when this program is executed. So all necessary settings must be mapped completely in the script. 

The use of \textit{quilt} or \textit{dquilt} is described in chapter \textit{Using Quilt} (chapter \ref{sec:NutzungQuilt}, page \pageref{sec:NutzungQuilt}). 

\chapter{\texttt{Set up Git}} 

\section{Branches} 

The \texttt{Git} repository of a \texttt{Debian} package usually has at least the following branches: 

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

The branch \textit{debian/sid} can also be called \textit{master}or \textit{main}. 

There can be an additional branch for \textit{experimental}. Branches can also be created for \textit{backports} and \textit{update-proposal}. 

Such further branches can also be created by the program script. (Chapter \ref{sec:NeuenBranchErstellen}, page \pageref{sec:NeuenBranchErstellen}) 

\section{Mergen} 

If merged from \textit{debian/experimental} to \textit{debian/sid}, a fast-forward merge is usually performed. 

This is the case when - as here - further updates were initially included in \textit{} {debian/experimental} for testing, but then development is to be continued in \textit{debian/sid}. 

However, if changes have also been added to the \textit{debian/sid} branch in the meantime, only a recursive merge can be performed. 

If necessary, some customizations, e.g. in the \textit{debian/} directory must be selected individually and added to the respective branch (\textit{git cherry-pick}). 

A command line proven for this purpose is: 

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

If multiple commits are to be fed to the branch at once, the following command line applies: 

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

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

The program script uses the applications from the \texttt{Debian} package \textit{git-buildpackage}. 

\textit{git-buildpackage (gbp)} can and should be configured. 

The configuration file \textit{gbp.conf} \index{gbp.conf} is used to control this application. It can be placed at different locations in the file system. 

\subsection{Sequence} 

The configuration files for gbp are read in the following order: 

\begin{enumerate} \item /etc/git-buildpackage/gbp.conf, the system-wide configuration file \item \textasciitilde/.gbp.conf, the user specific configuration file \item debian/gbp.conf, configuration for the repository or branch \item.git/gbp.conf, configuration for the local repository \end{enumerate} 

All configuration files have the same format. \footnote{\cite{Guenther2006-2017}, section \textit{Configuration Files} and the Manpage for \textit{gbp-conf}} 

By setting the environment variable \textit{GBP\_CONF\_FILES} this order can be overridden. The content of this variable can be determined with \textit{echo \$GBP\_CONF\_FILES}. \footnote{\cite{Guenther2006-2017} Section \textit{Configuration Files/Overriding Parsing Order}}. 

\subsection{Sections in the \textit{gbp.conf}} 

There are several sections in the \textit{gbp.conf}. These sections are all optional. 

For each \textit{gbp} command\footnote{\cite{Guenther2006-2017} Manpage for \textit{gbp-conf}} a separate section can be created. In addition, there is a section that applies to all commands 

Some important sections are listed below. 

\begin{description} \item[\lbrack{}DEFAULT\rbrack{}] Options specified in this section are applied to all \textit{gbp} commands. \footnote{\cite{Guenther2006-2017} Manpage for \textit{gbp-conf}} \item[\lbrack{}import-orig\rbrack{}]The options of this section overwrite those of the section \textit{\lbrack{}DEFAULT\rbrack{}}. They are applied to the \textit{gbp import-orig} command. \item[\lbrack{}pq\rbrack{}] The options of this section are applied to the \textit{gbp pq} command and override those of section \textit{\lbrack{}DEFAULT\rbrack{}}. \item[\lbrack{}dch\rbrack{}] The options of this section are applied to the \textit{gbp dch} command and override the options of the section \textit{\lbrack{}DEFAULT\rbrack{}}. \item[\lbrack{}buildpackage\rbrack{}] The options of this section are applied to the \textit{gbp buildpackage} command and override the options of section \textit{\lbrack{}DEFAULT\rbrack{}}. \end{description} 

\subsection{Syntax of the options} 

The options in the sections of \textit{gbp.conf} are formed from the command line options. The possible options for the individual \textit{gbp} commands can be taken from the respective man page. 

These are specified without the introductory double minus sign. For example, \textit{-{}-patch-num-format=\%02d\_} as a command line option becomes \textit{patch-num-format=\%02d\_}. 

In the case of \textit{gbp buildpackage}, \textit{git-} must also be omitted\footnote{Manpage for \textit{gbp-conf}\cite{Guenther2006-2017}}. 

So the entry \textit{pbuilder-options=PBUILDER\_OPTION} in the \textit{gbp.conf} corresponds to \textit{-{}-git-pbuilder-options=PBUILDER\_OPTION}. 

\subsection{Example} In the user's home directory, a \textit{\textasciitilde/.gbp.conf} \index{gbp.conf} file can be created as follows, for example: 

\nwenddocs{}\nwbegincode{36}\sublabel{NW4L0rPZ-1yPZlk-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-1yPZlk-1}}}\moddef{gbp.conf~{\nwtagstyle{}\subpageref{NW4L0rPZ-1yPZlk-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 

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

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

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

[dch] 
id-length = 7 

# Options only affecting gbp pq 
[pq] 
#patch-numbers = False 
# The format specifier for patch number prefixes 
#patch-num-format = ' 
patch-num-format = ' 
# Whether to renumber patches when exporting patch queues 
#renumber = False 
renumber = True 
# Whether to drop patch queue after export 
#drop = False \nwnotused{gbp.conf}\nwendcode{}\nwbegindocs{37}\nwdocspar 

%04d-'%02d_'
The \textit{/etc/git-buildpackage/gbp.conf} file lists the configuration options. 

\section{\texttt{Git} repositories on own infrastructure} \label{sec:GitRepoLocal} 

\subsection{Local \texttt{Git} repository} The local Git repository is either created by the script (chapter \ref{sec:LokalesGitRepoAnlegen}, page \pageref{sec:LokalesGitRepoAnlegen}) or generated by cloning (chapter \ref{sec:ClonenBestehendesRepo}, page \pageref{sec:ClonenBestehendesRepo}). Also, it can be created with \textit{gbp import-dsc} (chapter \ref{sec:ImportPackage}, page \pageref{sec:ImportPackage}). 

More branches can be added to it (chapter \ref{sec:NeuenBranchErstellen}, page \pageref{sec:NeuenBranchErstellen}). 

\subsection{Own \texttt{Git} server} \label{subsec:EigenerGitServer} The local Git repository can also be "`mirrored'" on its own Git server. 

The setup of the server is done manually. The use of \textit{cgit} or\textit{gitweb} facilitate access. 

In the program script the name or IP of the own Git server can be entered (chapter \ref{sec:NameEigenerGitServer}, page \pageref{sec:NameEigenerGitServer}). 

The "`workflow"' is then as follows: After creating the configuration file, the name or IP of the own Git server is entered first (chapter \ref{sec:NameEigenerGitServer}, page \pageref{sec:NameEigenerGitServer}) before starting to build a new package (chapter \ref{chap:CreateNewProject}, page \pageref{chap:CreateNewProject}). 

The "`finished'" package can then be uploaded to your own Git server (chapter \ref{sec:HochladenEigenerGitServer}, page \pageref{sec:HochladenEigenerGitServer}). 

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

\textsl{Salsa} is the name of a collaborative development server for \texttt{Debian}, based on the \texttt{GitLab} software. \textsl{Salsa} is intended to provide the necessary tools for collaborative development for package maintainers, packaging teams, and other Debian-related individuals and groups.\cite{Salsa2023} 

\textsl{Salsa} provides all the features of \texttt{GitLab}. The service is available at \url{https://salsa.debian.org}. There is documentation of the debian-specific idiosyncrasies \cite{SalsaDoc2023}, which you should familiarize yourself with first. 

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

Creating an account on \textsl{Salsa} is very simple. One calls the page \url{https://salsa.debian.org/users/sign_up}, which is self-explanatory. 

\section{Creation of a \textsl{Salsa}-Repository} \label{sec:ManuelleAnlage} 

A \texttt{Git} repository on \textit{salsa.debian.org} is not set up by the program script. 

After login and authentication to <i0>https://salsa.debian.org</i0>, a new repository can be created there in the respective team. 

For the creation of new projects on \url{https://salsa.debian.org } appropriate rights are required. These can be the rights of a \texttt{Debian Developer}. For team-supervised projects, these rights can also be assigned to other persons by the supervisors. 

A description of the creation of a project in the Java team is given in chapter \ref{sec:JavaTeam}, page \pageref{sec:JavaTeam}. 

After logging in to the \url{https://salsa.debian.org} page and selecting the appropriate project for the new package, clicking on the \textit{New Project} button calls the corresponding page. There you enter the project name. This is usually the name of the source code package. As visibility level \textit{Public} is selected. Then the button \textit{Create project} follows. 

On the following web page there are some more explanations. Much of it is first created locally with the program described. 

In the left navigation bar, in the \textit{Settings} area, further configurations are now made for the project. 

Here it is important to specify the path and the file name used under \textit{CI/CD}. 

\begin{description} \item[\textit{CI}] stands for Continuous Integration \item[\textit{CD}] stands for Continuous Delivery \end{description} 

The file used here is called \textit{salsa-ci.yml} (chapter \ref{subsec:SalsaCi}, page \pageref{subsec:SalsaCi}) in the \textit{debian/} directory. 

The build script enters the salsa repository as "`remote repository'" and reminds the user to attach to \textsf{salsa.debian.org} (chapter \ref{subsec:SalsaRepoAnlegen}, page \pageref{subsec:SalsaRepoAnlegen}) 

\section{\textsl{Salsa}-repository for the \texttt{Java} team} \label{sec:JavaTeam} 

\textsl{Salsa} repositories that are assigned to a special project (such as the \texttt{Java} team) should be created as uniformly as possible. Often a script is provided by the project, which should be used for this purpose. 

To do this, change to the desired team directory. 

\begin{figure}[h] \centering

\includegraphics[width=30em,height=30ex]{Pictures/SalsaJavaMaintainers.png} \caption{Information about \texttt{Java}-Team\protect\footnote{Source:\url{https://salsa.debian.org/java-team/}}}. \end{figure} 

\subsection{Source of the Script} 

Under 

\footnotesize

\url{https://salsa.debian.org/java-team/pkg-java-scripts/ blob/master/setup-salsa-repository} \normalsize

the script of the \textit{Java team} can be downloaded. It is also attached in the appendix (chapter \ref{sec:CreateJavaTeam}, page \pageref{sec:CreateJavaTeam}). 

\subsection{Dependencies} 

This \textit{setup script} uses \textit{jq}. \textit{jq} is a lightweight and flexible \textit{JSON} processor for the command line. It has minimal runtime dependencies. There is a \texttt{Debian} package of the same name. This package must be installed locally (chapter \ref{subsec:DependencyJava}, page \pageref{subsec:DependencyJava}). 

\subsection{Get access token} 

A project specific token\index{Access tokens} is still needed for the customization. 

After logging in to \textit{salsa.debian.org}, \textit{Preferences} is selected from the user's dropdown menu. This will bring up the logged in user's \textit{User Preferences} page. 

In the left bar there is now the entry \textit{access token}. There the page \textit{https://salsa.debian.org/profile/personal\_access\_tokens} is called to create such a token. It is generated anew for each project. 

\begin{figure}[h] \centering

\includegraphics[width=10em,height=45ex]{Pictures/AccessToken.png} \caption{Create access token\protect\footnote{Source:\url{https://salsa.debian.org}}} \end{figure} 

There the name of the project to be created is entered. Furthermore, an expiration date for the token is entered. Afterwards the validity range of the token is specified. As \textit{Scope} \textit{api} is to be selected here. By clicking on the \textit{Create personal access token} button, the access token appears at the top of the page. 

\subsection{Register token} 

The generated token is to be entered into the script as \textit{SALSA\_TOKEN}. The comment character is to be removed 

It seems to make sense to store this script in the project directory in each case. 

\subsection{Call script} 

The script is now called with the name of the new project (package) as parameter: 

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

After that the following messages are output (using the BeanValidationApi example): 

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

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

If only the first line appears, check the script used (see chapter \ref{sec:CreateJavaTeam}, page \pageref{sec:CreateJavaTeam}) and tokens. 

\section{Tasks on \textit{salsa.debian.org}} 

\subsection{Merge Request} 

Sometimes there are also so-called merge requests, in which others provide patches. 

On \textit{salsa.debian.org} there is then an entry "`Merge-Requests"' in the left navigation bar. There this can then be edited. 

This is done by clicking the commit message. 

\chapter{Packaging beyond the branch \textit{Unstable}} \label{chap:JenseitsUnstable} 

There are several reasons why it is allowed and encouraged to deviate from the general way of packaging new upstream versions exclusively for \textit{Unstable = sid}. The program script also allows this (chapter \ref{chap:BuildBeyondSid}, page \pageref{chap:BuildBeyondSid}). 

The developer reference \cite{Debian-Entwicklerreferenz} refers to uploading to the \textit{Stable} and \textit{Oldstable} distributions as a "`special case'". \footnote{Chapter 5.5.1 in the Developer Reference\cite{Debian-Entwicklerreferenz}} 

A major reason is the presence of a serious error or a security problem. Serious errors in a package are usually reported by an appropriately classified error report. 

Another deviation from the general rule exists regarding the packages of the \texttt{Mozilla} suite, \texttt{Firefox} and \texttt{Thunderbird}. These packages will also be made available as \textit{Security Updates} (chapter \ref{sec:SecurityUpdates}, page \pageref{sec:SecurityUpdates}) for the \textit{Stable} release promptly after their upstream release for the \textit{ESR = Extended Support Release} version. 

This can result in incompatibilities with the then current version in the \textit{Stable} release, e.g. for the extensions, described here as a web extension (chapter \ref{chap:WebextBauen}, page \pageref{chap:WebextBauen}). This is also a reason to update the \textit{Stable} release (see also chapter \ref{sec:StableProposal}, page \pageref{sec:StableProposal}). 

In addition, it is often desirable to use more up-to-date versions of desktop applications in a stable operating system environment. For this purpose, the desired packages are made available as so-called \textit{backports} (i.e. backports). (see chapter \ref{sec:StableBackports}, page \pageref{sec:StableBackports}) 

There are also good reasons to upload packages to \textit{Experimental} (also called \textit{rc-buggy}) first. This is especially true for new packages. During the period when existing versions are "`frozen'" and only bug fixes are allowed for the next release, new versions are often uploaded in advance to \textit{Experimental}. (see chapter \ref{sec:Experimental}, page \pageref{sec:Experimental}). 

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

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

It is important to backport\index{Backporting} changes to source code files because of security issues\index{Security Patches}. 

Whenever a security issue becomes known, the maintainer should work with the security team\index{Security-Team} to provide a corrected version for the \textit{Stable} or \textit{Oldstable} release. The bug fix should be targeted. Further information can be found in the chapters \href{https://www.debian.org/doc/manuals/developers-reference/developer-duties.de.html#maintain-packages-in-stable}{3.1.2} and \href{https://www.debian.org/doc/manuals/developers-reference/pkgs.de.html#bug-security}{5.8.5} of the \texttt{Debian} Developer Reference\cite{Debian-Entwicklerreferenz}. 

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

If packages with serious bugs that do not affect IT security are to be updated, this can be done in \textit{Proposed updates}\index{Proposed-Updates} under certain conditions. The same applies with regard to extensions for \texttt{Firefox} and \texttt{Thunderbird}. 

The following have been mentioned as criteria for adding packages to \textit{stable-updates} \footnote{\url{https://lists.debian.org/debian-devel-announce/2011/03/msg00010.html}}: 

\begin{itemize}\itemsep2pt 

\item The update is urgent and not security relevant. The security updates are done in the way mentioned above (chapter \ref{sec:SecurityUpdates}, page \pageref{sec:SecurityUpdates}). 

\item The package in question is a data package, and the data must be updated in a timely manner (e.g., tzdata). 

\item Corrections to packages that are affected by external changes and on which no other or only a few other packages depend. 

\item Packages that need to be up to date to be useful (e.g. clamav). 

\end{itemize} 

Anyone who believes that the requested update meets these criteria should confidentially contact the release team via the debian-release@lists.debian.org mailing list, and explain that this update should also be done via \textit{stable-updates}. 

The package intended for backporting this way should have already been released in \textit{Unstable} or better yet in \textit{Testing}. 

While backports are collected in a separate repository, \textit{Proposed updates} are added to the \textit{Stable} Proposed repository. These packages are uploaded to \textit{Stable} by the \texttt{Debian} developers. This applies to oldstable-proposed updates accordingly. They will be published in the next point release. 

\subsection{Bug report} 

A necessary prerequisite is also here first a meaningful error report (bug report) (see also chapter \ref{chap:StartEMail}, page \pageref{chap:StartEMail}). 

This error report requires the following parameters: 

\begin{verbatim} Package: release.debian.org 
Severity: normal 
Tags: <ReleaseName> 
User: release.debian.org@packages.debian.org 
Usertags: pu
 \end{verbatim} 

This bug report is generated against the \textit{release.debian.org} pseudo package. The severity of such a bug report is generally at most \textit{normal}. The subject will list the name of the package being built for \textit{proposed-updates}. 

\textit{Proposed updates}\index{Proposed-Updates} are only allowed under special circumstances, as outlined. The \textit{Release Team}\index{Release-Team} will decide whether to release. 

Therefore, the bug report must contain a reason why this version should be updated in \textit{stable}. If there is already an associated bug number, it must be provided. This bug report \textbf{must} have a severity of \textit{important} or higher. 

\subsection{Requirements for a patch} 

It should be possible to fix an error with a patch that is as small and accurate as possible. This is to prevent new errors from arising. Also, no new dependencies should be added. It must also be taken into account which other packages depend on this package. \footnote{Chapter 5.5.1 in the Developer Reference\cite{Debian-Entwicklerreferenz}} 

These matching patches are documented with \textit{debdiff <PreviousPackage>.dsc <NewPackage>.dsc > <filename>.txt}. It specifies the difference that should be made between the current package version in stable/oldstable (previous package) and the version that should be uploaded (new package). How to do this with the program script is described in chapter \ref{subsec:debdiff} (page \pageref{subsec:debdiff}). 

\subsection{Dependencies for \texttt{Mozilla} packages} 

A sufficient justification for \textit{Webextensions} may also be the exception for the packages of the \texttt{Mozilla} suite mentioned above (see chapter \ref{chap:JenseitsUnstable}, page \pageref{chap:JenseitsUnstable}). 

For these extensions namely incompatibilities with the then current version of \texttt{Firefox} or\texttt{Thunderbird} in the \textit{Stable} release can arise. Then the previous versions are unusable, which is a considerable problem, especially in production use. (Chapter \ref{chap:BuildBeyondSid}, page \pageref{chap:BuildBeyondSid}) 

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

To be able to build packages for backports, some preparations have to be made. 

Often such a package cannot be easily built in an \textit{} {Stable} environment. 

Then further packages from backports are needed. Packages from backports are not automatically installed in such a \textit{chroot}. 

Therefore it is necessary to enable such an installation in \textit{/etc/apt/preferences}. 

For this purpose \textit{hooks} are used in the \textit{pbuilder} (chapter \ref{subsec:HooksEinrichten}, page \pageref{subsec:HooksEinrichten}). 

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

\section{Backports-Repository} 

The packages for the unstable branch are built regularly, and from there - provided no errors are found - they are transferred to the testing branch. On release, the testing branch is first frozen and then becomes the new stable branch. A new testing branch is then opened. 

If program versions from \textit{testing} or (exceptionally \footnote{usually only security updates}) also from \textit{unstable} are transferred to an earlier release, this is called \textit{backporting}. 

Due to the practice oriented release cycles of the stable Debian version, it is sometimes desirable to have software packages or newer versions from testing also available under stable. 

The backports repository is used for this purpose. 

Versioning (e.g. +deb9u1) 

Backports are available for the stable and oldstable release. 

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

\section{Backporting of unfamiliar packages} pristine-tar NMU Dependencies from Backports 

Reference to (Chapter \ref{chap:BauenBackports}, Page \pageref{chap:BauenBackports}) \footnote{\cite{Debian-Entwicklerreferenz} Section \textit{upload-stable}} for release after \textit{Proposed updates} for \textit{Stable} or \textit{Old-Stable}. 

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

The cause or origin of the upgrade also affects the versioning. It must be ensured that \textit{dpkg} can correctly interpret newer versions as upgrades. A look at the next expected version number can help.. 

When building for \textit{experimental}, the following version entry is recommended in the file \textit{debian/changelog}: 

<version number>-<revision number>\textasciitilde exp<sequential number> 

The revision number is usually: 1 

When building for \textit{Proposed updates}, there are two cases to distinguish.. 

\begin{description} \item[Case A] A version existing in the \textit{Stable} release is to be corrected while retaining this version number. 

\item[Case B] Exceptionally, a new version is to be included in the release. 

For the version entry in \textit{debian/changelog} it is mandatory to use the following nomenclature: 

\item[Case A] <original version and revision number> +deb<Debian release number>u<revision number of the update> 

\item[Case B] <version and revision number from unstable/testing>\textasciitilde deb<De\-bi\-an release number>u<revision number of update>. 

Using the \textasciitilde causes the version in Stable to be smaller than the one in Testing (for the next release). This secures the update path. 

\end{description} 

\chapter{An email for the start} \label{chap:StartEMail} 

Before packaging with the goal of publishing in the \texttt{Debian} repository can begin, an email is required. This triggers a "`bugreport'", whose number is to be noted in the file \textit{debian/changelog}. By the publication of the package this bug report is to be closed namely then. 

For more information, visit \url{https://www.debian.org/devel/wnpp/} 

\section{ITP - Intent To Package} 

\textit{ITP} means "`Intent to Package"'. This means that this package is being worked on. 

This is the name of a bug report created against the \textit{WNPP} package, which means \textit{Work-Needing and Prospective Package}. This can be translated as \textit{Work-Needing and Prospective Package}. 

This should be announced in good time. Maybe there are still hints what to consider with the planned package. Also, this prevents different groups from trying to package this package for \texttt{Debian}. 

One possibility is to do this with the \texttt{reportbug} tool installed on every Debian system. But there is also the possibility to simply use an email template. The following template is based on the \textit{itp\_template} with which \textit{reportbug} creates this email. 

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

* Package name : <Package Name> 
Version : x.y.z 
Upstream Author : Name <somebody@example.org> 

* URL : http://www.example.org/ 
* License : (GPL, LGPL, BSD, MIT/X, etc.) 
Programming Lang: (C, C++, C#, Perl, Python, etc.) 
Description : <Short Description> 

(Include the long description here.) 

<And answer following questions:> 

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

\end{verbatim} 

The text in the first line after the \textit{To:} goes in the address line. The text in the second line after the \textit{Subject:} goes in the subject line, with the placeholders replaced by the name of the source code and a short description. 

If the package is uploaded, this number from the bug tracking system must be noted in the \textit{debian/changelog} (Closes:\#XXXXXXXX) 

\section{RFP - Request For Package} \textit{RFP} means \textit{Request for Package}. This means that such a package is desired in \texttt{Debian}. 

I once created an email template for this as well. 

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

* Package name : <Package Name> 
Version : x.y.z 
Upstream Author : Name <somebody@example.org> 

* URL : http://www.example.org/ 
* License : (GPL, LGPL, BSD, MIT/X, etc.) 
Programming Lang: (C, C++, C#, Perl, Python, etc.) 
Description : <Short Description> 

(Include the long description here.) 

<And answer following questions:> 

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

Again, the text in the first line after the \textit{To:} goes in the address line. The text in the second line after the \textit{Subject:} goes in the subject line, with the placeholders replaced by the name of the source code and a short description. 

\section{ITA - Intent To Adoption} This is used when a package that is marked with "`O"' or "`RFA"' is to be taken over. 

For this purpose, the previous error report must be renamed and "`O"' or "`RFA"' must be replaced by "`ITA"'. 

In doing so, you enter yourself as the owner. 

If a bug report is to be renamed or the owner changed, this must be done by email to \textit{control@bugs.debian.org} or directly to the bug report via the number (xxxxxx@bugs.debian.org)\footnote{\url{https://www.debian.org/devel/wnpp/}}. 

A structured \textit{pseudo header} must be used. \footnote{\url{https://www.debian.org/Bugs/Reporting\#control}} 

\section{RFA - Request for Adoption} 

\section{RFH - Request For Help} 

\section{O - Orphaned} 

\section{RFS - Request For Sponsor} 

As described on \url{https://mentors.debian.net/sponsor/rfs-howto}, the template was adjusted. 

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

Dear mentors, 

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

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

It builds those binary packages: 

<Name of the Binaries> 

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

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

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

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

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

Regards, 

\end{verbatim} 

\section{Changes to the bug report} 

In the course of such a process it may happen that changes have to be made to the bug report. Such a change can be a change of the maintainer, the title or something else. 

For this purpose the commands of the \textit{control email server} are used. The description of this can be found at \url{https://www.debian.org/Bugs/server-control} 

This can also be done with a defined structured email. It will be sent to \textit{control@bugs.debian.org}. The subject should be 

For the change of the title, an additional line is then added as follows. 

\begin{verbatim} Control: retitle -1 <neuer Titel> \end{verbatim} 

added. 

The following line is added for the maintainer change: 

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

If necessary, an erroneously closed report must be reopened. This is done with 

\begin{verbatim} Control: reopen bugnumber [ address of the author | = | ! ] \end{verbatim} 

\section{\textit{usertags} added} 

In the course of a maintainer's life it happens again and again that error messages must or should be tagged. 

For example, it is helpful for so-called \textit{bug squashing parties} to also mark the planned and executed bug fixes. 

For this, an email is written to the bug report. Address is then \textit{<bugnumber>\@debian.org}. At the same time this mail should also go \textit{CC} to \textit{control\@bugs.debian.org}. 

At the beginning of such an e-mail is then: 

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

\chapter{Set up report bug} 

The Comand-Line interface is already part of the basic installation. In addition, a graphical user interface can be installed with the package \textit{reportbug-gtk}. 

\chapter{Autopkgtest} 

\chapter{Reproducible builds} \label{chap:ReproducibleBuilds} 

\section{Configuration of \textit{sbuild}} \label{sec:confFileSBuild} 

After installing the required packages: 

\begin{verbatim} sudo apt install sbuild schroot debootstrap apt-cacher-ng devscripts \end{verbatim} 

the configuration file \textit{sbuild} is created\cite{SBuild2022}. 

This is done by copying the following section to the \textasciitilde/.sbuildrc file. These settings make it possible to avoid long command line options for typical workflows and run all tests after build. 

\nwenddocs{}\nwbegincode{38}\sublabel{NW4L0rPZ-3L4ZKJ-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-3L4ZKJ-1}}}\moddef{.sbuild.rc~{\nwtagstyle{}\subpageref{NW4L0rPZ-3L4ZKJ-1}}}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup 
############################################################################## 
# PACKAGE BUILD RELATED (additionally produce _source.changes) 
############################################################################## 
# -d 
$distribution = 'unstable'; 
# -A 
$build_arch_all = 1; 
# -s 
$build_source = 1; 
# --source-only-changes (applicable for dput. irrelevant for dgit push-source). 
$source_only_changes = 1; 
# -v 
$verbose = 1; 
\LA{}.sbuild.rc5~{\nwtagstyle{}\subpageref{NW4L0rPZ-24PwVH-1}}\RA{} \nwnotused{.sbuild.rc}\nwendcode{}\nwbegindocs{39}\nwdocspar 

Adapt parallel=5 to the resources of your system. 

\nwenddocs{}\nwbegincode{40}\sublabel{NW4L0rPZ-24PwVH-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-24PwVH-1}}}\moddef{.sbuild.rc5~{\nwtagstyle{}\subpageref{NW4L0rPZ-24PwVH-1}}}\endmoddef\nwstartdeflinemarkup\nwusesondefline{\\{NW4L0rPZ-3L4ZKJ-1}}\nwenddeflinemarkup 
# parallel build 
$ENV\{'DEB_BUILD_OPTIONS'\} = 'parallel=5'; 
\LA{}.sbuild.rc6~{\nwtagstyle{}\subpageref{NW4L0rPZ-4f4u7n-1}}\RA{} \nwused{\\{NW4L0rPZ-3L4ZKJ-1}}\nwendcode{}\nwbegindocs{41}\nwdocspar 

If instead the variable \$run\_lintian is set to 0, the execution of lintian is disabled. 

Any post-build package test function can be turned off by setting the corresponding variable to 0. 

\nwenddocs{}\nwbegincode{42}\sublabel{NW4L0rPZ-4f4u7n-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-4f4u7n-1}}}\moddef{.sbuild.rc6~{\nwtagstyle{}\subpageref{NW4L0rPZ-4f4u7n-1}}}\endmoddef\nwstartdeflinemarkup\nwusesondefline{\\{NW4L0rPZ-24PwVH-1}}\nwenddeflinemarkup 
############################################################################## 
# POST-BUILD RELATED (turn off functionality by setting variables to 0) 
############################################################################## 
$run_lintian = 1; 
$lintian_opts = ['-i', '-I']; 
\LA{}.sbuild.rc7~{\nwtagstyle{}\subpageref{NW4L0rPZ-DAnh5-1}}\RA{} \nwused{\\{NW4L0rPZ-24PwVH-1}}\nwendcode{}\nwbegindocs{43}\nwdocspar 

If the variable \$run\_piuparts is set to 0, the execution of piuparts is disabled. 

\nwenddocs{}\nwbegincode{44}\sublabel{NW4L0rPZ-DAnh5-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-DAnh5-1}}}\moddef{.sbuild.rc7~{\nwtagstyle{}\subpageref{NW4L0rPZ-DAnh5-1}}}\endmoddef\nwstartdeflinemarkup\nwusesondefline{\\{NW4L0rPZ-4f4u7n-1}}\nwenddeflinemarkup 
$run_piuparts = 1; 
$piuparts_opts = ['--schroot', 'unstable-amd64-sbuild'];
\LA{}.sbuild.rc8~{\nwtagstyle{}\subpageref{NW4L0rPZ-34itYR-1}}\RA{} \nwused{\\{NW4L0rPZ-4f4u7n-1}}\nwendcode{}\nwbegindocs{45}\nwdocspar 

The \textit{'-{}-no-eatmydata'} option for piuparts is needed when configuring \textit{schroot} with "command-prefix=eatmydata" in \textit{/etc/schroot/chroot.d/unstable-amd64-sbuild-*}. Then it must be added at the end -- after a comma. 

If you set the \$run\_autopkgtest variable to 0 instead, autopkgtest execution is disabled. 

\nwenddocs{}\nwbegincode{45}\sublabel{NW4L0rPZ-34itYR-1}\nwmargintag{{\nwtagstyle{}\subpageref{NW4L0rPZ-34itYR-1}}}\moddef{.sbuild.rc8~{\nwtagstyle{}\subpageref{NW4L0rPZ-34itYR-1}}}\endmoddef\nwstartdeflinemarkup\nwusesondefline{\\{NW4L0rPZ-DAnh5-1}}\nwenddeflinemarkup 
$run_autopkgtest = 1; 
$autopkgtest_root_args = ''; 
$autopkgtest_opts = [ '--', 'schroot', '\%r-\%a-sbuild’ ]; 

%r-%a-sbuild' ];
############################################################################## # PERL MAGIC ############################################################################## 1; 

\nwused{\\{NW4L0rPZ-DAnh5-1}}\nwendcode{} 

\nwixlogsorted{c}{{.sbuild.rc}{NW4L0rPZ-3L4ZKJ-1}{\nwixd{NW4L0rPZ-3L4ZKJ-1}}} \nwixlogsorted{c}{{.sbuild.rc5}{NW4L0rPZ-24PwVH-1}{\nwixu{NW4L0rPZ-3L4ZKJ-1}\nwixd{NW4L0rPZ-24PwVH-1}}} \nwixlogsorted{c}{{.sbuild.rc6}{NW4L0rPZ-4f4u7n-1}{\nwixu{NW4L0rPZ-24PwVH-1}\nwixd{NW4L0rPZ-4f4u7n-1}}} \nwixlogsorted{c}{{.sbuild.rc7}{NW4L0rPZ-DAnh5-1}{\nwixu{NW4L0rPZ-4f4u7n-1}\nwixd{NW4L0rPZ-DAnh5-1}}} \nwixlogsorted{c}{{.sbuild.rc8}{NW4L0rPZ-34itYR-1}{\nwixu{NW4L0rPZ-DAnh5-1}\nwixd{NW4L0rPZ-34itYR-1}}} \nwixlogsorted{c}{{debian/JavaPackage.poms}{NW4L0rPZ-1QcqCZ-1}{\nwixd{NW4L0rPZ-1QcqCZ-1}}} \nwixlogsorted{c}{{DefaultValues}{NW4L0rPZ-3rG2Ni-1}{\nwixd{NW4L0rPZ-3rG2Ni-1}}} \nwixlogsorted{c}{{Dependencies1}{NW4L0rPZ-32PlLN-1}{\nwixd{NW4L0rPZ-32PlLN-1}}} \nwixlogsorted{c}{{Dependencies5}{NW4L0rPZ-2nN1Rx-1}{\nwixu{NW4L0rPZ-32PlLN-1}\nwixd{NW4L0rPZ-2nN1Rx-1}}} \nwixlogsorted{c}{{DQuilt}{NW4L0rPZ-4PTXHR-1}{\nwixd{NW4L0rPZ-4PTXHR-1}}} \nwixlogsorted{c}{{gbp.conf}{NW4L0rPZ-1yPZlk-1}{\nwixd{NW4L0rPZ-1yPZlk-1}}} \nwixlogsorted{c}{{Hook-A}{NW4L0rPZ-3YzWY4-1}{\nwixd{NW4L0rPZ-3YzWY4-1}}} \nwixlogsorted{c}{{Hook-B}{NW4L0rPZ-1Pa3Pk-1}{\nwixd{NW4L0rPZ-1Pa3Pk-1}}} \nwixlogsorted{c}{{Hook-C}{NW4L0rPZ-3N4N5M-1}{\nwixd{NW4L0rPZ-3N4N5M-1}}} \nwixlogsorted{c}{{Hook-D}{NW4L0rPZ-CMLwe-1}{\nwixd{NW4L0rPZ-CMLwe-1}}} \nwixlogsorted{c}{{Hook-E}{NW4L0rPZ-4gXFPs-1}{\nwixd{NW4L0rPZ-4gXFPs-1}}} \nwixlogsorted{c}{{Hook-F}{NW4L0rPZ-23bUkq-1}{\nwixd{NW4L0rPZ-23bUkq-1}}} \nwixlogsorted{c}{{Hook-G}{NW4L0rPZ-2RRngG-1}{\nwixd{NW4L0rPZ-2RRngG-1}}} \nwixlogsorted{c}{{Hook-H}{NW4L0rPZ-kZ17Q-1}{\nwixd{NW4L0rPZ-kZ17Q-1}}} \nwixlogsorted{c}{{Hook-I}{NW4L0rPZ-41noFc-1}{\nwixd{NW4L0rPZ-41noFc-1}}} \nwixlogsorted{c}{{java-builds}{NW4L0rPZ-3WCS5x-1}{\nwixd{NW4L0rPZ-3WCS5x-1}}} \nwixlogsorted{c}{{maven-build}{NW4L0rPZ-2txdMG-1}{\nwixd{NW4L0rPZ-2txdMG-1}}} \nwixlogsorted{c}{{watch4xpi}{NW4L0rPZ-2sH2Wp-1}{\nwixd{NW4L0rPZ-2sH2Wp-1}}} \nwbegindocs{46}\nwdocspar 

%%%%%%%%%%%%%%%%%%%%%%%
For more options, see the sbuild.conf man page. 

Besides this, the user must be set up with 

\begin{verbatim} sudo sbuild-adduser \$LOGNAME \end{verbatim} 

n the \textit{sbuild} group. This will add your username so that it can use the \textit{sbuild} command. 

The following message appears after the user is set up: 

\begin{verbatim} Now try a build: 

cd /path/to/source sbuild-update -ud <distribution> (or "sbuild-apt <distribution> apt-get -f install" first if the chroot is broken) sbuild -d <distribution> <package>_<version> \end{verbatim} 

This means that \textit{sbuild-adduser} copies the \textit{sbuild} template configuration in /usr/share/doc/sbuild/examples/example.sbuildrc to each user's \textit{\textasciitilde/.sbuildrc} to use as the \textit{sbuild} configuration for that user. The \textit{sbuild} settings can be customized here. Usually, however, no adjustments are necessary. If they are, they should be done once per user. 

The creation of the \texttt{Sbuild} chroot is described in chapter \ref{subsec:CreateSchroot} (page \pageref{subsec:CreateSchroot}). 

\section{reprotest} 

\chapter{piuparts} 

\chapter{Overcome difficulties} 

\section{Unfreeze a package} 

One difficulty arises from the fact that there is a period of time before a scheduled release when packages no longer automatically migrate from \textit{unstable} to \textit{testing}. 

In the full `freeze', all packages that are yet to migrate from \textit{unstable} to \textit{testing} require an unblock by the release team.\cite{Release-Team2021}. This must be requested with an \textit{unblock bugreport}. 

\subsection{Request for unblocking} 

To do this, first create a file with \textit{debdiff} (see also chapter \ref{sec:StableProposal}, page \pageref{sec:StableProposal}). 

This creates the difference between the version in \textit{testing} (old version) and \textit{Unstable} (new version) with the respective \textit{dsc}. 

This difference file should be checked to make sure that it does not have any unimportant changes for the desired fix. 

Then, using the \textit{reportbug} tool, a bug report is generated against the \textit{release.debian.org} package and the difference file is attached. This bug report contains a detailed justification for the changes and references to bug numbers. Likewise, it contains a concise description of the problem that was fixed. 

The following questions should be addressed. 

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

Please unblock package <source name> 

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

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

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

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

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

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

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

\section{Fix release critical bugs} 

Before a new release, it is often necessary to help maintainers fix bugs that prevent the package from being released. 

This often happens at events organized for this purpose \footnote{\url{https://wiki.debian.org/BSP}}. 

Under \url{https://www.debian.org/doc/manuals/developers-reference/pkgs.html#non-maintainer-uploads-nmus} the desired procedure is described. 

It is essential that in the file \textit{debian/changelog} ( chapter \ref{sec:DebianChangelog}, page \pageref{sec:DebianChangelog} a corresponding entry is made in the second line. 

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

\section{Remove package from repository} 

The developer reference \footnote{\cite{Debian-Entwicklerreferenz}, Section 5.9 Remove packages} also describes how to remove a package. 

To do this, it must first be determined that no other package requires this as a depídency. 

\subsection{} 

A bug report must now be generated for the execution. \nwenddocs{} 