Skip to content

Commit

Permalink
Reformat some NOTES and README files
Browse files Browse the repository at this point in the history 
Formatting is still very mixed in the NOTES and README files.
This commit tries to make formatting more consistent with the one
introduced in pull request openssl#10545.

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#14042)
  • Loading branch information
@mspncp
mspncp committed Feb 12, 2021
1 parent 9f1fe6a commit dc589da
Show file tree
Hide file tree
Showing 4 changed files with 556 additions and 528 deletions.
186 changes: 97 additions & 89 deletions NOTES-PERL.md
View file
Original file line number Diff line number Diff line change
@@ -1,125 +1,133 @@
TOC
===
Notes on Perl
=============

- Notes on Perl
- Notes on Perl on Windows
- Notes on Perl modules we use
- Notes on installing a perl module
- [General Notes](#general-notes)
- [Perl on Windows](#perl-on-windows)
- [Perl on VMS](#perl-on-vms)
- [Required Perl modules](#required-perl-modules)
- [Notes on installing a Perl module](#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.
General Notes
-------------

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:
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.
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.

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 a Perl installation
that matches the 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>.

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.md` 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.

Required Perl modules
---------------------

Notes on Perl on Windows
------------------------
We do our best to limit ourselves to core Perl modules to keep the
requirements down. There are just a few exceptions.

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
--------------------
## For Building

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.md` 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.
* `Text::Template`

Notes on Perl modules we use
----------------------------
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.

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:
## For Testing

* `Test::More`
* `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.
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.
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
Text::Template

Notes on installing a perl module
---------------------------------
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.
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.
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:
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
$ 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.
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:
2. Install using CPAN. This is very easy, but usually requires root
access:

$ cpan -i Text::Template
$ 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!):
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
$ cpan -f -i Text::Template

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

$ cpan -i "Text::Template"
$ cpan -i "Text::Template"

and:
and:

$ cpan -f -i "Text::Template"
$ cpan -f -i "Text::Template"
132 changes: 70 additions & 62 deletions NOTES-VMS.md
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,110 @@
NOTES FOR THE OPENVMS PLATFORM
Notes for the OpenVMS platform
==============================

Requirement details
-------------------
- [Requirement details](#requirement-details)
- [About ANSI C compiler](#about-ansi-c-compiler)
- [About ODS-5 directory names and Perl](#about-ods-5-directory-names-and-perl)
- [About MMS and DCL](#about-mms-and-dcl)
- [About debugging](#about-debugging)
- [Checking the distribution](#checking-the-distribution)

In addition to the requirements and instructions listed
in [INSTALL.md](INSTALL.md), this are required as well:

Requirement details
-------------------

In addition to the requirements and instructions listed
in [INSTALL.md](INSTALL.md), this are required as well:

* At least ODS-5 disk organization for source and build.
Installation can be done on any existing disk organization.

About ANSI C compiler
---------------------
About ANSI C compiler
---------------------

An ANSI C compiled is needed among other things. This means that
VAX C is not and will not be supported.
An ANSI C compiled is needed among other things. This means that
VAX C is not and will not be supported.

We have only tested with DEC C (aka HP VMS C / VSI C) and require
version 7.1 or later. Compiling with a different ANSI C compiler may
require some work.
We have only tested with DEC C (aka HP VMS C / VSI C) and require
version 7.1 or later. Compiling with a different ANSI C compiler may
require some work.

Please avoid using C RTL feature logical names `DECC$*` when building
and testing OpenSSL. Most of all, they can be disruptive when
running the tests, as they affect the Perl interpreter.
Please avoid using C RTL feature logical names `DECC$*` when building
and testing OpenSSL. Most of all, they can be disruptive when
running the tests, as they affect the Perl interpreter.

About ODS-5 directory names and Perl
------------------------------------
About ODS-5 directory names and Perl
------------------------------------

It seems that the perl function canonpath() in the `File::Spec` module
doesn't treat file specifications where the last directory name
contains periods very well. Unfortunately, some versions of VMS tar
will keep the periods in the OpenSSL source directory instead of
converting them to underscore, thereby leaving your source in
something like `[.openssl-1^.1^.0]`. This will lead to issues when
configuring and building OpenSSL.
It seems that the perl function canonpath() in the `File::Spec` module
doesn't treat file specifications where the last directory name
contains periods very well. Unfortunately, some versions of VMS tar
will keep the periods in the OpenSSL source directory instead of
converting them to underscore, thereby leaving your source in
something like `[.openssl-1^.1^.0]`. This will lead to issues when
configuring and building OpenSSL.

We have no replacement for Perl's canonpath(), so the best workaround
for now is to rename the OpenSSL source directory, as follows (please
adjust for the actual source directory name you have):
We have no replacement for Perl's canonpath(), so the best workaround
for now is to rename the OpenSSL source directory, as follows (please
adjust for the actual source directory name you have):

$ rename openssl-1^.1^.0.DIR openssl-1_1_0.DIR

About MMS and DCL
-----------------
About MMS and DCL
-----------------

MMS has certain limitations when it comes to line length, and DCL has
certain limitations when it comes to total command length. We do
what we can to mitigate, but there is the possibility that it's not
enough. Should you run into issues, a very simple solution is to set
yourself up a few logical names for the directory trees you're going
to use.
MMS has certain limitations when it comes to line length, and DCL has
certain limitations when it comes to total command length. We do
what we can to mitigate, but there is the possibility that it's not
enough. Should you run into issues, a very simple solution is to set
yourself up a few logical names for the directory trees you're going
to use.

About debugging
---------------
About debugging
---------------

If you build for debugging, the default on VMS is that image
activation starts the debugger automatically, giving you a debug
prompt. Unfortunately, this disrupts all other uses, such as running
test programs in the test framework.
If you build for debugging, the default on VMS is that image
activation starts the debugger automatically, giving you a debug
prompt. Unfortunately, this disrupts all other uses, such as running
test programs in the test framework.

Generally speaking, if you build for debugging, only use the programs
directly for debugging. Do not try to use them from a script, such
as running the test suite.
Generally speaking, if you build for debugging, only use the programs
directly for debugging. Do not try to use them from a script, such
as running the test suite.

### The following is not available on Alpha
### The following is not available on Alpha

As a compromise, we're turning off the flag that makes the debugger
start automatically. If there is a program that you need to debug,
you need to turn that flag back on first, for example:
As a compromise, we're turning off the flag that makes the debugger
start automatically. If there is a program that you need to debug,
you need to turn that flag back on first, for example:

$ set image /flag=call_debug [.test]evp_test.exe

Then just run it and you will find yourself in a debugging session.
When done, we recommend that you turn that flag back off:
Then just run it and you will find yourself in a debugging session.
When done, we recommend that you turn that flag back off:

$ set image /flag=nocall_debug [.test]evp_test.exe

Checking the distribution
-------------------------
Checking the distribution
-------------------------

There have been reports of places where the distribution didn't quite
get through, for example if you've copied the tree from a NFS-mounted
Unix mount point.
There have been reports of places where the distribution didn't quite
get through, for example if you've copied the tree from a NFS-mounted
Unix mount point.

The easiest way to check if everything got through as it should is to
check that this file exists:
The easiest way to check if everything got through as it should is to
check that this file exists:

[.include.openssl]configuration^.h.in

The best way to get a correct distribution is to download the gzipped
tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
it and `VMSTAR` to unpack the resulting tar file.
The best way to get a correct distribution is to download the gzipped
tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
it and `VMSTAR` to unpack the resulting tar file.

Gzip and VMSTAR are available here:
Gzip and VMSTAR are available here:

<http://antinode.info/dec/index.html#Software>

Should you need it, you can find UnZip for VMS here:
Should you need it, you can find UnZip for VMS here:

<http://www.info-zip.org/UnZip.html>

Expand Down
Loading

0 comments on commit dc589da

Please sign in to comment.