NOTES-Perl.md

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