doc-src/System/basics.tex
author wenzelm
Tue, 20 May 1997 19:34:24 +0200
changeset 3262 7115da553895
parent 3217 d30d62128fe5
child 3278 636322bfd057
permissions -rw-r--r--
under construction;
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
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    58
startup scripts. Isabelle requires none such administrative chores of
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    59
its end-users --- the executables can be run straight away. Usually,
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    60
users would want to put the Isabelle \texttt{bin} directory into their
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    61
shell's search path, of course.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    62
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    63
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    64
\subsection{Building the environment}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    65
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    66
Whenever any of the Isabelle executables is run, their settings
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    67
environment is built as follows:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    68
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    69
\begin{enumerate}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    70
\item The special variable \settdx{ISABELLE_HOME} is determined
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    71
  automatically from the location of the binary that has been run.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    72
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    73
  You should not try to set \texttt{ISABELLE_HOME} manually. Also note
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    74
  that the Isabelle executables have to be run from their original
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    75
  location in the distribution directory --- copying or linking them
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    76
  somewhere else just won't work!
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    77
  
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    78
\item The file \texttt{\$ISABELLE_HOME/etc/settings} ist run as a
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    79
  shell script with the auto-export option for variables enabled.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    80
  
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    81
  This file typically contains a rather long list of assigments
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    82
  \texttt{FOO="bar"}, thus providing the site-wide default settings.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    83
  The Isabelle distribution already contains a global settings file
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    84
  with sensible defaults for most variables. When installing the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    85
  system, only a few of these have to be adapted (most likely
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    86
  \texttt{ML_SYSTEM} etc.).
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    87
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    88
\item The file \texttt{\$ISABELLE_HOME_USER/etc/settings} (if it
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    89
  exists) is run the same way as the site default settings. The
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    90
  variable \texttt{ISABELLE_HOME_USER} has already been set before ---
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    91
  usually to \texttt{\~\relax/isabelle}.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    92
  
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    93
  Thus individual users may override the site-wide defaults. See also
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    94
  file \texttt{etc/user-settings.sample} in the distribution.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    95
  Typically, user settings are a few lines only, just containing the
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    96
  assigments that are really needed.  One should definitely \emph{not}
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    97
  start with a full copy the central
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    98
  \texttt{\$ISABELLE_HOME/etc/settings}. This could cause very
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    99
  annoying maintainance problems later, when the Isabelle installation
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   100
  is updated or changed otherwise.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   101
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   102
\end{enumerate}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   103
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   104
Note that settings files are actually full GNU bash scripts. So one
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   105
may use complex shell commands, say \texttt{if} or \texttt{case}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   106
statements to set variables depending on the system architecture or
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   107
other environment variables, for example. Such advanced features
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   108
should be added only with great care, though. In particular, external
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   109
environment references should be kept at a minimum.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   110
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   111
\medskip A few variables are somewhat special:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   112
\begin{itemize}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   113
\item \settdx{ISABELLE} and \settdx{ISATOOL} are set automatically to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   114
  the absolute path names of the \texttt{isabelle} and
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   115
  \texttt{isatool} executables, respectively.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   116
  
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   117
\item \settdx{ISABELLE_PATH} and \settdx{ISABELLE_OUTPUT} will have
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   118
  the {\ML} system identifier (as specified by \texttt{ML_SYSTEM})
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   119
  automatically appended to their values.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   120
\end{itemize}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   121
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   122
\medskip The Isabelle settings scheme is basically quite simple, but
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   123
non-trivial.  For debugging purposes, the generated environment may be
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   124
inspected with the \texttt{getenv} utility, see
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   125
\S\ref{sec:tool-getenv}.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   126
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   127
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   128
\subsection{Common variables}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   129
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   130
Below is a reference of common Isabelle settings variables. Note that
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   131
the list is somewhat open-ended. Third-party utilities or interfaces
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   132
may add their own selection. Variables that are special in some sense
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   133
are marked with *.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   134
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   135
\begin{description}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   136
\item[\settdx{ISABELLE_HOME}*] is the location of the top-level
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   137
  Isabelle distribution directory. This is automatically determined
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   138
  from the Isabelle executable that has been invoked.  Do not try to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   139
  set \texttt{ISABELLE_HOME} yourself from the shell.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   140
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   141
\item[\settdx{ISABELLE_HOME_USER}] is the user-specific counterpart of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   142
  \texttt{ISABELLE_HOME}. The default value is
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   143
  \texttt{\~\relax/isabelle}, under rare circumstances this may be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   144
  changed in the global setting file.  Typically, the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   145
  \texttt{ISABELLE_HOME_USER} directory mimics \texttt{ISABELLE_HOME}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   146
  to some extend. In particular, site-wide defaults may be overridden
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   147
  by a private \texttt{etc/settings}.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   148
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   149
\item[\settdx{ISABELLE}*, \settdx{ISATOOL}*] are automatically set to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   150
  the full paths of the \texttt{isabelle} and \texttt{isatool}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   151
  executables, respectively.  Thus other tools and scripts need not
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   152
  assume that the Isabelle \texttt{bin} directory is on the current
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   153
  search path of the shell.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   154
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   155
\item[\settdx{ML_SYSTEM}, \settdx{ML_HOME}, \settdx{ML_OPTIONS}]
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   156
  specify the underlying {\ML} system to be used for Isabelle.  The
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   157
  choice of \texttt{ML_SYSTEM} identifiers is quite fixed, see the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   158
  global \texttt{etc/settings} file for some examples. The actual
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   159
  compiler binary will be run from directory \texttt{ML_HOME}, with
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   160
  \texttt{ML_OPTIONS} as first arguments on the command line.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   161
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   162
\item[\settdx{ISABELLE_PATH}*] is a list of directories (separated by
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   163
  colons) where Isabelle logic images may reside. Note that the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   164
  \texttt{ML_SYSTEM} identifier is appended to each component
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   165
  automatically.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   166
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   167
\item[\settdx{ISABELLE_OUTPUT}*] is a directory where output heap
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   168
  files should be stored by default. The \texttt{ML_SYSTEM} identifier
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   169
  is appended here, too.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   170
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   171
\item[\settdx{ISABELLE_LOGIC}] specifies the default logic to load if
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   172
  none is given explicitely by the user --- e.g.\ when running
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   173
  \texttt{isabelle} directly, or some user interface.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   174
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   175
\item[\settdx{ISABELLE_USEDIR_OPTIONS}] is implicitely prefixed to the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   176
  command line of any \texttt{isatool usedir} invocation (see also
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   177
  \S\ref{sec:tool-usedir}). This typically contains compilation
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   178
  options for object-logics --- \texttt{usedir} is the basic utility
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   179
  that builds them (cf.\ the \texttt{IsaMakefile}s in the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   180
  distribution).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   181
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   182
\item[\settdx{ISABELLE_TOOLS}] is a colon separated list of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   183
  directories that are scanned by \texttt{isatool} for utility
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   184
  programs (see also \S\ref{sec:isatool}).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   185
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   186
\item[\settdx{ISABELLE_DOCS}] is a colon separated list of directories
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   187
  with documentation files.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   188
  
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   189
\item[\settdx{DVI_VIEWER}] specifies the command to be used for
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   190
  displaying \texttt{dvi} files.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   191
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   192
\item[\settdx{ISABELLE_INSTALL_FONTS}] determines the way that the
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   193
  Isabelle symbol fonts are installed into your currently running X11
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   194
  display server. X11 fonts are a non-trivial issue, see
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   195
  \S\ref{sec:tool-installfonts} for more information.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   196
  
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   197
\item[\settdx{ISABELLE_INTERFACE}] is an identifier that specifies the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   198
  actual user interface that the capital \texttt{Isabelle} should
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   199
  invoke.  Currently available are \texttt{none}, \texttt{xterm} and
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   200
  \texttt{emacs}. See \S\ref{sec:interface} for more details.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   201
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   202
\end{description}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   203
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   204
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   205
\section{Isabelle proper --- \texttt{isabelle}}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   206
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   207
The \ttindex{isabelle} executable runs logic sessions --- either
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   208
interactively or in batch mode. It provides an abstraction over the
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   209
underlying {\ML} system, and over the actual heap file locations. Its
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   210
usage is:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   211
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   212
Usage: isabelle [OPTIONS] [INPUT] [OUTPUT]
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   213
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   214
  Options are:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   215
    -e MLTEXT    pass MLTEXT to the ML session
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   216
    -m MODE      add print mode for output
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   217
    -q           non-interactive session
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   218
    -r           open heap file read-only
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   219
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   220
  INPUT (default "\$ISABELLE_LOGIC") and OUTPUT specify in/out heaps.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   221
  These are either names to be searched in the Isabelle path, or actual
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   222
  file names (then containing at least one /).
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   223
  If INPUT is "RAW_ML_SYSTEM", just start the bare bones ML system.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   224
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   225
Input files without path specifications are looked up in the
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   226
\texttt{ISABELLE_PATH} setting, which may consist of multiple
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   227
components separated by colons --- these are tried in order.  Short
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   228
output names are relative to the directory specified by
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   229
\texttt{ISABELLE_OUTPUT} setting.  In any case, actual file locations
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   230
may also be given by including at least one \texttt{/} in the name
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   231
(hint: use \texttt{./} to refer to the current directory).
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   232
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   233
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   234
\subsection*{Options}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   235
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   236
If the input heap file does not have write permission bits set, or the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   237
\texttt{-r} option is given explicitely, then the session will be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   238
read-only. That is, the {\ML} world cannot be committed back into the
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   239
logic image.  Otherwise, a writable session enables commits into
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   240
either the input file, or into an alternative output heap file (in
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   241
case this is given as the second argument).
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   242
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   243
The read-write state of sessions is determined at startup only, it
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   244
cannot be changed intermediately. Also note that heap images may
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   245
require considerable amounts of disk space. Users are responsible
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   246
themselves to dispose their heap files when they are no longer needed.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   247
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   248
\medskip Using the \texttt{-e} option, arbitrary {\ML} code may be
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   249
passed to the Isabelle session from the command line. Multiple
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   250
\texttt{-e}'s are evaluated in order. Strange things may happen when
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   251
errorneous {\ML} code is given. Also make sure that commands are
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   252
terminated properly by semicolon.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   253
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   254
\medskip The \texttt{-m} option adds identifiers of print modes to be
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   255
made active for this session. Typically, this is used by some user
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   256
interface, for example to enable output of mathematical symbols from a
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   257
special screen font. See also \S\ref{sec:tool-installfonts} about
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   258
fonts and the \emph{Isabelle Reference Manual} about print modes in
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   259
general.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   260
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   261
\medskip Isabelle normally enters an interactice {\ML} top-level loop
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   262
(after processing the \texttt{-e} texts). The \texttt{-q} option
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   263
inhibits this, thus providing a pure batch mode facility.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   264
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   265
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   266
\subsection*{Examples}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   267
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   268
Run an interactive session of the default object-logic (as specified
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   269
by the \texttt{ISABELLE_LOGIC} setting) like this:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   270
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   271
isabelle
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   272
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   273
Usually \texttt{ISABELLE_LOGIC} refers to one of the standard logic
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   274
images, which are read-only by default.  A writable session --- based
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   275
on \texttt{FOL}, but output to \texttt{Foo} (in the directory
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   276
specified by the \texttt{ISABELLE_OUTPUT} setting) --- may be invoked
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   277
as follows:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   278
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   279
isabelle FOL Foo
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   280
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   281
Ending this session normally (e.g.\ by typing control-D) dumps the
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   282
whole {\ML} system state into \texttt{Foo}. Be prepared for several
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   283
megabytes!
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   284
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   285
The \texttt{Foo} session may be continued later (still in writable
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   286
state) by:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   287
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   288
isabelle Foo
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   289
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   290
A read-only \texttt{Foo} session may be started by:
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   291
\begin{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   292
isabelle -r Foo
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   293
\end{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   294
One may also use something like \texttt{chmod~-w} on the logic image
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   295
to have them read-only automatically.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   296
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   297
\medskip The next example demonstrates batch execution of Isabelle. We
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   298
print a certain theorem of \texttt{FOL}:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   299
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   300
isabelle -e "prth allE;" -q -r FOL
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   301
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   302
Note that the output text will be usually interspersed with some
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   303
garbage produced by the {\ML} compiler.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   304
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   305
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   306
\section{The Isabelle tools wrapper --- \texttt{isatool}} \label{sec:isatool}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   307
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   308
FIXME
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   309
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   310
\section{The Isabelle interface wrapper --- \texttt{Isabelle}} \label{sec:interface}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   311
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   312
FIXME