INSTALLING PERL AND RELATED MODULES TO USE WriteXLS June 24, 2009 BASIC REQUIREMENTS 1. A working version of Perl (http://www.perl.org/) 2. The following Perl modules: OLE::Storage_Lite Parse::RecDescent Getopt::Long File::Basename Spreadsheet::WriteExcel Encode Text::CSV_XS GENERAL COMMENTS Some or all of these modules may be installed with recent Perl distributions. For example, ActiveState's Perl distributions (http://www.activestate.com/activeperl/) version 5.8.8.x (Build 824 or later) and version 5.10.x (Build 1003 or later) contain all of the required Perl modules, with the default installation. Other Perl distributions, such as Strawberry Perl for Windows, Apple's Perl installation on OSX and others do not have all required modules in their default installation. Thus, one will need to install any missing Perl modules from the above list using operating system and Perl distribution specific actions. With the exception of the last three modules, all other modules are included with the WriteXLS CRAN package and should be used if not otherwise installed on your system. It is rather important to note, that the last two modules in the list (Encode and Text::CSV_XS) are not "Pure Perl" modules and are therefore not included with WriteXLS. They have been written in such a way as to call external C code. They are therefore operating system and Perl version specific. More information on 'XS' Perl modules is available here: http://en.wikipedia.org/wiki/XS_(Perl) It is my experience, that of the two, Encode seem to be part of most default Perl installations. Text::CSV_XS seems to be the one most likely to require separate installation, again, with the exception of ActiveState Perl, as noted above. Thus, in most cases, this may be the only Perl module that you will need to install beyond what is already provided in your Perl installation and the WriteXLS package. If you are missing any of these three modules and need to install them from CPAN (http://www.cpan.org/) from source, as opposed to having access to pre-compiled versions, such as is available from ActiveState or on some Linux distributions, you will also need to have a C compiler and related building tools (eg. make, tar, etc.) available on your system. The build process for these Perl modules from source code, involves compiling both the Perl and the C code included. In addition, Perl versions are not binary compatible, even on the same operating system. Thus, if for example, you should compile these modules using Perl version 5.8.x and then try to run them with Perl 5.10.x, you will almost certainly experience errors, likely manifesting themselves as version conflicts or the like. This can be a problem, if you should have more than one version of Perl installed on your system or upgrade from one to another. 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. 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. 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 has been noted above and 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 session is correct. If you should have another version of Perl installed (for example the RTools package provided by Duncan Murdoch at http://www.murdoch-sutherland.com/Rtools/), 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. The former would be the easiest approach in the long run, as the ActiveState version of Perl will provide the same functionality and more as compared to the RTools version. 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://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/ Alternatives to using the ActiveState version of Perl would include using the Strawberry Perl distribution available from: http://strawberryperl.com/ or as noted above, the RTools version of Perl that Duncan provides. In either case, as of this writing, some of the required Perl modules (notably Text::CSV_XS) are not included. In both of these cases, you would need to install the missing modules from CPAN, using a command in the Windows Command Terminal like: cpan -i Text::CSV_XS As noted above, these modules also require a C compiler and associated tools to be installed. Thus, if you have the RTools package installed, you should be set. If you are using the Strawberry Perl installation then you should install the RTools package, as it provides all of the required C compilers, make, tar and related tools that will be needed to build and install the additional Perl modules from source code. 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-xs-perl For RH/Fedora, these perl modules are packaged as 'RPM' files and are typically prefixed with 'perl-SOMETHING'. For example: perl-Text-CSV_XS 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 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. OSX Apple installs a default Perl distribution with OSX on Macs. However, at least Text::CSV_XS appears to not be installed by default on all OSX systems. 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 will also need a C compiler and related build tools. This will require the installation of the Apple XCode Tools bundle, which is available from the OSX installation DVD provided by Apple with your Mac, or can be downloaded separately from the Apple Developer web site at: http://developer.apple.com/TOOLS/xcode/ You can download the toolset after registering for a free online membership. 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 Text::CSV_XS 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