[thirdparty/openssl.git] / NOTES-VMS.md

NOTES FOR THE OPENVMS PLATFORM
==============================

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

 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.

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

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

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

 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.

 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.

 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

 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:

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

 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.

 The easiest way to check if everything got through as it should is to
 check for one of the following files:

    [.crypto]opensslconf^.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.

 Gzip and VMSTAR are available here:

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

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

   <http://www.info-zip.org/UnZip.html>
Commit	Line	Data
1dc1ea18 DDO	1	NOTES FOR THE OPENVMS PLATFORM
1dc1ea18 DDO	2	==============================
2acd8ec7 RL	3
	4	Requirement details
	5	-------------------
	6
1dc1ea18 DDO	7	In addition to the requirements and instructions listed
1dc1ea18 DDO	8	in [INSTALL.md](INSTALL.md), this are required as well:
2acd8ec7 RL	9
	10	* At least ODS-5 disk organization for source and build.
	11	Installation can be done on any existing disk organization.
	12
2acd8ec7 RL	13	About ANSI C compiler
	14	---------------------
	15
7793e174 RL	16	An ANSI C compiled is needed among other things. This means that
7793e174 RL	17	VAX C is not and will not be supported.
2acd8ec7	18
8c1cbc72	19	We have only tested with DEC C (aka HP VMS C / VSI C) and require
368058d0 RL	20	version 7.1 or later. Compiling with a different ANSI C compiler may
368058d0 RL	21	require some work.
7793e174	22
1dc1ea18	23	Please avoid using C RTL feature logical names `DECC$*` when building
7793e174 RL	24	and testing OpenSSL. Most of all, they can be disruptive when
7793e174 RL	25	running the tests, as they affect the Perl interpreter.
2acd8ec7	26
e8fd2a4c RL	27	About ODS-5 directory names and Perl
	28	------------------------------------
	29
1dc1ea18	30	It seems that the perl function canonpath() in the `File::Spec` module
e8fd2a4c RL	31	doesn't treat file specifications where the last directory name
	32	contains periods very well. Unfortunately, some versions of VMS tar
	33	will keep the periods in the OpenSSL source directory instead of
	34	converting them to underscore, thereby leaving your source in
1dc1ea18	35	something like `[.openssl-1^.1^.0]`. This will lead to issues when
e8fd2a4c RL	36	configuring and building OpenSSL.
	37
	38	We have no replacement for Perl's canonpath(), so the best workaround
	39	for now is to rename the OpenSSL source directory, as follows (please
	40	adjust for the actual source directory name you have):
	41
df443918	42	$ rename openssl-1^.1^.0.DIR openssl-1_1_0.DIR
e8fd2a4c	43
b54e35f6 RL	44	About MMS and DCL
	45	-----------------
	46
	47	MMS has certain limitations when it comes to line length, and DCL has
	48	certain limitations when it comes to total command length. We do
	49	what we can to mitigate, but there is the possibility that it's not
	50	enough. Should you run into issues, a very simple solution is to set
	51	yourself up a few logical names for the directory trees you're going
	52	to use.
	53
1ae4c07e RL	54	About debugging
	55	---------------
	56
	57	If you build for debugging, the default on VMS is that image
	58	activation starts the debugger automatically, giving you a debug
	59	prompt. Unfortunately, this disrupts all other uses, such as running
	60	test programs in the test framework.
	61
a2880aec RL	62	Generally speaking, if you build for debugging, only use the programs
	63	directly for debugging. Do not try to use them from a script, such
	64	as running the test suite.
	65
1dc1ea18	66	### The following is not available on Alpha
a2880aec	67
1ae4c07e RL	68	As a compromise, we're turning off the flag that makes the debugger
	69	start automatically. If there is a program that you need to debug,
	70	you need to turn that flag back on first, for example:
	71
	72	$ set image /flag=call_debug [.test]evp_test.exe
	73
a2880aec	74	Then just run it and you will find yourself in a debugging session.
69687aa8	75	When done, we recommend that you turn that flag back off:
1ae4c07e RL	76
	77	$ set image /flag=nocall_debug [.test]evp_test.exe
	78
2acd8ec7 RL	79	Checking the distribution
	80	-------------------------
	81
	82	There have been reports of places where the distribution didn't quite
	83	get through, for example if you've copied the tree from a NFS-mounted
	84	Unix mount point.
	85
	86	The easiest way to check if everything got through as it should is to
	87	check for one of the following files:
	88
1dc1ea18	89	[.crypto]opensslconf^.h.in
2acd8ec7 RL	90
2acd8ec7 RL	91	The best way to get a correct distribution is to download the gzipped
1dc1ea18 DDO	92	tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
1dc1ea18 DDO	93	it and `VMSTAR` to unpack the resulting tar file.
2acd8ec7 RL	94
	95	Gzip and VMSTAR are available here:
	96
1dc1ea18	97	<http://antinode.info/dec/index.html#Software>
2acd8ec7 RL	98
	99	Should you need it, you can find UnZip for VMS here:
	100
1dc1ea18	101	<http://www.info-zip.org/UnZip.html>