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 file contains notes for building perl on the Stratus VOS
  12 operating system.  Perl is a scripting or macro language that is
  13 popular on many systems.  See L<perlbook> for a number of good
  14 books on Perl.
  15
  16 These are instructions for building Perl from source.  Most people can
  17 simply download a pre-compiled distribution from the VOS anonymous FTP
  18 site.  If you are running VOS Release 14.2.0 or earlier, download Perl
  19 from ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html.  If you are
  20 running VOS Release 14.3.0 or later, download Perl from
  21 ftp://ftp.stratus.com/pub/vos/posix/ga/ga.html.  Instructions for
  22 unbundling the Perl distribution file are at
  23 ftp://ftp.stratus.com/pub/vos/utility/utility.html.
  24
  25 If you are running VOS Release 14.4.1 or later, you can obtain a
  26 pre-compiled, supported copy of perl by purchasing Release 2.0.1
  27 of the VOS GNU C++ and GNU Tools product from Stratus
  28 Technologies.
  29
  30 =head2 Multiple methods to build perl for VOS
  31
  32 If you elect to build perl from its source code, you have several
  33 different ways that you can build perl.  The method that you use
  34 depends on the version of VOS that you are using and on the
  35 architecture of you Stratus hardware platform.
  36
  37 =over 5
  38
  39 =item 1
  40
  41 If you have a Stratus XA2000 (Motorola 68k-based) platform, you
  42 must build perl using the alpha version of VOS POSIX support and
  43 using the VOS Standard C Cross-compiler.  You must build perl on
  44 VOS Release 14.1.0 (or later) on an XA/R or Continuum platform.
  45
  46 This version of perl is properly called "miniperl" because it
  47 does not contain the full perl functionality.
  48
  49 You must build perl with the compile_perl.cm command macro found
  50 in the vos subdirectory.
  51
  52 =item 2
  53
  54 If you have a Stratus XA/R (Intel i860-based) platform, you must
  55 build perl using the alpha version of VOS POSIX support and using
  56 the VOS Standard C compiler or cross-compiler.  You must build
  57 perl on VOS Release 14.1.0 (or later) on an XA/R or Continuum
  58 platform.
  59
  60 This version of perl is properly called "miniperl" because it
  61 does not contain the full perl functionality.
  62
  63 You must build perl with the compile_perl.cm command macro found
  64 in the vos subdirectory.
  65
  66 =item 3
  67
  68 If you have a Stratus Continuum (PARISC-based) platform that is
  69 running a version of VOS earlier than VOS 14.3.0, you must build
  70 perl using the alpha version of VOS POSIX support and using the
  71 VOS Standard C compiler or cross-compiler.  You must build perl
  72 on VOS Release 14.1.0 (or later) on an XA/R or Continuum
  73 platform.
  74
  75 This version of perl is properly called "miniperl" because it
  76 does not contain the full perl functionality.
  77
  78 You must build perl with the compile_perl.cm command macro found
  79 in the vos subdirectory.
  80
  81 =item 4
  82
  83 If you have a Stratus Continuum (PARISC-based) platform that is
  84 running VOS Release 14.3.0 through VOS Release 14.4.0, you must
  85 build perl using the generally-available version of VOS POSIX
  86 support, and using either the VOS Standard C compiler or the VOS
  87 GNU C compiler.  You must build perl on VOS Release 14.3.0 (or
  88 later) on a Continuum platform.
  89
  90 This version of perl is properly called "miniperl" because it
  91 does not contain the full perl functionality.
  92
  93 You must build perl with the compile_perl.cm command macro found
  94 in the vos subdirectory.
  95
  96 =item 5
  97
  98 If you have a Stratus Continuum (PA-RISC-based) platform that is
  99 running VOS Release 14.4.1 or later, you must build perl using
 100 the generally-available version of VOS POSIX support.  You must
 101 use the VOS GNU C compiler and the VOS GNU Tools product.  You
 102 must build perl on VOS Release 14.4.1 (or later) on a Continuum
 103 platform.
 104
 105 This version of perl is properly called "full perl" because it
 106 contains the full perl functionality.
 107
 108 You must use the supplied Configure script and makefiles to build
 109 perl.
 110
 111 =back
 112
 113 =head2 Stratus POSIX Support
 114
 115 Note that there are two different implementations of POSIX.1
 116 support on VOS.  There is an alpha version of POSIX that is
 117 available from the Stratus anonymous ftp site
 118 (ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html).  There
 119 is a generally-available version of POSIX that comes with VOS
 120 Release 14.3.0 or higher.  This port of POSIX will compile and
 121 bind with either version of POSIX.
 122
 123 Most of the Perl features should work on VOS regardless of which
 124 version of POSIX that you are using.  However, the alpha version
 125 of POSIX is missing a number of key functions, and therefore any
 126 attempt by perl.pm to call the following unimplemented POSIX
 127 functions will result in an error message and an immediate and
 128 fatal call to the VOS debugger.  They are "dup", "fork", and
 129 "waitpid".  The lack of these functions prevents you from
 130 starting VOS commands and grabbing their output in perl.  The
 131 workaround is to run the commands outside of perl, then have perl
 132 process the output file.  These functions are all available in
 133 the generally-available version of POSIX.
 134
 135 =head1 INSTALLING PERL IN VOS
 136
 137 =head2 Compiling Perl 5 on VOS
 138
 139 Before you can build Perl 5 on VOS, you need to have or acquire the
 140 following additional items.
 141
 142 =over 5
 143
 144 =item 1
 145
 146 The VOS Standard C Compiler (or the VOS Standard C
 147 Cross-Compiler) and the VOS C Runtime.  If you are using
 148 the generally-available version of POSIX support, you may
 149 instead use the VOS GNU C/C++ Compiler.  These are
 150 standard Stratus products.
 151
 152 =item 2
 153
 154 Either the VOS OS TCP/IP or STCP product set.  If you are
 155 building with the alpha version of POSIX you need the OS
 156 TCP/IP product set.  If you are building with the
 157 generally-available version of POSIX you need the STCP
 158 product set.  These are standard Stratus products.
 159
 160 =item 3
 161
 162 Either the alpha or generally-available version of the VOS
 163 POSIX.1 environment.
 164
 165 The alpha version of POSIX.1 support is available on the
 166 Stratus FTP site.  Login anonymously to ftp.stratus.com and
 167 get the file /pub/vos/posix/alpha/posix.save.evf.gz in
 168 binary file-transfer mode.  Or use the Uniform Resource
 169 Locator (URL)
 170 ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from
 171 your web browser.  Instructions for unbundling this file
 172 are at ftp://ftp.stratus.com/pub/vos/utility/utility.html.
 173 This is not a standard Stratus product.
 174
 175 In VOS Release 14.3.0, the generally-available version of
 176 POSIX.1 support is bundled with the VOS Standard C compiler
 177 (or Standard C Cross-Compiler).  In VOS Release 14.4.0 or
 178 higher, it is also bundled with the VOS C Runtime.  These
 179 are standard Stratus products.
 180
 181 =item 4
 182
 183 You must compile this version of Perl 5 on VOS Release
 184 14.1.0 or higher because some of the perl source files
 185 contain more than 32,767 source lines.  Due to VOS
 186 release-compatibility rules, this port of perl may not
 187 execute on VOS Release 12 or earlier.
 188
 189 =item 5
 190
 191 If you are using the generally-available version of VOS POSIX
 192 support, then you should also acquire the VOS GNU C/C++ Compiler
 193 and GNU Tools product.  When perl is built with this version of
 194 POSIX support, it assumes that it can find "bash", "sed" and
 195 other POSIX-compatible commands in the directory
 196 /system/gnu_library/bin.
 197
 198 =back
 199
 200 To build perl using the supplied VOS command macros, change to
 201 the "vos" subdirectory and type the command "compile_perl
 202 -processor X", where X is the processor type (mc68020, i80860,
 203 pa7100, pa8000) that you wish to use.  Note that the
 204 generally-available version of POSIX.1 support is not available
 205 for the mc68020 or i80860 processors.
 206
 207 Use the "-version alpha" control argument to build perl with
 208 the alpha version of POSIX support, and use the "-version
 209 ga" control argument to build it with the
 210 generally-available version of POSIX.  The default is "ga".
 211
 212 Use the "-compiler cc" control argument to build perl with
 213 the VOS Standard C compiler.  Use the "-compiler gcc"
 214 control argument to build it with the GNU GCC compiler.  The
 215 default is "cc".
 216
 217 You must have purchased the VOS Standard C Cross Compiler in
 218 order to compile perl for a processor type that is different
 219 from the processor type of the module.
 220
 221 Note that code compiled for the pa7100 processor type can
 222 execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
 223 that code compiled for the pa8000 processor type can execute on
 224 the PA8000, PA8500 and PA8600 processors.
 225
 226 To build perl using the supplied Configure script and makefiles,
 227 execute the following commands.
 228
 229      !add_library_path command >system>gnu_library>bin -after '(current_dir)'
 230      !bash
 231           gzip -d perl-5.8.0.tar.gz
 232           tar -xvf perl-5.8.0.tar
 233           cd perl-5.8.0
 234           Configure -d
 235           gmake
 236
 237 If you wish to run the test cases, type:
 238
 239           gmake test
 240
 241 =head2 Installing Perl 5 on VOS
 242
 243 =over 4
 244
 245 =item 1
 246
 247 If you have built perl using the Configure script, ensure that
 248 you have modify permission to >system>ported and type
 249
 250      gmake install
 251
 252 =item 2
 253
 254 If you have built perl using any of the other methods, type
 255
 256      install_perl -processor PROCESSOR -name NAME
 257
 258 where PROCESSOR is mc68020, i80860, pa7100, or pa8000, as
 259 appropriate, and NAME is perl or perl5, according to which name
 260 you wish to use.
 261
 262 This command macro will install perl and all of its related
 263 files in the proper directories.
 264
 265 =item 3
 266
 267 While there are currently no architecture-specific
 268 extensions or modules distributed with perl, the following
 269 directories can be used to hold such files:
 270
 271      >system>ported>lib>perl5>5.8.0>68k
 272      >system>ported>lib>perl5>5.8.0>860
 273      >system>ported>lib>perl5>5.8.0>7100
 274      >system>ported>lib>perl5>5.8.0>8000
 275
 276 =item 4
 277
 278 Site-specific perl extensions and modules can be installed in one of
 279 two places.  Put architecture-independent files into:
 280
 281      >system>ported>lib>perl5>site_perl>5.8.0
 282
 283 Put site-specific architecture-dependent files into one of the
 284 following directories:
 285
 286      >system>ported>lib>perl5>site_perl>5.8.0>68k
 287      >system>ported>lib>perl5>site_perl>5.8.0>860
 288      >system>ported>lib>perl5>site_perl>5.8.0>7100
 289      >system>ported>lib>perl5>site_perl>5.8.0>8000
 290
 291 =item 5
 292
 293 You can examine the @INC variable from within a perl program
 294 to see the order in which Perl searches these directories.
 295
 296 =back
 297
 298 =head1 USING PERL IN VOS
 299
 300 =head2 Unimplemented Features of Perl on VOS
 301
 302 If perl is built with the alpha version of VOS POSIX.1 support
 303 and if it attempts to call an unimplemented VOS POSIX.1
 304 function, it will print a fatal error message and enter the VOS
 305 debugger.  This error is not recoverable.  See vos_dummies.c for
 306 a list of the unimplemented POSIX.1 functions.  To see what
 307 functions are unimplemented and what the error message looks
 308 like, compile and execute "test_vos_dummies.c".
 309
 310 =head2 Restrictions of Perl on VOS
 311
 312 This port of Perl version 5 to VOS prefers Unix-style,
 313 slash-separated pathnames over VOS-style greater-than-separated
 314 pathnames.  VOS-style pathnames should work in most contexts, but
 315 if you have trouble, replace all greater-than characters by slash
 316 characters.  Because the slash character is used as a pathname
 317 delimiter, Perl cannot process VOS pathnames containing a slash
 318 character in a directory or file name; these must be renamed.
 319
 320 This port of Perl also uses Unix-epoch date values internally.
 321 As long as you are dealing with ASCII character string
 322 representations of dates, this should not be an issue.  The
 323 supported epoch is January 1, 1980 to January 17, 2038.
 324
 325 See the file pod/perlport.pod for more information about the VOS
 326 port of Perl.
 327
 328 =head1 SUPPORT STATUS
 329
 330 I'm offering this port "as is".  You can ask me questions, but I
 331 can't guarantee I'll be able to answer them.  There are some
 332 excellent books available on the Perl language; consult a book
 333 seller.
 334
 335 If you want a supported version of perl for VOS, purchase the VOS
 336 GNU C++ and GNU Tools Release 2.0.1 product from Stratus
 337 Technologies, along with a support contract (or from anyone else
 338 who will sell you support).
 339
 340 =head1 AUTHOR
 341
 342 Paul Green (Paul.Green@stratus.com)
 343
 344 =head1 LAST UPDATE
 345
 346 February 15, 2001
 347
 348 =cut