Readme File for Escher Verification Studio 5.10 for Linux
=========================================================

CONTENTS

1. General
2. Prerequisites
3. Installation
4. Known limitations
5. Files installed


1. GENERAL
----------
This file addresses issues with the installation of Escher Verification Studio
under Linux. After installing Escher Verification Studio under Linux, you
should also read the file 'opt/escher/verificationstudio5/doc/readme.rtf' for
information about Escher Verification Studio 5.10 that is common to all platforms.


2. PREREQUISITES
----------------
This release of Escher Verification Studio was compiled using gcc 4.3.3 under
Ubuntu Linux 9.04. It has been tested under Ubunto Linux 9.04 (32-bit x86).

To run Escher Verification Studio 5.10, you must have the following or suitable
substitutes installed:

  wxGTK version 2.8.x unicode build (libwxbase2.8.0 and libwxgtk2.8-0)
  GTK 2.16
  libc6 version 2.8
  libstdc++6-4.3

To download wxGTK, see http://wxwidgets.org/download (pre-built packages are
available for Debian and Ubuntu). Although wxGTK is needed to run the user interface
(file "verificationstudio"), it is not needed to run the compiler/verifier (file
"eschertool") or the new user interface preview (file "verificationstudio-preview").

If you wish to compile and run C++ code generated by Perfect Developer then we
recommend using a version of gcc that is recent (e.g. 4.3) and certainly no
older than 3.3.1. Some earlier versions are known to compile Perfect Developer
generated code incorrectly.

If you wish to compile and run Java code generated by Perfect Developer, you
will need to download and install the Java Development Kit version 1.5 or later
(including any version 1.6.x) from http://oracle.com/technetwork/java/index.html.

If you wish to compile and run C# code generated by Perfect Developer, you
will need an implementation of the Common Language Runtime, C# compiler, and
.NET Framework version 2.0 or later, such as Mono. We have not tested Perfect
Developer with Mono, however the demands made by the code generated by Perfect
Developer are modest so we do not forsee any particular problems. If you do
try out Perfect Developer with Mono, please report your experiences to us.


3. INSTALLATION UNDER 64-BIT LINUX
----------------------------------
To run Escher Verification Studio uder 64-bit (amd64/x64) builds of Linux,
you must install the 32-bit libraries, if they are not already installed.
Depending on your system, use either:

  sudo apt-get install ia32-libs

or:

  sudo aptitude install ia32-libs
  
You will also need to install a 32-bit build of wxGTK 2.8.x in /usr/lib32.
The following may work for 64-bit Ubuntu Linux:

  sudo apt-get install libgtk2.0-0:i386 libwxgtk2.8-0:i386


4. REMOVAL OF OLD VERSIONS
--------------------------
If you wish to remove previous versions of Perfect Developer prior to
installing Escher Verification Studio, proceed as follows. Remember to save
any of your own files that are in the relevant directories first!

To remove Perfect Developer 3.x, 4.x or 2.10.02 and later, remove subtree
/opt/escher, and remove files /etc/opt/escher/perfectdeveloper.conf and
~/escher/perfectdeveloper.conf.

To remove Escher Verification Studio 5.0, remove subtree /opt/escher, and
remove files /etc/opt/escher/verificationstudio.conf and
~/escher/verificationstudio.conf.


5. INSTALLATION
---------------
To install Escher Verification Studio 5.10, run the command:

 tar -z -P -xf /media/cdrom/linux/verificationstudio-5.10.tgz

You will need root privileges to do this, so either log on as root or prefix
the command with 'sudo'.

The above command assumes you are installing from a CDROM that is accessed
as /media/cdrom. If you are installing from a download, substitute the
appropriate path. The filename may differ slightly depending on the edition
and version of Escher Verification Studio.


6. KNOWN LIMITATIONS
--------------------

(a) Clicking on error messages

The User Guide states that when there are error or warning messages in the
results window of the Project Manager, you can double-click on a message to
open the corresponding source file at the error location, or right-click on a
message to display a menu of actions relating to the message. Under Linux,
double-clicking on a message does nothing. To pop up the menu of actions, you
need to highlight some text within the message first, then right-click on the
highlighted text.

(b) Opening User Guide and Language Reference from the Project Manager

In order to open the User Guide and Language Reference Manual directly from
the Project Manager 'Help' menu or toolbar buttons, the correct entries must
be set up in the mime-types and mailcap files. If you find that clicking on
the documentation icons in the Project Manager does not result in the
documentation being displayed in a browser window, check the following:

- File /etc/mime.types contains the line:

  text/html html htm

- File /etc/mailcap contains a suitable line for opening text/html files, such
as:

  text/html; firefox %s; test=test -n "$DISPLAY"

- If there is more than one line in /etc/mailcap relating to text/html files,
either the line you wish Perfect Developer to use is the last such line, or
the other lines are disabled in graphics mode with a test clause such as:

  test=test -z "$DISPLAY"

For example, the /etc/mailcap file for SuSE Linux 8.2 contains the following
line for text/html files:

  text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html

This line should be replaced by the following 2 lines:

  text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html; test=test -z "$DISPLAY"
  text/html; firefox "%s"; test=test -n "$DISPLAY"

You can replace 'firefox' by your preferred browser command. Changes made to
mailcap will not take effect until you restart the Project Manager.


7. FILES INSTALLED
------------------
'/opt/escher/verificationstudio5/bin/verificationstudio' - executable Project
Manager.

'/opt/escher/verificationstudio5/bin/verificationstudio-preview' - preview of
executable Project Manager with buld-in editor. The editor is usable but not
fully functional.

'/opt/escher/verificationstudio5/bin/eschertool' - executable
compiler/verifier. Normally invoked via the Project Manager, but you can
invoke it directly from a terminal or editor if you wish (see the User Guide
for command line parameters).

'/opt/escher/verificationstudio5/builtin/* - files needed by pdtool.

'/opt/escherverificationstudio5/doc/*' - documentation (html, gif, jpg, css,
pdf and rtf files in several subdirectories).

'/opt/escher/verificationstudio5/editorcustomization/*' - editor customization
files for Kate, Vim and XEmacs. See the Readme files in the corresponding
subdirectories for more information.

'/opt/escher/verificationstudio5/pd/lib/java/PerfectRuntime.jar' - run-time
library class archive for Java code generated by Perfect Developer.

'/opt/escher/verificationstudio5/pd/lib/java/PerfectRuntimeD.jar' - debug
version of the Java runtime library.

'/opt/escher/verificationstudio5/pd/lib/csharp/PerfectRuntime.dll' - C#
runtime library.

'/opt/escher/verificationstudio5/pd/include/cpp/*' - include files for C++
code generated by Perfect Developer.

'/opt/escher/verificationstudio5/pd/lib/cpp/libperfectruntime.a' - runtime
library for C++ code generated by Perfect Developer.

'/opt/escher/verificationstudio5/pd/lib/cpp/libperfectruntime-debug.a' -
runtime library for C++ code generated by Perfect Developer (debug version).

'/opt/escher/verificationstudio5/pd/lib/src/*' - source files for the C++
runtime library.

'/opt/escher/verificationstudio5/ecv/include/*' - include files for C projects
you wish to verify using Escher C Verifier.

'/opt/escher/verificationstudio5/examples/*' - examples (in several
subdirectories). Examples for Escher C Verifier are in subdirectory ecv.

'/etc/opt/escher/verificationstudio5.conf' - global configuration file. Escher
Verification Studio never writes to this file, so if you edit it your changes
will be retained unless you re-install the product. It includes the paths to
various files needed by Escher Verification Studio. If the Project Manager
reports that it is unable to find a file, check that the setting in
'/etc/opt/escher/verificationstudio5.conf' is correct.

'~/.escher/verificationstudio5.conf' - local configuration file, created and
updated by the Project Manager. Settings in this file override those in
'/etc/opt/escher/verificationstudio5.conf'.


Escher Technologies Ltd, March 2012.
