\input texinfo
@c ** start of header
@paragraphindent 0
@setfilename install
@settitle Installation of OCS
@setchapternewpage off
@c footnotestyle separate
@comment %**end of header 
@iftex
@c afourpaper
@end iftex

@c $__Header$

@finalout
@titlepage
@title Installation of OCS
@subtitle for Version 2.3g
  
@author by Wolfgang Grieskamp and Klaus Didrich
@author Copyright @copyright{} 2000 The OPAL Group
@end titlepage
@page

@c =========================================================================

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

@itemize @bullet
@item
The hotshot is served with @ref{Quick Installation}
@item
For the requirements to install and run OCS, @pxref{Requirements}.
@item
The complete configuration procedure is described in
@ref{Configuration}. For the diverse configuration options,
@pxref{Customizing the Configuration}.
@item 
The building and installation procedure is tackled with in
@ref{Installation}.
@item
Notes on installation problems are found in @ref{Problems}.
@end itemize

@c ========================================================================
@menu
* General Information::         
* Requirements::                
* Quick Installation::          
* Configuration::               
* Installation::                
* Graphical Installation Tool::
* Security::
* Testing the Installation::    
* Problems::                    
@end menu

@node General Information, Requirements
@comment  node-name,  next,  previous,  up
@chapter General Information

Starting with release 2.1e OCS is configured on the base of the GNU
@code{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:

@example
    SunOS >=5.3  Linux Cygwin 
@end example

Note: @ref{Cygwin support} is still rudimentary.

@c ========================================================================
@node Requirements, Quick Installation, General Information
@comment  node-name,  next,  previous,  up
@chapter Requirements
 
To install and run OCS you need the GNU @code{make} utility version 3.64
or later and an ANSI-C compiler, preferable @code{gcc}. You definitively
cannot use OCS with on older version of GNU-make than 3.64.  To find out
the version, type:

@example
    gmake --version
@end example
or
@example
    make --version
@end example

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.

@c ========================================================================
@node Quick Installation, Configuration, Requirements
@comment  node-name,  next,  previous,  up
@chapter Quick Installation

To configure and install OCS, run

@example
    ./configure 
    gmake install
@end example

This will install OCS in @file{/usr/local/ocs-VERSION/} path.  It will take
around 45 minutes on a 450 MHz stand-alone computer for the complete
installation. @footnote{It will take around 23 hours on a PC equipped with a 
486 processor at 33 MHz and 16M main memory; this includes generation of
documentation, but excludes the tivi2 package.}

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.


@c ========================================================================
@node Configuration, Installation, Quick Installation
@comment  node-name,  next,  previous,  up
@chapter Configuration


@menu
* Preparing the Configuration::  
* Running the Configuration::   
* Customizing the Configuration::  
@end menu

@node Preparing the Configuration, Running the Configuration, Configuration, Configuration
@comment  node-name,  next,  previous,  up
@section Preparing the Configuration

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

In particular, you should ensure:

@itemize @bullet
@item
an ANSI C compiler is found in the path (such as @code{gcc}), either
under the name @code{gcc} or @code{cc}.
@item
GNU @code{make} is found, either under the name @code{gmake} or
@code{make}.
@end itemize

The default configuration will write the absolute pathes of the tools into
the configuration files. This behaviour can be controlled with the option
@code{--enable-absolute-pathes} (@pxref{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 @file{/usr/local/bin}
and @file{/usr/bin}.
@sp 1

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


@node Running the Configuration, Customizing the Configuration, Preparing the Configuration, Configuration
@comment  node-name,  next,  previous,  up
@section Running the Configuration

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

@example
    ./configure --prefix=@var{install-dir} @var{feature} ... @var{feature}
@end example

where @var{install-dir} is the directory where OCS shall be installed,
and @var{feature} is described in @ref{Customizing the Configuration}.

The run of @code{./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 @code{./configure} as root.

The @code{./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 @code{./configure} is not capable of tracking any side-effects
induced by features or environment variables such as @code{PATH} on the
validness of the cache. To get rid of such effects, run
@example
    rm config.cache
@end example
before you rerun @code{./configure}.


@node Customizing the Configuration,  , Running the Configuration, Configuration
@comment  node-name,  next,  previous,  up
@section Customizing the Configuration

Several options may be passed to the @code{./configure} program to customize
the configuration. For each option of the form @code{--enable-@var{feature}}
an according @code{--disable-@var{feature}} option exists, which deselects
the given @var{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
@code{./configure} is unable to find them

@menu
* General options::             
* Opal Features::               
* Compiler and Linker Flags::   
* External Libraries::          
* Alpha Packages::              
@end menu

@node General options, Opal Features, Customizing the Configuration, Customizing the Configuration
@subsection General options
@table @code

@item --prefix=@var{install-dir}		
directory where OCS should be installed. Defaults to
@file{/usr/local/}. The installation will create a subdirectory
@code{ocs-VERSION} within the install directory.

@item --enable-dynamic
enable dynamic linking and support for shared libraries. Default is enabled.
The @sc{Oasys} interpreter depends on dynamic linking.

@item --enable-absolute-pathes
burn the locations of tools at installation time into the installed
OCS. This is the default.

@item --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 @code{dosfop} feature (see the following section).

@item --enable-locallinks
This generates small shell-scripts in @var{exec_prefix}/bin, which call the
executable OCS programs in @var{install-dir}. You may change the location by 
giving an explicit option @code{--exec-prefix=}@var{exec_dir}. The default
for @var{exec_prefix} is to use the same value as for @var{prefix}. The
default for the @code{locallinks} option is on.

@end table

@node Opal Features, Compiler and Linker Flags, General options, Customizing the Configuration
@subsection Opal Features

All these features are enabled by default.

@table @code
@item --enable-dosfop
install the @sc{Dosfop} documentation system
@item --enable-opalwin
install the OpalWin library. If you don't have X, or @sc{Tcl/Tk} you should
disable this feature.
@item --enable-oasys
install the @sc{Oasys} interpreter. The interpreter depends on @sc{Tcl} (not 
on @sc{Tk}), and on dynamic linking, and it benefits from the GNU readline
library.
@item --enable-reflections
install the reflections library for @sc{Opal}. See the documentation for
further details.
@item --enable-tivi2
install the @code{tivi2} tool. Disable this, if your memory is @emph{very}
low (less than 32M) -- it might save your computer from death by infinite
swapping. 
@end table

@node Compiler and Linker Flags, External Libraries, Opal Features, Customizing the Configuration
@subsection Compiler and Linker Flags

These flags are left empty by default.

@table @code
@item --with-cflags=@var{flags}
additional flags to be passed to the C compiler on every compilation. 

@item --with-ldflags=@var{flags}
additional flags to be passed to the C compiler on every linkage.

It should be noted that flags defined by @code{--with-cflags} are not
passed automatically on linkage. If flags are common both to compilation
and linkage, provide them twice.

@item --with-libs=@var{libs}
additional libraries (@code{-l@var{lib}} and @code{-L@var{path}}) to be
used for linking.

@item --with-dldflags=@var{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
@code{--with-ldflags}.

@item --with-dldlibs=@var{libs}
additional libraries to be used for linking a shared (dynamic) object.
These libraries will be appended to the libs given with
@code{--with-libs}.
@end table

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

@table @code
@item --with-ldrpath=@var{flags}
define runtime path for linking a dynamic library.
@item --with-ldrpathlink=@var{flags}
define linktime path for linking a dynamic library.
@item --with-soname=@var{flags}
define flag to set internal SONAME field.
@item --with-ldstatic=@var{flags}
flag to mark static link targets.
@item --with-lddynamic=@var{flags}
flag to mark dynamic link targets.

@end table

@node External Libraries, Alpha Packages, Compiler and Linker Flags, Customizing the Configuration
@subsection 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 @code{--without} option), the library will not be used.

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

@table @code
@item --with-readline-lib=@var{LIBFLAGS}
@itemx --with-readline-incl=@var{INCLFLAGS}
Specify location of the GNU readline library. (Define the include path such
that @code{readline/readline.h} can be successfully included.)

@item --with-tcl-lib=@var{LIBFLAGS}
@itemx --with-tcl-incl=@var{INCLFLAGS}
Specify location of the @sc{Tcl} library.

@item --with-tk-lib=@var{LIBFLAGS}
@itemx --with-tk-incl=@var{INCLFLAGS}
Specify location of the @sc{Tk} library.

@item --with-java-lib=@var{LIBFLAGS}
@itemx --with-java-incl=@var{INCLFLAGS}
Specify location of the @sc{Java} library. (Note that @file{jni.h} is
included which often requires another include in a different directory.)

@item --with-pizzahome=@var{PATH}
Specify path to the @sc{pizza} home directory. 

@end table

@node Alpha Packages,  , External Libraries, Customizing the Configuration
@subsection 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.

@table @code
@item --enable-opaljava
Install the @sc{Opal/Java} library. This requires the installation of a
@sc{jdk}. @footnote{If you want to compile @sc{Opal/Java} yourself, this
requires  that @sc{javacc} is found in your path, and that @sc{pizza} is available.
@sc{JavaCC} can be found at @url{http://www.metamata.com/JavaCC/}.
@sc{pizza} can be obtained at @url{http://www.cis.unisa.edu.au/~pizza/}.
Note that these tools are not required for proper installation, they are needed
only for developers of @sc{Opal/Java}.}

@item --enable-oc5
Install an alternative frontend of the @sc{Opal} compiler.
@item --enable-proofchecker
Install an enhanced @sc{oasys} interpreter with support for correctness
checks.  
@end table

@c ========================================================================
@node Installation, Graphical Installation Tool, Configuration
@comment  node-name,  next,  previous,  up
@chapter Installation

After successful configuration, OCS is installed by running

@example
    gmake install
@end example

in the distribution directory (or @code{make}, whatever is the name of
GNU make on your system). Make sure that you have write permission in the
installation directory (i.e. @file{/usr/local/} or the directory you
explicitly provided with a @code{--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 @code{--prefix} option on
configuration time.

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

@c
@c To cleanup every objects derived in the boot, check and build phases
@c run:

@c @example
@c     gmake clean
@c @end example

@c To cleanup everything including the configuration files run:

@c @example
@c     gmake cleanall
@c @end example

@node  Graphical Installation Tool, Security, Installation
@chapter Graphical Installation Tool

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

Currently, @code{opalwizard} supports only the most important configuration
options, and does not very efficiently do the installation procedure.

@c ======================================================================
@node Security, Preparation Per User, Graphical Installation Tool
@chapter Security

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

@enumerate
@item
Log in as @code{root}. Create an empty directory
@var{install-dir}/ocs-VERSION, e.g. @file{/usr/local/ocs-2.3e}. Make this
directory writable for the user who does the installation, and log out.
@item 
Configure and install the OCS system as described above. Set up the prefix,
if necessary, and disable the @code{locallinks} option.
@item
Log in as root again, remove the write permission from
@var{install-dir}/ocs-VERSION. 
@end enumerate

@c ======================================================================
@node Preparation Per User, Testing the Installation, Security
@chapter Preparation Per User

If you disabled the @code{locallinks} option, you have to extend the
@code{PATH} such that the ocs compiler driver is found:

@example
    PATH="@var{install-dir}/bin:$PATH"
@end example

If you use an editor from the emacs family (@sc{Emacs, XEmacs}), you should
copy the file @var{install-dir}@file{/lib/emacs/README} into your
@file{.emacs} configuration file. You need to customize the variable
@code{opal-path} and may configure other variables as well.

Users of the KDE desktop can copy icons and MIME configuration files:
@example
  >cp @var{install-dir}/lib/kde/*.gif ~/.kde/share/icons
  >cp @var{install-dir}/lib/kde/*.kdelnk ~/.kde/share/mimelnk
@end example


@node Testing the Installation, Problems, Preparation Per User
@chapter 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 @code{ocs}:
@example
% ocs info
You are using `ocs-2.3g' 
located at `/usr/local/ocs-2.3g'.
The project ($OCSPROJECT) is not specified.
@end example

If this test fails, you probably have not set your @code{PATH} environment
variable.

For the following tests copy the examples directory from the installation to 
your home directory (or another directory of your choice):
@example
% cp -r @var{install-path}/ocs-2.3g/examples ~ 
@end example

The next check compiles a program which does not use any extra libraries:
@example
% cd ~/examples/Integrator
% ocs
% ./integral
@end example

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

If you installed the @sc{OpalWin} library, you can compile the following
example:
@example
% cd ~/examples/Graphics/Queens
% ocs
% ./queens
@end example

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

Test the Opal reflections by executing one of the example programs:
@example
% cd ~/examples/Reflections/PrettyPrint
% export OCSPROJECT=$HOME/examples/Reflections/ProjectDefs.reflections
% ocs
% ./PrettyPrint
@end example

Finally, call the @sc{Opal} interpreter:
@example
% 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
@end example

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

@c ========================================================================
@node Problems,  , Testing the Installation
@comment  node-name,  next,  previous,  up
@chapter Problems


@menu
* POSIX::                       
* Handcrafting::                
* Out of Memory::               
* Re-Configuring::              
* Cygwin support::              
@end menu

@node POSIX, Handcrafting, Problems, Problems
@comment  node-name,  next,  previous,  up
@section POSIX

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

If @code{./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 @code{./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 @code{./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 @code{./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 @code{-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. 


@node Handcrafting, Out of Memory, POSIX, Problems
@comment  node-name,  next,  previous,  up
@section 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 @file{src/om/specs/Specs.basic} and
@file{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 @code{make}
file and the second a @code{sh} file. If you want to change compiler flags
(e. g. optimization flags) or the names of the tools (e. g. if you prefer
@code{gzip} to @code{bzip2}), you must change both files, before calling
@code{gmake/make}. 

The file @file{src/lib/Internal/Compiler/unixconfig.h} describes the view of
OCS onto the UNIX host system. 


@node Out of Memory, Re-Configuring, Handcrafting, Problems
@comment  node-name,  next,  previous,  up
@section Out of Memory


For some (@b{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
@code{gcc} or to edit one of the configuration files by hand to disable
the C compilers optimization (@pxref{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 @code{mkswap(8)}).


@node Re-Configuring, Cygwin support, Out of Memory, Problems
@section Re-Configuring

If you want to change the configuration (e. g. because @sc{Tcl/Tk} has been
installed in the meantime) the easiest way is to redo the installation
process. Use the target @code{reinstall} in the invocation of
@code{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 @code{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 @code{STDPACKAGES}.

Moving the installation to a different directory creates problems, if
shared libraries are used. You may need to set the environment variable
@code{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.

@node Cygwin support,  , Re-Configuring, Problems
@section 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.

@subsection 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:

@itemize @bullet
@item
The internally generated C header file for structure @file{S} is
	confused with a C library header file  @file{s.h}. This concerns
	structures @code{Time, Wait, Signal, Tcl, Tk, ReadLine}.

@item Two library structures are distinguished by case only. This concerns
	the pairs @code{BOOL/Bool, DENOTATION/Denotation,
REFLECTION/Reflection}.  
@end itemize


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 @code{genmake}
      program "know" which structures reside in renamed file names, and the
      configuration script renames the files accordingly. 

 The @code{Dosfop} system for building documentation has not been updated 
      and is @emph{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.


@subsection Handling of Libraries 

Handling of libraries is different for Cygwin systems. The following
      problems still persist:
@itemize
@item
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.
@item
 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.
@end itemize

@contents
@bye
