coxinterval: Installation instructions

------------
REQUIREMENTS
------------

Required software for coxinterval is summarized as follows. System-specific notes
for items 1 and 2 are provided below.

1. Development tools for R, including GNU make
2. C API for CPLEX available with IBM ILOG CPLEX Optimization Studio 12.5+.
   Members of IBM's Academic Initiative can obtain CPLEX at no charge. Without
   CPLEX, coxinterval offers reduced functionality.

Linux
-----

1. Install the r-base-dev package. For further details, see the R download
   documentation (http://cran.r-project.org/bin/linux/) for your Linux
   distribution.

Mac
---

1. Install software listed in the tools section of the Mac OS X R download
   documentation (http://cran.r-project.org/bin/macosx/tools). With R 3+, this
   amounts to the GNU Fortran compiler gfortran.

Windows
-------

1. Install Rtools (http://cran.r-project.org/bin/windows/Rtools/). From a command
   prompt run 'set PATH' and ensure that the value for the PATH environment
   variable includes the folders for both R and Rtools binaries. If not, update
   PATH using the Windows command set. For example:

   set PATH=C:/Rtools/bin;C:/Rtools/gcc-4.6.3/bin;%PATH%
   set PATH=C:/Program Files/R/R-3.2.0/bin;%PATH%

2. Install 32-bit CPLEX. Note that this means that the package's CPLEX-dependent
   functions are limited to 32-bit R.

----------
INSTALLING
----------

To install from CRAN, run in an R session:

> install.packages("coxinterval", type = "source")

To install a development release from GitHub, download the package tarball from
https://github.com/aboruvka/coxinterval/releases to your R session working
directory and run:

> install.packages("coxinterval_<version>.tar.gz", repos = NULL, type = "source")

Overriding installer defaults
-----------------------------

In the interest of easy installation over complete portability, the package's
Makevars files uses non-standard GNU make extensions to locate CPLEX's default
directory, which depends on the system.

- Linux: /opt/*/ILOG/CPLEX*
- Mac: /Users/*/Applications/IBM/ILOG/CPLEX*
- Windows 64-bit: C:/PROGRA~2/IBM/ILOG/CPLEX*
- Windows 32-bit: C:/PROGRA~1/IBM/ILOG/CPLEX*

With custom installations of CPLEX, a directory must specified in POSIX-like
format with the CPLEXDIR environment variable. For example, on a 64-bit Windows
system, install.packages could be preceded with:

> Sys.setenv(CPLEXDIR = "C:/PROGRA~2/IBM/ILOG/CPLEX_Studio126")

The CPLEX-related compiler variables can also be set directly, but the provided
values are not validated. Continuing the above example:

> Sys.setenv(CPLEXINCVARS =
    paste('-I"', Sys.getenv("CPLEXDIR"), '/cplex/include"', sep = ""))
> Sys.setenv(CPLEXLIBVARS =
    paste('-L"', Sys.getenv("CPLEXDIR"),
          '/cplex/lib/x86_windows_vs2010/stat_mda" -lcplex1260 -lm', sep = ""))

Note the use of quotes for correct reference to directory names. These are
unnecessary on (mostly) POSIX-compliant systems like Linux and Mac.

GNU make extensions are further used to locate CPLEX's include and library
directories. In general these have the form

CPLEXINCDIR = <CPLEXDIR>/cplex/include
CPLEXLIBDIR = <CPLEXDIR>/cplex/lib/<machine or compiler>/<library format>

respectively, where the include directory points to the header file
<CPLEXINCDIR>/ilcplex/cplex.h. The choice of the library format has no
consequence for CPLEX's C API. Under Linux and Mac adequate linking option
settings are `-lcplex -lm`. With Windows it is necessary to specify the CPLEX
version number in the library name: -lcplex<version> -lm, where <version> can be
obtained from the library file name <CPLEXLIBDIR>/cplex<version>.lib.

Installing on systems without GNU make
--------------------------------------

Precede the install instructions with:

1. Extract the source from the package tarball
2. Revise the coxinterval/src/Makevars file according to one of the templates
   below
3. Rebuild the package tarball with R CMD build coxinterval

Makevars template for systems with CPLEX:

CPLEXDIR = <add-on software directory>/IBM/ILOG/CPLEX_Studio<version>
CPLEXINCDIR = $(CPLEXDIR)/cplex/include
CPLEXLIBDIR = $(CPLEXDIR)/cplex/lib/<machine>/<library format>
CPLEXINCVARS = -I$(CPLEXINCDIR)
CPLEXLIBVARS = -L$(CPLEXLIBDIR) -lcplex -lm

PKG_CPPFLAGS = $(SHLIB_PTHREAD_FLAGS) $(CPLEXINCVARS)
PKG_LIBS = $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS) $(SHLIB_PTHREAD_FLAGS) \
	$(CPLEXLIBVARS)

Without CPLEX, the first five lines can be replaced with:

CPLEXINCVARS =
CPLEXLIBVARS =