Refactor file writing - information on our use of Perl and Perl modules
This includes a start on how to install missing modules.
Reviewed-by: Rich Salz <rsalz@openssl.org>
diff --git a/INSTALL b/INSTALL
index 4852105..f11d7cf 100644
--- a/INSTALL
+++ b/INSTALL
@@ -12,7 +12,8 @@
To install OpenSSL, you will need:
* make
- * Perl 5 with core modules (see 'Note on Perl' further down)
+ * Perl 5 with core modules (please read README.PERL)
+ * The perl module Text::Template (please read README.PERL)
* an ANSI C compiler
* a development environment in form of development libraries and C
header files
@@ -310,26 +311,6 @@
with names of the form <foo.h>.
- Note 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'.
-
- It is highly recommended that you have at least Perl version 5.12
- installed.
-
Note on multi-threading
-----------------------
diff --git a/INSTALL.DJGPP b/INSTALL.DJGPP
index 1047ec9..e1ec676 100644
--- a/INSTALL.DJGPP
+++ b/INSTALL.DJGPP
@@ -11,7 +11,8 @@
You should have a full DJGPP environment installed, including the
latest versions of DJGPP, GCC, BINUTILS, BASH, etc. This package
- requires that PERL and BC also be installed.
+ requires that PERL and the PERL module Text::Template also be
+ installed.
All of these can be obtained from the usual DJGPP mirror sites or
directly at "http://www.delorie.com/pub/djgpp". For help on which
diff --git a/INSTALL.WCE b/INSTALL.WCE
index 3525614..fe1431a 100644
--- a/INSTALL.WCE
+++ b/INSTALL.WCE
@@ -8,6 +8,8 @@
* Appropriate SDK might be required
* Perl for Win32 [commonly recommended ActiveState Perl is available
from http://www.activestate.com/Products/ActivePerl/]
+ You also need the perl module Text::Template.
+ Please read README.PERL for more information.
* wcecompat compatibility library available at
http://www.essemer.com.au/windowsce/
diff --git a/INSTALL.WIN b/INSTALL.WIN
index 4855b62..d579238 100644
--- a/INSTALL.WIN
+++ b/INSTALL.WIN
@@ -6,8 +6,10 @@
Here are a few comments about building OpenSSL for Windows environments.
- - you need Perl. Unless you will build on Cygwin, you will
- need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
+ - you need Perl. Unless you will build on Cygwin, you will need
+ ActiveState Perl, available from http://www.activestate.com/ActivePerl.
+ You also need the perl module Text::Template, available on CPAN.
+ Please read README.PERL for more information.
- one of the following C compilers:
diff --git a/README.PERL b/README.PERL
new file mode 100644
index 0000000..472b27e
--- /dev/null
+++ b/README.PERL
@@ -0,0 +1,99 @@
+ 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'.
+
+ It is highly recommended that you have at least Perl version 5.10
+ installed.
+
+ Notes on Perl on Windows
+ ------------------------
+
+ If you will build on Cygwin (and possibly some other POSIX layers),
+ Perl is already part of your distribution. Simply use the Cygwin
+ package manager to make sure Perl gets installed.
+
+ Otherwise, you will need to install Perl separately. The Perl
+ package that we know of is ActiveState Perl, available from
+ http://www.activestate.com/ActivePerl.
+
+ 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 server 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 install
+ comes with. This is usually a smooth operation, but there are
+ platforms where a failure is indicate 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
