This document describes the configuration and installation of the OPAL compilation system OCS, version 2.3d or later.
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.
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.
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.
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:
gcc), either
under the name gcc or cc.
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.
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.
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
--prefix=install-dir
ocs-VERSION within the install directory.
--enable-dynamic
--enable-absolute-pathes
--enable-doc
dosfop feature (see the following section).
--enable-locallinks
--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.
All these features are enabled by default.
--enable-dosfop
--enable-opalwin
--enable-oasys
--enable-reflections
--enable-tivi2
tivi2 tool. Disable this, if your memory is very
low (less than 32M) -- it might save your computer from death by infinite
swapping.
These flags are left empty by default.
--with-cflags=flags
--with-ldflags=flags
--with-cflags are not
passed automatically on linkage. If flags are common both to compilation
and linkage, provide them twice.
--with-libs=libs
-llib and -Lpath) to be
used for linking.
--with-dldflags=flags
--with-ldflags.
--with-dldlibs=libs
--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
--with-ldrpathlink=flags
--with-soname=flags
--with-ldstatic=flags
--with-lddynamic=flags
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
readline/readline.h can be successfully included.)
--with-tcl-lib=LIBFLAGS
--with-tcl-incl=INCLFLAGS
--with-tk-lib=LIBFLAGS
--with-tk-incl=INCLFLAGS
--with-java-lib=LIBFLAGS
--with-java-incl=INCLFLAGS
--with-pizzahome=PATH
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
--enable-oc5
--enable-proofchecker
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.
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.
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.
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.
locallinks option.
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
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.
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.
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.
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)).
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.
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.
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:
Time, Wait, Signal, Tcl, Tk, ReadLine.
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 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.