Home | History | Annotate | Line # | Download | only in dist 
      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. For VC-* builds we
     39  recommend ActiveState Perl, available from
     40  http://www.activestate.com/ActivePerl.
     41 
     42  Notes on Perl on VMS
     43  --------------------
     44 
     45  You will need to install Perl separately.  One way to do so is to
     46  download the source from http://perl.org/, unpacking it, reading
     47  README.vms and follow the instructions.  Another way is to download a
     48  .PCSI file from http://www.vmsperl.com/ and install it using the
     49  POLYCENTER install tool.
     50 
     51  Notes on Perl modules we use
     52  ----------------------------
     53 
     54  We make increasing use of Perl modules, and do our best to limit
     55  ourselves to core Perl modules to keep the requirements down.  There
     56  are just a few exceptions:
     57 
     58  Test::More         We require the minimum version to be 0.96, which
     59                     appeared in Perl 5.13.4, because that version was
     60                     the first to have all the features we're using.
     61                     This module is required for testing only!  If you
     62                     don't plan on running the tests, you don't need to
     63                     bother with this one.
     64 
     65  Text::Template     This module is not part of the core Perl modules.
     66                     As a matter of fact, the core Perl modules do not
     67                     include any templating module to date.
     68                     This module is absolutely needed, configuration
     69                     depends on it.
     70 
     71  To avoid unnecessary initial hurdles, we have bundled a copy of the
     72  following modules in our source.  They will work as fallbacks if
     73  these modules aren't already installed on the system.
     74 
     75     Text::Template
     76 
     77  Notes on installing a perl module
     78  ---------------------------------
     79 
     80  There are a number of ways to install a perl module.  In all
     81  descriptions below, Text::Template will serve as an example.
     82 
     83  1. for Linux users, the easiest is to install with the use of your
     84     favorite package manager.  Usually, all you need to do is search
     85     for the module name and to install the package that comes up.
     86 
     87     On Debian based Linux distributions, it would go like this:
     88 
     89         $ apt-cache search Text::Template
     90         ...
     91         libtext-template-perl - perl module to process text templates
     92         $ sudo apt-get install libtext-template-perl
     93 
     94     Perl modules in Debian based distributions use package names like
     95     the name of the module in question, with "lib" prepended and
     96     "-perl" appended.
     97 
     98  2. Install using CPAN.  This is very easy, but usually requires root
     99     access:
    100 
    101         $ cpan -i Text::Template
    102 
    103     Note that this runs all the tests that the module to be installed
    104     comes with.  This is usually a smooth operation, but there are
    105     platforms where a failure is indicated even though the actual tests
    106     were successful.  Should that happen, you can force an
    107     installation regardless (that should be safe since you've already
    108     seen the tests succeed!):
    109 
    110         $ cpan -f -i Text::Template
    111 
    112     Note: on VMS, you must quote any argument that contains uppercase
    113     characters, so the lines above would be:
    114 
    115         $ cpan -i "Text::Template"
    116 
    117     and:
    118 
    119         $ cpan -f -i "Text::Template"
    120