README.vos

   1 If you read this file _as_is_, just ignore the funny characters you
   2 see. It is written in the POD format (see pod/perlpod.pod) which is
   3 specially designed to be readable as is.
   4
   5 =head1 NAME
   6
   7 README.vos - Perl for Stratus VOS
   8
   9 =head1 SYNOPSIS
  10
  11 This is a port of Perl version 5, revision 7, to VOS.  Perl is a
  12 scripting or macro language that is popular on many systems.  See your
  13 local computer bookstore for a number of good books on Perl.
  14
  15 =head2 Stratus POSIX Support
  16
  17 Note that there are two different implementations of POSIX.1
  18 support on VOS.  There is an alpha version of POSIX that is
  19 available from the Stratus anonymous ftp site
  20 (ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html).  There
  21 is a generally-available version of POSIX that comes with the
  22 VOS Standard C compiler and C runtime in VOS Release 14.3.0 or
  23 higher.  This port of POSIX will compile and bind with either
  24 version of POSIX.
  25
  26 Most of the Perl features should work on VOS regardless of which
  27 version of POSIX that you are using.  However, the alpha version
  28 of POSIX is missing a number of key functions, and therefore any
  29 attempt by perl.pm to call the following unimplemented POSIX
  30 functions will result in an error message and an immediate and
  31 fatal call to the VOS debugger.  They are "dup", "fork", and
  32 "waitpid".  The lack of these functions pretty much prevents you
  33 from starting VOS commands and grabbing their output in perl.
  34 The workaround is to run the commands outside of perl, then have
  35 perl process the output file.  These functions are all available
  36 in the generally-available version of POSIX.
  37
  38 =head1 INSTALLING PERL IN VOS
  39
  40 =head2 Compiling Perl 5 on VOS
  41
  42 Before you can build Perl 5 on VOS, you need to have or acquire the
  43 following additional items.
  44
  45 =over 5
  46
  47 =item 1
  48
  49 The VOS Standard C Compiler (or the VOS Standard C
  50 Cross-Compiler) and the VOS C Runtime.  If you are using
  51 the generally-available version of POSIX support, you may
  52 instead use the the VOS GNU C/C++ Compiler.  These are
  53 standard Stratus products.
  54
  55 =item 2
  56
  57 Either the VOS OS TCP/IP or STCP product set.  If you are
  58 building with the alpha version of POSIX you need the OS
  59 TCP/IP product set.  If you are building with the
  60 generally-available version of POSIX you need the STCP
  61 product set.  These are standard Stratus products.
  62
  63 =item 3
  64
  65 Either the alpha or generally-available version of the VOS
  66 POSIX.1 environment.
  67
  68 The alpha version of POSIX.1 support is available on the
  69 Stratus FTP site.  Login anonymously to ftp.stratus.com and
  70 get the file /pub/vos/posix/alpha/posix.save.evf.gz in
  71 binary file-transfer mode.  Or use the Uniform Resource
  72 Locator (URL)
  73 ftp://ftp.stratus.com/pub/vos/alpha/posix.save.evf.gz from
  74 your web browser.  Instructions for unbundling this file
  75 are at ftp://ftp.stratus.com/pub/vos/utility/utility.html.
  76 This is not a standard Stratus product.
  77
  78 In VOS Release 14.3.0, the generally-available version of
  79 POSIX.1 support is bundled with the VOS Standard C compiler
  80 (or Standard C Cross-Compiler).  In VOS Release 14.4.0 or
  81 higher, it is also bundled with the VOS C Runtime.  These
  82 are standard Stratus products.
  83
  84 =item 4
  85
  86 You must compile this version of Perl 5 on VOS Release
  87 14.1.0 or higher because some of the perl source files
  88 contain more than 32,767 source lines.  Due to VOS
  89 release-compatibility rules, this port of perl may not
  90 execute on VOS Release 12 or earlier.
  91
  92 =item 5
  93
  94 If you are using the generally-available version of VOS
  95 POSIX support, then you should also acquire the VOS GNU
  96 C/C++ Compiler and GNU Tools product.  When perl is built
  97 with this version of POSIX support, it assumes that it can
  98 find "bash", "sed" and other POSIX-compatible commands in
  99 the directory /system/gnu_library/bin.
 100
 101 =back
 102
 103 To build perl 5, change to the "vos" subdirectory and type the
 104 command "compile_perl -processor X", where X is the processor
 105 type (mc68020, i80860, pa7100, pa8000) that you wish to use.
 106 Note that the generally-available version of POSIX.1 support is
 107 not available for the mc68020 or i80860 processors.
 108
 109 Use the "-version alpha" control argument to build perl with
 110 the alpha version of POSIX support, and use the "-version
 111 ga" control argument to build it with the
 112 generally-available version of POSIX.  The default is "ga".
 113
 114 Use the "-compiler cc" control argument to build perl with
 115 the VOS Standard C compiler.  Use the "-compiler gcc"
 116 control argument to build it with the GNU GCC compiler.  The
 117 default is "cc".
 118
 119 You must have purchased the VOS Standard C Cross Compiler in
 120 order to compile perl for a processor type that is different
 121 from the processor type of the module.
 122
 123 Note that code compiled for the pa7100 processor type can
 124 execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
 125 that code compiled for the pa8000 processor type can execute on
 126 the PA8000, PA8500 and PA8600 processors.
 127
 128 =head2 Installing Perl 5 on VOS
 129
 130 =over 4
 131
 132 =item 1
 133
 134 Create the directory >system>ported>command_library.
 135
 136 =item 2
 137
 138 Copy the appropriate version of the perl program module to
 139 this directory.  For example, with your current directory
 140 set to the top-level directory of Perl 5, to install the
 141 executable program module for the Motorola 68K
 142 architecture, enter:
 143
 144           !copy_file vos>obj>perl.pm >system>ported>command_library>*
 145
 146 (If you wish to use both Perl version 4 and Perl version 5,
 147 you must give them different names; for example, perl.pm
 148 and perl5.pm).
 149
 150 =item 3
 151
 152 Create the directory >system>ported>perl>lib.
 153
 154 =item 4
 155
 156 Copy all of the files and subdirectories from the lib
 157 subdirectory into this new directory.  For example, with
 158 the current directory set to the top-level directory of the
 159 perl distribution, enter:
 160
 161           !copy_dir lib >system>ported>perl>lib>5.7
 162
 163 =item 5
 164
 165 While there are currently no architecture-specific
 166 extensions or modules distributed with perl, the following
 167 directories can be used to hold such files:
 168
 169           >system>ported>perl>lib>5.7.68k
 170           >system>ported>perl>lib>5.7.860
 171           >system>ported>perl>lib>5.7.7100
 172           >system>ported>perl>lib>5.7.8000
 173
 174 =item 6
 175
 176 Site-specific perl extensions and modules can be installed in one of
 177 two places.  Put architecture-independent files into:
 178
 179           >system>ported>perl>lib>site>5.7
 180
 181 Put architecture-dependent files into one of the following
 182 directories:
 183
 184           >system>ported>perl>lib>site>5.7.68k
 185           >system>ported>perl>lib>site>5.7.860
 186           >system>ported>perl>lib>site>5.7.7100
 187           >system>ported>perl>lib>site>5.7.8000
 188
 189 =item 7
 190
 191 You can examine the @INC variable from within a perl program
 192 to see the order in which Perl searches these directories.
 193
 194 =back
 195
 196 =head1 USING PERL IN VOS
 197
 198 =head2 Unimplemented Features of Perl on VOS
 199
 200 If perl is built with the alpha version of VOS POSIX.1 support
 201 and if it attempts to call an unimplemented VOS POSIX.1
 202 function, it will print a fatal error message and enter the VOS
 203 debugger.  This error is not recoverable.  See vos_dummies.c for
 204 a list of the unimplemented POSIX.1 functions.  To see what
 205 functions are unimplemented and what the error message looks
 206 like, compile and execute "test_vos_dummies.c".
 207
 208 =head2 Restrictions of Perl on VOS
 209
 210 This port of Perl version 5 to VOS prefers Unix-style,
 211 slash-separated pathnames over VOS-style greater-than-separated
 212 pathnames.  VOS-style pathnames should work in most contexts, but
 213 if you have trouble, replace all greater-than characters by slash
 214 characters.  Because the slash character is used as a pathname
 215 delimiter, Perl cannot process VOS pathnames containing a slash
 216 character in a directory or file name; these must be renamed.
 217
 218 This port of Perl also uses Unix-epoch date values internally.
 219 As long as you are dealing with ASCII character string
 220 representations of dates, this should not be an issue.  The
 221 supported epoch is January 1, 1980 to January 17, 2038.
 222
 223 See the file pod/perlport.pod for more information about the VOS
 224 port of Perl.
 225
 226 =head1 SUPPORT STATUS
 227
 228 I'm offering this port "as is".  You can ask me questions, but I
 229 can't guarantee I'll be able to answer them.  There are some
 230 excellent books available on the Perl language; consult a book
 231 seller.
 232
 233 =head1 AUTHOR
 234
 235 Paul Green (Paul_Green@stratus.com)
 236
 237 =head1 LAST UPDATE
 238
 239 June 11, 2001
 240
 241 =cut