[thirdparty/openssl.git] / NOTES.PERL

 TOC
 ===

 - Notes on Perl
 - Notes on Perl on Windows
 - Notes on Perl modules we use
 - Notes on installing a perl module

 Notes on Perl
 -------------

 For our scripts, we rely quite a bit on Perl, and increasingly on
 some core Perl modules.  These Perl modules are part of the Perl
 source, so if you build Perl on your own, you should be set.

 However, if you install Perl as binary packages, the outcome might
 differ, and you may have to check that you do get the core modules
 installed properly.  We do not claim to know them all, but experience
 has told us the following:

 - on Linux distributions based on Debian, the package 'perl' will
   install the core Perl modules as well, so you will be fine.
 - on Linux distributions based on RPMs, you will need to install
   'perl-core' rather than just 'perl'.

 You MUST have at least Perl version 5.10.0 installed.  This minimum
 requirement is due to our use of regexp backslash sequence \R among
 other features that didn't exist in core Perl before that version.

 Notes on Perl on Windows
 ------------------------

 There are a number of build targets that can be viewed as "Windows".
 Indeed, there are VC-* configs targeting VisualStudio C, as well as
 MinGW and Cygwin. The key recommendation is to use "matching" Perl,
 one that matches build environment. For example, if you will build
 on Cygwin be sure to use the Cygwin package manager to install Perl.
 For MSYS builds use the MSYS provided Perl.
 For VC-* builds we recommend Strawberry Perl, from http://strawberryperl.com.
 An alternative is ActiveState Perl, from http://www.activestate.com/ActivePerl
 for which you may need to explicitly select the Perl module Win32/Console.pm
 available via https://platform.activestate.com/ActiveState.

 Notes on Perl on VMS
 --------------------

 You will need to install Perl separately.  One way to do so is to
 download the source from http://perl.org/, unpacking it, reading
 README.vms and follow the instructions.  Another way is to download a
 .PCSI file from http://www.vmsperl.com/ and install it using the
 POLYCENTER install tool.

 Notes on Perl modules we use
 ----------------------------

 We make increasing use of Perl modules, and do our best to limit
 ourselves to core Perl modules to keep the requirements down.  There
 are just a few exceptions:

 Test::More         We require the minimum version to be 0.96, which
                    appeared in Perl 5.13.4, because that version was
                    the first to have all the features we're using.
                    This module is required for testing only!  If you
                    don't plan on running the tests, you don't need to
                    bother with this one.

 Text::Template     This module is not part of the core Perl modules.
                    As a matter of fact, the core Perl modules do not
                    include any templating module to date.
                    This module is absolutely needed, configuration
                    depends on it.

 To avoid unnecessary initial hurdles, we have bundled a copy of the
 following modules in our source.  They will work as fallbacks if
 these modules aren't already installed on the system.

    Text::Template

 Notes on installing a perl module
 ---------------------------------

 There are a number of ways to install a perl module.  In all
 descriptions below, Text::Template will serve as an example.

 1. for Linux users, the easiest is to install with the use of your
    favorite package manager.  Usually, all you need to do is search
    for the module name and to install the package that comes up.

    On Debian based Linux distributions, it would go like this:

        $ apt-cache search Text::Template
        ...
        libtext-template-perl - perl module to process text templates
        $ sudo apt-get install libtext-template-perl

    Perl modules in Debian based distributions use package names like
    the name of the module in question, with "lib" prepended and
    "-perl" appended.

 2. Install using CPAN.  This is very easy, but usually requires root
    access:

        $ cpan -i Text::Template

    Note that this runs all the tests that the module to be installed
    comes with.  This is usually a smooth operation, but there are
    platforms where a failure is indicated even though the actual tests
    were successful.  Should that happen, you can force an
    installation regardless (that should be safe since you've already
    seen the tests succeed!):

        $ cpan -f -i Text::Template

    Note: on VMS, you must quote any argument that contains upper case
    characters, so the lines above would be:

        $ cpan -i "Text::Template"

    and:

        $ cpan -f -i "Text::Template"
Commit	Line	Data
d36ab9ce RL	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
de812820 RL	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.
d36ab9ce RL	29
	30	Notes on Perl on Windows
	31	------------------------
	32
4b16fa79 AP	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.
df4c1d80 DDO	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.
d36ab9ce	43
f578075a RL	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
073b1b72	49	README.vms and follow the instructions. Another way is to download a
fe072ed7 RL	50	.PCSI file from http://www.vmsperl.com/ and install it using the
fe072ed7 RL	51	POLYCENTER install tool.
f578075a	52
d36ab9ce RL	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 We require the minimum version to be 0.96, which
	61	appeared in Perl 5.13.4, because that version was
	62	the first to have all the features we're using.
	63	This module is required for testing only! If you
	64	don't plan on running the tests, you don't need to
	65	bother with this one.
	66
	67	Text::Template This module is not part of the core Perl modules.
	68	As a matter of fact, the core Perl modules do not
	69	include any templating module to date.
	70	This module is absolutely needed, configuration
	71	depends on it.
	72
	73	To avoid unnecessary initial hurdles, we have bundled a copy of the
	74	following modules in our source. They will work as fallbacks if
	75	these modules aren't already installed on the system.
	76
	77	Text::Template
	78
	79	Notes on installing a perl module
	80	---------------------------------
	81
	82	There are a number of ways to install a perl module. In all
3e4e43e6	83	descriptions below, Text::Template will serve as an example.
d36ab9ce RL	84
	85	1. for Linux users, the easiest is to install with the use of your
	86	favorite package manager. Usually, all you need to do is search
	87	for the module name and to install the package that comes up.
	88
	89	On Debian based Linux distributions, it would go like this:
	90
	91	$ apt-cache search Text::Template
	92	...
	93	libtext-template-perl - perl module to process text templates
	94	$ sudo apt-get install libtext-template-perl
	95
	96	Perl modules in Debian based distributions use package names like
	97	the name of the module in question, with "lib" prepended and
	98	"-perl" appended.
	99
	100	2. Install using CPAN. This is very easy, but usually requires root
	101	access:
	102
	103	$ cpan -i Text::Template
	104
073b1b72	105	Note that this runs all the tests that the module to be installed
d36ab9ce	106	comes with. This is usually a smooth operation, but there are
073b1b72	107	platforms where a failure is indicated even though the actual tests
d36ab9ce RL	108	were successful. Should that happen, you can force an
	109	installation regardless (that should be safe since you've already
	110	seen the tests succeed!):
	111
	112	$ cpan -f -i Text::Template
f578075a RL	113
	114	Note: on VMS, you must quote any argument that contains upper case
	115	characters, so the lines above would be:
	116
	117	$ cpan -i "Text::Template"
	118
	119	and:
	120
	121	$ cpan -f -i "Text::Template"