# Installation of OCS

## for Version 2.3g

This document describes the configuration and installation of the OPAL compilation system OCS, version 2.3d or later.

- The hotshot is served with Quick Installation
- For the requirements to install and run OCS, see Requirements.
- The complete configuration procedure is described in Configuration. For the diverse configuration options, see Customizing the Configuration.
- The building and installation procedure is tackled with in Installation.
- Notes on installation problems are found in Problems.

- General Information
- Requirements
- Quick Installation
- Configuration
- Installation
- Graphical Installation Tool
- Security
- Testing the Installation
- Problems

# General Information

Starting with release 2.1e OCS is configured on the base of the GNU `autoconf` utility. This shall provide an automatic adaption of OCS independent of the system type and local file organization.

The automatic configuration is still somewhat experimental, and has been validated only for the following systems:

        SunOS >=5.3  Linux Cygwin

Note: Cygwin Support is still rudimentary.

# Requirements

To install and run OCS you need the GNU `make` utility version 3.64 or later and an ANSI-C compiler, preferable `gcc`. You definitively cannot use OCS with on older version of GNU-make than 3.64. To find out the version, type:

        gmake --version

or

        make --version

whatever is the name of GNU make on your system.

You will need around 220 MB of free disk space during installation (even more, if you plan to install contributions). Permanently, around 60 MB is required.

You will need around 20MB of physical memory to install OCS. Less is possible, but expect extensive swapping (the C compiler will need the space). For the documentation, memory plus swap space should be about 80MB.

# Quick Installation

To configure and install OCS, run

        ./configure
        gmake install

This will install OCS in ``/usr/local/ocs-VERSION/'` path. It will take around 45 minutes on a 450 MHz stand-alone computer for the complete installation. (1)

Since the installation is somewhat time expensive, and hence trial-and-error is less appropriate, you should consider to study the sections below carefully before taking over.

# Configuration

- Preparing the Configuration
- Running the Configuration
- Customizing the Configuration

## Preparing the Configuration

The automatic configuration procedure will lookup the existence and locations of several UNIX tools such as the C compiler, the `make` program and so on. The lookup is done on the base of the environment variable `PATH`. Ensure that `PATH` is set such that your prefered variants of the tools will be found.

In particular, you should ensure:

- an ANSI C compiler is found in the path (such as `gcc`), either under the name `gcc` or `cc`.
- GNU `make` is found, either under the name `gmake` or `make`.

The default configuration will write the absolute pathes of the tools into the configuration files. This behaviour can be controlled with the option `--enable-absolute-pathes` (see Customizing the Configuration).

It should be noted that re-configuration of OCS will be necessary if the tools are moved to other locations, unless you have explicitely disabled absolut pathes. Disabling absolut pathes is not recommended on multi-user systems, since the functionality of OCS will then depend on personal user configurations. When using absolut pathes it is a good idea to have the tools at standard places such as ``/usr/local/bin'` and ``/usr/bin'`.

It is probably the easiest way to run the configuration procedure itself to inspect what tools will be choosen under the current `PATH`, and to re-configure if the result does not satisfy.

## Running the Configuration

Cd to the source directory of the distribution, and run:

        ./configure --prefix=install-dir feature ... feature

where install-dir is the directory where OCS shall be installed, and feature is described in Customizing the Configuration.

The run of `./configure` will check out the capabilities of your system. For this purpose it will create C programs on the fly, compile them, and occasionally run them. For security reasons you should not run `./configure` as root.

The `./configure` program automatically maintains a cache of the given features and the calculated results to be used for its next run. This may be useful to selectively enable or disable a particular feature without examining the system again. However, its should be noted that `./configure` is not capable of tracking any side-effects induced by features or environment variables such as `PATH` on the validness of the cache. To get rid of such effects, run

        rm config.cache

before you rerun `./configure`.

## Customizing the Configuration

Several options may be passed to the `./configure` program to customize the configuration. For each option of the form `--enable-feature` an according `--disable-feature` option exists, which deselects the given feature. Some Opal programs require or can benefit from external libraries, such as GNU readline, Tcl, Tk, or Java. You can disable the use of these libraries or give the necessary compiler flags if `./configure` is unable to find them

- General options
- Opal Features
- Compiler and Linker Flags
- External Libraries
- Alpha Packages

### General options

`--prefix=install-dir`
  directory where OCS should be installed. Defaults to ``/usr/local/'`. The installation will create a subdirectory `ocs-VERSION` within the install directory.
`--enable-dynamic`
  enable dynamic linking and support for shared libraries. Default is enabled. The OASYS interpreter depends on dynamic linking.
`--enable-absolute-pathes`
  burn the locations of tools at installation time into the installed OCS. This is the default.
`--enable-doc`
  generate and install documentation. This is disabled by default, you can get the archived documentation from the same place where you got the source distribution. If TeX is available, and your system is reasonably fast and has enough memory (about 80MB memory (swap + physical memory) will be needed), you can enable this generate the documentation yourself. In this case, you may not disable the `dosfop` feature (see the following section).
`--enable-locallinks`
  This generates small shell-scripts in exec_prefix/bin, which call the executable OCS programs in install-dir. You may change the location by giving an explicit option `--exec-prefix=`exec_dir. The default for exec_prefix is to use the same value as for prefix. The default for the `locallinks` option is on.

### Opal Features

All these features are enabled by default.

`--enable-dosfop`
  install the DOSFOP documentation system
`--enable-opalwin`
  install the OpalWin library. If you don't have X, or TCL/TK you should disable this feature.
`--enable-oasys`
  install the OASYS interpreter. The interpreter depends on TCL (not on TK), and on dynamic linking, and it benefits from the GNU readline library.
`--enable-reflections`
  install the reflections library for OPAL. See the documentation for further details.
`--enable-tivi2`
  install the `tivi2` tool. Disable this, if your memory is very low (less than 32M) -- it might save your computer from death by infinite swapping.

### Compiler and Linker Flags

These flags are left empty by default.

`--with-cflags=flags`
  additional flags to be passed to the C compiler on every compilation.
`--with-ldflags=flags`
  additional flags to be passed to the C compiler on every linkage. It should be noted that flags defined by `--with-cflags` are not passed automatically on linkage. If flags are common both to compilation and linkage, provide them twice.
`--with-libs=libs`
  additional libraries (`-llib` and `-Lpath`) to be used for linking.
`--with-dldflags=flags`
  additional flags to be passed to the C compiler on linking a shared (dynamic) object. These flags will be appended to the flags given with `--with-ldflags`.
`--with-dldlibs=libs`
  additional libraries to be used for linking a shared (dynamic) object. These libraries will be appended to the libs given with `--with-libs`.

If the following flags are not given, `configure` tries to find out the type of the linker and sets these flags accordingly.

`--with-ldrpath=flags`
  define runtime path for linking a dynamic library.
`--with-ldrpathlink=flags`
  define linktime path for linking a dynamic library.
`--with-soname=flags`
  define flag to set internal SONAME field.
`--with-ldstatic=flags`
  flag to mark static link targets.
`--with-lddynamic=flags`
  flag to mark dynamic link targets.

### External Libraries

Options for external libraries come in pairs, one for the linker flags and one for location of the include flags. If either of them is unset (using the corresponding `--without` option), the library will not be used.

If the flags argument contains spaces, enclose the whole commandline argument in quotes, e.g. `"--with-XXX-lib=-LPATH1 -RPATH1 -llib1"`

`--with-readline-lib=LIBFLAGS`
`--with-readline-incl=INCLFLAGS`
  Specify location of the GNU readline library. (Define the include path such that `readline/readline.h` can be successfully included.)
`--with-tcl-lib=LIBFLAGS`
`--with-tcl-incl=INCLFLAGS`
  Specify location of the TCL library.
`--with-tk-lib=LIBFLAGS`
`--with-tk-incl=INCLFLAGS`
  Specify location of the TK library.
`--with-java-lib=LIBFLAGS`
`--with-java-incl=INCLFLAGS`
  Specify location of the JAVA library. (Note that ``jni.h'` is included which often requires another include in a different directory.)
`--with-pizzahome=PATH`
  Specify path to the PIZZA home directory.

### Alpha Packages

These are packages in the alpha stage, which may or may not work on your system. Documentation (if any) is supplied in the source tree.

These packages are all disabled by default.

`--enable-opaljava`
  Install the OPAL/JAVA library. This requires the installation of a JDK. (2)
`--enable-oc5`
  Install an alternative frontend of the OPAL compiler.
`--enable-proofchecker`
  Install an enhanced OASYS interpreter with support for correctness checks.

# Installation

After successful configuration, OCS is installed by running

        gmake install

in the distribution directory (or `make`, whatever is the name of GNU make on your system). Make sure that you have write permission in the installation directory (i.e. ``/usr/local/'` or the directory you explicitly provided with a `--prefix` option).

This will bootstrap the OPAL compiler, check and build the library and selected features, and install everything at the place you have specified with the `--prefix` option on configuration time.

The whole process will take around 45 minutes on a 450MHz Pentium III.

# Graphical Installation Tool

In the top directory, you will find the Tcl/Tk script `opalwizard`, which provides a graphical user interface to the configuration and installation of OCS. Call `wish ./opalwizard &` from the command line and chose the appropriate actions from the `Action` menu.

Currently, `opalwizard` supports only the most important configuration options, and does not very efficiently do the installation procedure.

# Security

If you want to do a system-wide installation, but do not want to run the whole configuration and installation process as user `root`, you can proceed as follows.

1. Log in as `root`. Create an empty directory install-dir/ocs-VERSION, e.g. ``/usr/local/ocs-2.3e'`. Make this directory writable for the user who does the installation, and log out.
2. Configure and install the OCS system as described above. Set up the prefix, if necessary, and disable the `locallinks` option.
3. Log in as root again, remove the write permission from install-dir/ocs-VERSION.

# Preparation Per User

If you disabled the `locallinks` option, you have to extend the `PATH` such that the ocs compiler driver is found:

        PATH="install-dir/bin:$PATH"

If you use an editor from the emacs family (EMACS, XEMACS), you should copy the file install-dir``/lib/emacs/README'` into your ``.emacs'` configuration file. You need to customize the variable `opal-path` and may configure other variables as well.

Users of the KDE desktop can copy icons and MIME configuration files:

      >cp install-dir/lib/kde/*.gif ~/.kde/share/icons
      >cp install-dir/lib/kde/*.kdelnk ~/.kde/share/mimelnk

# Testing the Installation

If you completed the installation successfully, you have already used the new compiler. If you want to increase confidence in your installation, you can run the following checks.

The first check is to invoke `ocs`:

    % ocs info
    You are using `ocs-2.3g'
    located at `/usr/local/ocs-2.3g'.
    The project ($OCSPROJECT) is not specified.

If this test fails, you probably have not set your `PATH` environment variable.

For the following tests copy the examples directory from the installation to your home directory (or another directory of your choice):

    % cp -r install-path/ocs-2.3g/examples ~

The next check compiles a program which does not use any extra libraries:

    % cd ~/examples/Integrator
    % ocs
    % ./integral

The compiled program asks for a function and two real numbers for input. Use e.g. `(SIN x)` for the function. To quit, input an empty string for the value `a` and for the function `f`.

If you installed the OPALWIN library, you can compile the following example:

    % cd ~/examples/Graphics/Queens
    % ocs
    % ./queens

The program visualizes the search for the solutions of the eight-queens problem.

Test the Opal reflections by executing one of the example programs:

    % cd ~/examples/Reflections/PrettyPrint
    % export OCSPROJECT=$HOME/examples/Reflections/ProjectDefs.reflections
    % ocs
    % ./PrettyPrint

Finally, call the OPAL interpreter:

    % cd ~/ocs/examples/Rational
    % oasys
    oasys version 1.1e (ocs version 2.3g), (c) 1989-2001 The Opal Group
    > a Rational.sign
    > f Rational.sign
    Rational.sign>e 6/8 + 3/5
    checking Rational.sign
    checking Rational.impl
    compiling Rational.impl
    starting evaluator process
    27/20
    Rational.sign>q

If this doesn't work and you get error messages from the dynamic linker, you may need to replace your `glibc` with a current version. RedHat 5.0 and 5.1 require at least version 2.0.7-19 to work properly.

# Problems

- POSIX
- Handcrafting
- Out of Memory
- Re-Configuring
- Cygwin support

## POSIX

A main source of problems of the installation of OCS is the UNIX OPAL library (``src/lib/System/Unix'`). This library is implemented on the base of POSIX, which is not supported completely by some systems.

If `./configure` detects incompatibilities with POSIX, a fall back strategy is choosen, which means in the worst case that the incompatible feature is disabled at all. However, not all incompatibilties can be detected by `./configure` and fallback strategies have not been implemented for all cases yet.

Some systems may require a specific compiler switch to enable POSIX support which `./configure` fails to detect. On such systems OCS may not compile at all, or only with a largely reduced functionality of the UNIX library (see the `./configure` output).

If your C compiler and system headers propose to support POSIX, it isn't straightforward to say whether you should enable the support or not. Just defining `-D_POSIX_SOURCE` since the headers make a distinction about it is generally unsafe, since only the prototypes but not the libraries bound with a program are effected.

## Handcrafting

It should never be necessary to handcraft the configuration files of the OCS distribution, but here is what you should know in such a case.

The files ``src/om/specs/Specs.basic'` and ``src/om/specs/ShSpecs.basic'` contain the specification of where to find the UNIX tools and how to call the C compiler. Both files basically contain the same information: the first one as a `make` file and the second a `sh` file. If you want to change compiler flags (e. g. optimization flags) or the names of the tools (e. g. if you prefer `gzip` to `bzip2`), you must change both files, before calling `gmake/make`.

The file ``src/lib/Internal/Compiler/unixconfig.h'` describes the view of OCS onto the UNIX host system.

## Out of Memory

For some (really small) systems it has been reported that the C compiler runs out of memory during the installation. This is due to the fact that many C compilers do not expect that they are used as the backend of another compiler: the OPAL compiler produces single functions of a size humans would never write down.

To tackle with this problem, you might either consider to switch to `gcc` or to edit one of the configuration files by hand to disable the C compilers optimization (see Handcrafting).

The generation of the documentation needs about 80MB memory (physical memory plus swap space). On a stand-alone computer you might consider temporarily increassing the swap space (see man page of `mkswap(8)`).

## Re-Configuring

If you want to change the configuration (e. g. because TCL/TK has been installed in the meantime) the easiest way is to redo the installation process. Use the target `reinstall` in the invocation of `gmake/make` to indicate that you really want to overwrite an existing installation.

If you kept the intermediate files from the previous installation, it is faster to invoke `gmake/make` with the particular targets. A complete list of possible targets is contained in a commentary in the toplevel Makefile, just before the definition of `STDPACKAGES`.

Moving the installation to a different directory creates problems, if shared libraries are used. You may need to set the environment variable `LD_LIBRARY_PATH` such that the Opal shared libraries are found. This is done automatically for most of the Opal tools (compiler, interpreter), but not for the executables generated by the Opal compiler.

## Cygwin Support

The Opal compiler has been ported to the Cygwin environment, which provides a Unix-like GNU-based environment for Windows 9x/ME/NT/2000 operating system. Due to some differences/limitations/restrictions the support is not complete. The configuration program has been changed accordingly, so that the default installation will only consist of the unproblematic parts.

### Case Insensitivity of Filenames

Filenames are not case sensitive in the Cygwin environment. They are under most (all ?) other Unix-like systems, and the Opal library uses different cases to distinguish structures. During the port, we found the following problems:

- The internally generated C header file for structure ``S'` is confused with a C library header file ``s.h'`. This concerns structures `Time, Wait, Signal, Tcl, Tk, ReadLine`.
- Two library structures are distinguished by case only. This concerns the pairs `BOOL/Bool, DENOTATION/Denotation, REFLECTION/Reflection`.

In order to keep changes to the source code to a minimum, we decided to break the strong connection between filenames and structure names for the structures concerned. The Opal compiler and the `genmake` program "know" which structures reside in renamed file names, and the configuration script renames the files accordingly.

The `Dosfop` system for building documentation has not been updated and is not able to handle structures the names of which do not match their respective filenames. So you cannot generate the OCS documentation under Cygwin, instead you must install the documentation separately.

### Handling of Libraries

Handling of libraries is different for Cygwin systems. The following problems still persist:

- Linking external libraries does not work for the readline, tcl and tk libraries. This means that neither the Opal libraries that embed these C libraries can be used, nor the libraries and programs that build upon them, such as OpalWin, Oasys, and the Proofchecker.
- Building and using dynamic libraries is different for Windows' DLLs and Unix' shared objects. The scripts have not been updated. Opal libraries and programs that depend on dynamic linking cannot be used. This concerns Oasys and the Proofchecker.

This document was generated 19 June 2001 (13:29:32) using the texi2html translator version 1.51-kd-pl15.