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

ooRexx has been tested and is supported on Windows 7, 8, 8.1, 10 and 11.
Windows Vista and any version prior to that might work, but is not supported. 

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-12583.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 prior to Windows 7
---------------------------------------------

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. .rpm installers for CentOS, Fedora and
OpenSuse are provided. Debian based systems (Debian, Ubuntu, Kubuntu,
etc.,) use .deb files. .deb installers for Debian, Ubuntu and Linux
Mint are provided.

For systems using the systemd daemon the following may be needed at the end:

sudo systemctl --system daemon-reload

As for all versions of ooRexx, any previous installations should be completely
uninstalled first. In the following examples elevated privileges are implied,
i.e. you may need to use sudo. The commands to do a basic install are as follows:

Debian / Ubuntu / Linux Mint:

dpkg --purge oorexx
dpkg --install <packageFile>
dpkg --status oorexx

alternatively

apt purge oorexx
apt install ./<packageFile>
apt show oorexx

(./ indicates that the package file resides in the current directory)

CentOS / Fedora / OpenSuse

rpm --erase --verbose oorexx
rpm --install --verbose <packageFile>
rpm --query --info oorexx

alternatively CentOS / Fedora

dnf --verbose remove oorexx
dnf --verbose install <packageFile>
dnf info oorexx

alternatively OpenSuse

zypper --verbose remove oorexx
zypper --verbose install <packageFile>
zypper info oorexx


BSD
---
ooRexx 5.0.0 has been built and tested on FreeBSD, OpenBSD and NetBSD.
There is one installer available for FreeBSD; for OpenBSD and NetBSD
look at the portable installer below: 

pkg remove oorexx
pkg install <packageFile>
pkg info oorexx

Solaris
-------

Currently there is no .pkg install package for Solaris, please use the
portable installer (see below)

Mac OSX
-------

There is a .dmg installation package for Intel and arm based (M1/M2 etc)
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
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 and later:
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 or higher.

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 currently no support for AIX.


Portable Installer
------------------

New as of ooRexx 5.0.0 is the possibility to use a "portable" installer
that is available for almost all platforms. On sourceforge they are stored
in the files section in a separate subfolder /portable. There are two
flavors:
a "release.zip" version containing the "whole shebang"
a "release-runtime.zip" containing just a runtime version or ooRexx
The steps are basically the same for all platforms, here for OpenIndiana
and ooRexx 5.1.0:

1. Find and download the relevant zip file to the users home directory

2. Unpack the content

   unzip oorexx-5.0.0-12583.openindiana2021.i386-portable-release.zip

3. Move into the unzipped directory and run
   cd oorexx-5.0.0-12583.openindiana2021.i386-portable-release
   ./setupoorexx.sh

4. Thereafter you can run ooRexx using

   ./rxenv.sh rexx <anyRexxProgram.rex>

5. You can also make this change permanent for the current session using

   source ./setenv2rxenv.sh

   Thereafter you can run ooRexx using only

   rexx <anyRexxProgram.rex>


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, BSD, 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 current 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 5.0.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/5.0.0 oorexxSVN

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.
