3 \def\isabellecontext{Misc}%
12 \isacommand{theory}\isamarkupfalse%
14 \isakeyword{imports}\ Pure\isanewline
23 \isamarkupchapter{Miscellaneous tools \label{ch:tools}%
27 \begin{isamarkuptext}%
28 Subsequently we describe various Isabelle related utilities, given
29 in alphabetical order.%
33 \isamarkupsection{Displaying documents%
37 \begin{isamarkuptext}%
38 The \indexdef{}{tool}{display}\hypertarget{tool.display}{\hyperlink{tool.display}{\mbox{\isa{\isatt{display}}}}} utility displays documents in DVI or PDF
41 Usage: display [OPTIONS] FILE
44 -c cleanup -- remove FILE after use
46 Display document FILE (in DVI format).
49 \medskip The \verb|-c| option causes the input file to be
50 removed after use. The program for viewing \verb|dvi| files is
51 determined by the \hyperlink{setting.DVI-VIEWER}{\mbox{\isa{\isatt{DVI{\isacharunderscore}VIEWER}}}} setting.%
55 \isamarkupsection{Viewing documentation \label{sec:tool-doc}%
59 \begin{isamarkuptext}%
60 The \indexdef{}{tool}{doc}\hypertarget{tool.doc}{\hyperlink{tool.doc}{\mbox{\isa{\isatt{doc}}}}} utility displays online documentation:
64 View Isabelle documentation DOC, or show list of available documents.
66 If called without arguments, it lists all available documents. Each
67 line starts with an identifier, followed by a short description. Any
68 of these identifiers may be specified as the first argument in order
69 to have the corresponding document displayed.
71 \medskip The \hyperlink{setting.ISABELLE-DOCS}{\mbox{\isa{\isatt{ISABELLE{\isacharunderscore}DOCS}}}} setting specifies the list of
72 directories (separated by colons) to be scanned for documentations.
73 The program for viewing \verb|dvi| files is determined by the
74 \hyperlink{setting.DVI-VIEWER}{\mbox{\isa{\isatt{DVI{\isacharunderscore}VIEWER}}}} setting.%
78 \isamarkupsection{Getting logic images%
82 \begin{isamarkuptext}%
83 The \indexdef{}{tool}{findlogics}\hypertarget{tool.findlogics}{\hyperlink{tool.findlogics}{\mbox{\isa{\isatt{findlogics}}}}} utility traverses all directories
84 specified in \hyperlink{setting.ISABELLE-PATH}{\mbox{\isa{\isatt{ISABELLE{\isacharunderscore}PATH}}}}, looking for Isabelle logic
89 Collect heap file names from ISABELLE_PATH.
92 The base names of all files found on the path are printed --- sorted
93 and with duplicates removed. Also note that lookup in \hyperlink{setting.ISABELLE-PATH}{\mbox{\isa{\isatt{ISABELLE{\isacharunderscore}PATH}}}} includes the current values of \hyperlink{setting.ML-SYSTEM}{\mbox{\isa{\isatt{ML{\isacharunderscore}SYSTEM}}}}
94 and \hyperlink{setting.ML-PLATFORM}{\mbox{\isa{\isatt{ML{\isacharunderscore}PLATFORM}}}}. Thus switching to another ML compiler
95 may change the set of logic images available.%
99 \isamarkupsection{Inspecting the settings environment \label{sec:tool-getenv}%
103 \begin{isamarkuptext}%
104 The Isabelle settings environment --- as provided by the
105 site-default and user-specific settings files --- can be inspected
106 with the \indexdef{}{tool}{getenv}\hypertarget{tool.getenv}{\hyperlink{tool.getenv}{\mbox{\isa{\isatt{getenv}}}}} utility:
108 Usage: getenv [OPTIONS] [VARNAMES ...]
111 -a display complete environment
112 -b print values only (doesn't work for -a)
114 Get value of VARNAMES from the Isabelle settings.
117 With the \verb|-a| option, one may inspect the full process
118 environment that Isabelle related programs are run in. This usually
119 contains much more variables than are actually Isabelle settings.
120 Normally, output is a list of lines of the form \isa{name}\verb|=|\isa{value}. The \verb|-b| option
121 causes only the values to be printed.%
125 \isamarkupsubsubsection{Examples%
129 \begin{isamarkuptext}%
130 Get the ML system name and the location where the compiler binaries
131 are supposed to reside as follows:
133 isatool getenv ML_SYSTEM ML_HOME
134 {\out ML_SYSTEM=polyml}
135 {\out ML_HOME=/usr/share/polyml/x86-linux}
138 The next one peeks at the output directory for Isabelle logic
141 isatool getenv -b ISABELLE_OUTPUT
142 {\out /home/me/isabelle/heaps/polyml_x86-linux}
144 Here we have used the \verb|-b| option to suppress the
145 \verb|ISABELLE_OUTPUT=| prefix. The value above is what
146 became of the following assignment in the default settings file:
148 ISABELLE_OUTPUT="\$ISABELLE_HOME_USER/heaps"
151 Note how the \hyperlink{setting.ML-IDENTIFIER}{\mbox{\isa{\isatt{ML{\isacharunderscore}IDENTIFIER}}}} value got appended
152 automatically to each path component. This is a special feature of
153 \hyperlink{setting.ISABELLE-OUTPUT}{\mbox{\isa{\isatt{ISABELLE{\isacharunderscore}OUTPUT}}}}.%
157 \isamarkupsection{Installing standalone Isabelle executables \label{sec:tool-install}%
161 \begin{isamarkuptext}%
162 By default, the Isabelle binaries (\hyperlink{executable.isabelle}{\mbox{\isa{\isatt{isabelle}}}},
163 \hyperlink{executable.isatool}{\mbox{\isa{\isatt{isatool}}}} etc.) are just run from their location within
164 the distribution directory, probably indirectly by the shell through
165 its \verb|PATH|. Other schemes of installation are supported
166 by the \indexdef{}{tool}{install}\hypertarget{tool.install}{\hyperlink{tool.install}{\mbox{\isa{\isatt{install}}}}} utility:
168 Usage: install [OPTIONS]
171 -d DISTDIR use DISTDIR as Isabelle distribution
172 (default ISABELLE_HOME)
173 -p DIR install standalone binaries in DIR
175 Install Isabelle executables with absolute references to the current
176 distribution directory.
179 The \verb|-d| option overrides the current Isabelle
180 distribution directory as determined by \hyperlink{setting.ISABELLE-HOME}{\mbox{\isa{\isatt{ISABELLE{\isacharunderscore}HOME}}}}.
182 The \verb|-p| option installs executable wrapper scripts for
183 \hyperlink{executable.isabelle}{\mbox{\isa{\isatt{isabelle}}}}, \hyperlink{executable.isatool}{\mbox{\isa{\isatt{isatool}}}}, \hyperlink{executable.Isabelle}{\mbox{\isa{\isatt{Isabelle}}}}, containing proper absolute references to the Isabelle
184 distribution directory. A typical \verb|DIR| specification
185 would be some directory expected to be in the shell's \verb|PATH|, such as \verb|/usr/local/bin|. It is important to
186 note that a plain manual copy of the original Isabelle executables
187 does not work, since it disrupts the integrity of the Isabelle
192 \isamarkupsection{Creating instances of the Isabelle logo%
196 \begin{isamarkuptext}%
197 The \indexdef{}{tool}{logo}\hypertarget{tool.logo}{\hyperlink{tool.logo}{\mbox{\isa{\isatt{logo}}}}} utility creates any instance of the generic
198 Isabelle logo as an Encapsuled Postscript file (EPS):
200 Usage: logo [OPTIONS] NAME
202 Create instance NAME of the Isabelle logo (as EPS).
205 -o OUTFILE set output file (default determined from NAME)
208 You are encouraged to use this to create a derived logo for your
209 Isabelle project. For example, \verb|isatool logo Bali|
210 creates \verb|isabelle_bali.eps|.%
214 \isamarkupsection{Isabelle's version of make \label{sec:tool-make}%
218 \begin{isamarkuptext}%
219 The Isabelle \indexdef{}{tool}{make}\hypertarget{tool.make}{\hyperlink{tool.make}{\mbox{\isa{\isatt{make}}}}} utility is a very simple wrapper for
220 ordinary Unix \hyperlink{executable.make}{\mbox{\isa{\isatt{make}}}}:
222 Usage: make [ARGS ...]
224 Compile the logic in current directory using IsaMakefile.
225 ARGS are directly passed to the system make program.
228 Note that the Isabelle settings environment is also active. Thus one
229 may refer to its values within the \verb|IsaMakefile|, e.g.\
230 \verb|$(ISABELLE_OUTPUT)|. Furthermore, programs started from
231 the make file also inherit this environment. Typically, \verb|IsaMakefile|s defer the real work to the \indexref{}{tool}{usedir}\hyperlink{tool.usedir}{\mbox{\isa{\isatt{usedir}}}} utility.
233 \medskip The basic \verb|IsaMakefile| convention is that the
234 default target builds the actual logic, including its parents if
235 appropriate. The \verb|images| target is intended to build all
236 local logic images, while the \verb|test| target shall build
237 all related examples. The \verb|all| target shall do
238 \verb|images| and \verb|test|.%
242 \isamarkupsubsubsection{Examples%
246 \begin{isamarkuptext}%
247 Refer to the \verb|IsaMakefile|s of the Isabelle distribution's
248 object-logics as a model for your own developments. For example,
249 see \verb|src/FOL/IsaMakefile|.%
253 \isamarkupsection{Make all logics%
257 \begin{isamarkuptext}%
258 The \indexdef{}{tool}{makeall}\hypertarget{tool.makeall}{\hyperlink{tool.makeall}{\mbox{\isa{\isatt{makeall}}}}} utility applies Isabelle make to all logic
259 directories of the distribution:
261 Usage: makeall [ARGS ...]
263 Apply isatool make to all logics (passing ARGS).
266 The arguments \verb|ARGS| are just passed verbatim to each
267 \hyperlink{tool.make}{\mbox{\isa{\isatt{make}}}} invocation.%
271 \isamarkupsection{Printing documents%
275 \begin{isamarkuptext}%
276 The \indexdef{}{tool}{print}\hypertarget{tool.print}{\hyperlink{tool.print}{\mbox{\isa{\isatt{print}}}}} utility prints documents:
278 Usage: print [OPTIONS] FILE
281 -c cleanup -- remove FILE after use
286 The \verb|-c| option causes the input file to be removed
287 after use. The printer spool command is determined by the \hyperlink{setting.PRINT-COMMAND}{\mbox{\isa{\isatt{PRINT{\isacharunderscore}COMMAND}}}} setting.%
291 \isamarkupsection{Run Isabelle with plain tty interaction \label{sec:tool-tty}%
295 \begin{isamarkuptext}%
296 The \indexdef{}{tool}{tty}\hypertarget{tool.tty}{\hyperlink{tool.tty}{\mbox{\isa{\isatt{tty}}}}} utility runs the Isabelle process interactively
297 within a plain terminal session:
302 -l NAME logic image name (default ISABELLE_LOGIC)
303 -m MODE add print mode for output
304 -p NAME line editor program name (default ISABELLE_LINE_EDITOR)
306 Run Isabelle process with plain tty interaction, and optional line editor.
309 The \verb|-l| option specifies the logic image. The
310 \verb|-m| option specifies additional print modes. The The
311 \verb|-p| option specifies an alternative line editor (such
312 as the \hyperlink{executable.rlwrap}{\mbox{\isa{\isatt{rlwrap}}}} wrapper for GNU readline); the fall-back
313 is to use raw standard input.%
317 \isamarkupsection{Remove awkward symbol names from theory sources%
321 \begin{isamarkuptext}%
322 The \indexdef{}{tool}{unsymbolize}\hypertarget{tool.unsymbolize}{\hyperlink{tool.unsymbolize}{\mbox{\isa{\isatt{unsymbolize}}}}} utility tunes Isabelle theory sources to
323 improve readability for plain ASCII output (e.g.\ in email
324 communication). Most notably, \hyperlink{tool.unsymbolize}{\mbox{\isa{\isatt{unsymbolize}}}} replaces awkward
325 arrow symbols such as \verb|\|\verb|<Longrightarrow>|
328 Usage: unsymbolize [FILES|DIRS...]
330 Recursively find .thy/.ML files, removing unreadable symbol names.
331 Note: this is an ad-hoc script; there is no systematic way to replace
332 symbols independently of the inner syntax of a theory!
334 Renames old versions of FILES by appending "~~".
339 \isamarkupsection{Output the version identifier of the Isabelle distribution%
343 \begin{isamarkuptext}%
344 The \indexdef{}{tool}{version}\hypertarget{tool.version}{\hyperlink{tool.version}{\mbox{\isa{\isatt{version}}}}} utility outputs the full version string of
345 the Isabelle distribution being used, e.g.\ ``\verb|Isabelle2008: June 2008|. There are no options nor arguments.%
349 \isamarkupsection{Convert XML to YXML%
353 \begin{isamarkuptext}%
354 The \indexdef{}{tool}{yxml}\hypertarget{tool.yxml}{\hyperlink{tool.yxml}{\mbox{\isa{\isatt{yxml}}}}} tool converts a standard XML document (stdin)
355 to the much simpler and more efficient YXML format of Isabelle
356 (stdout). The YXML format is defined as follows.
360 \item The encoding is always UTF-8.
362 \item Body text is represented verbatim (no escaping, no special
363 treatment of white space, no named entities, no CDATA chunks, no
366 \item Markup elements are represented via ASCII control characters
367 \isa{{\isachardoublequote}\isactrlbold X\ {\isacharequal}\ {\isadigit{5}}{\isachardoublequote}} and \isa{{\isachardoublequote}\isactrlbold Y\ {\isacharequal}\ {\isadigit{6}}{\isachardoublequote}} as follows:
371 \verb|<|\isa{{\isachardoublequote}name\ attribute{\isachardoublequote}}\verb|=|\isa{{\isachardoublequote}value\ {\isasymdots}{\isachardoublequote}}\verb|>| &
372 \isa{{\isachardoublequote}\isactrlbold X\isactrlbold Yname\isactrlbold Yattribute{\isachardoublequote}}\verb|=|\isa{{\isachardoublequote}value{\isasymdots}\isactrlbold X{\isachardoublequote}} \\
373 \verb|</|\isa{name}\verb|>| & \isa{{\isachardoublequote}\isactrlbold X\isactrlbold Y\isactrlbold X{\isachardoublequote}} \\
376 There is no special case for empty body text, i.e.\ \verb|<foo/>| is treated like \verb|<foo></foo>|. Also note that
377 \isa{{\isachardoublequote}\isactrlbold X{\isachardoublequote}} and \isa{{\isachardoublequote}\isactrlbold Y{\isachardoublequote}} may never occur in
378 well-formed XML documents.
382 Parsing YXML is pretty straight-forward: split the text into chunks
383 separated by \isa{{\isachardoublequote}\isactrlbold X{\isachardoublequote}}, then split each chunk into
384 sub-chunks separated by \isa{{\isachardoublequote}\isactrlbold Y{\isachardoublequote}}. Markup chunks start
385 with an empty sub-chunk, and a second empty sub-chunk indicates
386 close of an element. Any other non-empty chunk consists of plain
389 YXML documents may be detected quickly by checking that the first
390 two characters are \isa{{\isachardoublequote}\isactrlbold X\isactrlbold Y{\isachardoublequote}}.%
399 \isacommand{end}\isamarkupfalse%
410 %%% TeX-master: "root"