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

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

README.machten - Perl version 5 on Power MachTen systems

=head1 DESCRIPTION

This document describes how to build Perl 5 on Power MachTen systems,
and discusses a few wrinkles in the implementation.

=head2 Compiling Perl 5 on MachTen

To compile perl under MachTen 4.1.4 (and probably earlier versions):

  ./Configure -de
  make
  make test
  make install

This builds and installs a statically-linked perl; MachTen's dynamic
linking facilities are not adequate to support Perl's use of
dynamically linked libraries.  (See F<hints/machten.sh> for more
information.)

You should have at least 32 megabytes of free memory on your
system before running the C<make> command.

For much more information on building perl -- for example, on how to
change the default installation directory -- see F<INSTALL>.

=head2 Failures during C<make test>

=over 4

=item op/lexassign.t

This test may fail when first run after building perl.  It does not
fail subsequently.  The cause is unknown.

=item op/taint.t

This test emits various complaints such as "Operation not permitted",
but passes.  The cause is an incomplete implementation of System V
inter-process communication in MachTen 4.1.4.  In versions prior to
4.1.4, the implementation was so incomplete that the hints file
disables its incorporation into perl; in 4.1.4, the facilities are
useable with care.

=item pragma/warnings.t

Test 257 fails due to a failure to warn about attempts to read from a
filehandle which is a duplicate of stdout when stdout is attached to a
pipe.  The output of the test contains a block comment which discusses
a different failure, not applicable to MachTen.

The root of the problem is that Machten does not assign a file type to
either end of a pipe (see L<stat>), resulting, among other things
in Perl's C<-p> test failing on file descriptors belonging to pipes.
As a result, perl becomes confused, and the test for reading from a
write-only file fails.  I am reluctant to patch perl to get around
this, as it's clearly an OS bug (about which Tenon has been informed),
and limited in its effect on practical Perl programs.

=back

=head2 Using external modules

If warnings are enabled with Perl's C<-w> command-line flag, you are
likely to see warnings when using external modules containing XS
(compiled) code:

  Subroutine DynaLoader::dl_error redefined at /usr/local/lib/perl5/5.6.0/powerpc-machten/DynaLoader.pm line 93.

This is a harmless consequence of the static linking used for MachTen
perl.  You can suppress the warnings by using the more modern
C<-Mwarnings> instead of the traditional C<-w>.  (See L<perllexwarn>.)

=head2 Building external modules

To add an external module to perl, build in the normal way, which
is documented in L<ExtUtils::MakeMaker>, or which can be driven
automatically by the CPAN module (see L<CPAN>), which is part of the
standard distribution.  If wou want to install a
module contains XS code (C or C++ source which compiles to object code
for linking with perl), you will have to replace your perl binary with
a new version containing the new statically-linked object module.  The
build process tells you how to do this.

There is a gotcha, however, which users usually encounter immediately
they respond to CPAN's invitation to C<install Bundle::CPAN>. When
installing a I<bundle> -- a group of modules which together achieve
some particular purpose, the installation process for later modules in
the bundle tends to assume that earlier modules have been fully
installed and are available for use.  This is not true on a
statically-linked system for earlier modules which contain XS code.
As a result the installation of the bundle fails.  The work-around is
not to install the bundle as a one-shot operation, but instead to see
what modules it contains, and install these one-at-a-time by hand in
the order given.

=head1 AUTHOR

Dominic Dunlop <domo@computer.org>

=head1 DATE

Version 1.0 2000-03-22
Commit	Line	Data
da369004	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.machten - Perl version 5 on Power MachTen systems
	8
	9	=head1 DESCRIPTION
	10
	11	This document describes how to build Perl 5 on Power MachTen systems,
	12	and discusses a few wrinkles in the implementation.
	13
	14	=head2 Compiling Perl 5 on MachTen
	15
	16	To compile perl under MachTen 4.1.4 (and probably earlier versions):
	17
	18	./Configure -de
	19	make
	20	make test
	21	make install
	22
	23	This builds and installs a statically-linked perl; MachTen's dynamic
	24	linking facilities are not adequate to support Perl's use of
	25	dynamically linked libraries. (See F<hints/machten.sh> for more
	26	information.)
	27
	28	You should have at least 32 megabytes of free memory on your
	29	system before running the C<make> command.
	30
	31	For much more information on building perl -- for example, on how to
	32	change the default installation directory -- see F<INSTALL>.
	33
	34	=head2 Failures during C<make test>
	35
	36	=over 4
	37
	38	=item op/lexassign.t
	39
	40	This test may fail when first run after building perl. It does not
	41	fail subsequently. The cause is unknown.
	42
	43	=item op/taint.t
	44
	45	This test emits various complaints such as "Operation not permitted",
	46	but passes. The cause is an incomplete implementation of System V
	47	inter-process communication in MachTen 4.1.4. In versions prior to
	48	4.1.4, the implementation was so incomplete that the hints file
	49	disables its incorporation into perl; in 4.1.4, the facilities are
	50	useable with care.
	51
	52	=item pragma/warnings.t
	53
	54	Test 257 fails due to a failure to warn about attempts to read from a
	55	filehandle which is a duplicate of stdout when stdout is attached to a
	56	pipe. The output of the test contains a block comment which discusses
	57	a different failure, not applicable to MachTen.
	58
	59	The root of the problem is that Machten does not assign a file type to
	60	either end of a pipe (see L<stat>), resulting, among other things
	61	in Perl's C<-p> test failing on file descriptors belonging to pipes.
	62	As a result, perl becomes confused, and the test for reading from a
	63	write-only file fails. I am reluctant to patch perl to get around
	64	this, as it's clearly an OS bug (about which Tenon has been informed),
65	and limited in its effect on practical Perl programs.
66
67	=back
68
69	=head2 Using external modules
70
71	If warnings are enabled with Perl's C<-w> command-line flag, you are
72	likely to see warnings when using external modules containing XS
73	(compiled) code:
74
75	Subroutine DynaLoader::dl_error redefined at /usr/local/lib/perl5/5.6.0/powerpc-machten/DynaLoader.pm line 93.
76
77	This is a harmless consequence of the static linking used for MachTen
78	perl. You can suppress the warnings by using the more modern
79	C<-Mwarnings> instead of the traditional C<-w>. (See L<perllexwarn>.)
80
81	=head2 Building external modules
82
83	To add an external module to perl, build in the normal way, which
84	is documented in L<ExtUtils::MakeMaker>, or which can be driven
85	automatically by the CPAN module (see L<CPAN>), which is part of the
86	standard distribution. If wou want to install a
87	module contains XS code (C or C++ source which compiles to object code
88	for linking with perl), you will have to replace your perl binary with
89	a new version containing the new statically-linked object module. The
90	build process tells you how to do this.
91
92	There is a gotcha, however, which users usually encounter immediately
93	they respond to CPAN's invitation to C<install Bundle::CPAN>. When
94	installing a I<bundle> -- a group of modules which together achieve
95	some particular purpose, the installation process for later modules in
96	the bundle tends to assume that earlier modules have been fully
97	installed and are available for use. This is not true on a
98	statically-linked system for earlier modules which contain XS code.
99	As a result the installation of the bundle fails. The work-around is
100	not to install the bundle as a one-shot operation, but instead to see
101	what modules it contains, and install these one-at-a-time by hand in
102	the order given.
103
104	=head1 AUTHOR
105
106	Dominic Dunlop <domo@computer.org>
107
108	=head1 DATE
109
110	Version 1.0 2000-03-22