add README.machten (from Dominic Dunlop)
Gurusamy Sarathy [Wed, 22 Mar 2000 19:41:46 +0000 (19:41 +0000)]
p4raw-id: //depot/perl@5889

MAINTAIN
MANIFEST
README.machten [new file with mode: 0644]
pod/perl.pod
win32/Makefile
win32/makefile.mk

index 9461c6c..37ef489 100644 (file)
--- a/MAINTAIN
+++ b/MAINTAIN
@@ -55,6 +55,7 @@ README.cygwin                 cygwin
 README.dos                     dos
 README.hpux                    hpux
 README.lexwarn                 lexwarn
+README.machten                 machten
 README.mpeix                   mpeix
 README.os2                     os2
 README.os390                   mvs
index 8b38398..0a4ed09 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -40,6 +40,7 @@ README.dos            Notes about dos/djgpp port
 README.epoc            Notes about EPOC port
 README.hpux            Notes about HP-UX port
 README.hurd            Notes about GNU/Hurd port
+README.machten         Notes about Power MachTen port
 README.mint            Notes about Atari MiNT port
 README.mpeix           Notes about MPE/iX port
 README.os2             Notes about OS/2 port
diff --git a/README.machten b/README.machten
new file mode 100644 (file)
index 0000000..99339df
--- /dev/null
@@ -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
index 221f7f4..59ca0e0 100644 (file)
@@ -85,6 +85,7 @@ sections:
     perlcygwin         Perl notes for Cygwin
     perldos            Perl notes for DOS
     perlhpux           Perl notes for HP-UX
+    perlmachten                Perl notes for Power MachTen
     perlos2            Perl notes for OS/2
     perlos390          Perl notes for OS/390
     perlvms            Perl notes for VMS
index 12adc38..f1aea75 100644 (file)
@@ -963,6 +963,13 @@ utils: $(PERLEXE) $(X2P)
        cd ..\utils
        $(MAKE) PERL=$(MINIPERL)
        cd ..\pod
+       copy ..\README.amiga .\perlamiga.pod
+       copy ..\README.cygwin .\perlcygwin.pod
+       copy ..\README.dos .\perldos.pod
+       copy ..\README.hpux .\perlhpux.pod
+       copy ..\README.machten .\perlmachten.pod
+       copy ..\README.os2 .\perlos2.pod
+       copy ..\vms\perlvms.pod .\perlvms.pod
        copy ..\README.win32 .\perlwin32.pod
        $(MAKE) -f ..\win32\pod.mak converters
        cd ..\win32
index 7dd2902..fdaeba3 100644 (file)
@@ -1182,7 +1182,14 @@ doc: $(PERLEXE)
 
 utils: $(PERLEXE) $(X2P)
        cd ..\utils && $(MAKE) PERL=$(MINIPERL)
-       copy ..\README.win32 ..\pod\perlwin32.pod
+       copy ..\README.amiga ..\pod\perlamiga.pod
+       copy ..\README.cygwin ..\pod\perlcygwin.pod
+       copy ..\README.dos ..\pod\perldos.pod
+       copy ..\README.hpux ..\pod\perlhpux.pod
+       copy ..\README.machten ..\pod\perlmachten.pod
+       copy ..\README.os2 ..\pod\perlos2.pod
+       copy ..\README.os2 ..\pod\perlos2.pod
+       copy ..\vms\perlvms.pod ..\pod\perlvms.pod
        cd ..\pod && $(MAKE) -f ..\win32\pod.mak converters
        $(PERLEXE) $(PL2BAT) $(UTILS)