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