Installation of OCS

for Version 2.3g

by Wolfgang Grieskamp and Klaus Didrich
Copyright © 2000 The OPAL Group


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

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

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:

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

--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

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:

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:


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