doc-src/System/basics.tex
author oheimb
Wed, 12 Nov 1997 18:58:50 +0100
changeset 4223 f60e3d2c81d3
parent 3278 636322bfd057
child 4540 24fcf5ecae88
permissions -rw-r--r--
added thin_refl to hyp_subst_tac
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     1
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     2
% $Id$
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     3
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     4
\chapter{Basic concepts}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     5
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
     6
The \emph{Isabelle System Manual} describes Isabelle together with
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
     7
related tools and user interfaces as seen from an outside (operating
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
     8
system oriented) view.  See the \emph{Isabelle Reference Manual} for
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
     9
all internal {\ML} level user commands, on the other hand.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    10
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    11
\medskip The Isabelle system level environment is based on a few
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    12
general concepts:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    13
\begin{itemize}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    14
\item The \emph{Isabelle settings mechanism}, which provides
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    15
  environment variables to all Isabelle programs (including tools and
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    16
  user interfaces).
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    17
\item \emph{Isabelle proper} (\ttindex{isabelle}), which runs logic
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    18
  sessions, both interactively or in batch mode. In particular,
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    19
  \texttt{isabelle} abstracts over the invocation of the actual {\ML}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    20
  system to be used.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    21
\item The \emph{Isabelle tools wrapper} (\ttindex{isatool}), which
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    22
  provides a generic startup platform for Isabelle related utilities.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    23
  Thus tools automatically benefit from the settings mechanism.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    24
  Furthermore, the shell's search path is kept clean from many small
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    25
  programs.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    26
\item The \emph{Isabelle interface wrapper}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    27
  (\ttindex{Isabelle}\footnote{Note the capital \texttt{I}!}), which
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    28
  provides some abstraction over the actual user interface to be used.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    29
\end{itemize}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    30
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    31
\medskip The beginning user would probably just run one of the
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    32
interfaces (by invoking the capital \texttt{Isabelle}), and maybe some
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    33
basic tools like \texttt{doc} (see \S\ref{sec:tool-doc}).  This
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    34
assumes that the system has already been installed properly, of
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    35
course.\footnote{In case you have to do this yourself, see the
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    36
  \ttindex{INSTALL} file in the top-level directory of the
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    37
  distribution. The information provided there should be sufficient as
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    38
  a start.}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    39
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    40
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    41
\section{Isabelle settings} \label{sec:settings}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    42
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    43
The Isabelle system heavily depends on the \emph{settings
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    44
  mechanism}\indexbold{settings}. Basically, this is just a collection
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    45
of environment variables, e.g.\ \texttt{ISABELLE_HOME},
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    46
\texttt{ML_SYSTEM}, \texttt{ML_HOME}.  These variables are \emph{not}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    47
intended to be set directly from the shell!
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    48
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    49
Isabelle employs a somewhat more sophisticated scheme of
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    50
\emph{settings files} --- one for site-wide defaults, another for
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    51
optional user-specific modifications.  With all configuration
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    52
variables in just a few places, this is considered much more
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    53
maintainable and user-friendly than ordinary shell environment
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    54
variables.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    55
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    56
In particular, we avoid the typical situation where prospective users
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    57
of a software package are told to put this and that in their shell
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    58
startup scripts, before being able to actually run it. Isabelle
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    59
requires none such administrative chores of its end-users --- the
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    60
executables can be invoked straight away. Usually, users would just
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    61
want to put the Isabelle \texttt{bin} directory into their shell's
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    62
search path, of course.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    63
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    64
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    65
\subsection{Building the environment}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    66
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    67
Whenever any of the Isabelle executables is run, their settings
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    68
environment is built as follows:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    69
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    70
\begin{enumerate}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    71
\item The special variable \settdx{ISABELLE_HOME} is determined
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    72
  automatically from the location of the binary that has been run.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    73
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    74
  You should not try to set \texttt{ISABELLE_HOME} manually. Also note
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    75
  that the Isabelle executables have to be run from their original
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    76
  location in the distribution directory --- copying or linking them
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    77
  somewhere else just won't work!
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    78
  
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    79
\item The file \texttt{\$ISABELLE_HOME/etc/settings} ist run as a
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    80
  shell script with the auto-export option for variables enabled.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    81
  
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    82
  This file typically contains a rather long list of shell variable
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    83
  assigments, thus providing the site-wide default settings.  The
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    84
  Isabelle distribution already contains a global settings file with
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    85
  sensible defaults for most variables. When installing the system,
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    86
  only a few of these have to be adapted (most likely
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    87
  \texttt{ML_SYSTEM} etc.).
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    88
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    89
\item The file \texttt{\$ISABELLE_HOME_USER/etc/settings} (if it
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    90
  exists) is run the same way as the site default settings. The
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    91
  variable \texttt{ISABELLE_HOME_USER} has already been set before ---
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    92
  usually to \texttt{\~\relax/isabelle}.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    93
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    94
  Thus individual users may override the site-wide defaults. See also
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    95
  file \texttt{etc/user-settings.sample} in the distribution.
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    96
  Typically, user settings should be a few lines only, just containing
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    97
  the assigments that are really needed.  One should definitely
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
    98
  \emph{not} start with a full copy the central
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    99
  \texttt{\$ISABELLE_HOME/etc/settings}. This could cause very
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   100
  annoying maintainance problems later, when the Isabelle installation
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   101
  is updated or changed otherwise.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   102
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   103
\end{enumerate}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   104
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   105
Note that settings files are actually full GNU bash scripts. So one
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   106
may use complex shell commands, say \texttt{if} or \texttt{case}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   107
statements to set variables depending on the system architecture or
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   108
other environment variables, for example. Such advanced features
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   109
should be added only with great care, though. In particular, external
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   110
environment references should be kept at a minimum.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   111
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   112
\medskip A few variables are somewhat special:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   113
\begin{itemize}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   114
\item \settdx{ISABELLE} and \settdx{ISATOOL} are set automatically to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   115
  the absolute path names of the \texttt{isabelle} and
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   116
  \texttt{isatool} executables, respectively.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   117
  
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   118
\item \settdx{ISABELLE_PATH} and \settdx{ISABELLE_OUTPUT} will have
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   119
  the {\ML} system identifier (as specified by \texttt{ML_SYSTEM})
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   120
  automatically appended to their values.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   121
\end{itemize}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   122
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   123
\medskip The Isabelle settings scheme is basically quite simple, but
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   124
non-trivial.  For debugging purposes, the generated environment may be
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   125
inspected with the \texttt{getenv} utility, see
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   126
\S\ref{sec:tool-getenv}.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   127
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   128
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   129
\subsection{Common variables}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   130
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   131
Below is a reference of common Isabelle settings variables. Note that
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   132
the list is somewhat open-ended. Third-party utilities or interfaces
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   133
may add their own selection. Variables that are special in some sense
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   134
are marked with *.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   135
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   136
\begin{description}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   137
\item[\settdx{ISABELLE_HOME}*] is the location of the top-level
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   138
  Isabelle distribution directory. This is automatically determined
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   139
  from the Isabelle executable that has been invoked.  Do not try to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   140
  set \texttt{ISABELLE_HOME} yourself from the shell.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   141
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   142
\item[\settdx{ISABELLE_HOME_USER}] is the user-specific counterpart of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   143
  \texttt{ISABELLE_HOME}. The default value is
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   144
  \texttt{\~\relax/isabelle}, under rare circumstances this may be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   145
  changed in the global setting file.  Typically, the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   146
  \texttt{ISABELLE_HOME_USER} directory mimics \texttt{ISABELLE_HOME}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   147
  to some extend. In particular, site-wide defaults may be overridden
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   148
  by a private \texttt{etc/settings}.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   149
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   150
\item[\settdx{ISABELLE}*, \settdx{ISATOOL}*] are automatically set to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   151
  the full paths of the \texttt{isabelle} and \texttt{isatool}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   152
  executables, respectively.  Thus other tools and scripts need not
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   153
  assume that the Isabelle \texttt{bin} directory is on the current
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   154
  search path of the shell.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   155
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   156
\item[\settdx{ML_SYSTEM}, \settdx{ML_HOME}, \settdx{ML_OPTIONS}]
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   157
  specify the underlying {\ML} system to be used for Isabelle.  The
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   158
  choice of \texttt{ML_SYSTEM} identifiers is quite fixed, see the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   159
  global \texttt{etc/settings} file for some examples. The actual
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   160
  compiler binary will be run from directory \texttt{ML_HOME}, with
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   161
  \texttt{ML_OPTIONS} as first arguments on the command line.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   162
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   163
\item[\settdx{ISABELLE_PATH}*] is a list of directories (separated by
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   164
  colons) where Isabelle logic images may reside. Note that the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   165
  \texttt{ML_SYSTEM} identifier is appended to each component
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   166
  automatically.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   167
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   168
\item[\settdx{ISABELLE_OUTPUT}*] is a directory where output heap
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   169
  files should be stored by default. The \texttt{ML_SYSTEM} identifier
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   170
  is appended here, too.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   171
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   172
\item[\settdx{ISABELLE_LOGIC}] specifies the default logic to load if
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   173
  none is given explicitely by the user --- e.g.\ when running
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   174
  \texttt{isabelle} directly, or some user interface.
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   175
  
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   176
\item[\settdx{ISABELLE_USEDIR_OPTIONS}] is implicitly prefixed to the
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   177
  command line of any \texttt{isatool usedir} invocation (see also
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   178
  \S\ref{sec:tool-usedir}). This typically contains compilation
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   179
  options for object-logics --- \texttt{usedir} is the basic utility
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   180
  that builds them (cf.\ the \texttt{IsaMakefile}s in the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   181
  distribution).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   182
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   183
\item[\settdx{ISABELLE_TOOLS}] is a colon separated list of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   184
  directories that are scanned by \texttt{isatool} for utility
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   185
  programs (see also \S\ref{sec:isatool}).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   186
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   187
\item[\settdx{ISABELLE_DOCS}] is a colon separated list of directories
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   188
  with documentation files.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   189
  
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   190
\item[\settdx{DVI_VIEWER}] specifies the command to be used for
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   191
  displaying \texttt{dvi} files.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   192
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   193
\item[\settdx{ISABELLE_INSTALL_FONTS}] determines the way that the
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   194
  Isabelle symbol fonts are installed into your currently running X11
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   195
  display server. X11 fonts are a non-trivial issue, see
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   196
  \S\ref{sec:tool-installfonts} for more information.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   197
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   198
\item[\settdx{ISABELLE_INTERFACE}] is an identifier that specifies the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   199
  actual user interface that the capital \texttt{Isabelle} should
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   200
  invoke.  Currently available are \texttt{none}, \texttt{xterm} and
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   201
  \texttt{emacs}. See \S\ref{sec:interface} for more details.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   202
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   203
\end{description}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   204
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   205
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   206
\section{Isabelle proper --- \texttt{isabelle}}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   207
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   208
The \ttindex{isabelle} executable runs logic sessions --- either
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   209
interactively or in batch mode. It provides an abstraction over the
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   210
underlying {\ML} system, and over the actual heap file locations. Its
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   211
usage is:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   212
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   213
Usage: isabelle [OPTIONS] [INPUT] [OUTPUT]
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   214
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   215
  Options are:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   216
    -e MLTEXT    pass MLTEXT to the ML session
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   217
    -m MODE      add print mode for output
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   218
    -q           non-interactive session
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   219
    -r           open heap file read-only
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   220
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   221
  INPUT (default "\$ISABELLE_LOGIC") and OUTPUT specify in/out heaps.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   222
  These are either names to be searched in the Isabelle path, or actual
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   223
  file names (then containing at least one /).
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   224
  If INPUT is "RAW_ML_SYSTEM", just start the bare bones ML system.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   225
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   226
Input files without path specifications are looked up in the
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   227
\texttt{ISABELLE_PATH} setting, which may consist of multiple
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   228
components separated by colons --- these are tried in order.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   229
Likewise, short output names are relative to the directory specified
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   230
by \texttt{ISABELLE_OUTPUT}.  In any case, actual file locations may
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   231
also be given by including at least one \texttt{/} in the name (hint:
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   232
use \texttt{./} to refer to the current directory).
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   233
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   234
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   235
\subsection*{Options}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   236
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   237
If the input heap file does not have write permission bits set, or the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   238
\texttt{-r} option is given explicitely, then the session will be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   239
read-only. That is, the {\ML} world cannot be committed back into the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   240
logic image.  Otherwise, a writable session enables commits into
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   241
either the input file, or into an alternative output heap file (in
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   242
case this is given as the second argument).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   243
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   244
The read-write state of sessions is determined at startup only, it
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   245
cannot be changed intermediately. Also note that heap images may
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   246
require considerable amounts of disk space. Users are responsible
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   247
themselves to dispose their heap files when they are no longer needed.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   248
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   249
\medskip Using the \texttt{-e} option, arbitrary {\ML} code may be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   250
passed to the Isabelle session from the command line. Multiple
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   251
\texttt{-e}'s are evaluated in order. Strange things may happen when
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   252
errorneous {\ML} code is given. Also make sure that commands are
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   253
terminated properly by semicolon.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   254
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   255
\medskip The \texttt{-m} option adds identifiers of print modes to be
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   256
made active for this session. Typically, this is used by some user
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   257
interface, for example to enable output of mathematical symbols from a
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   258
special screen font.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   259
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   260
\medskip Isabelle normally enters an interactice {\ML} top-level loop
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   261
(after processing the \texttt{-e} texts). The \texttt{-q} option
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   262
inhibits this, thus providing a pure batch mode facility.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   263
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   264
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   265
\subsection*{Examples}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   266
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   267
Run an interactive session of the default object-logic (as specified
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   268
by the \texttt{ISABELLE_LOGIC} setting) like this:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   269
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   270
isabelle
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   271
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   272
Usually \texttt{ISABELLE_LOGIC} refers to one of the standard logic
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   273
images, which are read-only by default.  A writable session --- based
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   274
on \texttt{FOL}, but output to \texttt{Foo} (in the directory
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   275
specified by the \texttt{ISABELLE_OUTPUT} setting) --- may be invoked
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   276
as follows:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   277
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   278
isabelle FOL Foo
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   279
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   280
Ending this session normally (e.g.\ by typing control-D) dumps the
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   281
whole {\ML} system state into \texttt{Foo}. Be prepared for several
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   282
megabytes!
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   283
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   284
The \texttt{Foo} session may be continued later (still in writable
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   285
state) by:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   286
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   287
isabelle Foo
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   288
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   289
A read-only \texttt{Foo} session may be started by:
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   290
\begin{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   291
isabelle -r Foo
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   292
\end{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   293
One may also use something like \texttt{chmod~-w} on the logic image
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   294
to have it read-only automatically.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   295
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   296
\medskip The next example demonstrates batch execution of Isabelle. We
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   297
print a certain theorem of \texttt{FOL}:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   298
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   299
isabelle -e "prth allE;" -q -r FOL
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   300
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   301
Note that the output text will be usually interspersed with some
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   302
garbage produced by the {\ML} compiler.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   303
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   304
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   305
\section{The Isabelle tools wrapper --- \texttt{isatool}} \label{sec:isatool}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   306
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   307
All Isabelle related utilities are called via a common wrapper ---
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   308
\ttindex{isatool}:
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   309
\begin{ttbox}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   310
Usage: isatool TOOL [ARGS ...]
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   311
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   312
  Start Isabelle utility program TOOL with ARGS. Pass "-?" to TOOL
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   313
  for more specific help.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   314
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   315
  Available tools are:
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   316
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   317
    doc - view Isabelle documentation
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   318
    \(\vdots\)
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   319
\end{ttbox}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   320
Basically, Isabelle tools are ordinary executable scripts.  These are
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   321
run within the same settings environment as Isabelle proper, though,
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   322
see \S\ref{sec:settings}.  The set of available tools is collected by
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   323
isatool from the directories listed in the \texttt{ISABELLE_TOOLS}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   324
setting.  Do not try to call the scripts directly. Neither should you
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   325
add the tools directories to your shell's search path.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   326
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   327
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   328
\medskip See chapter~\ref{ch:tools} for descriptions of most utilities
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   329
that come with the Isabelle distributions. Third-parties may add their
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   330
own, of course.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   331
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   332
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   333
\section{The Isabelle interface wrapper --- \texttt{Isabelle}} \label{sec:interface}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   334
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   335
Isabelle is a generic theorem prover, even w.r.t.\ its user interface.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   336
The \ttindex{Isabelle} command (note the capital \texttt{I}) provides
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   337
a uniform way for end-users to invoke a certain interface. Which one
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   338
to actually start is determined by the \settdx{ISABELLE_INTERFACE}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   339
setting variable. Currently, the following are recognized:
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   340
\begin{ttdescription}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   341
\item[none] is just a pass-through to \texttt{isabelle}. Thus
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   342
  \texttt{Isabelle} basically becomes an alias for \texttt{isabelle}.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   343
  
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   344
\item[xterm] refers to a simple xterm-based interface which is part of
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   345
  the Isabelle distribution.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   346
  
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   347
\item[emacs] refers to David Aspinall's \emph{Isamode} for emacs.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   348
  Isabelle just provides a wrapper for this, the actual Isamode
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   349
  distribution is available elsewhere.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   350
\end{ttdescription}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   351
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   352
The factory default for \texttt{ISABELLE_INTERFACE} is \texttt{xterm}.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   353
This interface runs \texttt{isabelle} within its own xterm window.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   354
Usually, display of mathematical symbols from the Isabelle font is
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   355
also enabled (see \S\ref{sec:tool-installfonts} for font configuration
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   356
issues).  Furthermore, different kinds of identifiers in logical terms
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   357
are highlighted appropriately, e.g.\ free variables in bold and bound
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   358
variables underlined.
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   359
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   360
There are some more options available.  Just pass \texttt{-?} to the
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   361
\texttt{xterm} interface to have its usage printed.