\documentclass[a4paper,11pt,twoside,openright]{memoir}

% rubber: module index

%BEGIN LATEX
\usepackage{comment}
%\usepackage{todonotes}
\newcommand{\ahref}[2]{{#2}}
\excludecomment{htmlonly}
\newenvironment{latexonly}{}{}
%END LATEX

%HEVEA\@addimagenopt{-pdf}

%BEGIN LATEX
% tells memoir style to number subsections
\setsecnumdepth{subsection}
%END LATEX

\usepackage[T1]{fontenc}
\usepackage{lmodern}
%\usepackage{url}
\usepackage[pdftex,colorlinks=true,urlcolor=blue,pdfstartview=FitH]{hyperref}

%BEGIN LATEX
\usepackage{upquote}
%END LATEX

%BEGIN LATEX
\usepackage{graphicx}
%END LATEX
%HEVEA \newcommand{\includegraphics}[2][2]{\imgsrc{#2}}

\usepackage{listings}
\usepackage{xspace}

%BEGIN LATEX
\setulmarginsandblock{30mm}{30mm}{*}
\setlrmarginsandblock{30mm}{30mm}{*}
\setheadfoot{15pt}{38pt}
\checkandfixthelayout

% placement of figures
\renewcommand{\textfraction}{0.01}
\renewcommand{\topfraction}{0.99}
\renewcommand{\bottomfraction}{0.99}
%END LATEX
\setcounter{topnumber}{4}
\setcounter{bottomnumber}{4}
\setcounter{totalnumber}{8}

%HEVEA \newstyle{table.lstframe}{width:100\%;border-width:1px;}

% \usepackage[toc,nonumberlist]{glossaries}
% \makeglossaries

% \usepackage{glossary}
% \makeglossary
% \glossary{name={entry name}, description={entry description}}

% for ocamldoc generated pages
%\usepackage{ocamldoc}
%\let\tt\ttfamily
%\let\bf\bfseries

\usepackage{ifthen}

% avoid double spacing after '.' and ':' in texttt
%BEGIN LATEX
\makeatletter
\let\ttfamily\relax
\DeclareRobustCommand\ttfamily
   {\not@math@alphabet\ttfamily\mathtt\fontfamily\ttdefault\selectfont\frenchspacing}
\makeatother
%END LATEX

\input{./macros.tex}
\input{./replayer_macros.tex}
\input{./version.tex}

\makeindex

%HEVEA\title{The Why3 platform}

\begin{document}
\sloppy
%BEGIN LATEX
\hbadness=5000
%END LATEX

\thispagestyle{empty}

\begin{center}

%BEGIN LATEX
\rule\textwidth{0.8mm}
%END LATEX

\vfill

{
%BEGIN LATEX
\fontsize{40}{40pt}\selectfont
%END LATEX
%HEVEA \Huge
\bfseries\sffamily The Why3 platform}

\vfill

%BEGIN LATEX
\rule\textwidth{0.8mm}
%END LATEX

\vfill

%\todo{NE PAS DISTRIBUER TANT QU'IL RESTE DES TODOS}

%BEGIN LATEX
\begin{LARGE}
%END LATEX
  Version \whyversion{}, October 2019
%BEGIN LATEX
\end{LARGE}
%END LATEX

\vfill

%BEGIN LATEX
\begin{Large}
%END LATEX
  \begin{tabular}{c}
  Fran\c{c}ois Bobot$^{1,2}$ \\
  Jean-Christophe Filli\^atre$^{1,2}$  \\
  Claude March\'e$^{2,1}$ \\
  Guillaume Melquiond$^{2,1}$\\
  Andrei Paskevich$^{1,2}$
\end{tabular}
%BEGIN LATEX
\end{Large}
%END LATEX
\vfill

\begin{flushleft}

\begin{tabular}{l}
$^1$ LRI, CNRS \& University Paris-Sud, Orsay, F-91405 \\
$^2$ Inria Saclay -- \^Ile-de-France, Palaiseau, F-91120
\end{tabular}

%BEGIN LATEX
\bigskip
%END LATEX

\textcopyright 2010--2018 University Paris-Sud, CNRS, Inria

\urldef{\urlutcat}{\url}{http://frama-c.com/u3cat/}
\urldef{\urlhilite}{\url}{http://www.open-do.org/projects/hi-lite/}
\urldef{\urlbware}{\url}{http://bware.lri.fr/}
\urldef{\urlproofinuse}{\url}{http://www.spark-2014.org/proofinuse}
\urldef{\urlcolis}{\url}{http://colis.irif.univ-paris-diderot.fr/}
\urldef{\urlvocal}{\url}{https://vocal.lri.fr/}

This work has been partly supported by the `\ahref{\urlutcat}{U3CAT}'
national ANR project (ANR-08-SEGI-021-08\begin{latexonly},
  \urlutcat\end{latexonly}), the `\ahref{\urlhilite}{Hi-Lite}'
\begin{latexonly}(\urlhilite)\end{latexonly} FUI project of the
System@tic competitivity cluster, the `\ahref{\urlbware}{BWare}'
ANR project (ANR-12-INSE-0010\begin{latexonly},
  \urlbware\end{latexonly}), the \ahref{\urlproofinuse}{Joint Laboratory ProofInUse} (ANR-13-LAB3-0007\begin{latexonly}, \urlproofinuse\end{latexonly});
the `\ahref{\urlcolis}{CoLiS}' ANR project (ANR-15-CE25-0001\begin{latexonly},
  \urlcolis\end{latexonly}), and the `\ahref{\urlvocal}{VOCaL}' ANR project (ANR-15-CE25-008\begin{latexonly},
  \urlvocal\end{latexonly}).
\end{flushleft}
\end{center}

\chapter*{Foreword}
%HEVEA\cutname{foreword.html}

%This is the manual for the Why platform version 3, or \why for
%short.
\why is a platform for deductive program verification. It provides
a rich language for specification and programming, called \whyml, and
relies on external theorem provers, both automated and interactive,
to discharge verification conditions. \why comes with a standard
library of logical theories (integer and real arithmetic, Boolean
operations, sets and maps, etc.) and basic programming data structures
(arrays, queues, hash tables, etc.). A user can write \whyml programs
directly and get correct-by-construction OCaml programs through an
automated extraction mechanism. \whyml is also used as an intermediate
language for the verification of C, Java, or Ada programs.

\why is a complete reimplementation %~\cite{boogie11why3}
of the former Why platform~\cite{filliatre07cav}.
%for program verification.
Among the new features are: numerous
extensions to the input language, a new architecture for calling
external provers, and a well-designed API, allowing to use \why as a
software library.  An important emphasis is put on modularity and
genericity, giving the end user a possibility to easily reuse \why
formalizations or to add support for a new external prover if wanted.

\subsection*{Availability}

\why project page is \url{http://why3.lri.fr/}.  The last distribution
is available there, in source format, together with this documentation
and several examples.

\why is also distributed under the form of an OPAM package and a
Debian package.

\why is distributed as open source and freely available under the
terms of the GNU LGPL 2.1. See the file \texttt{LICENSE}.

See the file \texttt{INSTALL} for quick installation instructions, and
Section~\ref{sec:install} of this document for more detailed
instructions.

\subsection*{Contact}

There is a public mailing list for users' discussions:
\url{http://lists.gforge.inria.fr/mailman/listinfo/why3-club}.

Report any bug to the \why Bug Tracking System:
\url{https://gitlab.inria.fr/why3/why3/issues}.


\subsection*{Acknowledgements}

We gratefully thank the people who contributed to \why, directly or
indirectly:
Stefan Berghofer,
Sylvie Boldo,
Martin Clochard,
Simon Cruanes,
Sylvain Dailler,
Cl\'ement Fumex,
L\'eon Gondelman,
David Hauzar,
Daisuke Ishii,
Johannes Kanig,
Mikhail Mandrykin,
David Mentr\'e,
Benjamin Monate,
Kim Nguyen,
Thi-Minh-Tuyen Nguyen,
M\'ario Pereira,
Rapha\"el Rieu-Helft,
Sim\=ao Melo de Sousa,
Asma Tafat,
Piotr Trojanek,
Makarius Wenzel.

\cleardoublepage

%BEGIN LATEX
\tableofcontents
%END LATEX

%\input{intro.tex}

\part{Tutorial}

\input{starting.tex}

% \input{syntax.tex}

% \input{ide.tex}

\input{whyml.tex}

\input{api.tex}

\part{Reference Manual}

\input{install.tex}

\input{manpages.tex}

\input{syntaxref.tex}

\input{exec.tex}

% maintaining library.tex up to date is hopeless
% \input{library.tex}

\input{itp.tex}


% \chapter{Complete API documentation} *)
% \label{chap:apidoc} *)

% \input{./apidoc.tex} *)

\input{technical.tex}

\part{Appendix}

\appendix

\chapter{Release Notes}
%HEVEA\cutname{changes.html}

\section{Release Note for version 1.2: new syntax for ``auto-dereference''}

Version 1.2 introduces a simplified syntax for reference variables, to
avoid the somehow heavy OCaml syntax using bang character. In short,
this is syntactic sugar summarized in the following table.  An example
using this new syntax is in \url{examples/isqrt.mlw}

\begin{center}
  \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{auto-dereference syntax} & \textbf{desugared to} \\
\hline
\texttt{let \&x = ... in} & \texttt{let (x: ref ...) = ... in} \\
\hline
\texttt{f x;} & \texttt{f x.contents;} \\
\hline
\texttt{x <- ...} & \texttt{x.contents <- ...} \\
\hline
\texttt{let ref x = ...} & \texttt{let \&x = ref ...} \\
\hline
\end{tabular}
\end{center}
Notice that:
\begin{itemize}
\item The \verb|&| marker adds the typing constraint \verb|(x: ref ...)|
\item Top-level \verb|let/val ref| and \verb|let/val &| are allowed
\item Auto-dereferencing works in logic, but such variables
  cannot be introduced inside logical terms.
\end{itemize}

That syntactic sugar is further extended to pattern matching, function
parameters and reference passing as follows.
\begin{center}
  \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{auto-dereference syntax} & \textbf{desugared to} \\
\hline
\texttt{match e with (x,\&y) -> y end} & \texttt{match e with
 (x,(y: ref ...)) -> y.contents end} \\
  \hline
  \texttt{\begin{tabular}{l}
            let incr (\&x: ref int) = \\
            ~ x <- x + 1 \\
            ~ \\
            let f () = \\
            ~ let ref x = 0 in \\
            ~ incr x; \\
            ~ x
          \end{tabular}}
  &
    \texttt{\begin{tabular}{l}
              let incr (x: ref int) = \\
              ~ x.contents <- x.contents + 1 \\
              ~ \\
              let f () = \\
              ~ let x = ref 0 in \\
              ~ incr x; \\
              ~ x.contents
            \end{tabular}}
  \\
  \hline
  \texttt{let incr (ref x: int)  ...} & \texttt{let incr (\&x: ref int) ...}
                                        \\\hline
\end{tabular}
\end{center}

The type annotation is not required. Let-functions with such formal
parameters also prevent the actual argument from auto-dereferencing
when used in logic. Pure logical symbols cannot be declared with such
parameters.

Auto-dereference suppression does not work in the middle of a relation
chain: in \verb|0 < x :< 17|, \verb|x| will be dereferenced even if \verb|(:<)| expects a
ref-parameter on the left.

Finally, that syntactic sugar applies to the caller side:
\begin{center}
  \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{auto-dereference syntax} & \textbf{desugared to} \\
\hline
 \texttt{\begin{tabular}{l}
    let f () = \\
    ~ let ref x = 0 in \\
    ~ g \&x
         \end{tabular}}
  &
 \texttt{\begin{tabular}{l}
          let f () = \\
          ~ let x = ref 0 in \\
          ~ g x
         \end{tabular}
  }
  \\\hline
\end{tabular}
\end{center}
The \verb|&| marker can only be attached to a variable. Works in logic.

Ref-binders and \verb|&|-binders in variable declarations, patterns,
and function parameters do not require importing \verb|ref.Ref|.
Any example that does not use references inside data structures
can be rewritten by using ref-binders, without importing \verb|ref.Ref|.

Explicit use of type symbol "ref", program function "ref",
or field "contents" require importing \verb|ref.Ref| or \verb|why3.Ref.Ref|.
Operations \verb|(:=)| and \verb|(!)| require importing \verb|ref.Ref|.

Operation \verb|(:=)| is fully subsumed by direct assignment \verb|(<-)|.

\section{Release Notes for version 1.0: syntax changes w.r.t. 0.88}

The syntax of \whyml programs changed in release 1.0.
The table in Figure~\ref{fig:syntax-1.0} summarizes the changes.

Note also that logical symbols can no longer be used in non-ghost code;
in particular, there is no polymorphic equality in programs anymore,
so equality functions must be declared/defined on a per-type basis
(already done for type \texttt{int} in the standard library). The \texttt{CHANGES.md}
file describes other potential sources of incompatibility.

\begin{figure}[thbp]
\centering
\begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{version 0.88} & \textbf{version 1.0} \\
\hline
\texttt{function f ...} & \texttt{let function f ...} if called in
                          programs \\
\hline
\texttt{'L:} & \texttt{label L in} \\
\hline
\texttt{at x 'L} & \texttt{x at L} \\
\hline
\texttt{\char`\\ x. e} & \texttt{fun x -> e} \\
\hline
\texttt{use HighOrd} & nothing, not needed anymore \\
\hline
\texttt{HighOrd.pred ty} & \texttt{ty -> bool} \\
\hline
\texttt{type t model ...} & \texttt{type t = abstract ...} \\
\hline
\texttt{abstract e ensures \{ Q \}} & \texttt{begin ensures \{ Q \} e end} \\
\hline
\texttt{namespace N} & \texttt{scope N} \\
\hline
\texttt{use import M} & \texttt{use M} \\
\hline
\texttt{"attribute"} & \texttt{[@attribute]} \\
\hline
\texttt{meta M prop P} & \texttt{meta M lemma P} or \texttt{meta M axiom P} or \texttt{meta M goal P} \\
\hline
\texttt{loop ... end} & \texttt{while true do ... done} \\
\hline
\texttt{type ... invariant \{ ... self.foo ... \}} & \texttt{type ... invariant \{ ... foo ... \}}\\
\hline
\end{tabular}
\caption{Syntax changes from version 0.88 to version 1.0}
\label{fig:syntax-1.0}
\end{figure}

Here are a few more semantic changes
\begin{description}
\item[Proving only partial correctness] In versions 0.xx of Why3, when
  a program function is recursive but not given a variant, or contains
  a while loop not given a variant, then it was assumed that the user
  wants to prove partial correctness only. A warning was issued,
  recommending to add an extra \verb|diverges| clause to that
  function's contract. It was also possible to disable that warning by
  adding the label \verb|"W:diverges:N"| to the function's
  name. Version 1.00 of Why3 is more aggressively requiring the user
  to prove the termination of functions which are not given the
  \verb|diverges| clause, and the previous warning is now an
  error. The possibility of proving only partial correctness is now
  given on a more fine-grain basis: any expression for which one wants
  to prove partial correctness only, must by annotated with the
  attribute \verb|[@vc:divergent]|.

  In other words, if one was using the following structure in Why3 0.xx:
  \begin{lstlisting}
    let f "W:diverges:N" <parameters> <contract> = <body>
  \end{lstlisting}
  then in 1.00 it should be written as
  \begin{lstlisting}
    let f <parameters> <contract> = [@vc:divergent] <body>
  \end{lstlisting}
\item[Semantics of the \texttt{any} construct] The \verb|any| construct
  in Why3 0.xx was introducing an arbitrary value satisfying the
  associated post-condition. In some sense, this construct was
  introducing some form of an axiom stating that such a value
  exists. In Why3 1.00, it is now mandatory to prove the existence of
  such a value, and a VC is generated for that purpose.

  To obtain the effect of the former semantics of the \verb|any| construct, one should use instead a local \verb|val| function. In other words, if one was using the following structure in Why3 0.xx:
  \begin{lstlisting}
    any t ensures { P }
  \end{lstlisting}
  then in 1.00 it should be written as
  \begin{lstlisting}
    val x:t ensures { P } in x
  \end{lstlisting}


\end{description}
\section{Release Notes for version 0.80: syntax changes w.r.t. 0.73}

The syntax of \whyml programs changed in release 0.80.
The table in Figure~\ref{fig:syntax-0.80} summarizes the changes.

\begin{figure}[thbp]
  \centering
\begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{version 0.73} & \textbf{version 0.80} \\
\hline
\ttfamily
type t = \{| field~:~int |\}
&
\ttfamily
type t = \{ field~:~int \}
\\
\hline
\ttfamily
\{| field = 5 |\}
&
\ttfamily
\{ field = 5 \}
\\
\hline
\ttfamily
use import module M
&
\ttfamily
use import M
\\
\hline
\ttfamily
let rec f (x:int) (y:int)~:~t \newline
\null~~~~variant \{ t \} with rel = \newline
\null~~~~\{ P \} \newline
\null~~~~e \newline
\null~~~~\{ Q \} \newline
\null~~~~| Exc1 -> \{ R1 \} \newline
\null~~~~| Exc2 n -> \{ R2 \}
&
\ttfamily
let rec f (x:int) (y:int)~:~t \newline
\null~~~~variant \{ t with rel \} \newline
\null~~~~requires \{ P \} \newline
\null~~~~ensures \{ Q \} \newline
\null~~~~raises \{ Exc1 -> R1 \newline
\null~~~~~~~~~~~| Exc2 n -> R2 \} \newline
\null~~~~= e
\\
\hline
\ttfamily
val f (x:int) (y:int)~:\newline
\null~~~~\{ P \} \newline
\null~~~~t \newline
\null~~~~writes a b \newline
\null~~~~\{ Q \} \newline
\null~~~~| Exc1 -> \{ R1 \} \newline
\null~~~~| Exc2 n -> \{ R2 \}
&
\ttfamily
val f (x:int) (y:int)~:~t \newline
\null~~~~requires \{ P \} \newline
\null~~~~writes \{ a, b \} \newline
\null~~~~ensures \{ Q \} \newline
\null~~~~raises \{ Exc1 -> R1 \newline
\null~~~~~~~~~~~| Exc2 n -> R2 \}
\\
\hline
\ttfamily
val f~:~x:int -> y:int ->\newline
\null~~~~\{ P \} \newline
\null~~~~t \newline
\null~~~~writes a b \newline
\null~~~~\{ Q \} \newline
\null~~~~| Exc1 -> \{ R1 \} \newline
\null~~~~| Exc2 n -> \{ R2 \}
&
\ttfamily
val f (x y:int)~:~t \newline
\null~~~~requires \{ P \} \newline
\null~~~~writes \{ a, b \} \newline
\null~~~~ensures \{ Q \} \newline
\null~~~~raises \{ Exc1 -> R1 \newline
\null~~~~~~~~~~~| Exc2 n -> R2 \}
\\
\hline
\ttfamily
abstract e \{ Q \}
&
\ttfamily
abstract e ensures \{ Q \}
\\
\hline
\end{tabular}
\caption{Syntax changes from version 0.73 to version 0.80}
\label{fig:syntax-0.80}
\end{figure}

\section{Summary of Changes w.r.t. Why 2}

The main new features with respect to Why 2.xx
are the following.
\begin{enumerate}
\item Completely redesigned input syntax for logic declarations
  \begin{itemize}
  \item new syntax for terms and formulas
  \item enumerated and algebraic data types, pattern matching
  \item recursive definitions of logic functions and predicates, with
    termination checking
  \item inductive definitions of predicates
  \item declarations are structured in components called ``theories'',
    which can be reused and instantiated
  \end{itemize}

\item More generic handling of goals and lemmas to prove
  \begin{itemize}
  \item concept of proof task
  \item generic concept of task transformation
  \item generic approach for communicating with external provers
  \end{itemize}

\item Source code organized as a library with a documented API, to
  allow access to \why features programmatically.

\item GUI with new features with respect to the former GWhy
  \begin{itemize}
  \item session save and restore
  \item prover calls in parallel
  \item splitting, and more generally applying task transformations,
    on demand
  \item ability to edit proofs for interactive provers (Coq only for
    the moment) on any subtask
  \end{itemize}

\item Extensible architecture via plugins
  \begin{itemize}
  \item users can define new transformations
  \item users can add connections to additional provers
  \end{itemize}
\end{enumerate}

% \begin{itemize}
% \item New syntax for terms and formulas
% \item Algebraic data types, pattern matching
% \item Recursive definitions
% \item Inductive predicates
% \item Declaration encapsulated in theories. Using and cloning theories.
% \item Concept of proof task transformation
% \item Generic communication with provers
% \item OCaml library with documented API
% \item New GUI with session save and restore
% % \item New syntax for programs, new VC generator, intentionaly left *)
% %   undocumented, since the syntax is likely to evolve significantly in *)
% %   the future. Examples are available in \texttt{examples/programs}. *)
% \end{itemize}

\bibliographystyle{plain}
\bibliography{manual}
%\bibliography{abbrevs,demons,demons2,demons3,team,crossrefs}


% \cleardoublepage
% \input{glossary.tex}

\cleardoublepage
\listoffigures
\cleardoublepage
\printindex

\end{document}

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