   Building Open Object Rexx on Unix-like Systems (Linux, Solaris, etc.)
   =====================================================================

Please read ALL of these notes before building ooRexx!

The process of building ooRexx is slightly different if building from a
release source file achieve or from a svn checkout.  When building from a
svn checkout, the bootstrap script will need to be executed first.  Some
details on this are further down in this file under the "Notes for
developers" section.  If building from svn, check that section first before
proceeding with the next "Build and Install" section.  In addition, at the
end of the file are some notes on packaging ooRexx.

Build and Install
=================

To install ooRexx, you first need to configure it.  This is done by
executing the configure script provided in the archive.

Generally all you need to run is "configure", but there are some
options that can be passed to the configure script; use
"configure --help" to view them. If the configure script does not
exist then run the "bootstrap" script to create it.  If you need to run the
bootstrap script, you will also need to read the "Notes for developers"
section further down in this section.

Once the configure script has been run, you can then type "make".
This will create the following objects:

 rexx            the ooRexx interpreter
 rexxc           the ooRexx "compiler"; it is really a tokenizer
 rxapi           the ooRexx API daemon
 rxqueue         interface from command line to Rexx queue
 rxsubcom        enables subcommand environments to be manipulated
 librexx.so      shared library containing majority of interpreter
 librexxapi.so   shared library containing API functionality
 librxmath.so    maths extension library
 librexxutil.so  RexxUtil extension library; system functions
 librxregexp.so  Regular Expression extension library
 librxsock.so    Low-level socket extension library

Once you have ooRexx compiled, it can then be installed.  By default, the
ooRexx executables will be installed into /opt/ooRexx/bin and the libraries
and external function packages (*.so) will be installed into
/opt/ooRexx/lib/ooRexx.  The base path "/opt" can be changed by adding the
--prefix=path (where path is the base path) to the configure command.  E.g.,
to install ooRexx into your home directory: $HOME/bin and $HOME/lib/ooRexx,
configure --prefix=$HOME ...  This is particularly useful if you do not have
root access on the machine on which you are building ooRexx.

On most platforms, it is necessary to include the directory where shared
libraries (including *.so) reside, to the LD_LIBRARY_PATH
environment variable.

Under AIX this environment variable is LIBPATH (no modification needed).
Under HP-UX this environment variable is SHLIB_PATH.
Under SGI seems to be LD_LIBRARYN32_PATH.

It is not possible to install the 32-bit and 64-bit version on the same
machine.

Platform Specific Notes
======================

This version of ooRexx should compile as either a 32-bit or a 64-bit binary.

Linux:
-----
ooRexx should build on all 32-bit and 64-bit Linux platforms.

AIX:
---
Currently, the development team is having trouble building on AIX with the
gcc compiler. Contributions to the project in the form of patches that allow
ooRexx to be built using gcc on AIX would be most appreciated.

ooRexx can successfully be built on AIX 5L/6.1 using the following IBM
compilers:

* IBM's XL C/C++ V8 compiler with April 2009 PTF
* IBM's XL C/C++ V9 compiler with January 2009 PTF
* IBM's XL C/C++ V10.1 compiler with February 2009 PTF

You can get the necessary PTFs here:

URL: http://ftp.software.ibm.com/aix/products/ccpp/ptfs
URL: ftp://ftp.software.ibm.com/aix/products/ccpp/ptfs

XL C/C++ V8:

  vacpp.80.aix51.apr2009.ptf.tar.Z
  vacpp.80.aix52-53TL5.apr2009.ptf.tar.Z
  vacpp.80.aix53TL6-61.apr2009.ptf.tar.Z

XL C/C++ V9:

  vacpp.90.aix52-53TL5.jan2009.ptf.tar.Z
  vacpp.90.aix53TL6-61.jan2009.ptf.tar.Z

XL C/C++ V10.1:

  vacpp.101.aix53TL6-61.feb2009.ptf.tar.Z

32 bit build

Before running the configure script, set the following environment
variables:

% export CC=xlc_r
% export CXX=xlC_r
% export LDFLAGS="-Wl,-brtl -Wl,-bmaxdata:0x80000000"

% ./configure --disable-static
% make
% make install
% mkdir /var/run

64 bit build

Before running the configure script, set the following environment
variables:

% export CC=xlc_r
% export CXX=xlC_r
% export LDFLAGS="-Wl,-brtl"
% export OBJECT_MODE=64

% ./configure --disable-static
% make
% make install
% mkdir /var/run

As long as you do not move the binaries it is not necessary to add the
directory containing the libraries to the LIBPATH. If you want to switch
between 32 bit and 64 bit ooRexx then make sure that you kill the rxapi
daemon before the switch.

The rxapi daemon needs to be started as user root. This could be done
via /etc/inittab:

rxapi:2:once:/opt/ooRexx/bin/rxapi >/dev/console 2>&1

It is also possible to put the rxapi daemon under the control of the
subsystem resource controller (SRC).

Add the rxapi daemon to the SRC:

  mkssys \
    -s rxapi \
    -p /opt/ooRexx/bin/rxapi \
    -i /dev/null \
    -e /dev/console \
    -o /dev/console \
    -u 0 \
    -S \
    -n 15 \
    -f 9 \
    -R \
    -Q

Remove the rxapi daemon from the SRC:

  rmssys -s rxapi

If you like to use the SRC method you need to add this to your /etc/inittab:

rxapi:2:once:/usr/bin/startsrc -s rxapi > /dev/console 2>&1

If you want to bootstrap ooRexx on AIX you will need the following tools:

- libtool 1.5.26
- autoconf 2.63
- automake 1.10.1


DEC/HP Alpha:
------------
ooRexx currently has not been built on this platform. This is due to lack
of resources for the development team.

*BSD Platforms:
--------------
ooRexx builds on FreeBSD 5.4 and 6.1, NetBSD 2.0.2 and OpenBSD 3.4.
May be a bug due to ooRexx using members of internal C structs which are not
portable across platforms.

Mac OSX Platforms (Darwin):
--------------------------
This release of ooRexx should build out-of-the box on OSX 10.3 and above.

To build on OSX 10.2, you must have the libdl.dylib shared library and
dlfcn.h installed.  If these have not been installed in /usr/lib and
/usr/include respectively, you will need to do the following before running
configure:

% export CPPFLAGS=-I/sw/include
% export LDFLAGS=-L/sw/lib

(Assuming the library and header file have been installed in /sw/lib and
/sw/include respectively).

OSX 10.2 does not support the NLS message catalog functions such as
catopen() etc.  This means that you will NOT get meaningful error messages
from the interpreter and utility programs.  ooRexx may or may not build on
OSX 10.1 or below.  You're on your own here.

Notes for developers
====================
For full details of making changes to the ooRexx source, consult the
Developer's Guide (when it is written). In the interim, some actions will
need to be carried out if any changes are made to the build targets,
particularly when porting to other platforms. If any changes are made
to Makefile.am or configure.ac, then the generation of the configure
script will need to be re-executed. The safest way to do this to ensure
all steps are carried is to execute the
"bootstrap" script.

% bootstrap

You will require recent versions of autoconf, automake and libtool to get
the best out of the "auto" tools. At least the following versions should
be used:
- automake 1.9.5
- autoconf 2.59
- libtool  1.5.14

Packaging
=========
A "package" target exists in the Makefile. It will create ooRexx-x.y.tar.gz
containing the same files and directory structure as you would get when
doing a "make install".

By default libtool creates static libraries, which on some platforms are not
stripped and can be HUGE. Distribution of the static libraries is not
required for the base packages, so to ensure that only those files that are
required are distributed you will need to build ooRexx without static
libraries.

To do this (must be done in an empty directory, or after a "make clean":

% ./configure --disable-static
% make

Then the packaging steps...

% make DESTDIR=`pwd`/tmp install
% make DESTDIR=`pwd`/tmp package
Creates ./ooRexx-x.y.z-TARGET.tar.gz where TARGET is the canonical platform
name.

Specific platform packaging notes...

RPM - Linux RedHat/Fedora and related systems
---------------------------------------------
A rpm target exists in the make file.  This target will build a binary
install rpm of ooRexx on a Linux system that has the rpm building tools
available.  This is well tested on RedHat / Fedora and SuSE / Open SuSE.  It
should work on any Linux distribution where the rpm build tools work.

% make rpm

This will create a 'rpm' subdirectory off the root of the source tree.  The
finished rpm file will be located in a subdirectory off of the rpm
directory.

Debian and related dpkg-based systems
-------------------------------------
A deb target exists in the make file.  This target will build a binary 'deb'
install package on a Debian based system where the deb package creating
tools are installed.  This is well tested on Debian, Ubuntu, and Kubuntu
systems.  The debian package creating tools strictly enforce a directory
naming convention.  To build the deb package you *must* name the root of
directory of the source tree to conform to the naming convention.

The root directory must be named:  oorexx-<versionNumber>  For example, when
building the 4.0.0 version of ooRexx the root directory of the source tree
must be named:  oorexx-4.0.0

After naming the root directory of the source tree correctly, build ooRexx
as described above, then execute the deb make target.  I.e.:

...
% make
% make deb

At the finish of the deb package creation, the location of the deb package
is printed out.  (Normally the location is the parent directory of the root
directory of the source tree.)

Solaris - PKG
-------------
When building ooRexx for packaging, configure the build as follows:
% ./configure --disable-static --prefix=/opt/sfw

The "make DESTDIR=`pwd`/tmp package" above will also create:
a gzipped ./ooRexx-x.y.z.pkg suitable for Solaris' "pkgadd"

Later versions of g++ build in a dependency between ooRexx and g++
shared libraries; libstdc++.so.x and libgcc_s.so.x.
These shared libraries may be required to be installed on machines that
do not have the version of g++ installed that ooRexx was built with.

The ooRexx package will include these dependencies in the base ooRexx
package.
