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