doc-src/System/misc.tex
author paulson
Fri, 27 Nov 1998 13:13:22 +0100
changeset 5980 2e9314c07146
parent 5571 3613c5d22cc6
child 6414 d1bbea22217b
permissions -rw-r--r--
added Real/Hyperreal
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
5405
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   116
\section{Installing standalone Isabelle binaries -- \texttt{isatool install}}
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   117
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   118
Usually, the Isabelle binaries (\texttt{isabelle}, \texttt{isatool}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   119
etc.) are just run from their location within the distribution
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   120
directory, probably indirectly by the shell through its \texttt{PATH}.
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   121
In some cases, though, another more traditional installation scheme
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   122
might be preferably where executables are put into some global system
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   123
directory (like \texttt{/usr/local/bin}).
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   124
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   125
Doing a plain copy of the Isabelle executables just would not work,
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   126
though.  One should use the \tooldx{install} utility instead:
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   127
\begin{ttbox}
5405
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   128
Usage: install BINDIR
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   129
5405
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   130
  Options are:
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   131
    -d DISTDIR   use DISTDIR as Isabelle distribution
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   132
                 (default ISABELLE_HOME)
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   133
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   134
  Install standalone Isabelle binaries in directory BINDIR with absolute
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   135
  references to DISTDIR/bin, which becomes non-relocatable this way.
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   136
\end{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   137
5405
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   138
This installs standalone executables in \texttt{BINDIR} containing
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   139
absolute references to \texttt{DISTDIR} (the default is
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   140
\texttt{ISABELLE_HOME} as figured out by the current \texttt{isatool}
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   141
invocation).  While the generated scripts themselves may be relocated
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   142
afterwards, they cease working if the referenced Isabelle distribution
2ecb74e65439 tuned isatool install;
wenzelm
parents: 5366
diff changeset
   143
is moved somewhere else.  Here is an example use of \texttt{install}:
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   144
\begin{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   145
  isatool install /usr/local/bin
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   146
\end{ttbox}
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   147
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   148
5571
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   149
\section{Creating instances of the Isabelle logo -- \texttt{isatool
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   150
    logo}}
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   151
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   152
The \tooldx{logo} utility creates any instance of the generic Isabelle logo as
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   153
an Encapsuled Postscript file (EPS):
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   154
\begin{ttbox}
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   155
Usage: logo [OPTIONS] NAME
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   156
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   157
  Create instance NAME of the Isabelle logo (as EPS).
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   158
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   159
  Options are:
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   160
    -o OUTFILE   set output file (default determined from NAME)
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   161
    -q           quiet mode
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   162
\end{ttbox}
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   163
You are encouraged to use this to create a derived logo for your Isabelle
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   164
project.  For example, \texttt{isatool logo HOOL} creates
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   165
\texttt{isabelle_hool.eps}.
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   166
3613c5d22cc6 added isatool logo;
wenzelm
parents: 5405
diff changeset
   167
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   168
\section{Isabelle's version of make --- \texttt{isatool make}}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   169
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   170
The Isabelle \tooldx{make} utility is a very simple wrapper for
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   171
ordinary Unix \texttt{make}:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   172
\begin{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   173
Usage: isatool make [ARGS ...]
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   174
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   175
  Compiles logic in current directory using IsaMakefile.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   176
  ARGS are directly passed to the system make program.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   177
\end{ttbox}
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   178
Note that the Isabelle settings environment is also active. Thus one
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   179
may refer to its values within the \ttindex{IsaMakefile}, e.g.\ 
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   180
\texttt{\$(ISABELLE_OUTPUT)}. Furthermore, programs started from the
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   181
make file also inherit this environment.  Typically,
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   182
\texttt{IsaMakefile}s defer the real work to the \texttt{usedir}
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   183
utility, see \S\ref{sec:tool-usedir}.
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   184
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   185
\medskip The basic \texttt{IsaMakefile} convention is that the default
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   186
target builds the actual logic, including its parents if appropriate.
4555
wenzelm
parents: 4540
diff changeset
   187
The \texttt{images} target is intended to build all local logic
wenzelm
parents: 4540
diff changeset
   188
images, while the \texttt{test} target shall build all related
wenzelm
parents: 4540
diff changeset
   189
examples.  The \texttt{all} target shall do \texttt{images} and
wenzelm
parents: 4540
diff changeset
   190
\texttt{test}.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   191
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   192
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   193
\subsection*{Examples}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   194
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   195
Refer to the \texttt{IsaMakefile}s of the Isabelle distribution's
4555
wenzelm
parents: 4540
diff changeset
   196
object-logics as a model for your own developements.  For example, see
wenzelm
parents: 4540
diff changeset
   197
\texttt{src/FOL/IsaMakefile}.
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   198
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   199
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   200
\section{Make all logics -- \texttt{isatool makeall}}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   201
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   202
The \tooldx{makeall} utility applies Isabelle make to all logic
4555
wenzelm
parents: 4540
diff changeset
   203
directories of the distribution:
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   204
\begin{ttbox}
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   205
Usage: makeall [ARGS ...]
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   206
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   207
  Apply isatool make to all logics (passing ARGS).
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   208
\end{ttbox}
4555
wenzelm
parents: 4540
diff changeset
   209
The arguments \texttt{ARGS} are just passed verbatim to each
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   210
\texttt{make} invocation.
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   211
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   212
3217
d30d62128fe5 still under construction!
wenzelm
parents: 3188
diff changeset
   213
\section{Running complete logics --- \texttt{isatool usedir}} \label{sec:tool-usedir}
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   214
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   215
The \tooldx{usedir} utility builds object-logic images, or runs
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   216
example sessions based on existing logics. Its usage is:
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   217
\begin{ttbox}
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   218
Usage: usedir LOGIC NAME
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   219
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   220
  Options are:
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   221
    -b           build mode (output heap image, use dir ".")
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   222
    -i BOOL      generate theory browsing information,
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   223
                 i.e. HTML / graph data (default false)
3188
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   224
    -s NAME      override session NAME
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   225
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   226
  Build object-logic or run examples. Also creates browsing
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   227
  information (HTML etc.) according to settings.
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   228
\end{ttbox}
445555a7b714 preliminary!
wenzelm
parents:
diff changeset
   229
4555
wenzelm
parents: 4540
diff changeset
   230
Note that the value of the \settdx{ISABELLE_USEDIR_OPTIONS} setting is
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   231
implicitly prefixed to \emph{any} \texttt{usedir} call. Since the
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   232
\ttindex{IsaMakefile}s of all object-logics distributed with Isabelle
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   233
just invoke \texttt{usedir} for the real work, one may control
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   234
compilation options globally via above variable. In particular,
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   235
generation of \rmindex{HTML} browsing information is enabled or
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   236
disabled this way.
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   237
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   238
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   239
\subsection*{Options}
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   240
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   241
Basically, there are two different modes of operation: \emph{build
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   242
  mode} (enabled through the \texttt{-b} option) and \emph{example
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   243
  mode} (default).
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   244
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   245
Calling \texttt{usedir} with \texttt{-b} runs \texttt{isabelle} with
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   246
input image \texttt{LOGIC} and output to \texttt{NAME}, as provided on
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   247
the command line. This will be a batch session, running
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   248
\texttt{ROOT.ML} from the current directory and then quitting.  It is
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   249
assumed that \texttt{ROOT.ML} contains all {\ML} commands required to
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   250
build the logic.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   251
4555
wenzelm
parents: 4540
diff changeset
   252
In example mode on the other hand, \texttt{usedir} runs a read-only
4540
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   253
session of \texttt{LOGIC} (typically just built before) and
24fcf5ecae88 updated to Isabelle98;
wenzelm
parents: 3752
diff changeset
   254
automatically runs \texttt{ROOT.ML} from within directory
4555
wenzelm
parents: 4540
diff changeset
   255
\texttt{NAME}.  It assumes that file \texttt{ROOT.ML} in directory
wenzelm
parents: 4540
diff changeset
   256
\texttt{NAME} contains appropriate {\ML} commands to run the desired
wenzelm
parents: 4540
diff changeset
   257
examples.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   258
3752
7ae403333ec6 Updated usage information for tool "usedir".
berghofe
parents: 3278
diff changeset
   259
\medskip The \texttt{-i} option controls theory browsing data
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   260
generation. It may be explicitely turned on or off --- the last
4555
wenzelm
parents: 4540
diff changeset
   261
occurrence of \texttt{-i} on the command line wins.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   263
\medskip Any \texttt{usedir} session is named by some \emph{session
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   264
  identifier}. These accumulate, documenting the way sessions depend
4555
wenzelm
parents: 4540
diff changeset
   265
on others. For example, consider \texttt{Pure/FOL/ex}, which refers to
wenzelm
parents: 4540
diff changeset
   266
the examples of {\FOL} which is built upon {\Pure}.
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   267
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   268
The current session's identifier is by default just the base name of
3278
636322bfd057 release version (sort of);
wenzelm
parents: 3262
diff changeset
   269
the \texttt{LOGIC} argument (in build mode), or of the \texttt{NAME}
3262
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   270
argument (in example mode). This may be overridden explicitely via the
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   271
\texttt{-s} option.
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   272
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   273
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   274
\subsection*{Examples}
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   275
7115da553895 under construction;
wenzelm
parents: 3217
diff changeset
   276
Refer to the \texttt{IsaMakefile}s of the Isabelle distribution's
4555
wenzelm
parents: 4540
diff changeset
   277
object-logics as a model for your own developements.  For example, see
wenzelm
parents: 4540
diff changeset
   278
\texttt{src/FOL/IsaMakefile}.
wenzelm
parents: 4540
diff changeset
   279
5366
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   280
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   281
%%% Local Variables: 
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   282
%%% mode: latex
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   283
%%% TeX-master: "system"
8521cd8b0a40 emacs local vars;
wenzelm
parents: 4555
diff changeset
   284
%%% End: