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