Development Environment for ISAC core

First a note on the relation between ISAC development and Isabelle development: Between 2002 and 2009 ISAC focused on development of its own frontend and kept ISAC's core (the mathematics engine) within Isabelle2002. Updating ISAC's core to Isabelle2009 was extremely hard, because so much had changed in Isabelle. Since 2013 ISAC regularly updated to Isabelle's official releases and since then strives for integration into Isabelle.

In 2014 Isabelle dropped the tty interface, which is used by ISAC's mathematics engine to communicate with ISAC's frontend. Since ISAC requires session management for groups of students, ISAC will stay with its own frontend until Isabelle becomes a session management as well (when integrating collaborative development as we hope).

Below you find steps, how to setup the isac core for development within Isabelle's development environment and within Isac's repository. These steps (beginning with (2)) are also appropriate, if ISAC has been updated to a new Isabelle version: with the new Isabelle-bundles creating the development environment from scratch is easier than updating.

Step 1: Install auxiliary software
The development of Isabelle/Isac cooperates with Isabelle and thus uses the same software components.

If you install to Windows, the version management system Mercurial is already contained in cygwin and you can skip the first point and go to Step 2.


 * (1.1) Download Mercurial, our source control management tool.

$ hg causes a message beginning with Mercurial Distributed SCM basic commands: add       add the specified files on ...     ...
 * (1.2) Check the installation of Mercurial by typing

[ui] username = N.N.  [extensions] hgext.extdiff = hgext.fetch= [extdiff] cmd.opendiff = meld [defaults] fetch = -m "merged"
 * (1.3) Install a diff-tool, for instance "meld" (which you find called in Mercurial's "hgrc" below). This tool is required by Mercurial's merging. This is the recommended template /etc/mercurial/hgrc:
 * 1) system-wide mercurial configuration file
 * 2) See hgrc(5) for more information


 * (1.4) Install TortoiseHg as a tool for inspection of local Mercurial repositories (see Policies_of_repository_usage).

Step 2: Install the official Isabelle version
Isabelle publishes official releases once or twice a year. Isac tries to follow Isabelle's new releases, but doesn't care about intermediate repository snapshots --- Isac lives in Isabelle's user space and not in the developer space.

For reasons mentioned on top of the page, ISAC sticks to Isabelle2013-2 presently. Go to Isabelle's website archive, select [Isabelle2013-2] and follow the download procedure described there. Let us designate the directory where you installed Isabelle with "~ ~ ~", usually "/usr/local/" in Linux (the blanks between the three tildes are enforced by MediaWiki).

Don't start this Isabelle installation now because at the first launch lots of changes are done, which might affect Step 4 and  Step 5 below; the most noteworthy is the creation of directory ~/.isabelle which is used by all installed versions of Isabelle, including ISAC's development environment.

Step 3: Clone Isac's repository
Isac's repository only controls the directories "/doc-isac/*", "/src/*" and "/test/*", which can be seen in "/.hgignore". Isac's repository also contains the changesets of the Isabelle development up to the last official release in order allow for merges any time (see Update_Isabelle_version).


 * (3.1) You get Isac's repository with all changesets added in the Isac project by

TODO: with Isabelle2020 the first command clone below raises the error abort: destination 'isabisac' is not empty Thus replace with meld ?!? ... ~ ~ ~$ sudo hg clone https://hg.risc.uni-linz.ac.at/wneuper/isa/ isabisac ~ ~ ~$ cd isabisac ~ ~ ~/isabisac$ hg st hg st should show the complete history of changesets and a Working Directory without updates. From now on, ~ ~ ~/isabisac$ is shortcut by $, which conforms with Isabelle conventions.

Step 4: Make Isac executable
For running the development environment we establish a state in Isac's working directory isabisac, whis is as close to the standard installation prepared in Step 2.

$ rm -rf bin $ cp -r ../Isabelle20XX/bin. $ rm -rf contrib $ cp -r ../Isabelle20XX/contrib. $ rm -rf doc $ cp -r ../Isabelle20XX/doc. $ rm -rf etc $ cp -r ../Isabelle20XX/etc. $ rm -rf lib $ cp -r ../Isabelle20XX/lib. And we don't touch the three directories "/doc-isac/*, /src/* and /test/*, which differ from the official Isabelle version.
 * (4.1) Copy Isabelle's directories from the download (in "~ ~ ~/Isabelle20XX/") to isabisac, removing the respective directories first:

$ sudo chown -R MYUSERNAME ../isabisac $ sudo chgrp -R MYUSERNAME ../isabisac
 * (4.2) Change owner and group for all of the directories copied in Step (4.1):

$ hg revert etc/components This way you avoid messages "### missing component ..."
 * (4.3) Restore the original version of one file (which is tracked, although contained in .hgignore ?!?):

$ sudo apt-get install libwww-perl
 * (4.4) Install a component missing in some Linux versions, but required for running isabelle components -a in Step (4.5):

$ ./bin/isabelle components -I $ ./bin/isabelle components -a The latter fetches components from http://isabelle.in.tum.de/ and might take some time. The following directories are created ("~/" is the home directory in Linux): ~/.isabelle/contrib ~/.isabelle/Isabelle20XX/etc ~/.isabelle/Isabelle20XX/heaps  \# created by (4.1) ~/.isabelle/Isabelle20XX/jedit
 * (4.5) Make Isac executable by Isabelle's development environment

Further information about Isabelle's development environment can be found in ""/README_REPOSITORY".

Step 5: Build and test Isac
$ ./bin/isabelle jedit -l Isac test/Tools/isac/Test_Isac.thy At the first start-up this takes some time, because first time Isabelle creates some Scala jars and the jEdit distribution respectively in /usr/local/isabisac/lib/classes/ /usr/local/isabisac/src/Tools/jEdit/dist/ and successively build Isabelle/Pur, Isabelle/HOL and Isabelle/Isac and finally run /test/Tools/isac/Test_Isac.thy to see that everything is ok (see the Policies_for_the_test_suite: no commits without running all tests successfully!).
 * (5.1) Since Isabelle's build has been greatly automated you just start Isabelle's front-end by

In further sessions the built binaries are re-used and startup is comparably fast.

theory Test imports Main begin ML {* "hello world" *} end Don't forget to save the theory with the name you have chosen (in our case "Test.thy"), otherwise Isabelle reports the error "Bad file name "Test.thy" for theory "Scratch.thy" and doesn't evaluate anything. By clicking on "hello world" you see success in the Output window at the bottom.
 * (5.2) Type in a first theory into jEdit for test purposes:

Usually a first step of adapting jEdit is to decrease the font size by the menues Utilities > Global Options > Text Area.

Step 6: Prepare additional local repository clones
Isabelle's repository shows how version control can be an effective part of documentation for developers: The changesets are kept to a minimum such that change of a certain functionality can be traced along updates of several files (such surveys cannot be established with some separated document or within comments in the code).

Isac tries to follow this model since July 2013, changeset 5d55c6c812aa. Stability of Isac's code is not yet comparable to Isabelle; thus there are some changesets with large chunks of unrelated updates, see Policies_of_repository_usage.

Step 7: Start development
TODO
 * Coding_standards_for_SML

An important rule for Isac developers is to commit changes to Isac's repository only if all tests are running. The file "/test/Tools/isac/Test_Isac.thy" runs all tests and gives information about how Isac organises tests. In order to go sure, verify that you start with a sane repository:


 * Run all of Isac's tests by

$ ./bin/isabelle jedit -l Isac test/Tools/isac/Test_Isac_Short.thy

Evaluation of this file takes some time. First the files addressed by imports are evaluated --- observe their evaluation by opening the Theories-window on the right margin. Evaluation of Test_Isac.thy is enforced by setting the cursor within this file to

ML {*"%%%%%%%%%%%%%%%%% end Knowledge %%%%%%%%%%%%%%%%%%%%%%%%";*}

Evaluation should succeed without an error (errors are indicated by a red icon on the left margin of jEdit). "Isac" is a session which creates a heap at the first start-up and later any time a file in "/src/Tools/isac/" has been updated. See


 * /test/Tools/isac/Test_Isac_Short.thy
 * /test/Tools/isac/Test_Some.thy
 * /test/Tools/isac/Test_Theory.thy

/test/Tools/isac/Test_Isac_Short.thy deserves specific handling, see TODO