[thirdparty/openssl.git] / NOTES.VMS


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

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

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