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