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