add README.machten (from Dominic Dunlop)

p4raw-id: //depot/perl@5889

1 files changed, 110 insertions, 0 deletions

diff --git a/README.machten b/README.machten
new file mode 100644
index 0000000000..99339df7f2
--- /dev/null
+++ b/README.machten
@@ -0,0 +1,110 @@
+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