NOTES-PERL.md

   1 Notes on Perl
   2 =============
   3
   4  - [General Notes](#general-notes)
   5  - [Perl on Windows](#perl-on-windows)
   6  - [Perl on VMS](#perl-on-vms)
   7  - [Perl on NonStop](#perl-on-nonstop)
   8  - [Required Perl modules](#required-perl-modules)
   9  - [Notes on installing a Perl module](#notes-on-installing-a-perl-module])
  10
  11
  12 General Notes
  13 -------------
  14
  15 For our scripts, we rely quite a bit on Perl, and increasingly on
  16 some core Perl modules.  These Perl modules are part of the Perl
  17 source, so if you build Perl on your own, you should be set.
  18
  19 However, if you install Perl as binary packages, the outcome might
  20 differ, and you may have to check that you do get the core modules
  21 installed properly.  We do not claim to know them all, but experience
  22 has told us the following:
  23
  24  - on Linux distributions based on Debian, the package `perl` will
  25    install the core Perl modules as well, so you will be fine.
  26  - on Linux distributions based on RPMs, you will need to install
  27    `perl-core` rather than just `perl`.
  28
  29 You MUST have at least Perl version 5.10.0 installed.  This minimum
  30 requirement is due to our use of regexp backslash sequence \R among
  31 other features that didn't exist in core Perl before that version.
  32
  33 Perl on Windows
  34 ---------------
  35
  36 There are a number of build targets that can be viewed as "Windows".
  37 Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
  38 MinGW and Cygwin. The key recommendation is to use a Perl installation
  39 that matches the build environment. For example, if you will build
  40 on Cygwin be sure to use the Cygwin package manager to install Perl.
  41 For MSYS builds use the MSYS provided Perl.
  42 For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
  43 An alternative is ActiveState Perl, from <http://www.activestate.com/ActivePerl>
  44 for which you may need to explicitly select the Perl module Win32/Console.pm
  45 available via <https://platform.activestate.com/ActiveState>.
  46
  47 Perl on VMS
  48 -----------
  49
  50 You will need to install Perl separately.  One way to do so is to
  51 download the source from <http://perl.org/>, unpacking it, reading
  52 `README-VMS.md` and follow the instructions.  Another way is to download a
  53 `.PCSI` file from <http://www.vmsperl.com/> and install it using the
  54 POLYCENTER install tool.
  55
  56 Perl on NonStop
  57 ---------------
  58
  59 Perl is installed on HPE NonStop platforms as part of the Scripting Languages
  60 package T1203PAX file. The package is shipped as part of a NonStop RVU
  61 (Release Version Updates) package. Individual SPRs (Software Product Release)
  62 representing fixes can be obtained from the Scout website at
  63 <https://h22204.www2.hpe.com/NEP>. Follow the appropriate set of installation
  64 instructions for your operating system release as described in the
  65 Script Language User Guide available from the NonStop Technical Library.
  66
  67 Required Perl modules
  68 ---------------------
  69
  70 We do our best to limit ourselves to core Perl modules to keep the
  71 requirements down. There are just a few exceptions.
  72
  73
  74 ## For Building
  75
  76  * `Text::Template`
  77
  78    This module is not part of the core Perl modules.
  79    As a matter of fact, the core Perl modules do not
  80    include any templating module to date.
  81    This module is absolutely needed,
  82    configuration depends on it.
  83
  84 ## For Testing
  85
  86  * `Test::More`
  87
  88    We require the minimum version to be 0.96, which
  89    appeared in Perl 5.13.4, because that version was
  90    the first to have all the features we're using.
  91    This module is required for testing only!
  92    If you don't plan on running the tests,
  93    you don't need to bother with this one.
  94
  95
  96
  97 To avoid unnecessary initial hurdles, we have bundled a copy of the
  98 following modules in our source.  They will work as fallbacks if
  99 these modules aren't already installed on the system.
 100
 101    Text::Template
 102
 103 Notes on installing a Perl module
 104 ---------------------------------
 105
 106 There are a number of ways to install a perl module.  In all
 107 descriptions below, `Text::Template` will serve as an example.
 108
 109 1. for Linux users, the easiest is to install with the use of your
 110    favorite package manager.  Usually, all you need to do is search
 111    for the module name and to install the package that comes up.
 112
 113    On Debian based Linux distributions, it would go like this:
 114
 115        $ apt-cache search Text::Template
 116        ...
 117        libtext-template-perl - perl module to process text templates
 118        $ sudo apt-get install libtext-template-perl
 119
 120    Perl modules in Debian based distributions use package names like
 121    the name of the module in question, with "lib" prepended and
 122    "-perl" appended.
 123
 124 2. Install using CPAN.  This is very easy, but usually requires root
 125    access:
 126
 127        $ cpan -i Text::Template
 128
 129    Note that this runs all the tests that the module to be installed
 130    comes with.  This is usually a smooth operation, but there are
 131    platforms where a failure is indicated even though the actual tests
 132    were successful.  Should that happen, you can force an
 133    installation regardless (that should be safe since you've already
 134    seen the tests succeed!):
 135
 136        $ cpan -f -i Text::Template
 137
 138    Note: on VMS, you must quote any argument that contains upper case
 139    characters, so the lines above would be:
 140
 141        $ cpan -i "Text::Template"
 142
 143    and:
 144
 145        $ cpan -f -i "Text::Template"