This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
patch@26052 - compile rule for mathoms.c
[perl5.git] / README.macosx
index 1c1e2d9..04f8d10 100644 (file)
@@ -13,12 +13,13 @@ This document briefly describes perl under Mac OS X.
 
 =head1 DESCRIPTION
 
-The latest Perl (5.8.1-RC3 as of this writing) builds without changes
-under Mac OS X. Under the 10.3 "Panther" release, all self-tests pass,
+The latest Perl (5.8.8 as of this writing) builds without changes
+under Mac OS X. Under the 10.4 "Tiger" release, all self-tests pass,
 and all standard features are supported.
 
-Earlier Mac OS X releases did not include a completely thread-safe libc,
-so threading is not fully supported. Also, earlier releases included a
+Mac OS X releases prior to 10.3 "Panther" did not include a completely
+thread-safe libc, so threading is not fully supported when Perl is built
+for these releases. Also, earlier releases included a
 somewhat buggy libdb, so some of the DB_File tests are known to fail on
 those releases.
 
@@ -56,17 +57,10 @@ significantly greater than either the static library, or Apple's
 pre-bound dynamic library.
 
 
-=head2 Updating Panther
+=head2 Updating Apple-supplied Perl
 
-As of this writing, the latest Perl release that has been tested and
-approved for inclusion in the 10.3 "Panther" release of Mac OS X is
-5.8.1 RC3. It is currently unknown whether the final 5.8.1 release will
-be made in time to be tested and included with Panther.
-
-If the final release of Perl 5.8.1 is not made in time to be included
-with Panther, it is recommended that you wait for an official Apple
-update to the OS, rather than attempting to update it yourself. In most
-cases, if you need a newer Perl, it is preferable to install it in some
+Apple ships a threaded build of perl 5.8.6 with Mac OS 10.4.x, "Tiger".
+In most cases, if you need a newer Perl, it is preferable to install it in some
 other location, such as /usr/local or /opt, rather than overwriting the
 system Perl.  The default location (no -Dprefix=... specified when running
 Configure) is /usr/local.
@@ -81,9 +75,39 @@ static libperl, you need to be sure to delete the older dynamic library
 after you've installed the update.
 
 Note that this is only an issue when updating from an older build of the
-same Perl version. If you're updating from (for example) 5.8.1 to 5.8.2,
+same Perl version. If you're updating from (for example) 5.8.6 to 5.8.8,
 this issue won't affect you.
 
+=head2 64-bit Perl
+
+By default, perl is built to use 32-bit integers and pointers. The hints file,
+F<hints/darwin.sh>, provides experimental support for 64-bit integers 
+and pointers (on G5 processors only) when Configure is run with the
+C<-Duse64bitall> option. Expect many compiler warnings and a number
+of test failures.
+
+=head2 Intel processor support
+
+At the time of writing, the Perl developers have no knowledge of the
+behaviour (or misbehaviour) of the Perl build process when hosted by
+an Intel-based Macintosh. As far as we know, Apple ships Perl 5.8.6
+with Intel developer builds of Mac OS X, so we presume that there
+are few or no problems in building that version of Perl. (The source
+package used by Apple may be found at L<http://opendarwin.org/>.)
+If you encounter problems in building a later version of Perl for an
+Intel-based Macintosh, please file a bug report, if possible by using
+the following command in the build directory: 
+
+    ./perl -Ilib utils/perlbug
+
+=head2  Universal binaries
+
+Apple's Xcode development tools, version 2.1 and later, provide
+support for the creation of I<universal binaries>, which contain
+code for both PowerPC and Intel architectures. (In the past, and on
+other platforms, such executable files have been known as I<fat
+binaries>.) Perl's build process currently provides no support for
+the production of universal binaries.
 
 =head2 Known problems
 
@@ -111,6 +135,11 @@ applications like Tk: in that case consider building shared Perl
 but remember that there's a startup cost to pay in that case (see above
 "libperl and Prebinding").
 
+Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
+the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
+failures in the C<lib/locale> test. These failures have been supressed
+in the current release of Perl by making the test ignore the broken locale.
+If you need to use the eu_ES locale, you should contact Apple support.
 
 =head2 MacPerl
 
@@ -150,10 +179,46 @@ can be built in Perl. CamelBones can be found on SourceForge, at
 L<http://www.sourceforge.net/projects/camelbones/>.
 
 
+=head1 Starting From Scratch
+
+Unfortunately it is not that difficult somehow manage to break one's
+Mac OS X Perl rather severely.  If all else fails and you want to
+really, B<REALLY>, start from scratch and remove even your Apple Perl
+installation (which has become corrupted somehow), the following
+instructions should do it.  B<Please think twice before following
+these instructions: they are much like conducting brain surgery to
+yourself.  Without anesthesia.>  We will B<not> come to fix your system
+if you do this.
+
+First, get rid of the libperl.dylib:
+
+    # cd /System/Library/Perl/darwin/CORE
+    # rm libperl.dylib
+
+Then delete every .bundle file found anywhere in the folders:
+
+    /System/Library/Perl
+    /Library/Perl
+
+You can find them for example by
+
+    # find /System/Library/Perl /Library/Perl -name '*.bundle' -print
+
+After this you can either copy Perl from your operating system CDs
+(you will need at least the /System/Library/Perl and /usr/bin/perl),
+or rebuild Perl from the source code with C<Configure -Dprefix=/usr
+-Dusershrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
+works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
+settings were not quite right.
+
+
 =head1 AUTHOR
 
-This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>.
+This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
+and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>.
+The "Starting From Scratch" recipe was contributed by John Montbriand
+E<lt>montbriand@apple.comE<gt>.
 
 =head1 DATE
 
-Last modified 2003-08-16.
+Last modified 2005-11-07.