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