doc-src/System/misc.tex
author wenzelm
Wed, 26 Aug 1998 16:33:29 +0200
changeset 5374 6ef3742b6153
parent 5366 8521cd8b0a40
child 5405 2ecb74e65439
permissions -rw-r--r--
moved images to gfx dir;
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
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
     4
\chapter{Miscellaneous tools} \label{ch:tools}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
     5
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
     6
Subsequently we describe various Isabelle related utilities --- in
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
     7
alphabetical order.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
     8
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
     9
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    10
\section{Viewing documentation --- \texttt{isatool doc}} \label{sec:tool-doc}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    11
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    12
The \tooldx{doc} utility displays online documentation:
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    13
\begin{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    14
Usage: isatool doc [DOC]
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    15
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    16
  View Isabelle documentation DOC, or show list of available documents.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    17
\end{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    18
If called without arguments, it lists all available documents. Each
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    19
line starts with an identifier, followed by some comment. Any of these
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    20
identifiers may be specified as the first argument in order to have
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    21
the corresponding document displayed.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    22
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    23
\medskip The \texttt{ISABELLE_DOCS} setting specifies the list of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    24
directories (separated by colons) to be scanned for documentations.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    25
The program for viewing \texttt{dvi} files is determined by the
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    26
\texttt{DVI_VIEWER} setting.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    27
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    28
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    29
\section{Tuning proof scripts --- \texttt{isatool expandshort}}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    30
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    31
The \tooldx{expandshort} utility tunes {\ML} proof scripts to enhance
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    32
readability:
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    33
\begin{ttbox}
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    34
Usage: expandshort [FILES|DIRS...]
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    35
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    36
  Recursively find .ML files, expand shorthand goal commands.
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    37
  Also contracts uses of resolve_tac, dresolve_tac, eresolve_tac,
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    38
  rewrite_goals_tac on 1-element lists; furthermore expands tabs,
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    39
  since they are now forbidden in ML string constants.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    40
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    41
  Renames old versions of files by appending "~~".
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    42
\end{ttbox}
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    43
In the files or directories supplied as arguments, all occurrences of
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    44
the shorthand commands \texttt{br}, \texttt{be} etc.\ in proof scripts
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    45
are replaced with the corresponding full commands.  The old versions
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    46
of the files are renamed to have the suffix~\verb'~~'.
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    47
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    48
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
    49
\section{Getting logic images --- \texttt{isatool findlogics}}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    50
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    51
The \tooldx{findlogics} utility traverses all directories specified in
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    52
\texttt{ISABELLE_PATH}, looking for Isabelle logic images. Its usage
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    53
is:
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    54
\begin{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    55
Usage: isatool findlogics
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    56
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    57
  Collect heap file names from ISABELLE_PATH.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    58
\end{ttbox}
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    59
The base names of all files found on the path are printed --- sorted
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    60
and with duplicates removed. Also note that \texttt{ISABELLE_PATH}
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
    61
implicitly depends upon \texttt{ML_SYSTEM}. Thus switching to another
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    62
{\ML} compiler may change the set of logic images available.
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    63
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    64
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    65
\section{Inspecting the settings environment -- \texttt{isatool getenv}}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    66
\label{sec:tool-getenv}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    67
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    68
The Isabelle settings environment --- as provided by the site-default
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    69
and user-specific settings files --- can be inspected with the
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    70
\tooldx{getenv} utility:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    71
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    72
Usage: isatool getenv [OPTIONS] [VARNAMES ...]
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    73
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    74
  Options are:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    75
    -a           display complete environment
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    76
    -b           print values only (doesn't work for -a)
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    77
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    78
  Get value of VARNAMES from the Isabelle settings.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    79
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    80
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    81
With the \texttt{-a} option, one may inspect the full process
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    82
environment that Isabelle related programs are run in. This usually
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    83
contains much more variables than are actually Isabelle settings.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    84
Normally, output is a list of lines of the form
4555
wenzelm
parents: 4540
diff changeset
    85
\mbox{$name$\texttt{=}$value$}. The \texttt{-b} option causes only the
wenzelm
parents: 4540
diff changeset
    86
values to be printed.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    87
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    88
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    89
\subsection*{Examples}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    90
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    91
Get the {\ML} system identifier and the location where the compiler
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    92
binaries are supposed to reside as follows:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    93
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    94
isatool getenv ML_SYSTEM ML_HOME
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    95
{\out ML_SYSTEM=smlnj-110}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
    96
{\out ML_HOME=/usr/local/smlnj-110/bin}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    97
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
    98
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
    99
The next one peeks at the search path that \texttt{isabelle} uses to
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   100
locate logic images:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   101
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   102
isatool getenv -b ISABELLE_PATH
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   103
{\out /home/me/isabelle/heaps/smlnj-110:/usr/local/isabelle/heaps/smlnj-110}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   104
\end{ttbox}
4555
wenzelm
parents: 4540
diff changeset
   105
Here we have used the \texttt{-b} option to suppress the
wenzelm
parents: 4540
diff changeset
   106
\texttt{ISABELLE_PATH=} prefix.  The value above is what became of the
wenzelm
parents: 4540
diff changeset
   107
following assignment in the default settings file:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   108
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   109
ISABELLE_PATH=\$ISABELLE_HOME_USER/heaps:\$ISABELLE_HOME/heaps
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   110
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   111
Note how the \texttt{ML_SYSTEM} value got appended automatically to
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   112
each path component. This is a special feature of
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   113
\texttt{ISABELLE_PATH} (and also of \texttt{ISABELLE_OUTPUT}).
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   114
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   115
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   116
\section{Installing Isabelle binaries with absolute references -- \texttt{isatool install}}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   117
\label{sec:tool-install}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   118
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   119
Usually, the Isabelle binaries (\texttt{isabelle}, \texttt{isatool}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   120
etc.) are just run from their location within the distribution
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   121
directory, probably indirectly by the shell through its \texttt{PATH}.
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   122
In some cases, though, another more traditional installation scheme
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   123
might be preferably where executables are put into some global system
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   124
directory (like \texttt{/usr/local/bin}).
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   125
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   126
Doing a plain copy of the Isabelle executables just would not work,
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   127
though.  One should use the \tooldx{install} utility instead:
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   128
\begin{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   129
Usage: install DIR
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   130
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   131
  Install binaries in directory DIR with absolute references to
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   132
  \$ISABELLE_HOME/bin (non-movable).
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   133
\end{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   134
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   135
The generated executables contain absolute references to
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   136
\texttt{ISABELLE_HOME}, as figured out by the \texttt{isatool}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   137
invocation.  While the scripts themselves may be relocated afterwards,
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   138
they would cease working if the referenced Isabelle distribution is
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   139
moved.  This is an example use of \texttt{install}:
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   140
\begin{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   141
  isatool install /usr/local/bin
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   142
\end{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   143
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   144
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   145
\section{Isabelle's version of make --- \texttt{isatool make}}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   146
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   147
The Isabelle \tooldx{make} utility is a very simple wrapper for
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   148
ordinary Unix \texttt{make}:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   149
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   150
Usage: isatool make [ARGS ...]
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   151
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   152
  Compiles logic in current directory using IsaMakefile.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   153
  ARGS are directly passed to the system make program.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   154
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   155
Note that the Isabelle settings environment is also active. Thus one
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   156
may refer to its values within the \ttindex{IsaMakefile}, e.g.\ 
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   157
\texttt{\$(ISABELLE_OUTPUT)}. Furthermore, programs started from the
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   158
make file also inherit this environment.  Typically,
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   159
\texttt{IsaMakefile}s defer the real work to the \texttt{usedir}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   160
utility, see \S\ref{sec:tool-usedir}.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   161
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   162
\medskip The basic \texttt{IsaMakefile} convention is that the default
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   163
target builds the actual logic, including its parents if appropriate.
4555
wenzelm
parents: 4540
diff changeset
   164
The \texttt{images} target is intended to build all local logic
wenzelm
parents: 4540
diff changeset
   165
images, while the \texttt{test} target shall build all related
wenzelm
parents: 4540
diff changeset
   166
examples.  The \texttt{all} target shall do \texttt{images} and
wenzelm
parents: 4540
diff changeset
   167
\texttt{test}.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   168
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   169
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   170
\subsection*{Examples}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   171
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   172
Refer to the \texttt{IsaMakefile}s of the Isabelle distribution's
4555
wenzelm
parents: 4540
diff changeset
   173
object-logics as a model for your own developements.  For example, see
wenzelm
parents: 4540
diff changeset
   174
\texttt{src/FOL/IsaMakefile}.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   175
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   176
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   177
\section{Make all logics -- \texttt{isatool makeall}}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   178
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   179
The \tooldx{makeall} utility applies Isabelle make to all logic
4555
wenzelm
parents: 4540
diff changeset
   180
directories of the distribution:
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   181
\begin{ttbox}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   182
Usage: makeall [ARGS ...]
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   183
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   184
  Apply isatool make to all logics (passing ARGS).
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   185
\end{ttbox}
4555
wenzelm
parents: 4540
diff changeset
   186
The arguments \texttt{ARGS} are just passed verbatim to each
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   187
\texttt{make} invocation.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   189
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   190
\section{Running complete logics --- \texttt{isatool usedir}} \label{sec:tool-usedir}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   191
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   192
The \tooldx{usedir} utility builds object-logic images, or runs
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   193
example sessions based on existing logics. Its usage is:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   194
\begin{ttbox}
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   195
Usage: usedir LOGIC NAME
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   196
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   197
  Options are:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   198
    -b           build mode (output heap image, use dir ".")
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   199
    -i BOOL      generate theory browsing information,
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   200
                 i.e. HTML / graph data (default false)
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   201
    -s NAME      override session NAME
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   202
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   203
  Build object-logic or run examples. Also creates browsing
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   204
  information (HTML etc.) according to settings.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   205
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   206
4555
wenzelm
parents: 4540
diff changeset
   207
Note that the value of the \settdx{ISABELLE_USEDIR_OPTIONS} setting is
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   208
implicitly prefixed to \emph{any} \texttt{usedir} call. Since the
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   209
\ttindex{IsaMakefile}s of all object-logics distributed with Isabelle
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   210
just invoke \texttt{usedir} for the real work, one may control
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   211
compilation options globally via above variable. In particular,
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   212
generation of \rmindex{HTML} browsing information is enabled or
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   213
disabled this way.
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   214
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   215
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   216
\subsection*{Options}
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   217
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   218
Basically, there are two different modes of operation: \emph{build
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   219
  mode} (enabled through the \texttt{-b} option) and \emph{example
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   220
  mode} (default).
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   221
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   222
Calling \texttt{usedir} with \texttt{-b} runs \texttt{isabelle} with
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   223
input image \texttt{LOGIC} and output to \texttt{NAME}, as provided on
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   224
the command line. This will be a batch session, running
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   225
\texttt{ROOT.ML} from the current directory and then quitting.  It is
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   226
assumed that \texttt{ROOT.ML} contains all {\ML} commands required to
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   227
build the logic.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   228
4555
wenzelm
parents: 4540
diff changeset
   229
In example mode on the other hand, \texttt{usedir} runs a read-only
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   230
session of \texttt{LOGIC} (typically just built before) and
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   231
automatically runs \texttt{ROOT.ML} from within directory
4555
wenzelm
parents: 4540
diff changeset
   232
\texttt{NAME}.  It assumes that file \texttt{ROOT.ML} in directory
wenzelm
parents: 4540
diff changeset
   233
\texttt{NAME} contains appropriate {\ML} commands to run the desired
wenzelm
parents: 4540
diff changeset
   234
examples.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   235
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   236
\medskip The \texttt{-i} option controls theory browsing data
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   237
generation. It may be explicitely turned on or off --- the last
4555
wenzelm
parents: 4540
diff changeset
   238
occurrence of \texttt{-i} on the command line wins.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   239
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   240
\medskip Any \texttt{usedir} session is named by some \emph{session
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   241
  identifier}. These accumulate, documenting the way sessions depend
4555
wenzelm
parents: 4540
diff changeset
   242
on others. For example, consider \texttt{Pure/FOL/ex}, which refers to
wenzelm
parents: 4540
diff changeset
   243
the examples of {\FOL} which is built upon {\Pure}.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   244
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   245
The current session's identifier is by default just the base name of
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   246
the \texttt{LOGIC} argument (in build mode), or of the \texttt{NAME}
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   247
argument (in example mode). This may be overridden explicitely via the
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   248
\texttt{-s} option.
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   249
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   250
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   251
\subsection*{Examples}
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   252
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   253
Refer to the \texttt{IsaMakefile}s of the Isabelle distribution's
4555
wenzelm
parents: 4540
diff changeset
   254
object-logics as a model for your own developements.  For example, see
wenzelm
parents: 4540
diff changeset
   255
\texttt{src/FOL/IsaMakefile}.
wenzelm
parents: 4540
diff changeset
   256
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   257
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   258
%%% Local Variables: 
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   259
%%% mode: latex
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   260
%%% TeX-master: "system"
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   261
%%% End: