Update Isabelle version

This sequence of steps applies to the case, where ISAC's repository is updated to a new Isabelle release once: once the steps described below are done, all developers of Isabelle/Isac delete their respective workspace and follow the guidelines for setup at Development_Environment_for_ISAC_core (and do NOT update the Isabelle/Isac workspace).

ISAC's repository contains protocols of previous updates. See for instance, changesets 130688f277ba to changeset a556fcaf2ae3 at https://intra.ist.tugraz.at/hg/isa, i.e. https://intra.ist.tugraz.at/hg/isa/rev/130688f277ba : https://intra.ist.tugraz.at/hg/isa/rev/a556fcaf2ae3

Step 1: Save the current working directory
When updating Isac to a new Isabelle version (also later) it is useful to have the old Isabelle/Isac run for comparison with new versions. For this reason it is helpful to have at least the latest versions on your personal computer (presently Isabelle development has a release cycle of eight months).

Isabelle bundles all components since 2011, so going back to elder Isabelle versions within ISAC's repository is easy since 2011 (~/.isabelle/contrib/ holds the respective components).

We update from Isabelle20XX to Isabelle20YY beginning with these steps:


 * (1.0) start from a state where Test_Isac.thy evaluates without errors, for instance changeset 76126151fa0f.


 * (1.1) summarize Isac development since the previous Isabelle update in Test_Isac.thy in analogy to the previous entries in section {* history of tests *}

$ hg commit -m "final isabisacXX on Isabelle20XX"
 * (1.2) commit to the repository with a standardised log-entry

hg tag isabisacXX
 * (1.3) tag the respective changeset

/usr/local$ sudo mv isabisac isabisacXX
 * (1.4) save the current working directory:

Step 2: Adapt Isabelle's standard installation
Merging repositories of Isabelle and Isac causes dangers, so the Isac repository is trickily inserted into a standard installation of Isabelle since Isabelle2015.


 * (2.1) download the last official release from http://isabelle.in.tum.de to ~/tmp/

~/tmp$ tar -xvzpf Isabelle20XX_app.tar.gz
 * (2.2) unpack with

~/tmp$ mkdir /usr/local/isabisac ~/tmp$ cp -r Isabelle20XX/* /usr/local/isabisac/
 * (2.3) copy the sources to the installation location (isabisac has been moved to isabisacXX)


 * (2.4) do NOT start Isabelle: this would cause problems later (even if the root directory already has the final name).

~/.isabelle$ rm -rf isabisac Messages like Bad component catalog file: "/home/wneuper/repos/isabisacREP/Admin/components/main" are caused by a corrupted isabisac
 * (2.5) remove the outdated heaps (if not done already by Step 1)

$ cd /usr/local/isabisac
 * (2.6) change to the new working directory indicated by $ in the sequel

Step 3: Copy ISAC's repository into Isabelle's files
Now we make an Isabelle/Isac working space ($ denotes /usr/local/isabisac$) and copy Isac into the already present Isabelle files.

$ sudo cp -r ../isabisacXX/.hg*. $ sudo chown -R wneuper .hg* $ sudo chgrp -R wneuper .hg*
 * (3.1) copy repository from old installation into the new one


 * (3.2) rollback \\-- DONT PUSH

$ cp -r ../isabisac17/src/Tools/isac ./src/Tools/ $ cp -r ../isabisac17/test. $ cp -r ../isabisac17/doc-isac. $ cp ../isabisac17/CLEANUP. $ cp ../isabisac17/README_WN. $ cp ../isabisac17/README_REPOSITORY. $ cp ../isabisac17/xcoding-to-test.sh. $ cp ../isabisac17/zcoding-to-test.sh. $ cp ../isabisac17/xtest-to-coding.sh. $ cp ../isabisac17/ztest-to-coding.sh. $ hg st The last command shows, that many Isabelle files have changed and that the Isac files are not listed (i.e. the Isac history is NOT affected by the following hg commit)
 * (3.2) copy Isac sources into the new installation (beforehand update "17" accordingly)

$ hg add
 * (3.2) add new Isabelle files to the repository (indicated by ? in the list created by hg st)

$ hg forget xxxxx         # do this file by file in thg You can use hg forget xxxxx also for non-existing directories xxxxx/.
 * (3.3) forget the old Isabelle files from the repository (indicated by ! in the list created by hg st). This is tiresome because hg forget xxxxx/* also affects files to be merged and files already added. Marking multiple files in thg and then forget by menue helps. So use 'hg forget' carefully !

hg commit -m "\- start update Isabelle20XX --> Isabelle20YY" This is a large change set.
 * (3.4) do the first commit from the new working space with a specific comment

Step 4: Finish Step 1: make installation of old version usable
isabisacXX$ hg commit -m "\- DO NOT PUSH FROM HERE: you are out of development"
 * (4.1) mark the saved repository (it will be still useful for coming back to tests on the old version later)

in file /urs/local/isabisacXX/etc/settings: : if [ -z "$ISABELLE_IDENTIFIER" ]; then ISABELLE_HOME_USER="$USER_HOME/.isabelle/isabisacXX" else ISABELLE_HOME_USER="$USER_HOME/.isabelle/isabisacXX" fi : and commit with a specific comment isabisacXX$ hg commit -m "define storage for installation-specific settings"
 * (4.2) specify the place for installation-specific settings (using gedit etc)
 * 1) The place for user configuration, heap files, etc.

/usr/local/isabisacXX$ rm -rf ~/.isabelle/isabisacXX /usr/local/isabisacXX$ ./bin/isabelle/jedit & In case the saved installation does not work any more see Fix_kernel_installation.
 * (4.3) create this place from /usr/local/isabisacXX (NEVER try to change it, RATHER delete it, if existing for some reason..)

:
 * (4.4) beware the Isac frontend isac-java from unstable kernel versions and connect with the saved installation in isac-java/src/java/properties/BridgeMain.properties

Step 5: Copy libisabelle into the installation
libisabelle is a ML/Scala library "which talks to Isabelle" and is used by Isac for communication between the Isac kernel (ML) and the Isac front-end (in Java/Scala). The library is packed for other applications than Isac, so we need the following manual procedure ~/tmp$ tar -xvzpf libisabelle*
 * (5.1) Download the latest version, e.g. libisabelle 1.0.0-RC3, from the changelog and unpack

~/tmp/libisabelle-1.0.0-RC3$ sbt
 * (5.2) Using sbt download the appropriate tools (compiler, etc) and build the libisabelle project

sbt:root> cli/run --resources /tmp/libisabelle-protocol --internal --verbose This takes some time while retrieving resources via internet.
 * (5.3) Dump libisabelle's protocol into /tmp/libisabelle-protocol

sbt:root> setup/assembly In case of errors in steps (5.2-4) remove all directories created so far ~/tmp/libisabelle-1.0.0-RC3/ ~/.ivy2/ ~/.local/share/libisabelle /tmp/libisabelle-protocol/ and restart from step (5.2).
 * (5.4) Create the *.jar for the connection on the Java side (see Step 8) by

$ rm -rf /usr/local/isabisac/libisabelle-protocol /tmp$ cp -r libisabelle-protocol /usr/local/isabisac/
 * (5.5) Copy libisabelle's protocol into Isac

$ export ISABELLE_VERSION=20YY
 * (5.6) set the environment variable required by libisabelle in the shell you build Isac to the appropriate year YY

$ ./bin/isabelle build -v -b Protocol This creates "Classy" and "Protocol" in ~/.isabelle/isabisac/heaps/..
 * (5.7) Create the session required for using libisabelle

$ hg commit -m "Isabelle20XX->YY: insert new libisabelle"
 * (5.8) Commit with a specific message

Step 6: Re-build Isabelle's heaps
Now everything is in place to build Isac again.

$ rm -rf ~/.isabelle/isabisac
 * (6.1) reset installation-specific settings  (NEVER try to change these, RATHER delete, if existing for some reason..)

in file /urs/local/isabisacXX/etc/settings: : if [ -z "$ISABELLE_IDENTIFIER" ]; then ISABELLE_HOME_USER="$USER_HOME/.isabelle/isabisac" else ISABELLE_HOME_USER="$USER_HOME/.isabelle/isabisac" fi : and commit with a specific comment hg commit -m "Isabelle20XX->YY: define storage for installation-specific settings"
 * (6.2) define storage for installation-specific settings (using gedit etc)
 * 1) The place for user configuration, heap files, etc.

$ ./bin/isabelle/jedit & In case the installation does not work any more see Fix_kernel_installation.
 * (6.3) create the installation-specific settings from /usr/local/isabisac

file /ROOTS +src/Tools/isac +libisabelle-protocol +test/Tools/isac/ADDTESTS/session-get_theory/ and commit with a specific comment hg commit -m "Isabelle20XX->YY: notify Isabelle about Isac and libisabelle"
 * (6.4) notify Isabelle about Isac and libisabelle


 * (6.5) separate appearance of Isac from Isabelle

file /src/Pure/System/distribution.ML: let val version = get_execution_version state; val node = get_node (nodes_of version) node_name; + val version = "Isabelle2018 + Isac"; in the_entry node command_id end;

file /src/Pure/System/distribution.scala: - val version = "Isabelle20XX: mm.yy" + val version = "Isabelle20XX + Isac" - val is_official = true + val is_official = false and commit with a specific comment hg commit -m "Isabelle20XX->YY: separate appearance of Isac from Isabelle"

hg commit -m "Isabelle20XX->YY: insert Isac's hooks in /src/Pure/thm.ML"
 * (6.6) insert Isac's hooks in ~ ~/src/Pure/thm.ML, which requires care in case there were major updates in Isabelle: Search thm.ML for WN and copy respective code from the old Isabelle to the new one. And commit with a specific comment

$ ./bin/isabelle jedit & Invasiveness of Isabelle's updates changes from version to version.
 * (6.7) compile Pure and HOL with updated thm.ML

hg commit -m "Isabelle20XX->YY: Pure and HOL build with updated thm.ML"
 * (6.8) commit with a specific comment (after having edited 1 character)

Step 7: Build ISAC from the new Isabelle code
ISAC is deeply integrated in Isabelle and Isabelle is still under rapid development, so this step usually involves some efforts. Some general hints are helpful:
 * (7.1) Check Isac code incrementally following the dependencies shown in Build_Isac.thy


 * (7.2) Apply a change in Isabelle to the whole Isac code in src/Tools/isac when encountering an error caused by a change of Isabelle (e.g. if an Isabelle function changes to another module).


 * (7.3) In case an Isabelle function has changed
 * lookup /NEWS in the new Isabelle
 * search the function in the old Isabelle code and lookup a respective code piece in the new Isabelle.


 * (7.4) In case the Output window does not help copy all code of xxx.sml into the theory and bisect using this structure:

ML {* *} ML {* ... insert here and then bisect with "*} ML {*" ... *} ML {* *}

hg commit -m "-- finish update Isabelle20XX --> Isabelle20YY for Build_Isac.thy"
 * (7.5) If Build_Isac.thy works, finish with a specific commit message


 * (7.6) Test_Isac.thy requires specific handling introduced  here

hg commit -m "/- finish update Isabelle20XX --> Isabelle20YY for Test_Isac.thy"
 * (7.7) Finish updating /test/ to new Isabelle20YY with a specfic commit message

Step 8: Connect ISAC's Java front-end with the new version of the math-engine
As soon as Test_Isac.thy works again, Isac's overall development should continue with the new version. : ISABELLE_HOME=/usr/local/isabisac :
 * (8.1) Connect by updating isac-java/src/java/properties/BridgeMain.properties, for instance, by

libisabelle-master$ cp ./modules/setup/target/scala-2.12/setup-assembly-1.1.0-SNAPSHOT.jar ~/proto4/repos/isac-java/lib/
 * (8.2) Copy the *.jar created in step (5.4) into the prototype installation, for instance, by

isac-java >  >  > 
 * (8.3) Remove the old *.jar and add the new one to the libraries in eclipse


 * (8.4) Update the code in Isac's BridgeMain.java following the model of libisabelle's Hello_PIDE.java.

~/proto4/repos$ hg commit -m "-- connection to new math-engine on Isabelle20YY"
 * (8.5) Commit the new connection to the repository with a specific message


 * (8.6) The libisabelle repository is obsolete after creating libisabelle-protocol for the Isabelle-side(see Step 5) and setup-assembly*.jar as described in (8.2-3).