README.plan9

   1 # vim: syntax=pod
   2
   3 If you read this file _as_is_, just ignore the funny characters you see.
   4 It is written in the POD format (see pod/perlpod.pod) which is specially
   5 designed to be readable as is.
   6
   7 =head1 NAME
   8
   9 perlplan9 - Plan 9-specific documentation for Perl
  10
  11 =head1 DESCRIPTION
  12
  13 These are a few notes describing features peculiar to
  14 Plan 9 Perl. As such, it is not intended to be a replacement
  15 for the rest of the Perl 5 documentation (which is both
  16 copious and excellent). If you have any questions to
  17 which you can't find answers in these man pages, contact
  18 Luther Huffman at lutherh@stratcom.com and we'll try to
  19 answer them.
  20
  21 =head2 Invoking Perl
  22
  23 Perl is invoked from the command line as described in
  24 L<perl>. Most perl scripts, however, do have a first line
  25 such as "#!/usr/local/bin/perl". This is known as a shebang
  26 (shell-bang) statement and tells the OS shell where to find
  27 the perl interpreter. In Plan 9 Perl this statement should be
  28 "#!/bin/perl" if you wish to be able to directly invoke the
  29 script by its name.
  30      Alternatively, you may invoke perl with the command "Perl"
  31 instead of "perl". This will produce Acme-friendly error
  32 messages of the form "filename:18".
  33
  34 Some scripts, usually identified with a *.PL extension, are
  35 self-configuring and are able to correctly create their own
  36 shebang path from config information located in Plan 9
  37 Perl. These you won't need to be worried about.
  38
  39 =head2 What's in Plan 9 Perl
  40
  41 Although Plan 9 Perl currently only  provides static
  42 loading, it is built with a number of useful extensions.
  43 These include Opcode, FileHandle, Fcntl, and POSIX. Expect
  44 to see others (and DynaLoading!) in the future.
  45
  46 =head2 What's not in Plan 9 Perl
  47
  48 As mentioned previously, dynamic loading isn't currently
  49 available nor is MakeMaker. Both are high-priority items.
  50
  51 =head2 Perl5 Functions not currently supported in Plan 9 Perl
  52
  53 Some, such as C<chown> and C<umask> aren't provided
  54 because the concept does not exist within Plan 9. Others,
  55 such as some of the socket-related functions, simply
  56 haven't been written yet. Many in the latter category
  57 may be supported in the future.
  58
  59 The functions not currently implemented include:
  60
  61     chown, chroot, dbmclose, dbmopen, getsockopt,
  62     setsockopt, recvmsg, sendmsg, getnetbyname,
  63     getnetbyaddr, getnetent, getprotoent, getservent,
  64     sethostent, setnetent, setprotoent, setservent,
  65     endservent, endnetent, endprotoent, umask
  66
  67 There may be several other functions that have undefined
  68 behavior so this list shouldn't be considered complete.
  69
  70 =head2 Signals in Plan 9 Perl
  71
  72 For compatibility with perl scripts written for the Unix
  73 environment, Plan 9 Perl uses the POSIX signal emulation
  74 provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
  75 isn't supported. The signals provided are:
  76
  77     SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
  78     SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM,
  79     SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
  80     SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU
  81
  82 =head1 COMPILING AND INSTALLING PERL ON PLAN 9
  83
  84 WELCOME to Plan 9 Perl, brave soul!
  85
  86    This is a preliminary alpha version of Plan 9 Perl. Still to be
  87 implemented are MakeMaker and DynaLoader. Many perl commands are
  88 missing or currently behave in an inscrutable manner. These gaps will,
  89 with perseverance and a modicum of luck, be remedied in the near
  90 future.To install this software:
  91
  92 1. Create the source directories and libraries for perl by running the
  93 plan9/setup.rc command (i.e., located in the plan9 subdirectory).
  94 Note: the setup routine assumes that you haven't dearchived these
  95 files into /sys/src/cmd/perl. After running setup.rc you may delete
  96 the copy of the source you originally detarred, as source code has now
  97 been installed in /sys/src/cmd/perl. If you plan on installing perl
  98 binaries for all architectures, run "setup.rc -a".
  99
 100 2. After making sure that you have adequate privileges to build system
 101 software, from /sys/src/cmd/perl/5.00301 (adjust version
 102 appropriately) run:
 103
 104         mk install
 105
 106 If you wish to install perl versions for all architectures (68020,
 107 mips, sparc and 386) run:
 108
 109         mk installall
 110
 111 3. Wait. The build process will take a *long* time because perl
 112 bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30
 113 minutes to build the distribution from scratch.
 114
 115 =head2 Installing Perl Documentation on Plan 9
 116
 117 This perl distribution comes with a tremendous amount of
 118 documentation. To add these to the built-in manuals that come with
 119 Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately)
 120 run:
 121
 122         mk man
 123
 124 To begin your reading, start with:
 125
 126         man perl
 127
 128 This is a good introduction and will direct you towards other man
 129 pages that may interest you.
 130
 131 (Note: "mk man" may produce some extraneous noise. Fear not.)
 132
 133 =head1 BUGS
 134
 135 "As many as there are grains of sand on all the beaches of the
 136 world . . ." - Carl Sagan
 137
 138 =head1 Revision date
 139
 140 This document was revised 09-October-1996 for Perl 5.003_7.
 141
 142 =head1 AUTHOR
 143
 144 Direct questions, comments, and the unlikely bug report (ahem) direct
 145 comments toward:
 146
 147 Luther Huffman, lutherh@stratcom.com,
 148 Strategic Computer Solutions, Inc.