               Installation Notes for Open Object Rexx
               =======================================

There are 3 basic ways to install ooRexx.  From simplest to most complex
they are:

Use a binary installer package, download and build ooRexx from a release
source archive (a tar or zip file,) or checkout and build from the source in
the Subversion repository.

Please read ALL of these notes before building ooRexx!

Install Using an Installer Package
==================================

Installer packages are provided for common platforms.  Basic instructions
for each installer package are provided here.  Check the specific platform
documentation of the installer type for advanced options.  For platforms
that do not have an installer package, it still may be possible to build a
version of ooRexx for that platform from the source.

Windows
-------

The Windows installer is a .exe file, a NSIS (Nullsoft Scriptable Install
System) installer.  NSIS has a similar look and feel to the Windows .msi
installer.

To install simply execute the file from a command prompt or double click on
the file from Windows Explorer.  The install dialog is easy to follow and
exhibits the same behavior as other common Windows installers.

When executed from a command prompt, the installer also supports the /S and
the /D options.  /S runs the installer silently; the user is not prompted
and the installer defaults are used.  The /D option specifies to install in
a directory other than the default.  The /D option must be last on the
command line and the directory must NOT be enclosed in quotes, even if the
directory name contains spaces.

Using this release as an example, to install without prompting into the
"D:\Local Interpreters" directory, the following command line could be used:

E:\downloads\ooRexx312.exe /S /D=D:\Local Interpreters\ooRexx

It is recommended that an existing version of ooRexx first be uninstalled
before installation.  Starting the installer when a previous version of
ooRexx is installed will automatically run the uninstaller first.  This is
true even when the installer is started from a command prompt using the /S
option.

Vista Notes
-----------
ooRexx is supported on Vista starting with release 3.1.2.  The same Windows
installer is used as on other versions of Windows.  On Vista the installer
must be run as administrator.  To do this, from Windows Explorer, right
click on the installer and select the "Run as administrator" menu item.  To
run the installer from a command prompt, the user should right click on the
command prompt icon and select the run as administrator menu item.  From
within this console window, the installer can be run from the command prompt
in the same way as on other versions of Windows.

If the user does not right click and select to run as administrator, when
the installer starts the elevated privileges dialog will pop up.  Right
clicking first simply saves a step and is not really necessary.

ooRexx runs a process: rxapi.exe the first time a Rexx program executes.
The rxapi process can be installed as a service, or not.  Although the
installer offers the choice to install as a service, on Vista the user
*should* always install rxapi as a service.  This allows Rexx programs to
run without using "elevated privileges."

If rxapi is *not* installed as a service on Vista, the rxapi process will
not start for standard users.  This prevents almost all Rexx programs from
running.  Note that on Vista even users in the administrator group will
normally be running as standard users.

However, if rxapi is not installed as a service, there are several methods
that will allow the user to run Rexx programs.  Both of these methods
circumvent, to some degree, MicroSoft's improved security measures in Vista.
Therefore the user is advised to install rxapi as a service on Vista.  Two
of these methods are as follows:

1.) Run all Rexx programs from a console session (command prompt) that has
been started using the "Run as administrator" option.

2.) Add the SeCreateGlobalPrivilege to either the user account running the
Rexx programs or to the "Users" group.  This setting can be accessed through
Administrative Tools -> Local Security Policy -> User Rights Assignment->
Create global objects

Linux
-----

Both .rpm (Redhat Package Manager) and .deb (Debian) install packages are
available.  Both Redhat and SuSE Linux generally use .rpm files, as do many
other Linux distributions.  Debian based systems (Debian, Ubuntu, Kubuntu,
etc.,) use .deb files.  The commands to do a basic install are as follows:

Debian: dpkg -i <packageFile>

RPM: rpm -iv <packageFile>

Using the 3.1.2 files as an example:

tom@Loon:~/downloads$ dpkg -i ooRexx-3.1.2-1.i386-debian-3.1.deb

Raven:/home/tom # rpm -iv ooRexx-3.1.2-1.i386.rpm

Solaris
------

There are .pkg install packages for several versions of Solaris on both
Intel and Sparc architectures. The commands to install a .pkg file are as
follows:

%

Mac OSX
-------

There are .dmg install packages for both Intel and PowerPC based Mac OSX
systems.  The commands to install a .dmg file are as follows:

%

AIX
---

There is a LPP install package for AIX.

This LPP will add an SRC subsystem named rxapi. The subsystem is started
automatically after the installation and via an entry in the /etc/inittab
during boot.

Copy the ooRexx 32 bit _or_ 64 bit installation package to an empty
directory and then execute the following commands:

To install the 32 bit version:

root@box # inutoc ./
root@box # installp -a -c -X -v -Y -V2 -g -d./ ooRexx.32.rte 4.0.0.1

To uninstall the 32 bit version:

root@box # installp -u ooRexx.32.rte

To install the 64 bit version:

root@box # inutoc ./
root@box # installp -a -c -X -v -Y -V2 -g -d./ ooRexx.64.rte 4.0.0.1

To uninstall the 64 bit version:

root@box # installp -u ooRexx.64.rte


Build and Install From a Release Source Archive
===============================================

Download and unpack the release source archive file in the format desired (a
tar or a zip file.) Both the tar and the zip files contain the same content.

Windows
-------

The "windows-build.txt" file included in the archive has the details for
building and installing on a Windows system.

Unix-like Systems (Linux, Solaris, AIX, etc.)
---------------------------------------------

The "unix-like-build.txt" file included in the archive has the details for
building and installing on Unix-like systems, including Mac OSX.


Checkout, Build, and Install from the Subversion Repository
===========================================================

The entire source tree for ooRexx is available for anyone and can be checked
out using a Subversion client and anonymous access.  Apart from the client,
the procedure is the same on all platforms.  Subversion clients and / or
instructions for installing Subversion clients for most platforms are
available at:

  http://subversion.tigris.org/project_packages.html

Once the Subversion client is installed, the command to checkout is as
follows, using the 4.x head as an example:

E:\work>svn co https://oorexx.svn.sourceforge.net/svnroot/oorexx/main/trunk interpreter

You can also check out the 4.0.0 release code:

E:\work>svn co https://oorexx.svn.sourceforge.net/svnroot/oorexx/main/releases/4.0.0 interpreter

In this command, the last word of the command is the directory into which
the source tree will be checked out.  The name of the directory can be any
name that is desired, 'interpreter' might be a common choice.

Again, note that the svn command is the same on any platform.  The example
happens to be from a Windows system, the svn command is the same on Linux,
AIX, etc..

When the source tree is checked out, it will include the "windows-build.txt"
and the "unix-like-build.txt" files.  Pick the file appropriate for the
platform on which the build is to take place and follow the directions in
the file.
