CADiZ

Tutorial guides / Running cadiz


This tutorial assumes that you have already prepared a Z specification for cadiz using either the LaTeX mark-up or the troff mark-up.

Contents of this page

Initial preparation

We must first tell the shell (command interpreter) where to look to find the cadiz program. Assuming your shell is the standard Bourne shell, /bin/sh, and $CADIZ is the name of the directory in which the CADi\num system has been installed on your machine, this is done by setting the PATH environment variable as follows. If you have chosen to use a different shell command language, then it is up to you to translate these commands appropriately. You should either replace the $CADIZ part by the actual pathname, including the relevant release name, or ensure that there is already a CADIZ environment variable set to that pathname.

PATH=$CADIZ/mip/bin:$PATH export PATH

This makes the shell look in the mip/bin directory of the CADi\num release first, then in all the other places where it had already been told to look. The above commands are best placed in a script that is run whenever you login, for example .profile in the case of Bourne shell, so that you never have to type these commands again.

Whether cadiz expects to be given LATEX mark-up or troff mark-up is determined by the value of the MARKUP environment variable: cadiz does not work out what the mark-up is for itself. The default value is groff, indicating troff mark-up. You should set it to latex if you are using LATEX mark-up. If you are never going to use troff mark-up, or if you at least want latex to be the default, you could set MARKUP in your login profile.

MARKUP=latex export MARKUP

If you are using LATEX mark-up, you will have to tell latex where to find the cadiz-related style files. The following command, which is best placed in your login profile, does this.

TEXINPUTS=$TEXINPUTS:$CADIZ/mip/lib export TEXINPUTS

If you are using a networked workstation and choose to run cadiz on a remote server, rather than on the workstation itself, then you must arrange for cadiz's windows to appear on your local screen. On the local workstation, give the following command to grant the remote machine permission to create the windows, substituting the name of the remote machine for remotename.

xhost +remotename

On the remote machine, give the following command to tell it on which workstation to create the windows, substituting the name of your workstation for localname.

DISPLAY=localname:0.0 export DISPLAY

The :0.0 part identifies the default X server, which will probably be appropriate.

That should be sufficient preparation for most initial use of cadiz. The reference manual gives details of some other environment variables for use in sophisticated circumstances.

Running cadiz

Having done the initial preparations described above, your Z specification should be prepared in a file whose name has as suffix either .z or (only in the case of LATEX mark-up) .tex, for example spec.z. You can then use cadiz in any of several modes. This section lists those modes, then subsequent sections consider use of the modes in performing typical tasks. The first three modes are the most frequently used ones.

Verify mode

All modes of running cadiz cause the specification to be typechecked. The one that doesn't do anything else, and so is the quickest, is the -v mode. In this mode, any reports about the specification from cadiz are written to its standard output.

cadiz -v spec

If no output appears, or if all the messages start with the word Warning, then you have not made any errors in your use of the Z notation (but that doesn't imply that the specification means what you intended).

Examine mode

The specification is typechecked, typeset and displayed by the -x mode. Any reports from typechecking are displayed in another window alongside the specification. The typeset specification is left in a file whose name ends in .dit for example spec.dit.

cadiz -x spec

The examine mode lets an author cross-reference any reports from cadiz with their contexts in the typeset view of the specification. It is also useful for readers of specifications, as it eases the location of referenced declarations.

xmode

Proof mode

The specification is typechecked, typeset and displayed by the -P mode. Any reports from typechecking are displayed in another window alongside the specification, which is also used for displaying goals in proofs. A third window displays a proof tree showing the structure of the current proof.

cadiz -P spec

The proof mode offers everything that the examine mode offers and more, such as interactive investigation of conjectures.

Pmode

Browse mode

The specification is typechecked and displayed by the -b mode - an already typeset .dit file is required for this mode.

cadiz -b spec

The browse mode offers the same functionality as the -x mode, but avoids the re-typesetting of an already-typeset specification.

Typeset mode

By default, i.e. without any mode option, cadiz typechecks and typesets the specification, writing any reports to standard output, and saving the typeset specification in a file whose name ends in .dit for example spec.dit.

cadiz spec

The default mode provides a way of typesetting the specification without any interaction with windows.

Preview mode

The specification is typechecked, typeset and displayed by the -p mode. Any reports from typechecking are written to the standard output.

cadiz -p spec

The preview mode is rarely used, as it does not permit interactive browsing of the specification.

Error mode

The specification is typechecked by the -e mode, and any reports are displayed in a window.

cadiz -e spec

The error mode may be found preferable to the verify mode in cases where the reports involve mathematical symbols, as it shows their typeset form rather than their mark-up.

Other command-line options

Only one of the above mode options can be used with each invocation of cadiz. There are other options that are applicable in various modes, and which affect the behaviour of cadiz. None of them are needed for elementary use of cadiz; a full list of command-line options may be found in the reference manual.


IT 21-Oct-2000