The IDE provides the following functionality with a simple graphical
interface:

• Managing specifications
• A TLA+ specification editor with features like:
  • SANY integration
  • Syntax Highlighting
  • Basic content assist
  • Error markers
• PlusCal translation
• Displaying a pretty-printed PDF version using TLATeX
• The TLC Model Checker, with:
  • A simple interface for managing models
  • A rich model editor
  • An extended TLC result display
  • A cool trace explorer
• The TLAPS proof system, with features for:
  • Viewing and editing hierarchical proofs
  • Running the prover (soon to be released)
  • Displaying the status of proofs (soon to be released)

See the TLA Toolbox page for more details.

In order to enhance the user experience with the tools and simplify the access to the languages some improvements are being developed in the scope of the project run by Microsoft Research and INRIA. Along with the focus on the proof aspect of TLA+, the development of a complete Integrated Development Environment (IDE) for writing and debugging of specifications has been identified as a project goal. The IDE unifies the editors for specifications and models with already existing TLA+ tools for syntax analyze, PlusCal translation and model checking in one application. It includes the console-based TLA+ Tools and enables the use of their whole functionality via rich graphical user interface.

The IDE is currently being finalized and will be available soon. It will include:

• Simple interface for managing specifications
• Integrated TLA+ specification editor with features like:
  • SANY integration
  • Syntax Highlighting
  • Basic content assist
  • Error marker support
  • and others
• PlusCal Translator integration
• TLC Model Checker integration
  • Simple interface for managing models
  • Rich model editor
  • Extended TLC result display
  • Trace Explorer
  • and others…

Stay tuned for the TLA+ Toolbox release…

The command line switches are detected, by the fact that they begin with a ‘-’ character. Once the first command line element that is not a switch is encountered, the rest are presumed to be file names.

SANY, the Syntax Analyzer

java tla2sany.SANY [-S] [-L] [-D] [-STAT] FILES

where FILES is a list of modules separated by spaces and

• -S: disable semantic analysis
• -L: disable level checking
• -D: enable debugging
• -STAT: print statistics

The switches are useful for finding errors in SANY ony and are not providing particular helpful features for the user.

TLC, the Model Checker

The model checker (TLC) provides the following functionalities:

• Model checking of TLA+ specs
• Simulation of TLA+ specs

The program can be executed by typing the following to the console

java tlc2.TLC [GENERAL-SWITCHES] [MODE-SWITCHES] SPEC

where SPEC is the name of the specification’s root module (the .tla extension can be omitted) and the optional GENERAL-SWITCHES are:

• -cleanup: clean up the states directory
• -config file: provide the config file. Defaults to .cfg if not provided.
• -continue: continue running even when invariant is violated. Defaults to stop at the first violation if not specified.
• -coverage minutes: collect coverage information on the spec, print out the information every minutes. Defaults to no coverage if not specified.
• -deadlock: do not check for deadlock. Defaults to checking deadlock if not specified.
• -difftrace: when printing trace, show only the differences between successive states. Defaults to printing full state descriptions if not specified.
• -dump file: dump all the states into file
• -fp num: use the num’th irreducible polynomial from the list stored in the class FP64.
• -gzip: control if gzip is applied to value input/output stream. Defaults to use gzip.
• -metadir path: store metadata in the directory at path. Defaults to specdir/states if not specified.
• -nowarning: disable all the warnings. Defaults to report warnings if not specified
• -recover path: recover from the checkpoint at path. Defaults to scratch run if not specified.
• -terse: do not expand values in Print statement. Defaults to expand value if not specified.
• -workers num: the number of TLC worker threads. Defaults to 1.

By default TLC starts in the model checking mode using breadth-first approach for state space exploration. This can be changed using the MODE-SWITCHES. In contrast to the GENERAL-SWITCHES these can be used if applied in certain combinations only:

{[-dfid num][ -view]|-simulate[ -depth num][ -aril num][ -seed num]}

• -modelcheck: run model checking and explore the state space in breadth first manner. This is a default mode.
• -dfid num: run model checking and use depth-first iterative deepening with initial depth num
• -view: apply VIEW (if provided) when printing out states. Applicable only in model checking mode.
• -simulate: run simulation
• -depth num: specify the depth of random simulation. Defaults to 100 if not specified, relevant for simulation mode only.
• -seed num: provide the seed for random simulation. Defaults to a random seed if not specified, relevant for simulation mode only.
• -aril num: adjust the seed for random simulation. Defaults to 0 if not specified, relevant for simulation mode only.

PlusCal, the Translator

The PlusCal translator translates a PlusCal algorithm into a TLA+ specification. The translator is called by typing

java pcal.trans [SWITCHES] SPEC

where SPEC is a TLA+ file (the extension .tla need not be typed)
containing the algorithm. See the PlusCal manual for an explanation of
what the TLA+ file must contain. The possible options are

• -help: Prints out the usage instead of running the translator.
• -wf: Conjoin to formula Spec weak fairness of each process’s next-state action
• -sf: Conjoin to formula Spec strong fairness of each process’s next-state action
• -wfNext: Conjoin to formula Spec weak fairness of the entire next-state action
• -nof: Conjoin no fairness formula to Spec. This is the default, except when the -termination option is chosen.
• -termination: Add to the .cfg file the command PROPERTY Termination With this option, the default fairness option becomes -wf.
• -nocfg: Suppress writing of the .cfg file.
• -label: Tells the translator to add missing labels. This is the default only for a uniprocess algorithm in which the user has typed no labels.
• -reportLabels: True if the translator should print the names and locations of all labels it adds. Like -label, it tells the translator to add missing labels.
• -labelRoot name: If the translator adds missing labels, it names them name1, name2, etc. The default value is “Lbl_”.
• -unixEOL: Forces the use of Unix end-of-line convention, regardless of the system’s default. Without this, when run on Windows, the files it writes seem to have a “^M” at the end of every line when viewed with Emacs.
• -debug: This is useful only for maintainers of the program and has no effect on normal execution.
• -reportLabels: True if the translator should print the names and locations of all labels it adds. Like -label, it tells the translator to add missing labels.
• -lineWidth: The translation tries to perform the translation so lines have this maximum width. (It will often fail.) Default is 78, minimum value is 60.
• -version: The version of PlusCal for which this algorithm is written. If the language is ever changed to make algorithms written for earlier versions no longer legal, then the translator should do the appropriate thing when the earlier version number is specified.

Starting with Version 1.5, the following options no longer work. They can be used only if the -version 1.4 option is also used. Moreover, the -writeAST option does not work from the Toolbox. If there is any demand, these options may be made to work again in later versions.

• -spec name: Uses TLC and the TLA+ specification name.tla to do the translation. It copies the files name.tla and name.cfg from the directory containing the translator’s Java source files to the current directory; it writes in the current director the file AST.tla that defines `fairness’ to equal the fairness option and `ast’ to equal the the AST data structure representing the algorithm; and it runs TLC on name.tla to produce the translation.
• -myspec name: Like -spec, except it finds the files names.tla and names.cfg in the current directory, instead of writing them there.
• -spec2 name: Like -spec, except it uses TLC2 insead of the old version of TLC (aka TLC1).
• -myspec2 name: Like -myspec, except it uses TLC2 instead of TLC (aka TLC1).
• -writeAST: Writes the AST file as in the -spec option, but does not perform the translation.

Installation on Windows

Choose (or create) a folder into which you want to put the tools and unzip the downloaded file into it. Suppose your folder is c:\user\myfolder, the sub folder named tla will be created in it, which contains the tools. Add c:\user\myfolder\tla to your CLASSPATH environment variable. How you do that depends on what version of Windows you’re using:

Non-Ancient Versions of Windows

Open Start > Settings > ControlPanel. On the Control Panel, open System, click on Advanced tab and open the Environment Variables, then look for the CLASSPATH variable among user or system variables. If it exists, append ;c:\user\myfolder\tla to the end of its value. If not, create a new CLASSPATH variable whose value is c:\user\myfolder\tla.

Windows 95 (and MS-DOS)

Modify your AUTOEXEC.BAT file. If there is a command
set CLASSPATH = c:\foo\bar;d:\myjava\files
then change it to
set CLASSPATH = c:\foo\bar;d:\myjava\files;c:\user\myfolder\tla
If there is no such command in the file, then add
set CLASSPATH = c:\user\myfolder\tla
to your AUTOEXEC.BAT file.

Installation on UNIX

Choose (or create) a directory into which you want to put the tools and unzip the downloaded file into that directory. Suppose that your directory is /udir/user/mydir, the sub directory named tla will be created in it, which contains the tools. Add /udir/user/mydir/tla to the CLASSPATH environment variable. Assuming you’re running the C-shell or some derivative, you do this by typing
setenv CLASSPATH /udir/user/mydir/tla
However, you’ll probably want to have the CLASSPATH variable set automatically when you login. To do this, your .login or .csh file must contain a command to set that variable. If a command
setenv CLASSPATH ...
already exists in your .login or .csh file, just add the command
setenv CLASSPATH $CLASSPATH":/udir/user/mydir/tla"
after it. Otherwise, just add the command
setenv CLASSPATH /udir/user/mydir/tla

Validation of the installation

In order to validate if the TLA+ tools has been successfully installed, first create a file test.tla and paste the following content into it:

---- MODULE test ----
====

Then open the console (Start > Run > cmd on Windows) in the directory, the file is located in and type: java tla2sany.SANY test. If you did everything right, you should see:

****** SANY2 Version .91 created 10 April 2008
Parsing file test.tla
Semantic processing of module test

If you see

Exception in thread "main" java.lang.NoClassDefFoundError: tla2sany/SANY
Caused by: java.lang.ClassNotFoundException: tla2sany.SANY
        at java.net.URLClassLoader$1.run(URLClassLoader.java:200)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:307)
        at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:252)
        at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:320)
Could not find the main class: tla2sany.SANY.  Program will exit.

you probably misspelled the CLASSPATH. If you see something like:

'java' is not recognized as an internal or external command,
operable program or batch file.

you are missing the JRE.

Running from a script

In some scenarios, setting up the global CLASSPATH variable is not desirable. In this case it is possible to create scripts for each tool which set the CLASSPATH only for the execution. Here is an example script for calling SANY on Windows:

set TLA_PATH=c:/tools/tla2
java -cp %TLA_PATH% tla2sany.SANY %1 %2 %3 %4

The script should be invoked with the name of the TLA file.