%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  Copyright (C) 2010-2012  Pietro Abate <pietro.abate@pps.jussieu.fr>   %
%                           Ralf Treinen <ralf.treinen@pps.jussieu.fr>   %
%                           Unversité Paris-Diderot                      %
%                                                                        %
%  This documentation is free software: you can redistribute it and/or   %
%  modify it under the terms of the GNU General Public License as        %
%  published by the Free Software Foundation, either version 3 of the    %
%  License, or (at your option) any later version.                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Input Data: Packages and Repositories}
\label{sec:data}
\subsection{Packages}
\label{sec:packages}
Debian control stanzas are defined in \texttt{deb-control~(5)}. For
\debcheck{} only the following fields are relevant, all others are
ignored:
\begin{description}
\item[Package] giving the package name. \debcheck{} is more liberal as
  to which package names are acceptable, for instance it allows a
  slightly larger character set than the debian policy for
  constituting names. Required.
\item[Version] giving the version of the package. The version must be
  in conformance with the Debian policy. Required.
\item[Architecture] specifying the architectures on which the package
  may be installed. Required.
\item[Multiarch] specifies whether the package may be installed
  simultaneously for different architectures, and whether it may
  satisfy dependencies across architecture boundaries. Values may be
  \texttt{No}, \texttt{Same}, \texttt{Foreign}, or \texttt{Allowed}
  (\cite{ubuntu:multiarch}). Optional, defaults to \texttt{No}.
\item[Depends] is a list of items required for the installation of
  this package. Each item is a package name optionally with a version
  constraint, or a disjunction of these.  Items may also be annotated
  with \texttt{:any}. Optional, defaults to the empty list.
\item[Pre-Depends] are by \debcheck{} treated like Depends.
\item[Conflicts] is a list of package names, possibly with a version
  constraint, that cannot be installed together with the package. Optional,
  defaults to the empty list.
\item[Breaks] are by \debcheck{} treated like Conflicts.
\item[Provides] is a list of names symbolizing functionalities
  realized by the package. They have to be taken into account for
  dependencies and conflicts of other packages, see
  Section~\ref{sec:installability}. Optional, defaults to the empty
  list.
\item[Essential] specifies whether the package must be installed
  (\texttt{yes} or \texttt{no}). Optional, defaults to \texttt{no}.
\end{description}

In particular, \texttt{Recommends} and \texttt{Suggests} are ignored
by \debcheck. Also, \debcheck{} does not check for the presence of
fields that are required by Debian policy but that are not relevant
for the task of \debcheck, like \texttt{Maintainer} or
\texttt{Description}.

Also note that \debcheck{} is slightly more liberal than the Debian
policy in accepting input, and hence cannot be used to check strict
policy conformance of package stanzas.

\subsection{Repositories}
\label{sec:repositories}
A \emph{repository} is a set of package stanzas. This set may be given
to \debcheck{} in form of a single file or as several files, in the
latter case the repository is constituted by all stanzas in all input
files (see Section~\ref{sec:invocation}). \debcheck{} assures that the
repositories has two important properties:

\begin{enumerate}
\item
  We assume that there are no two package stanzas in the repository
  that have the same values of all three fields \texttt{Package},
  \texttt{Version}, and \texttt{Architecture}. Having different
  versions for the same package name is OK, as it is of course OK to
  have two stanzas with different package names and the same version.
  In other words, the \debcheck{} tool uses internally the triple of
  name, architecture and version as an identifier for packages.

  In the following, when we speak of \emph{a package}, we mean a
  precise package stanza that is identified by a name, a version, and
  an architecture, like the package of name \texttt{gcc} in version
  \texttt{4:4.3.2-2} and for architecture \texttt{amd64}. The stanza with name
  \texttt{gcc} and version \texttt{4:4.4.4-2} for architecture
  \texttt{amd64} would constitute a different package.

  If the input contains several stanzas with the same name, version
  and architecture then all but the last such stanza are dropped, and a 
  warning message is issued.

\begin{example} The following input does not constitute a repository:
\begin{verbatim}
Package: abc
Version: 42
Architecture: amd64
Depends: xyz

Package: abc
Version: 42
Architecture: amd64
Depends: pqr
\end{verbatim}
The reason is that the triple $(abc,42,amd64)$ is not
unique. \debcheck{} will warn us that it only accepts the second
stanza and drops the first one from its input:
\begin{verbatim}
(W)Debian: the input contains two packages with the same name, version and architecture (abc,42,amd64). Only the latter will be considered.
\end{verbatim}
\end{example}

\item
  We assume that Multiarch information is consistent: If the
  repository contains packages with the same name and version and
  different architecture then both packages have to agree on the value
  of their \texttt{Multiarch} field.

\end{enumerate}


