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 (or later) 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 your 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 complete 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 complete 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 (PA-RISC-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 complete 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 (PA-RISC-based) platform that is
  84 running VOS Release 14.3.0 through VOS Release 14.4.1, 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 complete 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.5.0 or later, you can either use the
 100 previous method to build "miniperl" or you can build "full
 101 perl", which contains the complete functionality of perl.  I
 102 strongly recommend that you build full perl.  To build full
 103 perl, you must use the generally-available version of VOS POSIX
 104 support.  You must use the VOS GNU C compiler and the VOS GNU
 105 C/C++ and GNU Tools Release 2.0.1 (or later) product.  You must
 106 build full perl on VOS Release 14.5.0 (or later) on a Continuum
 107 platform.
 108
 109 You must build full perl with the compile_full_perl.cm command
 110 macro found in the vos subdirectory.
 111
 112 =back
 113
 114 =head2 Stratus POSIX Support
 115
 116 Note that there are two different implementations of POSIX.1
 117 support on VOS.  There is an alpha version of POSIX that is
 118 available from the Stratus anonymous ftp site
 119 ( ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html ).  There
 120 is a generally-available version of POSIX that comes with VOS
 121 Release 14.3.0 or higher.  This port of POSIX will compile and
 122 bind with either version of POSIX.
 123
 124 Most of the Perl features should work on VOS regardless of which
 125 version of POSIX that you are using.  However, the alpha version
 126 of POSIX is missing a number of key functions, and therefore any
 127 attempt by perl.pm to call the following unimplemented POSIX
 128 functions will result in an error message and an immediate and
 129 fatal call to the VOS debugger.  They are "dup", "fork", and
 130 "waitpid".  The lack of these functions prevents you from
 131 starting VOS commands and grabbing their output in perl.  The
 132 workaround is to run the commands outside of perl, then have perl
 133 process the output file.  These functions are all available in
 134 the generally-available version of POSIX.
 135
 136 =head1 INSTALLING PERL IN VOS
 137
 138 =head2 Compiling Perl 5 on VOS
 139
 140 Before you can build Perl 5 on VOS, you need to have or acquire the
 141 following additional items.
 142
 143 =over 5
 144
 145 =item 1
 146
 147 The VOS Standard C Compiler (or the VOS Standard C
 148 Cross-Compiler) and the VOS C Runtime.  If you are using
 149 the generally-available version of POSIX support, you may
 150 instead use the VOS GNU C/C++ Compiler.  These are
 151 standard Stratus products.
 152
 153 =item 2
 154
 155 Either the VOS OS TCP/IP or STCP product set.  If you are
 156 building with the alpha version of POSIX you need the OS
 157 TCP/IP product set.  If you are building with the
 158 generally-available version of POSIX you need the STCP
 159 product set.  These are standard Stratus products.
 160
 161 =item 3
 162
 163 Either the alpha or generally-available version of the VOS
 164 POSIX.1 environment.
 165
 166 The alpha version of POSIX.1 support is available on the
 167 Stratus FTP site.  Login anonymously to ftp.stratus.com and
 168 get the file /pub/vos/posix/alpha/posix.save.evf.gz in
 169 binary file-transfer mode.  Or use the Uniform Resource
 170 Locator (URL)
 171 ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from
 172 your web browser.  Instructions for unbundling this file
 173 are at ftp://ftp.stratus.com/pub/vos/utility/utility.html
 174 This is NOT a standard Stratus product.
 175
 176 In VOS Release 14.3.0, the generally-available version of
 177 POSIX.1 support is bundled with the VOS Standard C compiler
 178 (or Standard C Cross-Compiler).  In VOS Release 14.4.0 or
 179 higher, it is also bundled with the VOS C Runtime.  These
 180 are standard Stratus products.
 181
 182 =item 4
 183
 184 You must compile this version of Perl 5 on VOS Release
 185 14.1.0 or higher because some of the perl source files
 186 contain more than 32,767 source lines.  Due to VOS
 187 release-compatibility rules, this port of perl may not
 188 execute on VOS Release 12 or earlier.
 189
 190 =item 5
 191
 192 If you are using the generally-available version of VOS POSIX
 193 support, then you should also acquire the VOS GNU C/C++ Compiler
 194 and GNU Tools product.  When perl is built with this version of
 195 POSIX support, it assumes that it can find "bash", "sed" and
 196 other POSIX-compatible commands in the directory
 197 /system/gnu_library/bin.
 198
 199 =back
 200
 201 To build perl using the supplied VOS command macros, change to
 202 the "vos" subdirectory and type the command "compile_perl
 203 -processor X", where X is the processor type (mc68020, i80860,
 204 pa7100, pa8000) that you wish to use.  Note that the
 205 generally-available version of POSIX.1 support is not available
 206 for the mc68020 or i80860 processors.
 207
 208 Use the "-version alpha" control argument to build perl with
 209 the alpha version of POSIX support, and use the "-version
 210 ga" control argument to build it with the
 211 generally-available version of POSIX.  The default is "ga".
 212
 213 Use the "-compiler cc" control argument to build perl with
 214 the VOS Standard C compiler.  Use the "-compiler gcc"
 215 control argument to build it with the GNU GCC compiler.  The
 216 default is "cc".
 217
 218 You must have purchased the VOS Standard C Cross Compiler in
 219 order to compile perl for a processor type that is different
 220 from the processor type of the module.
 221
 222 Note that code compiled for the pa7100 processor type can
 223 execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
 224 that code compiled for the pa8000 processor type can execute on
 225 the PA8000, PA8500 and PA8600 processors.
 226
 227 To build full perl using the supplied Configure script and
 228 makefiles, change to the "vos" subdirectory and type the command
 229 "compile_full_perl" or "start_process compile_full_perl".  This
 230 will configure, build, and test perl.
 231
 232 =head2 Installing Perl 5 on VOS
 233
 234 =over 4
 235
 236 =item 1
 237
 238 If you have built perl using the Configure script, ensure that
 239 you have modify permission to C<< >system>ported >> and type
 240
 241      gmake install
 242
 243 =item 2
 244
 245 If you have built perl using any of the other methods, type
 246
 247      install_perl -processor PROCESSOR -name NAME
 248
 249 where PROCESSOR is mc68020, i80860, pa7100, or pa8000, as
 250 appropriate, and NAME is perl or perl5, according to which name
 251 you wish to use.
 252
 253 This command macro will install perl and all of its related
 254 files in the proper directories.
 255
 256 =item 3
 257
 258 While there are currently no architecture-specific
 259 extensions or modules distributed with perl, the following
 260 directories can be used to hold such files:
 261
 262      >system>ported>lib>perl5>5.8.0>68k
 263      >system>ported>lib>perl5>5.8.0>860
 264      >system>ported>lib>perl5>5.8.0>7100
 265      >system>ported>lib>perl5>5.8.0>8000
 266
 267 =item 4
 268
 269 Site-specific perl extensions and modules can be installed in one of
 270 two places.  Put architecture-independent files into:
 271
 272      >system>ported>lib>perl5>site_perl>5.8.0
 273
 274 Put site-specific architecture-dependent files into one of the
 275 following directories:
 276
 277      >system>ported>lib>perl5>site_perl>5.8.0>68k
 278      >system>ported>lib>perl5>site_perl>5.8.0>860
 279      >system>ported>lib>perl5>site_perl>5.8.0>7100
 280      >system>ported>lib>perl5>site_perl>5.8.0>8000
 281
 282 =item 5
 283
 284 You can examine the @INC variable from within a perl program
 285 to see the order in which Perl searches these directories.
 286
 287 =back
 288
 289 =head1 USING PERL IN VOS
 290
 291 =head2 Unimplemented Features of Perl on VOS
 292
 293 If perl is built with the alpha version of VOS POSIX.1 support
 294 and if it attempts to call an unimplemented VOS POSIX.1
 295 function, it will print a fatal error message and enter the VOS
 296 debugger.  This error is not recoverable.  See vos_dummies.c for
 297 a list of the unimplemented POSIX.1 functions.  To see what
 298 functions are unimplemented and what the error message looks
 299 like, compile and execute "test_vos_dummies.c".
 300
 301 =head2 Restrictions of Perl on VOS
 302
 303 This port of Perl version 5 to VOS prefers Unix-style,
 304 slash-separated pathnames over VOS-style greater-than-separated
 305 pathnames.  VOS-style pathnames should work in most contexts, but
 306 if you have trouble, replace all greater-than characters by slash
 307 characters.  Because the slash character is used as a pathname
 308 delimiter, Perl cannot process VOS pathnames containing a slash
 309 character in a directory or file name; these must be renamed.
 310
 311 This port of Perl also uses Unix-epoch date values internally.
 312 As long as you are dealing with ASCII character string
 313 representations of dates, this should not be an issue.  The
 314 supported epoch is January 1, 1980 to January 17, 2038.
 315
 316 See the file pod/perlport.pod for more information about the VOS
 317 port of Perl.
 318
 319 =head2 Handling of underflow and overflow
 320
 321 Prior to VOS Release 14.7.0, VOS does not support automatically
 322 mapping overflowed floating-point values to +infinity, nor
 323 automatically mapping underflowed floating-point values to zero,
 324 unlike many other platforms.  The Perl pack function has been
 325 modified to perform such mapping in software on VOS.  Performing
 326 other floating-point computations that underflow or overflow
 327 will probably result in SIGFPE.  Don't push your luck.
 328
 329 As of VOS Release 14.7.0, the VOS POSIX runtime sets up the
 330 PA-RISC hardware floating-point status register so that the
 331 overflow and underflow exceptions do not trap, but instead
 332 automatically convert the result to infinity or zero, as
 333 appropriate.  As of this writing, there are still floating-point
 334 operations that can trap, for example, subtracting two infinite
 335 values.  This is recorded as suggestion posix-1022, which is not
 336 yet fixed.
 337
 338 =head1 TEST STATUS
 339
 340 When Perl 5.8.3 is built using the native build process on VOS
 341 Release 14.7.0 and GNU C++/GNU Tools 2.0.2a, all but three
 342 attempted tests either pass or result in TODO (ignored)
 343 failures.  The tests that fail are:
 344
 345 t/io/tell.t, test 28
 346 t/op/pack.t, test 39
 347 lib/Net/ing/t/450_service.t, test 8
 348
 349 =head1 SUPPORT STATUS
 350
 351 I'm offering this port "as is".  You can ask me questions, but I
 352 can't guarantee I'll be able to answer them.  There are some
 353 excellent books available on the Perl language; consult a book
 354 seller.
 355
 356 If you want a supported version of perl for VOS, purchase the
 357 VOS GNU C++ and GNU Tools Release 2.0.1 (or later) product from
 358 Stratus Technologies, along with a support contract (or from
 359 anyone else who will sell you support).
 360
 361 =head1 AUTHOR
 362
 363 Paul Green (Paul.Green@stratus.com)
 364
 365 =head1 LAST UPDATE
 366
 367 January 15, 2004
 368
 369 =cut