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