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