INSTALLING PERL AND RELATED MODULES TO USE WriteXLS
July 20, 2024


BASIC REQUIREMENTS

1. A working version of Perl (http://www.perl.org/)

2. The following Perl modules:

  Archive::Zip
  Excel::Writer::XLSX
  File::Basename
  Getopt::Long
  OLE::Storage_Lite
  Parse::RecDescent
  Spreadsheet::WriteExcel
  Text::CSV_PP (Frequently packaged in Text::CSV)


GENERAL COMMENTS

As of this writing, the current release version of Perl is 5.40.0, however not all computer
systems are using this version. Some will be using earlier distributions of Perl.

File::Basename and Getopt::Long are "Core" Perl modules and should be part of a standard Perl installation,
however, they are both included in the inst/Perl folder in WriteXLS as a fall back.

The other modules may or may not be installed. Archive::Zip, Excel::Writer::XLSX, OLE::Storage_Lite, 
Parse::RecDescent, Spreadsheet::WriteExcel and Text::CSV_PP are included in the inst/Perl folder in WriteXLS
in order to make it easier for you to use WriteXLS.

Thus, in most cases, all you should have to install is a recent Perl distribution for your operating system
if one is not already installed.


TESTING YOUR PERL INSTALLATION

A function, testPerl(), has been provided in this package to check for Perl and the required Perl
modules. If you have any questions as to whether or not your Perl installation is sufficient to support
WriteXLS(), please use this function. If Perl or any of the required modules are missing, this function
will provide a list of them. If one or more Perl modules are indicated as being missing, please run 
testPerl(verbose = TRUE) to output additional information, such as search paths, which you may find helpful
in debugging any issues, especially if you may have more than one Perl installation on your computer. If that
is the case, you may need to shift the needed version of Perl in your operating system search path ($PATH), 
so that it is found first.


OPERATING SYSTEM SPECIFIC RECOMMENDATIONS

Below are some recommendations for common scenarios on the 3 major operating systems in use 
for R to get you up and running with WriteXLS as easily as possible.

Ideally, all you need to do is to use:

  install.packages("WriteXLS")

within R and have a Perl distribution installed.

Note that you should only consider these following options, if testPerl() (see above) reports missing 
components or you already know that you do not have Perl installed at all.

Be aware, that depending upon the nature of your working computer environment, you may
need to seek the assistance of a System Administrator, who has full access rights to your
computer in order to install third party software. You may also be restricted by any local
computer use policies that affect the software that you can install and use.


WINDOWS

As of this writing, the easiest way to install Perl is to use the ActiveState Perl distribution from: 

  http://www.activestate.com/activeperl/

If this is the only Perl installation on your computer, that should be all that you need to then
run WriteXLS. The ActiveState installer should also modify your $PATH to enable you to easily run
Perl. To verify this, within a Windows Command Terminal, run:

  perl -v

to check to be sure that ActiveState Perl is run and to verify the version and build number 
information. 

Thus, the easiest installation for WriteXLS on Windows is a two step process:

1. Install the WriteXLS binary from CRAN (.zip file)
2. Install ActiveState Perl

Be sure to start a new R session after the installation of ActiveState, so that the $PATH for the 
R session is correct.

If you should have another version of Perl installed, it is possible that the other version
of Perl will be in your $PATH before the ActiveState version. You can either modify your $PATH so
that the ActiveState version is located first, or use the 'perl' argument in the WriteXLS() function
to indicate the full path to the ActiveState Perl executable. 

If you should have an older version of ActiveState installed on your system, which may be missing
any of the required modules, you can either upgrade or the easiest way to install them would be to
use ActiveState's Perl Package Manager (PPM). This would allow you to easily install the additional
modules from the PPM repositories without requiring additional building tools. More information on
using PPM is available here:

  http://www.activestate.com/activeperl

Alternatives to using the ActiveState version of Perl would include using the Strawberry Perl distribution
available from:

  http://strawberryperl.com/

If you should need a C compiler and related tools for Windows, please see the RTools package at:

  https://cran.r-project.org/bin/windows/Rtools/

Note that if you have installed RTools version 4.x or greater, these tools now include Perl as distributed by the MSYS2 project 
(https://www.msys2.org). As this version of Perl is based upon Cygwin, which emulates Linux/Unix behavior, the
default text file line ending character sequence is a LF (linefeed), rather than CRLF (carriage return/linefeed),
the latter being the default on Windows. Beginning with WriteXLS version 6.7.0, this difference is better handled
to allow for the use of the RTools Perl distribution. If you would prefer to use a different Perl distribution, 
use the 'perl' argument in WriteXLS() to point to the perl binary for the other Perl distribution, as the RTools
distribution will otherwise be used by default within R. You can run the testPerl() function in WriteXLS to see which
Perl binary is found and is being used.


LINUX

The more common Linux distributions, such as Debian, Ubuntu, Red Hat and Fedora, provide relatively easy
to use "package management" systems that would allow you to install Perl and add-on modules via command line
and GUI based tools. On the former two, the most common is 'apt-get'. On the latter two, 'yum' is common.

These package management systems will also check and handle any package dependencies that may also be required
on your system, including Perl itself.

These systems would enable you to install Perl and any additional modules using pre-compiled binary packages
via these command line and/or GUI based tools without needing additional build tools.

For Debian/Ubuntu, these Perl modules are packaged as '.deb' files and are typically prefixed with 
'libSOMETHING-perl'. For example:

  libtext-csv-perl 

For RH/Fedora, these perl modules are packaged as 'RPM' files and are typically prefixed with 'perl-SOMETHING'.
For example:
  
  perl-Text-CSV

Thus, using the package management tool for your system, install the missing modules as may be required.

You could also install the modules from source code using CPAN and if that is your preferred approach, feel
free to do so. Remember that you will need the required Perl, C and build tools (in the case of Encode) in 
order to use this methodology.

Lastly, ActiveState does offer a Linux compatible Perl distribution and PPM repository structure. So that is
also an option for you.


macOS

Apple installs a default Perl distribution with macOS on Macs. As of this writing, version 5.30.3 appears
to be the most recent version on Sonoma (14.2.1).

As with Windows above, the easiest approach may very well be to replace/supercede Apple's installation with the
ActiveState Perl installation, which would provide all of the required modules.

If you prefer to stay with the Apple provided Perl distribution and tools, which I did, you may need to install
the missing Perl modules.

In order to do this, Apple uses CPAN and provides the 'cpan' command line tool to install and manage Perl modules.

As discussed, you may also need a C compiler and related build tools to install Encode. This will require the 
installation of the Apple XCode Tools bundle, which can be downloaded separately from the Apple Developer web site at:

  https://developer.apple.com/xcode/

or directly from the Mac App Store. 

Note that recent versions of Xcode no longer include command line tools. These will need to be installed separately 
from within Xcode by going to Preferences -> Downloads or directly via the Apple Developer web site link above.

Once the tools are installed, you can then install any missing Perl modules by using the command line in a Terminal
such as:

  [sudo -H] cpan -i Encode

The 'sudo -H' is optional. It is required if you want to install the additional modules for yourself and other users 
of the Mac. Otherwise, if you just want to perform a 'local' install for yourself, it is not required.


OTHERS

On other operating systems, such as Solaris, the basic approach will be similar to that of Linux, where you can use the 
vendor supplied Perl and installation/build tools or possibly use the ActiveState Perl distribution, which is also
available for Solaris.

If you have another operating system not referenced here, check with your vendor and/or post a message to r-help. If you 
do elect to post to r-help, please be sure to read the Posting Guide to maximize the likelihood of getting a reasonable
response: http://www.R-project.org/posting-guide.html