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