%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  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{Invocation}
\label{sec:invocation}

\subsection{Basic usage}

\debcheck{} accepts several different options, and also arguments.

\begin{alltt}
  \debcheck{} [option] ... [file] ...
\end{alltt}

The package repository is partionend into a \emph{background} and a
\emph{foreground}. The foreground contains the packages we are actually
interested in, the background contains packages that are just available
for satisfying dependencies, but for which we do not care about installability.

All arguments are interpreted as filenames of Packages input files,
the contents of which go into the foreground. If no argument is given
then metadata of foreground packages is read from standard input.  In
addition, one may specify listings of foreground packages with the
option \verb|--fg=<filename>|, and listings of background packages
with the option \verb|--bg=<filename>|. Input from files (but not from
standard input) may be compressed with gzip or bzip2, provided
\debcheck{} was compiled with support for these compression libraries.

The option \texttt{-f} and \texttt{-s} ask for a listing of uninstallable,
resp.\ installable packages. The option \texttt{-e} asks for an explanation
of each reported case. The exact effect of these options will be explained
in Section~\ref{sec:output}.

\begin{example}
We may check whether packages in \textit{non-free} are installable,
where dependencies may be satisfied from \textit{main} or \textit{contrib}:
\begin{verbatim}
dose-distcheck  -f -e \
    --bg=/var/lib/apt/lists/ftp.fr.debian.org_debian_dists_sid_main_binary-amd64_Packages\
    --bg=/var/lib/apt/lists/ftp.fr.debian.org_debian_dists_sid_contrib_binary-amd64_Packages\
    /var/lib/apt/lists/ftp.fr.debian.org_debian_dists_sid_non-free_binary-amd64_Packages
\end{verbatim}
\end{example} 

\subsection{Checking only selected packages}
\label{sec:invocation-background}
The initial distinction between foreground and background packages is
modified when using the \verb|--checkonly| option. This option takes
as value a comma-separated list of package names, possibly qualified
with a version constraint. The effect is that only packages that match
one of these package names are kept in the foreground, all others are
pushed into the background.

\begin{example}
\begin{alltt}
\debcheck{} --checkonly "libc6, 2ping (= 1.2.3-1)" Packages
\end{alltt}
\end{example}

\subsection{Checking for co-installability}
\label{sec:invocation-coinst}
Co-installability of packages can be easily checked with the
\verb|--coinst| option. This option takes as argument a
comma-separated list of packages, each of them possibly with a version
constraint. In that case, \debcheck{} will check whether the packages
specified are co-installable, that is whether it is possible to
install these packages at the same time (see
Section~\ref{sec:coinstallability}).

Note that it is possible that the name of a package, even when
qualified with a version constraint, might be matched by several
packages with different versions. In that case, co-installability will
be checked for \emph{each} combination of real packages that match the
packages specified in the argument of the \verb|--coinst| option.
\begin{example}
  Consider the following repository (architectures are omitted for
  clarity):
\begin{verbatim}
Package: a
Version: 1

Package: a 
Version: 2

Package: a
Version: 3

Package: b
Version: 10

Package: b
Version: 11

...
\end{verbatim}
Executing the command \verb|debcheck --coinst a (>1), b| on this
repository will check co-installability of 4 pairs of packages: there
are two packages that match \verb|a (>1)|, namely package \texttt{a} in
versions 2 and 3, and there are two packages that match \texttt{b}. Hence,
the following four pairs of packages will be checked for co-installability:
\begin{enumerate}
\item (a,2), (b,10)
\item (a,2), (b,11)
\item (a,3), (b,10)
\item (a,3), (b,11)
\end{enumerate}
\end{example}

Mathematically speaking, the set of checked tuples is the Cartesian product
of the denotations of the single package specifications.

\subsection{Changing the Notion of Installability}

Some options affect the notion of installability:
\begin{itemize}
\item \texttt{--deb-ignore-essential} drops the Foundation requirement
  of installation sets (Section~\ref{sec:installability}). In other
  words, it is no longer required that any installation set contains all
  essential packages.
\end{itemize}

Other options concern Multiarch:
\begin{itemize}
\item \texttt{--deb-native-arch=}\textit{a} sets the native
  architecture to the value $a$. Note that the native architecture is
  not necessarily the architecture on which the tool is executed, it
  is just the primary architecture for which we are checking
  installability of packages. In particular, packages with the
  architecture field set to \texttt{all} are interpreted as packages of the
  native architecture \cite{ubuntu:multiarch}.
\item \texttt{--deb-foreign-archs=}$a_1,\ldots,a_n$ sets the foreign
  architectures to the list $a_1,\ldots,a_n$. Packages may only be installed
  when their architecture is the native architecture (including \texttt{all}),
  or one of the foreign architectures.
\end{itemize}


\subsection{Filtering Packages and Multiarch}
Filtering out packages is a different operation than pushing packages
into the background (Section~\ref{sec:invocation-background}): Background
packages are still available to satisfy dependencies, while filtering out a 
package makes it completely invisible.

\begin{itemize}
\item The effect of \texttt{--latest} is to keep only the latest version of any
package.
\end{itemize}


\subsection{Other Options}
Other options controlling the output are explained in detail in
Section~\ref{sec:output}. A complete listing of all options can be found in
the \debcheck(1) manpage.


