README.macosx from Sherm Pendley.

p4raw-id: //depot/perl@20394

diff --git a/MANIFEST b/MANIFEST
index 2b40f3e..0681cd5 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -2449,6 +2449,7 @@ README.jp         About using Perl and Japanese
 README.ko              About using Perl and Korean
 README.machten         Notes about Power MachTen port
 README.macos           Notes about Mac OS (Classic)
+README.macosx          Notes about Mac OS X
 README.micro           Notes about microperl
 README.mint            Notes about Atari MiNT port
 README.mpeix           Notes about MPE/iX port

diff --git a/README.macosx b/README.macosx
new file mode 100644 (file)
index 0000000..27921e0
--- /dev/null
+++ b/README.macosx
@@ -0,0 +1,130 @@
+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.macosx - Perl under Mac OS X
+
+=head1 SYNOPSIS
+
+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,
+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
+somewhat buggy libdb, so some of the DB_File tests are known to fail on
+those releases.
+
+
+=head1 INSTALLATION PREFIX
+
+The default installation location for this release uses the traditional
+UNIX directory layout under /usr/local. This is the recommended location
+for most users, and will leave the Apple-supplied Perl and its modules
+undisturbed.
+
+Using an installation prefix of '/usr' will result in a directory layout
+that mirrors that of Apple's default Perl, with core modules stored in
+'/System/Library/Perl/${version}', CPAN modules stored in
+'/Library/Perl/${version}', and the addition of
+'/Network/Library/Perl/${version}' to @INC for modules that are stored
+on a file server and used by many Macs.
+
+
+=head1 LIBPERL AND PREBINDING
+
+Mac OS X ships with a dynamically-loaded libperl, but the default for
+this release is to compile a static libperl. The reason for this is
+pre-binding. Dynamic libraries can be pre-bound to a specific address in
+memory in order to decrease load time. To do this, one needs to be aware
+of the location and size of all previously-loaded libraries. Apple
+collects this information as part of their overall OS build process, and
+thus has easy access to it when building Perl, but ordinary users would
+need to go to a great deal of effort to obtain the information needed
+for pre-binding.
+
+You can override the default and build a shared libperl if you wish, but
+the load time will be significantly greater than either the static
+library, or Apple's pre-bound dynamic library.
+
+
+=head1 UPDATING PANTHER
+
+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
+other location, such as /usr/local or /opt, rather than overwriting the
+system Perl.
+
+If you find that you do need to update the system Perl, there is one
+potential issue. If you upgrade using the default static libperl, you
+will find that the dynamic libperl supplied by Apple will not be
+deleted. If both libraries are present when an application that links
+against libperl is built, ld will link against the dynamic library by
+default. So, if you need to replace Apple's dynamic libperl with a
+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,
+this issue won't affect you.
+
+
+=head1 MACPERL
+
+Quite a bit has been written about MacPerl, the Perl distribution for
+"Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it
+runs in environment that's very different from that of UNIX, many things
+are done differently in MacPerl. Modules are installed using a different
+procedure, Perl itself is built differently, path names are different,
+etc.
+
+From the perspective of a Perl programmer, Mac OS X is more like a
+traditional UNIX than Classic MacOS. If you find documentation that
+refers to a special procedure that's needed for MacOS that's drastically
+different from the instructions provided for UNIX, the MacOS
+instructions are quite often intended for MacPerl on Classic MacOS. In
+that case, the correct procedure on Mac OS X is usually to follow the
+UNIX instructions, rather than the MacPerl instructions.
+
+
+=head1 CARBON
+
+MacPerl ships with a number of modules that are used to access the
+classic MacOS toolbox. Many of these modules have been updated to use
+Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the
+"Mac::Carbon" module.
+
+
+=head1 COCOA
+
+There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
+module, included with Mac OS X, can be used by standalone scripts to
+access Foundation (i.e. non-GUI) classes and objects.
+
+An alternative is CamelBones, a framework that allows access to both
+Foundation and AppKit classes and objects, so that full GUI applications
+can be built in Perl. CamelBones can be found on SourceForge, at
+L<http://www.sourceforge.net/projects/camelbones/>.
+
+
+=head1 AUTHOR
+
+This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>.
+
+=head1 DATE
+
+Last modified 2003.07.31.