[p5sagit/p5-mst-13.2.git] / README.plan9

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

perlplan9 - Plan 9-specific documentation for Perl

=head1 DESCRIPTION

These are a few notes describing features peculiar to
Plan 9 Perl. As such, it is not intended to be a replacement
for the rest of the Perl 5 documentation (which is both 
copious and excellent). If you have any questions to 
which you can't find answers in these man pages, contact 
Luther Huffman at lutherh@stratcom.com and we'll try to 
answer them.

=head2 Invoking Perl

Perl is invoked from the command line as described in 
L<perl>. Most perl scripts, however, do have a first line 
such as "#!/usr/local/bin/perl". This is known as a shebang 
(shell-bang) statement and tells the OS shell where to find 
the perl interpreter. In Plan 9 Perl this statement should be 
"#!/bin/perl" if you wish to be able to directly invoke the 
script by its name.
     Alternatively, you may invoke perl with the command "Perl"
instead of "perl". This will produce Acme-friendly error
messages of the form "filename:18".

Some scripts, usually identified with a *.PL extension, are 
self-configuring and are able to correctly create their own 
shebang path from config information located in Plan 9 
Perl. These you won't need to be worried about.

=head2 What's in Plan 9 Perl

Although Plan 9 Perl currently only  provides static 
loading, it is built with a number of useful extensions. 
These include Opcode, FileHandle, Fcntl, and POSIX. Expect 
to see others (and DynaLoading!) in the future.

=head2 What's not in Plan 9 Perl

As mentioned previously, dynamic loading isn't currently 
available nor is MakeMaker. Both are high-priority items.

=head2 Perl5 Functions not currently supported in Plan 9 Perl

Some, such as C<chown> and C<umask> aren't provided 
because the concept does not exist within Plan 9. Others,
such as some of the socket-related functions, simply
haven't been written yet. Many in the latter category 
may be supported in the future.

The functions not currently implemented include:

    chown, chroot, dbmclose, dbmopen, getsockopt, 
    setsockopt, recvmsg, sendmsg, getnetbyname, 
    getnetbyaddr, getnetent, getprotoent, getservent, 
    sethostent, setnetent, setprotoent, setservent, 
    endservent, endnetent, endprotoent, umask

There may be several other functions that have undefined 
behavior so this list shouldn't be considered complete.

=head2 Signals in Plan 9 Perl

For compatibility with perl scripts written for the Unix 
environment, Plan 9 Perl uses the POSIX signal emulation
provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
isn't supported. The signals provided are:

    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
    SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM, 
    SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
    SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU

=head1 COMPILING AND INSTALLING PERL ON PLAN 9

WELCOME to Plan 9 Perl, brave soul!

   This is a preliminary alpha version of Plan 9 Perl. Still to be
implemented are MakeMaker and DynaLoader. Many perl commands are
missing or currently behave in an inscrutable manner. These gaps will,
with perserverance and a modicum of luck, be remedied in the near
future.To install this software:

1. Create the source directories and libraries for perl by running the
plan9/setup.rc command (i.e., located in the plan9 subdirectory).
Note: the setup routine assumes that you haven't dearchived these
files into /sys/src/cmd/perl. After running setup.rc you may delete
the copy of the source you originally detarred, as source code has now
been installed in /sys/src/cmd/perl. If you plan on installing perl
binaries for all architectures, run "setup.rc -a".

2. After making sure that you have adequate privileges to build system
software, from /sys/src/cmd/perl/5.00301 (adjust version
appropriately) run:

	mk install

If you wish to install perl versions for all architectures (68020,
mips, sparc and 386) run:

	mk installall

3. Wait. The build process will take a *long* time because perl
bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30
minutes to build the distribution from scratch.

=head2 Installing Perl Documentation on Plan 9

This perl distribution comes with a tremendous amount of
documentation. To add these to the built-in manuals that come with
Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately)
run:

	mk man

To begin your reading, start with:

	man perl

This is a good introduction and will direct you towards other man
pages that may interest you.

(Note: "mk man" may produce some extraneous noise. Fear not.)

=head1 BUGS

"As many as there are grains of sand on all the beaches of the 
world . . ." - Carl Sagan

=head1 Revision date

This document was revised 09-October-1996 for Perl 5.003_7.

=head1 AUTHOR

Direct questions, comments, and the unlikely bug report (ahem) direct
comments toward:

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