
\chapter{Compilation, Installation}
\label{sec:install}
%HEVEA\cutname{install.html}

\section{Installing Why3}

\subsection{Installation via \opam}

The simplest way to install Why3 is via \opam, the OCaml
package manager. It is as simple as
\begin{verbatim}
> opam install why3
\end{verbatim}
Then jump to Section~\ref{provers} to install external provers.

\subsection{Installation Instructions from Source Distribution}

In short, installation from sources proceeds as follows.
\begin{flushleft}\ttfamily
  > ./configure\\
  > make\\
  > make install \mbox{\rmfamily (as super-user)}
\end{flushleft}

After unpacking the distribution, go to the newly created directory
\texttt{why3-\whyversion}. Compilation must start with a
configuration phase which is run as
\begin{verbatim}
> ./configure
\end{verbatim}
This analyzes your current configuration and checks if requirements hold.
Compilation requires:
\begin{itemize}
\item The Objective Caml compiler. It is
  available as a binary package for most Unix distributions. For
  Debian-based Linux distributions, you can install the packages
\begin{verbatim}
ocaml ocaml-native-compilers
\end{verbatim}
It is also installable from sources, downloadable from the site
\url{http://caml.inria.fr/ocaml/}
\end{itemize}

\noindent
For some of the \why tools, additional OCaml libraries are needed:
\begin{itemize}
\item For the graphical interface, the Lablgtk2 library is needed.
  It provides OCaml
  bindings of the gtk2 graphical library. For Debian-based Linux
  distributions, you can install the packages
\begin{verbatim}
liblablgtk2-ocaml-dev liblablgtksourceview2-ocaml-dev
\end{verbatim}
It is also installable from sources, available from the site
\url{http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html}

% \item For \texttt{why3 bench}, the OCaml bindings of the sqlite3 library
% are needed.
% For Debian-based Linux distributions, you can install the package
% \begin{verbatim}
% libsqlite3-ocaml-dev
% \end{verbatim}
% It is also installable from sources, available from the site
% \url{http://ocaml.info/home/ocaml_sources.html#ocaml-sqlite3}
\end{itemize}


If you want to use the Coq realizations
(Section~\ref{sec:realizations}), then Coq has to be installed before
\why. Look at the summary printed at the end of the configuration
script to check if Coq has been detected properly. Similarly, in order to
use PVS (Section~\ref{sec:pvs}) or Isabelle (Section~\ref{sec:isabelle})
to discharge proofs, PVS and Isabelle must be
installed before \why. You should check that those proof assistants
are correctly detected by the configure script.

When configuration is finished, you can compile \why.
\begin{verbatim}
make
\end{verbatim}
Installation is performed (as super-user if needed) using
\begin{verbatim}
make install
\end{verbatim}
Installation can be tested as follows:
\begin{enumerate}
\item install some external provers (see Section~\ref{provers} below)
\item run \verb|why3 config --detect|
\item run some examples from the distribution, \eg you should
obtain the following (provided the required provers are installed on
your machine):
\begin{verbatim}
$ cd examples
$ why3 replay logic/scottish-private-club
 1/1 (replay OK)
$ why3 replay same_fringe
 18/18 (replay OK)
\end{verbatim}
\end{enumerate}

\subsubsection{Local Use, Without Installation}

It is not mandatory to install \why into system directories.
\why can be configured and compiled for local use as follows:
\begin{verbatim}
./configure --enable-local
make
\end{verbatim}
The \why executables are then available in the subdirectory
\texttt{bin/}. This directory can be added in your \texttt{PATH}.

\subsubsection{Installation of the \why API}
\label{sec:installlib}\index{API}

By default, the \why API is not installed. It can be installed using
\begin{flushleft}\ttfamily
make byte opt \\
make install-lib \mbox{\rmfamily (as super-user)}
\end{flushleft}

\section{Installing External Provers}
\label{provers}

\why can use a wide range of external theorem provers. These need to
be installed separately, and then \why needs to be configured to use
them. There is no need to install automatic provers, \eg SMT solvers,
before compiling and installing \why.
For installation of external provers, please refer to the specific
section about provers from \url{http://why3.lri.fr/}.
(If you have installed \why via \opam, note that you can install the
SMT solver Alt-Ergo via \opam as well.)

Once you have installed a prover, or a new version of a prover, you
have to run the following command:
\begin{verbatim}
> why3 config --detect
\end{verbatim}
It scans your \texttt{PATH} for provers and updates your configuration
file (see Section~\ref{sec:why3config}) accordingly.

\subsection{Multiple Versions of the Same Prover}

\why is able to use several versions of the same
prover, \eg it can use both CVC4 1.4 and CVC4 1.5 at the same time.
The automatic detection of provers looks for typical names for their
executable command, \eg \texttt{cvc4} for CVC3. However, if you
install several versions of the same prover it is likely that you would
use specialized executable names, such as \texttt{cvc4-1.4} or
\texttt{cvc4-1.5}. If needed, option \verb|--add-prover| can be
added to the \texttt{config} command to specify names of prover executables, \eg
\index{add-prover@\verb+--add-prover+}
\begin{verbatim}
why3 config --add-prover cvc4 cvc4-dev /usr/local/bin/cvc4-dev
\end{verbatim}
the first argument (here \verb|cvc4|) must be one of the family of
provers known. The list of these famillies can be obtain using
\begin{verbatim}
why3 config --list-prover-families
\end{verbatim}
as they are in fact listed in the file \verb|provers-detection-data.conf|, typically
located in \verb|/usr/local/share/why3| after installation. See
Appendix~\ref{sec:proverdetecttiondata} for details.


\subsection{Session Update after Prover Upgrade}
\label{sec:uninstalledprovers}

If you happen to upgrade a prover, \eg installing CVC4 1.5 in place
of CVC4 1.4, then the proof sessions formerly recorded will still
refer to the old version of the prover. If you open one such a session
with the GUI, and replay the proofs, a popup window will show up for asking you to choose
between three options:
\begin{itemize}
\item Keep the former proof attempts as they are, with the old prover version. They will not be replayed.
\item Remove the former proof attempts.
\item Upgrade the former proof attempts to an installed prover
  (typically an upgraded version). The corresponding proof attempts
  will become attached to this new prover, and marked as obsolete, to
  make their replay mandatory. If a proof attempt with this installed prover
  is already present the old proof attempt is just removed. Note that you
  need to invoke again the replay command to replay those proof
  attempts.
\item Copy the former proofs to an installed prover. This is a
  combination of the actions above: each proof attempt is duplicated,
  one with the former prover version, and one for the new
  version marked as obsolete.
\end{itemize}

Notice that if the prover under consideration is an interactive one, then
the copy option will duplicate also the edited proof scripts, whereas
the upgrade-without-copy option will just reuse the former proof scripts.

Your choice between the three options above will be recorded, one for
each prover, in the \why configuration file. Within the GUI, you can
discard these choices via the \textsf{Preferences} dialog: just click on one choice to remove it.

Outside the GUI, the prover upgrades are handled as follows. The
\texttt{replay} command will take into account any prover upgrade policy stored in the configuration.
The \texttt{session} command performs move or copy operations on
proof attempts in a fine-grained way, using filters, as detailed in
Section~\ref{sec:why3session}.


% pour l'instant on ne documente pas
% {que devient l'option -to-known-prover de why3session ?
%   (d'ailleurs documenté en tant que --convert-unknown ??) Pourrait-on
%   permettre à why3session d'appliquer les choix d'association
%   vieux-prover/nouveau-prouveur stockés par l'IDE ?}


%%% Local Variables:
%%% mode: latex
%%% TeX-PDF-mode: t
%%% TeX-master: "manual"
%%% End:
