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