.. _installing-rlm:

##############
Installing RLM
##############

To install RLM, follow these steps:

************************************************
First, Download the kit from the Reprise website
************************************************

To download RLM, go to the 
`Reprise Website Download <https://www.reprisesoftware.com/support/publishers/developer-kits-for-
software-publishers/>`_ area, enter your username and password, and select the kit(s) you want to 
download. Save these on your system, then uncompress and (on Unix) extract the binaries with the 
*tar xvf* command.

Each kit has a descriptive name on the website. The file names of the kits follow Reprise
Software's platform naming conventions, with ".tar.gz" (Unix) or ".zip" (Windows) appended.

.. collapse:: View Platform Kits

	.. list-table:: 
		:widths: 50 18 32
		:header-rows: 1

		* - Platform 
		  - Platform Name 
		  - Kit file name
		* - Windows on Intel X86 (Visual C 2013) 
		  - x86_w3 
		  - rlm.vX.YBLZ-x86_w3.zip
		* - Windows 64-bit on Intel X86 (Visual C 2013) 
		  - x64_w3 
		  - rlm.vX.YBLZ-x64_w3.zip
		* - Windows on Intel X86 (visual C 2015+) 
		  - x86_w4 
		  - rlm.vX.YBLZ-x86_w4.zip
		* - Windows 64-bit on Intel X86 (visual C 2015+) 
		  - x64_w4 
		  - rlm.vX.YBLZ-x64_w4.zip
		* - Windows ARM64 (visual C 2015+) 
		  - arm64_w4 
		  - rlm.vX.YBLZ-arm_w4.zip
		* - Linux on Intel X86 
		  - x86_l1, x86_l2 
		  - x86_l1.tar.gz, x86_l2.tar.gz
		* - Linux 64-bit on Intel 
		  - x64_l1 
		  - x64_l1.tar.gz		
		* - Mac on Intel X86 
		  - x86_m1 
		  - x86_m1.tar.gz
		* - Mac on PPC 
		  - ppc_m1 
		  - ppc_m1.tar.gz	
		* - Java for Unix (requires x86_l2, x64_l1, or x86_m1 kit. x86_l2 only prior to RLM v6) 
		  - java_unix 
		  - java_unix.tar.gz		  	   
		* - HP-UX on PA-Risc
		  - hp_h1
		  - hp_h1.tar.gz
		* - HP-UX 64-bit on PA-Risc 
		  - hp64_h1 
		  - hp64_h1.tar.gz
		* - IBM AIX 32-bit 
		  - ibm_a1 
		  - ibm_a1.tar.gz
		* - IBM AIX 64-bit 
		  - ibm64_a1 
		  - ibm64_a1.tar.gz
		* - Solaris 32-bit on Intel 
		  - x86_s1 
		  - x86_s1.tar.gz
		* - Solaris 64-bit on Intel 
		  - x64_s1 
		  - x64_s1.tar.gz
		* - Solaris on Sparc 
		  - sun_s1 
		  - sun_s1.tar.gz
		* - Solaris 64-bit on Sparc 
		  - sun64_s1 
		  - sun64_s1.tar.gz



.. raw:: html

   <hr>

********************************
Next, unpack the kit and install
********************************

* For the majority of cases using a C-compiler, follow the instructions in this section.
* For information on using RLM with Java, see :ref:`using-rlm-languages-other-than-c`.
* For information on using RLM in a cross-development environment, see :ref:`building-rlm-kit-\
  cross-compiler`.

To unpack the kit and perform the installation, follow these steps:
At the shell prompt on Unix:

:: 

	% gunzip platform.tar.gz
	% tar xvf platform.tar
	% ./INSTALL
	% # update src/license_to_run.h if required
	% # Your license for RLM comes via email from Reprise Software.
	% # RLM kits are pre-built with demo licenses valid for
	% # approximately two months from date of release.
	% cd platform
	% make

.. warning:: RLM requires a license to operate from Reprise Software.


On Windows, the kit is a Windows .zip file. Extract the .zip file, whose name is 
rlm.\ *ver-platform*\ .zip, where *ver* is the RLM version and platform is the RLM platform name. 
For example, rlm.v13.0BL1-x86_w4.zip is the kit for v13.0BL2 on the x86_w4 platform. Extract the
.zip file to the preferred installation location (for example: C:\\Reprise\\).

Previously, the Windows kit came packaged as an executable that provided the option to copy the key
pair from an existing RLM installation into the new install. The key pair must now be manually copied
if there is an existing installation. Copying the key pair is useful if you are upgrading your RLM
version, or installing RLM on another system at the same release level and wish to use the same
key pair. Copying the key pair is important for having compatible license signatures across the 
installations and is recommended.

RLM kits are pre-built for ISV "demo", with licenses that expire 30-60 days after the release date. 
If your demo license has expired, you will need to put the new license you received from Reprise 
Software into the file src\\license_to_run.h. If you have purchased RLM, you will need to edit 
src\\license_to_run.h to replace the license there with your permanent license, and you will also 
need to edit the makefile in the binary directory (x86_w* or x64_w*) to change your ISV name. If 
you plan to use the example license file example.lic in the platform directory, edit the file, 
and change all instances of "demo" to your ISV name.

.. warning:: RLM requires a license to operate from Reprise Software.

You have 2 options for building RLM on Windows - you can either use a Visual Studio or Visual C++
Project, or a Command Window. Each method has the same outputs; choose the method you’re more
comfortable with.

To build using Visual Studio/Visual C++:
========================================

1. The platform directories (x86_w* and x64_w*) contain Microsoft Visual Studio or Visual
   C++ project and workspace files. Double-click on the appropriate file to launch Visual
   Studio/Visual C++. In x86_w3, double-click on **x86_w3.vcproj**. In x64_w4, double-click
   on **x64_w4vcproj**, etc.
2. When the development environment comes up, click on the Build menu and select
   "Rebuild All" (Visual C++) or "Build Solution" (Visual Studio). When the build is done,
   the output window should indicate 0 errors and warnings.

You may be prompted to allow Visual C++ to convert the project to a later version. Allow
it to do so, then proceed.

To build using a Command Window:
================================

1. Create a command window with the Visual C++ environment set up

	* Create a command window and run a batch file provided by Microsoft to set up
	  your command window for the next step. The batch file is Program Files 
	  [(x86)]\Microsoft Visual Studio *<version>*\ \\VC\\vcvarsall.bat
  
    -OR-

	* Create a command window via the Start->MS VisualStudioxxx or Start->MS
	  Visual C++ menu. The specific sub-menu items vary with version, but the target
	  is "Visual Studio Command Prompt".

2. cd to the platform directory of the SDK, for example:
	 
	 .. code-block::
	 			text
				
				cd x86_w3

3. Type nmake

------

********************
A note about OpenSSL
********************

As of RLM v16.1, OpenSSL has been updated to 3.0.15 and the private name space for OpenSSL routines 
(rlmssl) has been removed. If you need to link an older or newer build of OpenSSL to RLM, build the 
NOSSL from the RLM makefile.

------

.. _building-rlm-kit-cross-compiler:

*******************************************
Building the RLM kit using a cross-compiler
*******************************************

On certain platforms (e.g., arm_l1 and xpi_l1), the RLM kit must be cross-compiled on a host system 
which doesn't run the target instruction set. For these platforms, follow the directions here.

.. note:: These directions are for Unix systems only, to do cross-development on Windows, you are 
   on your own. See the makefile.

To unpack the kit and perform the installation, follow these steps:

At the shell prompt on Unix:

.. code-block::
		text

		% gunzip platform.tar.gz
		% tar xvf platform.tar
		% ./INSTALL
		%   # update src/license_to_run.h if required
		%   # Your license for RLM comes via email from Reprise Software.
		%   # RLM kits are pre-built with demo licenses valid for
		%   # approximately two months from date of release.
		% cd platform

At this point, on a “normal” RLM platform, you would simply type “make”. However, in a cross
development environment, the make process is split into 4 or 5 steps. In these instructions, we will 
refer to the two systems as the host (the system with the cross-development tools), and the target 
- the target system which does not have development tools.

1. First, on the **host** system (the one with the cross-development tools):
	
	 .. code-block::
		 	text

			% make step1

2. Next, copy *rlmgenkeys* to the **target**; run rlmgenkeys; copy rlm_privkey.c and
   rlm_pubkey.c back to the **host** system into the src directory.
3. Next, on the **host** system:

	 .. code-block::
		 	text

			% make step3

4. Next, copy the kit (the whole directory, e.g. arm_l1) to the **target**.
5. Next, on the **target**: (optional, only if you have a full client-server RLM kit).
	 
	 .. code-block::
	 		text

			% make step5

Your kit is now built on the target and ready to use.

.. note:: Skip steps 1 and 2 if you have a key pair from another RLM platform, and put the keys 
   into the src directory on the **host** system; start from step 3 above. Skip step 5 if you have 
   a client-only kit, or if you do not care about creating an ISV.set settings file.

------

**************
RLM kit layout
**************

Each RLM kit (for a particular platform) is contained in 3 or 5 subdirectories:

* Machine-independent subdirectory (src)
* Machine-independent examples subdirectory (examples)
* Machine-dependent subdirectory (name varies for each platform)

In addition, on Windows, there is an additional directory:

* A directory of .NET support files called "dotnet".

Java support is contained in an independent directory called either "java_unix" or "java_win".

The platform names for RLM follow the convention:

	\arch_[\ *os*\ ][\ *ver*\ ]

where:

* *arch* is the Reprise Software name for the processor/chip architecture
* *os* is the Reprise Software identifier for the operating system, and
* *ver* is the Reprise Software identifier for our version of RLM OS support (note: this is NOT the
  operating system version)

Current RLM platform names are:
===============================

.. list-table::
	:header-rows: 1

	* - Platform 
	  - Directory Name 
	  - Notes
	* - Windows 32-bit 
	  - x86_w3 
	  - Visual Studio 2013
	* - Windows 32-bit 
	  - x86_w4 
	  - Visual Studio 2015 and later
	* - Windows 64-bit 
	  - x64_w3 
	  - Visual Studio 2013
	* - Windows 64-bit 
	  - x64_w4 
	  - Visual Studio 2015 and later	  
	* - Windows ARM64
	  - arm64_w4 
	  - Visual Studio 2022 and later	  	  
	* - Linux on ARM 
	  - arm_l1 
	  - Client-only kit
	* - Linux on Intel X86 
	  - x86_l2
	  - 
	* - Linux (64-bit) on Intel 
	  - x64_l1
	  - 
	* - Linux on PPC 
	  - ppc_l1, ppc64_l1
	  - 
	* - Linux on Xeon PI coprocessor 
	  - xpi_l1 
	  - Client-only kit	
	* - MAC on Intel X86 
	  - x86_m1
	  - 
	* - MAC (64-bit) on X86 
	  - x64_m1
	  - 
	* - MAC on PPC 
	  - ppc_m1
	  - 	    
	* - HP-UX on PA-Risc 
	  - hp_h1
	  - 
	* - HP-UX 64-bit on PA-Risc 
	  - hp64_h1
	  - 
	* - IBM AIX 32-bit 
	  - ibm_a1
	  - 
	* - IBM AIX 64-bit 
	  - ibm64_a1
	  - 
	* - NetBSD on Intel 
	  - x86_n1
	  - 
	* - Solaris (32-bit) on Intel 
	  - x86_s1
	  - 
	* - Solaris (64-bit) on Intel 
	  - x64_s1
	  - 
	* - Solaris on Sparc 
	  - sun_s1
	  - 
	* - Solaris (64-bit) on Sparc 
	  - sun64_s1
	  - 


RLM Kit Contents
================

The Machine Independent (src) directory contains:
-------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents
	* - license.h 
	  - RLM include file.
	* - license_to_run.h 
	  - License for RLM itself.
	* - rlm_isv_config.c 
	  - Configuration data for ISV server.
	* - RELEASE_NOTES 
	  - Release notes for this version of RLM.
	* - RLM_Reference.txt 
	  - Pointer to RLM documentation on website.
	* - VERSION 
	  - RLM kit version information (not on client-only kits).

The Machine Independent (examples) directory contains:
------------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents
	* - act_api_example.c 
	  - Sample client-side activation code.
	* - activation_example.html 
	  - Sample HTML page for activation.
	* - actpro_demo.c 
	  - Demo program for Activation Pro.
	* - detached_demo.c 
	  - Sample code to implement a Detached Demo\ :sup:`tm`.
	* - example.opt 
	  - Example license administration option file.
	* - integrate_older.c 
	  - Example code for integrating RLM alongside an older LM.
	* - rehost_example.c 
	  - Example for using rehostable hostids and revoking them.
	* - rlm_transfer.c 
	  - Example ISV-defined server transfer code.
	* - rlmclient.c 
	  - Example RLM application program.
	* - roam_example.c 
	  - Example code to implement license roaming.
	* - unsupported 
	  - Directory of unsupported example programs (Fortran
	    interface, python interface).

Each Unix Platform-dependent directory contains (before executing "make" ):
---------------------------------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents 
	  - Notes
	* - example.lic 
	  - Example license file 
	  - Created by INSTALL
	* - librlm.a 
	  - Symbolic link to rlm.a
	  -
	* - makefile 
	  - Makefile
	  -
	* - RLM 
	  - The generic RLM server 
	  - Not on client-only kits
	* - rlm.a 
	  - RLM library
	  -
	* - rlmanon 
	  - RLM logfile anonymizer 
	  - Not on client-only kits
	* - rlmmains.a 
	  - RLM main() functions for misc programs
	  -
	* - rlmutil 
	  - RLM utilities
	  -

The Windows Platform-dependent directory contains (before executing "nmake"):
-----------------------------------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents
	* - example.lic 
	  - Example license file.
	* - isv_main.obj 
	  - main() for ISV server.
	* - isv_server.lib 
	  - library for ISV server.
	* - makefile 
	  - Makefile
	* - rlc.obj 
	  - main() for Activation administration (rlc).
	* - rlm.def 
	  - RLM DLL export definitions.
	* - rlm.exe 
	  - The generic RLM server.
	* - rlm.res 
	  - RLM version resource file.
	* - rlm_genlic.obj 
	  - License generator object.
	* - rlm_mklic.obj 
	  - main() for Activation license generator.
	* - rlmact.obj 
	  - rlc object file.
	* - rlmanon.exe 
	  - RLM logfile anonymizer.
	* - rlmclient.lib 
	  - RLM client library.
	* - rlmclient_md.lib 
	  - RLM client library - compiled with /Md.
	* - rlmclient_mdd.lib 
	  - RLM client library - compiled with /Mdd.
	* - rlmclient_mtd.lib 
	  - RLM client library - compiled with /Mtd.
	* - rlmgen.obj 
	  - rlc license generation module.
	* - rlmgenkeys.obj 
	  - main() for rlmgenkeys utility.
	* - rlmsign.obj 
	  - main() for rlmsign utility.
	* - rlmutil.exe 
	  - RLM utilities.
	* - rlmverify.obj 
	  - main() for RLM log file authentication utility.
	* - x86_w*.vcproj, x64_w*.vcproj 
	  - Visual Studio/Visual C++ project for building the SDK.

The Java directory (java_unix, java_win) contains:
--------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents
	* - docs 
	  - Directory of HTML documentation.
	* - makefile 
	  - Makefile
	* - rlmVVRB.jar 
	  - Java Library (VV=ver, R=rev, B=build).
	* - RlmClient.java 
	  - Example RLM application program.
	* - INSTALL 
	  - Java kit installation script (Unix only).
	* - VERSION 
	  - RLM kit version information.

The dotnet directory (RLM .NET support – Windows only) contains:
----------------------------------------------------------------

.. list-table::
	:header-rows: 1

	* - File 
	  - Contents
	* - Reprise 
	  - Visual Studio 2022 Project Directory for RLM .NET
	    support.
	* - RLMTest 
	  - Visual Studio 2022 Project Directory for RLM .NET Test
	    program.