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

* Checkout and build from the source in the Subversion repository.

Please read ALL of these notes before attempting to build 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.

Important: An "upgrade" type of installation is neither tested nor supported
on any platform.  Please completely uninstall a prior version of ooRexx
before installing a new version.  Installing over the top of an existing
installation is likely to produce unpredictable results.

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 a generically named release as an example, to install without
prompting into the "D:\Local Interpreters" directory, the following command
line could be used:

E:\downloads\ooRexx-5.0.0-12188.windows.x86_64.exe /S /D=D:\Local Interpreters\ooRexx

An existing version of ooRexx must 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.

Notes for Windows Versions After XP
-----------------------------------
Windows Vista and later versions have a feature known as User Account
Control (UAC.)  ooRexx is fully supported on these versions of Windows,
however UAC places some restrictions on the ooRexx installer.  The same
Windows installer is used on all versions of Windows.

On Vista or later 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 and later 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 and later, 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, which
are largely based on UAC.  Therefore the user is advised to install rxapi as
a service on versions of Windows with UAC.  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.

As for all versions of ooRexx, any previous installations must be completely
uninstalled first.  The commands to do a basic install are as follows:

Debian:

dpkg -P ooRexx
dpkg -i <packageFile>

RPM:

rpm -e ooRexx
rpm -iv <packageFile>

System using the systemd daemon:

sudo systemctl --system daemon-reload

Using a generically named packages as an example. They must be executed as
root or using sudo.  If there is no previous installation of ooRexx, skip
the first command, (dpkg -P or rpm -e) they are the commands to uninstall a
previous version.

tom@Loon:~/downloads$ dpkg -P ooRexx
tom@Loon:~/downloads$ dpkg -i ooRexx-5.0.0-12189.ubuntu1604.x86_64.deb
# if systemd is installed:
tom@Loon:~/downloads$ sudo systemctl --system daemon-reload

Raven:/home/tom # rpm -e ooRexx
Raven:/home/tom # rpm -iv oorexx/5.0.0beta/ooRexx-5.0.0-12189.centos7.x86_64.rpm
# if systemd is installed:
Raven:/home/tom # sudo systemctl --system daemon-reload

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 is a .dmg install package for Intel based macOS systems.

The commands to install a .dmg file are as follows:

1. Copy the ooRexx5 image (.dmg file) to the desktop or to a folder. Image name
   will show version and revision such as ooRexx-5.0.0-12149.macOS.x86_64
2. Mount the image by double clicking on it
3. Drag ooRexx5 to the Applications icon
For Mojave and before:
4a. Add "export PATH=/Applications/ooRexx5/bin:$PATH" to .bash_profile
For Catalina:
4b. Add "export PATH=/Applications/ooRexx5/bin:$PATH" to .zshrc

Confirm that the installation works by entering one of:

rexx -v (display version of Rexx)

rexx (show syntax)

rexx /Applications/ooRexx5/share/ooRexx/rexxcps (benchmark)

To uninstall just drag the folder ooRexx5 in /Applications to the garbage
bin and remove the export line from .bash_profile or .zshrc.

NOTE: .bash_profile and .zshrc are invisible files that resides in each users
home folder, to see it press shift command . (dot or period character),
all 3 at the same time.

If you do not have .bash_profile enter touch .bash_profile in a terminal
window to create it. Same for .zshrc if you are using Catalina.

PLEASE ALSO NOTE:
ooRexx 5 can be installed anywhere, without any elevated rights, i.e. it is
"sudo free" as long as it is installed where the user has R/W rights. You
can for instance make a folder "Applications" (if not already existing) in
the home folder (~) and drag ooRexx5 there. The export line in .bash_profile
or .zshrc should be amended correspondingly.

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.1.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.1.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.) The tar file should be used on unix-like systems and the
zip file on Windows systems.  Both the tar and the zip files contain the
same source code, but with suitable line endings.  The zip also contains the
PDF docs, which are needed in the packaging step on Windows.  The tar file
contains the configure skip so that ooRexx can be built on a unix-like
system without installing the autoconf tools.

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, macOS, AIX, etc.)
---------------------------------------------

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


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:

  https://subversion.apache.org/

Once the Subversion client is installed, the command to checkout is as
follows, using the 5.0.0 trunk as an example:

svn co svn://svn.code.sf.net/p/oorexx/code-0/main/trunk oorexxSVN

For a specific revision:
svn co svn://svn.code.sf.net/p/oorexx/code-0/main/trunk@12000 oorexxSVN

You can also check out the release code for any prior version of ooRexx.
Using the 4.2.0 relase as an example, use the proper release number for 
other versions:

svn co svn://svn.code.sf.net/p/oorexx/code-0/main/releases/4.2.0/trunk OldSVN

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.

Again, note that the svn command is the same on any platform (Windows, Linux,
macOS, 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.
%