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 0: The RASREF library IS NO LONGER NEEDED.  The RSA patent
  86         expires September 20, 2000, and RSA Security chose to make
  87         the algorithm public domain two weeks before that.
  88
  89 Note 1: If you still want to use RSAREF, the library is NOT INCLUDED
  90         and you have to download it.  RSA Security doesn't carry it
  91         any more, but there are a number of places where you can find
  92         it.  You have to get the ".tar-Z" file as the ".zip" file
  93         doesn't have the directory structure stored.  You have to
  94         extract the file into the [.RSAREF] directory as that is where
  95         the scripts will look for the files.
  96
  97 Note 2: I have never done this, so I've no idea if it works or not.
  98
  99 <debug-p> must be one of the following:
 100
 101       DEBUG     compile with debugging info (will not optimize)
 102       NODEBUG   compile without debugging info (will optimize)
 103
 104 <compiler> must be one of the following:
 105
 106       DECC      For DEC C.
 107       GNUC      For GNU C.
 108
 109
 110 You will find the crypto library in [.xxx.EXE.CRYPTO], called LIBCRYPTO.OLB,
 111 where xxx is VAX or AXP.  You will find the SSL library in [.xxx.EXE.SSL],
 112 named LIBSSL.OLB, and you will find a bunch of useful programs in
 113 [.xxx.EXE.APPS].  However, these shouldn't be used right off unless it's
 114 just to test them.  For production use, make sure you install first, see
 115 Installation below.
 116
 117 Note 1: Some programs in this package require a TCP/IP library.
 118
 119 Note 2: if you want to compile the crypto library only, please make sure
 120         you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and
 121         a @MAKEVMS SOFTLINKS.  A lot of things will break if you don't.
 122
 123
 124 Logical names:
 125 ==============
 126
 127 There are a few things that can't currently be given through the command
 128 line.  Instead, logical names are used.
 129
 130 Currently, the logical names supported are:
 131
 132       OPENSSL_NO_ASM    with value YES, the assembler parts of OpenSSL will
 133                         not be used.  Instead, plain C implementations are
 134                         used.  This is good to try if something doesn't work.
 135       OPENSSL_NO_'alg'  with value YES, the corresponding crypto algorithm
 136                         will not be implemented.  Supported algorithms to
 137                         do this with are: RSA, DSA, DH, MD2, MD4, MD5, RIPEMD,
 138                         SHA, DES, MDC2, CR2, RC4, RC5, IDEA, BF, CAST, HMAC,
 139                         SSL2.  So, for example, having the logical name
 140                         OPENSSL_NO_RSA with the value YES means that the
 141                         LIBCRYPTO.OLB library will not contain an RSA
 142                         implementation.
 143
 144
 145 Test:
 146 =====
 147
 148 Testing is very simple, just do the following:
 149
 150   @[.TEST]TESTS
 151
 152 If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
 153 it's an ugly hack!) and rebuild. Please send a bug report to
 154 <openssl-bugs@openssl.org>, including the output of "openssl version -a"
 155 and of the failed test.
 156
 157
 158 Installation:
 159 =============
 160
 161 Installation is easy, just do the following:
 162
 163   @INSTALL <root>
 164
 165 <root> is the directory in which everything will be installed,
 166 subdirectories, libraries, header files, programs and startup command
 167 procedures.
 168
 169 N.B.: INSTALL.COM builds a new directory structure, different from
 170 the directory tree where you have now build OpenSSL.
 171
 172 In the [.VMS] subdirectory of the installation, you will find the
 173 following command procedures:
 174
 175   OPENSSL_STARTUP.COM
 176
 177         defines all needed logical names.  Takes one argument that
 178         tells it in what logical name table to insert the logical
 179         names.  If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
 180         call should look like this:
 181
 182           @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"
 183
 184   OPENSSL_UTILS.COM
 185
 186         sets up the symbols to the applications.  Should be called
 187         from for example SYS$MANAGER:SYLOGIN.COM
 188
 189 The logical names that are set up are the following:
 190
 191   SSLROOT       a dotted concealed logical name pointing at the
 192                 root directory.
 193
 194   SSLCERTS      Initially an empty directory, this is the default
 195                 location for certificate files.
 196   SSLMISC       Various scripts.
 197   SSLPRIVATE    Initially an empty directory, this is the default
 198                 location for private key files.
 199
 200   SSLEXE        Contains the openssl binary and a few other utility
 201                 programs.
 202   SSLINCLUDE    Contains the header files needed if you want to
 203                 compile programs with libcrypto or libssl.
 204   SSLLIB        Contains the OpenSSL library files (LIBCRYPTO.OLB
 205                 and LIBSSL.OLB) themselves.
 206
 207   OPENSSL       Same as SSLINCLUDE.  This is because the standard
 208                 way to include OpenSSL header files from version
 209                 0.9.3 and on is:
 210
 211                         #include <openssl/header.h>
 212
 213                 For more info on this issue, see the INSTALL. file
 214                 (the NOTE in section 4 of "Installation in Detail").
 215                 You don't need to "deleting old header files"!!!
 216
 217
 218 Backward portability:
 219 =====================
 220
 221 One great problem when you build a library is making sure it will work
 222 on as many versions of VMS as possible.  Especially, code compiled on
 223 OpenVMS version 7.x and above tend to be unusable in version 6.x or
 224 lower, because some C library routines have changed names internally
 225 (the C programmer won't usually see it, because the old name is
 226 maintained through C macros).  One obvious solution is to make sure
 227 you have a development machine with an old enough version of OpenVMS.
 228 However, if you are stuck with a bunch of Alphas running OpenVMS version
 229 7.1, you seem to be out of luck.  Fortunately, the DEC C header files
 230 are cluttered with conditionals that make some declarations and definitions
 231 dependent on the OpenVMS version or the C library version, *and* you
 232 can use those macros to simulate older OpenVMS or C library versions,
 233 by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
 234 correct values.  In the compilation scripts, I've provided the possibility
 235 for the user to influence the creation of such macros, through a bunch of
 236 symbols, all having names starting with USER_.  Here's the list of them:
 237
 238   USER_CCFLAGS           - Used to give additional qualifiers to the
 239                            compiler.  It can't be used to define macros
 240                            since the scripts will do such things as well.
 241                            To do such things, use USER_CCDEFS.
 242   USER_CCDEFS            - Used to define macros on the command line.  The
 243                            value of this symbol will be inserted inside a
 244                            /DEFINE=(...).
 245   USER_CCDISABLEWARNINGS - Used to disable some warnings.  The value is
 246                            inserted inside a /DISABLE=WARNING=(...).
 247
 248 So, to maintain backward compatibility with older VMS versions, do the
 249 following before you start compiling:
 250
 251   $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
 252   $ USER_CCDISABLEWARNINGS := PREOPTW
 253
 254 The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
 255 that those macros have been changed.
 256
 257 Note: Currently, this is only usefull for library compilation.  The
 258       programs will still be linked with the current version of the
 259       C library shareable image, and will thus complain if they are
 260       faced with an older version of the same C library shareable image.
 261       This will probably be fixed in a future revision of OpenSSL.
 262
 263
 264 Possible bugs or quirks:
 265 ========================
 266
 267 I'm not perfectly sure all the programs will use the SSLCERTS:
 268 directory by default, it may very well be that you have to give them
 269 extra arguments.  Please experiment.
 270
 271
 272 TODO:
 273 =====
 274
 275 There are a few things that need to be worked out in the VMS version of
 276 OpenSSL, still:
 277
 278 - Description files. ("Makefile's" :-))
 279 - Script code to link an already compiled build tree.
 280 - A VMSINSTALlable version (way in the future, unless someone else hacks).
 281 - shareable images (DLL for you Windows folks).
 282
 283 There may be other things that I have missed and that may be desirable.
 284 Please send mail to <openssl-users@openssl.org> or to me directly if you
 285 have any ideas.
 286
 287 --
 288 Richard Levitte <richard@levitte.org>
 289 2000-02-27