[perl5.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 Perl version 5.8.x and greater not supported

B<Power MachTen is not supported by versions of Perl later than
5.6.x.>
If you wish to build a version from the 5.6 track, please
obtain a source distribution from the archive at
L<http://cpan.org/src/5.0/> and follow the instructions in its
README.machten file.

MachTen is no longer supported by its developers, Tenon Intersystems.
A UNIX environment hosted on Mac OS Classic, MachTen has been
superseded by Mac OS X and by BSD and Linux implementations for Macintosh
hardware.
The final version of Power MachTen, 4.1.4, lacks many features found in
modern implementations of UNIX, and has a number of bugs.
These shortcomings prevent recent versions of Perl from being able to use
extensions on MachTen, and cause numerous test suite failures in the
perl core.

In September 2003, a discussion on the MachTen mailing list determined
that there was no interest in making a later version of Perl build
successfully on MachTen.
Consequently, support for building Perl under MachTen has been suppressed
in Perl distributions published after February 2004.
The hints file, F<hints/machten.sh>, remains a part of the
distributions for reference purposes.

=head2 Compiling Perl 5.6.x on MachTen

To compile perl 5.6.x 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> on MachTen

=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 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 Building external modules on MachTen

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 you want to install a module which
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.1.0 2004-02-13
Commit	Line	Data
da369004 GS	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
d0c3e6d6 DD	14	=head2 Perl version 5.8.x and greater not supported
	15
	16	B<Power MachTen is not supported by versions of Perl later than
	17	5.6.x.>
	18	If you wish to build a version from the 5.6 track, please
	19	obtain a source distribution from the archive at
	20	L<http://cpan.org/src/5.0/> and follow the instructions in its
	21	README.machten file.
	22
	23	MachTen is no longer supported by its developers, Tenon Intersystems.
	24	A UNIX environment hosted on Mac OS Classic, MachTen has been
	25	superseded by Mac OS X and by BSD and Linux implementations for Macintosh
	26	hardware.
	27	The final version of Power MachTen, 4.1.4, lacks many features found in
	28	modern implementations of UNIX, and has a number of bugs.
	29	These shortcomings prevent recent versions of Perl from being able to use
	30	extensions on MachTen, and cause numerous test suite failures in the
	31	perl core.
	32
	33	In September 2003, a discussion on the MachTen mailing list determined
	34	that there was no interest in making a later version of Perl build
	35	successfully on MachTen.
	36	Consequently, support for building Perl under MachTen has been suppressed
	37	in Perl distributions published after February 2004.
	38	The hints file, F<hints/machten.sh>, remains a part of the
	39	distributions for reference purposes.
	40
	41	=head2 Compiling Perl 5.6.x on MachTen
	42
	43	To compile perl 5.6.x under MachTen 4.1.4 (and probably earlier versions):
da369004 GS	44
	45	./Configure -de
	46	make
	47	make test
	48	make install
	49
	50	This builds and installs a statically-linked perl; MachTen's dynamic
	51	linking facilities are not adequate to support Perl's use of
	52	dynamically linked libraries. (See F<hints/machten.sh> for more
	53	information.)
	54
	55	You should have at least 32 megabytes of free memory on your
	56	system before running the C<make> command.
	57
	58	For much more information on building perl -- for example, on how to
	59	change the default installation directory -- see F<INSTALL>.
	60
a83b6f46	61	=head2 Failures during C<make test> on MachTen
da369004 GS	62
	63	=over 4
	64
	65	=item op/lexassign.t
	66
	67	This test may fail when first run after building perl. It does not
	68	fail subsequently. The cause is unknown.
	69
da369004 GS	70	=item pragma/warnings.t
	71
	72	Test 257 fails due to a failure to warn about attempts to read from a
	73	filehandle which is a duplicate of stdout when stdout is attached to a
	74	pipe. The output of the test contains a block comment which discusses
	75	a different failure, not applicable to MachTen.
	76
	77	The root of the problem is that Machten does not assign a file type to
	78	either end of a pipe (see L<stat>), resulting, among other things
	79	in Perl's C<-p> test failing on file descriptors belonging to pipes.
	80	As a result, perl becomes confused, and the test for reading from a
	81	write-only file fails. I am reluctant to patch perl to get around
	82	this, as it's clearly an OS bug (about which Tenon has been informed),
	83	and limited in its effect on practical Perl programs.
	84
	85	=back
	86
a83b6f46	87	=head2 Building external modules on MachTen
da369004 GS	88
	89	To add an external module to perl, build in the normal way, which
	90	is documented in L<ExtUtils::MakeMaker>, or which can be driven
	91	automatically by the CPAN module (see L<CPAN>), which is part of the
4375e838 GS	92	standard distribution. If you want to install a module which
4375e838 GS	93	contains XS code (C or C++ source which compiles to object code
da369004 GS	94	for linking with perl), you will have to replace your perl binary with
	95	a new version containing the new statically-linked object module. The
	96	build process tells you how to do this.
	97
	98	There is a gotcha, however, which users usually encounter immediately
	99	they respond to CPAN's invitation to C<install Bundle::CPAN>. When
	100	installing a I<bundle> -- a group of modules which together achieve
	101	some particular purpose, the installation process for later modules in
	102	the bundle tends to assume that earlier modules have been fully
	103	installed and are available for use. This is not true on a
	104	statically-linked system for earlier modules which contain XS code.
	105	As a result the installation of the bundle fails. The work-around is
	106	not to install the bundle as a one-shot operation, but instead to see
	107	what modules it contains, and install these one-at-a-time by hand in
	108	the order given.
	109
	110	=head1 AUTHOR
	111
	112	Dominic Dunlop <domo@computer.org>
	113
	114	=head1 DATE
	115
d0c3e6d6	116	Version 1.1.0 2004-02-13