]> git.ipfire.org Git - thirdparty/openssl.git/blame - INSTALL.VMS
Add a few notes on perl
[thirdparty/openssl.git] / INSTALL.VMS
CommitLineData
7d7d2cbc
UM
1 VMS Installation instructions
2 written by Richard Levitte
3 <richard@levitte.org>
4
5
6Intro:
7======
8
9This file is divided in the following parts:
10
713f2261 11 Requirements - Mandatory reading.
2e98ec56 12 Checking the distribution - Mandatory reading.
7d7d2cbc 13 Compilation - Mandatory reading.
2e98ec56 14 Logical names - Mandatory reading.
7d7d2cbc
UM
15 Test - Mandatory reading.
16 Installation - Mandatory reading.
17 Backward portability - Read if it's an issue.
18 Possible bugs or quirks - A few warnings on things that
19 may go wrong or may surprise you.
2e98ec56
RL
20 TODO - Things that are to come.
21
22
713f2261
RL
23Requirements:
24=============
25
26To build and install OpenSSL, you will need:
27
187bad4c
RL
28 * Perl 5 with core modules. If you don't want to build it yourself,
29 we suggest you look here: http://sourceforge.net/projects/vmsperlkit/files/
713f2261
RL
30 * DEC C or some other ANSI C compiler. VAX C is *not* supported.
31 [Note: OpenSSL has only been tested with DEC C. Compiling with
32 a different ANSI C compiler may require some work]
33
2e98ec56
RL
34Checking the distribution:
35==========================
36
37There have been reports of places where the distribution didn't quite get
3b80e3aa 38through, for example if you've copied the tree from a NFS-mounted Unix
2e98ec56
RL
39mount point.
40
41The easiest way to check if everything got through as it should is to check
3b80e3aa 42for one of the following files:
2e98ec56
RL
43
44 [.CRYPTO]OPENSSLCONF.H_IN
45 [.CRYPTO]OPENSSLCONF_H.IN
46
47They should never exist both at once, but one of them should (preferably
48the first variant). If you can't find any of those two, something went
49wrong.
50
51The best way to get a correct distribution is to download the gzipped tar
52file from ftp://ftp.openssl.org/source/, use GUNZIP to uncompress it and
53use VMSTAR to unpack the resulting tar file.
54
55GUNZIP is available in many places on the net. One of the distribution
56points is the WKU software archive, ftp://ftp.wku.edu/vms/fileserv/ .
57
58VMSTAR is also available in many places on the net. The recommended place
59to find information about it is http://www.free.lp.se/vmstar/ .
7d7d2cbc 60
1a8b087a 61
7d7d2cbc
UM
62Compilation:
63============
64
65I've used the very good command procedures written by Robert Byer
66<byer@mail.all-net.net>, and just slightly modified them, making
67them slightly more general and easier to maintain.
68
69You can actually compile in almost any directory separately. Look
70for a command procedure name xxx-LIB.COM (in the library directories)
71or MAKExxx.COM (in the program directories) and read the comments at
72the top to understand how to use them. However, if you want to
73compile all you can get, the simplest is to use MAKEVMS.COM in the top
3b80e3aa 74directory. The syntax is the following:
7d7d2cbc 75
537c9823 76 @MAKEVMS <option> <bits> <debug-p> [<compiler>]
7d7d2cbc
UM
77
78<option> must be one of the following:
79
80 ALL Just build "everything".
1a8b087a
RL
81 CONFIG Just build the "[.CRYPTO]OPENSSLCONF.H" file.
82 BUILDINF Just build the "[.INCLUDE]BUILDINF.H" file.
7d7d2cbc 83 SOFTLINKS Just copies some files, to simulate Unix soft links.
3b80e3aa 84 BUILDALL Same as ALL, except CONFIG, BUILDINF and SOFTLINKS aren't done.
7d7d2cbc
UM
85 RSAREF Just build the "[.xxx.EXE.RSAREF]LIBRSAGLUE.OLB" library.
86 CRYPTO Just build the "[.xxx.EXE.CRYPTO]LIBCRYPTO.OLB" library.
87 SSL Just build the "[.xxx.EXE.SSL]LIBSSL.OLB" library.
1a8b087a
RL
88 TEST Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL.
89 APPS Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL.
7d7d2cbc 90
537c9823 91<bits> must be one of the following:
7d7d2cbc 92
537c9823
RL
93 "" compile using default pointer size
94 32 compile using 32 bit pointer size
95 64 compile using 64 bit pointer size
7d7d2cbc
UM
96
97<debug-p> must be one of the following:
98
99 DEBUG compile with debugging info (will not optimize)
100 NODEBUG compile without debugging info (will optimize)
101
102<compiler> must be one of the following:
103
7d7d2cbc
UM
104 DECC For DEC C.
105 GNUC For GNU C.
106
107
537c9823
RL
108You will find the crypto library in [.xxx.EXE.CRYPTO] (where xxx is VAX,
109ALPHA or IA64), called SSL_LIBCRYPTO32.OLB or SSL_LIBCRYPTO.OLB depending
110on how it was built. You will find the SSL library in [.xxx.EXE.SSL],
111named SSL_LIBSSL32.OLB or SSL_LIBSSL.OLB, and you will find a bunch of
112useful programs in [.xxx.EXE.APPS]. However, these shouldn't be used
113right off unless it's just to test them. For production use, make sure
114you install first, see Installation below.
7d7d2cbc 115
1a8b087a 116Note 1: Some programs in this package require a TCP/IP library.
7d7d2cbc
UM
117
118Note 2: if you want to compile the crypto library only, please make sure
1a8b087a
RL
119 you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and
120 a @MAKEVMS SOFTLINKS. A lot of things will break if you don't.
121
122
123Logical names:
124==============
125
126There are a few things that can't currently be given through the command
127line. Instead, logical names are used.
128
129Currently, the logical names supported are:
130
131 OPENSSL_NO_ASM with value YES, the assembler parts of OpenSSL will
132 not be used. Instead, plain C implementations are
133 used. This is good to try if something doesn't work.
4fdde1aa
RL
134 OPENSSL_NO_'alg' with value YES, the corresponding crypto algorithm,
135 protocol or other routine will not be implemented if
136 disabling it is supported. Supported algorithms to
137 do this with are: AES, BF, CAMELLIA, CAST, CMS, COMP,
138 DES, DGRAM, DH, DSA, EC, EC2M, ECDH, ECDSA, ENGINE,
e36827f6 139 ERR, GOST, HEARTBEATS, HMAC, IDEA, MD2, MD4,
4fdde1aa 140 MD5, OCB, OCSP, PSK, RC2, RC4, RC5, RMD160, RSA, SCTP,
e481f9b9 141 SEED, SOCK, SRP, SRTP, WHIRLPOOL. So, for
4fdde1aa
RL
142 example, having the logical name OPENSSL_NO_RSA with
143 the value YES means that the LIBCRYPTO.OLB library
144 will not contain an RSA implementation.
145 OPENSSL_EXPERIMENTAL_'alg'
146 with value YES, the corresponding experimental
147 algorithm is enabled. Note that is also requires
148 the application using this to define the C macro
149 OPENSSL_EXPERIMENTAL_'alg'. Supported algorithms
150 to do this with are: JPAKE, STORE.
58dc480f 151
7d7d2cbc
UM
152Test:
153=====
154
155Testing is very simple, just do the following:
156
157 @[.TEST]TESTS
158
159If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
160it's an ugly hack!) and rebuild. Please send a bug report to
161<openssl-bugs@openssl.org>, including the output of "openssl version -a"
162and of the failed test.
163
1a8b087a 164
7d7d2cbc
UM
165Installation:
166=============
167
168Installation is easy, just do the following:
169
537c9823 170 @INSTALL <root> <bits>
7d7d2cbc
UM
171
172<root> is the directory in which everything will be installed,
173subdirectories, libraries, header files, programs and startup command
174procedures.
175
537c9823
RL
176<bits> works the same way as for MAKEVMS.COM
177
58dc480f
BM
178N.B.: INSTALL.COM builds a new directory structure, different from
179the directory tree where you have now build OpenSSL.
180
7d7d2cbc
UM
181In the [.VMS] subdirectory of the installation, you will find the
182following command procedures:
183
184 OPENSSL_STARTUP.COM
185
186 defines all needed logical names. Takes one argument that
187 tells it in what logical name table to insert the logical
188 names. If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
189 call should look like this:
190
191 @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"
192
193 OPENSSL_UTILS.COM
194
195 sets up the symbols to the applications. Should be called
196 from for example SYS$MANAGER:SYLOGIN.COM
197
537c9823
RL
198 OPENSSL_UNDO.COM
199
200 deassigns the logical names created with OPENSSL_STARTUP.COM.
201
7d7d2cbc
UM
202The logical names that are set up are the following:
203
204 SSLROOT a dotted concealed logical name pointing at the
205 root directory.
7d7d2cbc 206
9dff4cc0
UM
207 SSLCERTS Initially an empty directory, this is the default
208 location for certificate files.
9dff4cc0
UM
209 SSLPRIVATE Initially an empty directory, this is the default
210 location for private key files.
211
212 SSLEXE Contains the openssl binary and a few other utility
213 programs.
214 SSLINCLUDE Contains the header files needed if you want to
215 compile programs with libcrypto or libssl.
537c9823
RL
216 SSLLIB Contains the OpenSSL library files themselves:
217 - SSL_LIBCRYPTO32.OLB and SSL_LIBSSL32.OLB or
218 - SSL_LIBCRYPTO.OLB and SSL_LIBSSL.OLB
9dff4cc0
UM
219
220 OPENSSL Same as SSLINCLUDE. This is because the standard
221 way to include OpenSSL header files from version
222 0.9.3 and on is:
223
224 #include <openssl/header.h>
225
226 For more info on this issue, see the INSTALL. file
227 (the NOTE in section 4 of "Installation in Detail").
228 You don't need to "deleting old header files"!!!
7d7d2cbc 229
1a8b087a 230
7d7d2cbc
UM
231Backward portability:
232=====================
233
234One great problem when you build a library is making sure it will work
235on as many versions of VMS as possible. Especially, code compiled on
236OpenVMS version 7.x and above tend to be unusable in version 6.x or
237lower, because some C library routines have changed names internally
238(the C programmer won't usually see it, because the old name is
239maintained through C macros). One obvious solution is to make sure
240you have a development machine with an old enough version of OpenVMS.
241However, if you are stuck with a bunch of Alphas running OpenVMS version
2427.1, you seem to be out of luck. Fortunately, the DEC C header files
243are cluttered with conditionals that make some declarations and definitions
244dependent on the OpenVMS version or the C library version, *and* you
245can use those macros to simulate older OpenVMS or C library versions,
246by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
247correct values. In the compilation scripts, I've provided the possibility
657e60fa 248for the user to influence the creation of such macros, through a bunch of
7d7d2cbc
UM
249symbols, all having names starting with USER_. Here's the list of them:
250
251 USER_CCFLAGS - Used to give additional qualifiers to the
252 compiler. It can't be used to define macros
253 since the scripts will do such things as well.
254 To do such things, use USER_CCDEFS.
255 USER_CCDEFS - Used to define macros on the command line. The
256 value of this symbol will be inserted inside a
257 /DEFINE=(...).
258 USER_CCDISABLEWARNINGS - Used to disable some warnings. The value is
259 inserted inside a /DISABLE=WARNING=(...).
260
261So, to maintain backward compatibility with older VMS versions, do the
262following before you start compiling:
263
264 $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
265 $ USER_CCDISABLEWARNINGS := PREOPTW
266
267The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
268that those macros have been changed.
269
3b80e3aa 270Note: Currently, this is only useful for library compilation. The
7d7d2cbc
UM
271 programs will still be linked with the current version of the
272 C library shareable image, and will thus complain if they are
273 faced with an older version of the same C library shareable image.
274 This will probably be fixed in a future revision of OpenSSL.
275
276
277Possible bugs or quirks:
278========================
279
280I'm not perfectly sure all the programs will use the SSLCERTS:
281directory by default, it may very well be that you have to give them
282extra arguments. Please experiment.
283
284
58dc480f
BM
285TODO:
286=====
287
288There are a few things that need to be worked out in the VMS version of
289OpenSSL, still:
290
291- Description files. ("Makefile's" :-))
292- Script code to link an already compiled build tree.
293- A VMSINSTALlable version (way in the future, unless someone else hacks).
294- shareable images (DLL for you Windows folks).
295
296There may be other things that I have missed and that may be desirable.
297Please send mail to <openssl-users@openssl.org> or to me directly if you
298have any ideas.
299
300--
301Richard Levitte <richard@levitte.org>
537c9823 3022000-02-27, 2011-03-18