%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  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{Installability}
\label{sec:installability}

\subsection{A Precise Definition}

In order to understand what installability exactly means for us we
need a little bit of theory.  Let $R$ be a repository (see
Section~\ref{sec:data}).  An \emph{$R$-installation set}, or sometimes
simply called an \emph{$R$-installation}, is a subset $I$ of $R$ that
has the following four properties:
\begin{description}
  \item[flatness:] $I$ does not contain two different packages with
    the same name (which then would have different versions or
    architecture), unless the package is marked as
    \texttt{Multiarch=Same}. If package $(p,a,n)$ has
    \texttt{Multiarch=Same} then $I$ just must not contain any package
    with name $p$ and a version different from $n$.
  \item[abundance:] For each package $p$ in $I$, every of its
    dependencies is satisfied by some package $q$ in $I$, either
    directly or through a virtual package in case the dependency does
    not carry a version constraint. 
    \begin{itemize}
    \item If $q$ has a Multiarch value of \texttt{No} or \texttt{Same}
      then the architecture of $q$ must be the same as the
      architecture of $p$.
    \item If $q$ has a Multiarch value of \texttt{Foreign} then the
      architecture of $q$ may be different then the architecture of $p$.
    \item If $q$ has a Multiarch value of \texttt{Allowed} then the
      architecture of $q$ must be the same as the architecture of $p$,
      or the dependency relation must carry the annotation \texttt{:any}.
    \end{itemize}
    In this context, the architecture value \texttt{all} is identified with
    the native architecture \cite{ubuntu:multiarch}.
  \item[peace:] For each package in $I$ and for each item in its list
    of conflicts, no package in $I$ satisfies the description of that
    item.  As an exception, it is allowed that a package in $I$ both
    provides a virtual package and at the same time conflicts with it.
  \item[foundation:] If package $(p,n)\in R$ is essential, then $I$
    must contain a package $(p,m)$ such that $(p,m)$ is essential.
\end{description}
Hence, the notion of an installation captures the idea that a certain
set of packages may be installed together on a machine, following the
semantics of binary package relations according to the Debian Policy.
The foundation requirement expresses that essential packages must be
installed; it is formulated in a way that also caters to the
(extremely rare) case that a package changes its \texttt{Essential}
value between different versions. The foundation property may be
switched off by giving the option \texttt{--deb-ignore-essential}.

\begin{example}
  Let $R$ be the following repository:
\begin{verbatim}
    Package: a
    Version: 1
    Depends: b (>= 2) | v

    Package: a 
    Version: 2
    Depends: c (> 1)

    Package: b
    Version: 1
    Conflicts: d

    Package: c
    Version: 3
    Depends: d
    Conflicts: v

    Package: d
    Version: 5
    Provides: v
    Conflicts: v
\end{verbatim}

The following subsets of $R$ are not $R$-installation sets:
\begin{itemize}
\item The complete set $R$ since it is not flat (it contains two
  different packages with name $a$)
\item The set $\{(a,1), (c,3)\}$ since it not abundant (the dependency
  of $(a,1)$ is not satisfied, nor is the dependency of $(c,3)$).
\item The set $\{(a,2), (c,3), (d,5)\}$ since it is not in peace
  (there is conflict between $(c,3)$ and $(d,5)$ via the virtual package $v$)
\end{itemize}
Examples of $R$-installation sets are
\begin{itemize}
\item The set $\{(d,5)\}$ (self conflicts via virtual packages are ignored)
\item The set $\{(a,1), (b,1)\}$
\item The set $\{(a,1), (d,5)\}$
\end{itemize}
\end{example}

A package $(p,n)$ is said to be \emph{installable} in a repository $R$
if there exists an $R$-installation set $I$ that contains $(p,n)$.

\begin{example}
  In the above example, $(a,1)$ is $R$-installable since it is contained
  in the $R$-installation set $\{(a,1), (d,5) \}$.

  However, $(a,2)$ is not $R$-installable: Any $R$-installation set
  containing $(a,2)$ must also contain $(c,3)$ (since it is the only
  package in $R$ that can satisfy the dependency of $(a,2)$ on $c
  (>1)$, and in the same way it must also contain $(d,5)$. However, this
  destroys the peace as $(c,3)$ and $(d,5)$ are in conflict. Hence, no such
  $R$-installation set can exist.
\end{example}

\subsection{What Installability does Not Mean}

\begin{itemize}
\item Installability in the sense of \debcheck{} only concerns the
  relations between different binary packages expressed in their
  respective control files. It does not mean that a package indeed
  installs cleanly in a particular environment since an installation
  attempt may still fail for different reasons, like failure of a
  maintainer script or attempting to hijack a file owned by another
  already installed package.
\item Installability means theoretical existence of a solution. It
  does not mean that a package manager (like \texttt{aptitude},
  \texttt{apt-get}) actually finds a way to install that package.
  This failure to find a solution may be due to an inherent
  incompleteness of the dependency resolution algorithm employed by
  the package manager, or may be due to user-defined preferences that
  exclude certain solutions.
\end{itemize}

\subsection{Co-installability}
\label{sec:coinstallability}
One also should keep in mind that, even when two packages are
$R$-installable, this does not necessarily mean that both packages can
be installed \emph{together}. A set $P$ of packages is called
$R$-\emph{co-installable} when there exists a single $R$-installation
set extending $P$.

\begin{example}
  Again in the above example, both $(b,1)$ and $(d,5)$ are
  $R$-installable; however they are not $R$-co-installable.
\end{example}

See Section~\ref{sec:tricks} on how co-installability can be encoded.
