[Summary view] [Print] [Text view]

   1  If you read this file _as_is_, just ignore the funny characters you see.
   2  It is written in the POD format (see pod/perlpod.pod) which is specially
   3  designed to be readable as is.
   4  
   5  =head1 NAME
   6  
   7  README.macosx - Perl under Mac OS X
   8  
   9  =head1 SYNOPSIS
  10  
  11  This document briefly describes perl under Mac OS X.
  12  
  13  
  14  =head1 DESCRIPTION
  15  
  16  The latest Perl release (5.8.8 as of this writing) builds without changes
  17  under Mac OS X. Under 10.3 "Panther" and newer OS versions, all self-tests
  18  pass, and all standard features are supported.
  19  
  20  Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a
  21  completely thread-safe libc, so threading is not fully supported. Also,
  22  earlier releases included a buggy libdb, so some of the DB_File tests
  23  are known to fail on those releases.
  24  
  25  
  26  =head2 Installation Prefix
  27  
  28  The default installation location for this release uses the traditional
  29  UNIX directory layout under /usr/local. This is the recommended location
  30  for most users, and will leave the Apple-supplied Perl and its modules
  31  undisturbed.
  32  
  33  Using an installation prefix of '/usr' will result in a directory layout
  34  that mirrors that of Apple's default Perl, with core modules stored in
  35  '/System/Library/Perl/$version}', CPAN modules stored in
  36  '/Library/Perl/$version}', and the addition of
  37  '/Network/Library/Perl/$version}' to @INC for modules that are stored
  38  on a file server and used by many Macs.
  39  
  40  
  41  =head2 SDK support
  42  
  43  First, export the path to the SDK into the build environment:
  44  
  45      export SDK=/Developer/SDKs/MacOSX10.3.9.sdk
  46  
  47  Use an SDK by exporting some additions to Perl's 'ccflags' and '..flags'
  48  config variables:
  49  
  50      ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc \
  51                             -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
  52                             -F$SDK/System/Library/Frameworks" \
  53                  -Aldflags="-Wl,-syslibroot,$SDK" \
  54                  -de
  55  
  56  =head2 Universal Binary support
  57  
  58  To compile perl as a universal binary (built for both ppc and intel), export
  59  the SDK variable as above, selecting the 10.4u SDK:
  60  
  61      export SDK=/Developer/SDKs/MacOSX10.4u.sdk
  62  
  63  In addition to the compiler flags used to select the SDK, also add the flags
  64  for creating a universal binary:
  65  
  66      ./Configure -Accflags="-arch i686 -arch ppc -nostdinc -B$SDK/usr/include/gcc \
  67                             -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
  68                             -F$SDK/System/Library/Frameworks" \
  69                  -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK" \
  70                  -de
  71  
  72  Keep in mind that these compiler and linker settings will also be used when
  73  building CPAN modules. For XS modules to be compiled as a universal binary, any
  74  libraries it links to must also be universal binaries. The system libraries that
  75  Apple includes with the 10.4u SDK are all universal, but user-installed libraries
  76  may need to be re-installed as universal binaries.
  77  
  78  =head2 64-bit PPC support
  79  
  80  Follow the instructions in F<INSTALL> to build perl with support for 64-bit 
  81  integers (C<use64bitint>) or both 64-bit integers and 64-bit addressing
  82  (C<use64bitall>). In the latter case, the resulting binary will run only
  83  on G5-based hosts.
  84  
  85  Support for 64-bit addressing is experimental: some aspects of Perl may be
  86  omitted or buggy. Note the messages output by F<Configure> for further 
  87  information. Please use C<perlbug> to submit a problem report in the
  88  event that you encounter difficulties.
  89  
  90  When building 64-bit modules, it is your responsiblity to ensure that linked
  91  external libraries and frameworks provide 64-bit support: if they do not,
  92  module building may appear to succeed, but attempts to use the module will
  93  result in run-time dynamic linking errors, and subsequent test failures.
  94  You can use C<file> to discover the architectures supported by a library:
  95  
  96      $ file libgdbm.3.0.0.dylib 
  97      libgdbm.3.0.0.dylib: Mach-O fat file with 2 architectures
  98      libgdbm.3.0.0.dylib (for architecture ppc):      Mach-O dynamically linked shared library ppc
  99      libgdbm.3.0.0.dylib (for architecture ppc64):    Mach-O 64-bit dynamically linked shared library ppc64
 100  
 101  Note that this issue precludes the building of many Macintosh-specific CPAN
 102  modules (C<Mac::*>), as the required Apple frameworks do not provide PPC64
 103  support. Similarly, downloads from Fink or Darwinports are unlikely to provide
 104  64-bit support; the libraries must be rebuilt from source with the appropriate
 105  compiler and linker flags. For further information, see Apple's
 106  I<64-Bit Transition Guide> at 
 107  L<http://developer.apple.com/documentation/Darwin/Conceptual/64bitPorting/index.html>.
 108  
 109  =head2 libperl and Prebinding
 110  
 111  Mac OS X ships with a dynamically-loaded libperl, but the default for
 112  this release is to compile a static libperl. The reason for this is
 113  pre-binding. Dynamic libraries can be pre-bound to a specific address in
 114  memory in order to decrease load time. To do this, one needs to be aware
 115  of the location and size of all previously-loaded libraries. Apple
 116  collects this information as part of their overall OS build process, and
 117  thus has easy access to it when building Perl, but ordinary users would
 118  need to go to a great deal of effort to obtain the information needed
 119  for pre-binding.
 120  
 121  You can override the default and build a shared libperl if you wish
 122  (S<Configure ... -Duseshrlib>), but the load time on pre-10.4 OS
 123  releases will be greater than either the static library, or Apple's
 124  pre-bound dynamic library.
 125  
 126  With 10.4 "Tiger" and newer, Apple has all but eliminated the performance
 127  penalty for non-prebound libraries.
 128  
 129  
 130  =head2 Updating Apple's Perl
 131  
 132  In a word - don't, at least without a *very* good reason. Your scripts
 133  can just as easily begin with "#!/usr/local/bin/perl" as with
 134  "#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
 135  part of installation packages and such have generally only been tested
 136  with the /usr/bin/perl that's installed by Apple.
 137  
 138  If you find that you do need to update the system Perl, one issue worth
 139  keeping in mind is the question of static vs. dynamic libraries. If you
 140  upgrade using the default static libperl, you will find that the dynamic
 141  libperl supplied by Apple will not be deleted. If both libraries are
 142  present when an application that links against libperl is built, ld will
 143  link against the dynamic library by default. So, if you need to replace
 144  Apple's dynamic libperl with a static libperl, you need to be sure to
 145  delete the older dynamic library after you've installed the update.
 146  
 147  
 148  =head2 Known problems
 149  
 150  If you have installed extra libraries such as GDBM through Fink
 151  (in other words, you have libraries under F</sw/lib>), or libdlcompat
 152  to F</usr/local/lib>, you may need to be extra careful when running
 153  Configure to not to confuse Configure and Perl about which libraries
 154  to use.  Being confused will show up for example as "dyld" errors about
 155  symbol problems, for example during "make test". The safest bet is to run
 156  Configure as
 157  
 158      Configure ... -Uloclibpth -Dlibpth=/usr/lib
 159  
 160  to make Configure look only into the system libraries.  If you have some
 161  extra library directories that you really want to use (such as newer
 162  Berkeley DB libraries in pre-Panther systems), add those to the libpth:
 163  
 164      Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'
 165  
 166  The default of building Perl statically may cause problems with complex
 167  applications like Tk: in that case consider building shared Perl
 168  
 169      Configure ... -Duseshrplib
 170  
 171  but remember that there's a startup cost to pay in that case (see above
 172  "libperl and Prebinding").
 173  
 174  Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
 175  the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
 176  failures in the C<lib/locale> test. These failures have been supressed
 177  in the current release of Perl by making the test ignore the broken locale.
 178  If you need to use the eu_ES locale, you should contact Apple support.
 179  
 180  =head2 MacPerl
 181  
 182  Quite a bit has been written about MacPerl, the Perl distribution for
 183  "Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it
 184  runs in environment that's very different from that of UNIX, many things
 185  are done differently in MacPerl. Modules are installed using a different
 186  procedure, Perl itself is built differently, path names are different,
 187  etc.
 188  
 189  From the perspective of a Perl programmer, Mac OS X is more like a
 190  traditional UNIX than Classic MacOS. If you find documentation that
 191  refers to a special procedure that's needed for MacOS that's drastically
 192  different from the instructions provided for UNIX, the MacOS
 193  instructions are quite often intended for MacPerl on Classic MacOS. In
 194  that case, the correct procedure on Mac OS X is usually to follow the
 195  UNIX instructions, rather than the MacPerl instructions.
 196  
 197  
 198  =head2 Carbon
 199  
 200  MacPerl ships with a number of modules that are used to access the
 201  classic MacOS toolbox. Many of these modules have been updated to use
 202  Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the
 203  "Mac::Carbon" module.
 204  
 205  
 206  =head2 Cocoa
 207  
 208  There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
 209  module, included with Mac OS X, can be used by standalone scripts to
 210  access Foundation (i.e. non-GUI) classes and objects.
 211  
 212  An alternative is CamelBones, a framework that allows access to both
 213  Foundation and AppKit classes and objects, so that full GUI applications
 214  can be built in Perl. CamelBones can be found on SourceForge, at
 215  L<http://www.sourceforge.net/projects/camelbones/>.
 216  
 217  
 218  =head1 Starting From Scratch
 219  
 220  Unfortunately it is not that difficult somehow manage to break one's
 221  Mac OS X Perl rather severely.  If all else fails and you want to
 222  really, B<REALLY>, start from scratch and remove even your Apple Perl
 223  installation (which has become corrupted somehow), the following
 224  instructions should do it.  B<Please think twice before following
 225  these instructions: they are much like conducting brain surgery to
 226  yourself.  Without anesthesia.>  We will B<not> come to fix your system
 227  if you do this.
 228  
 229  First, get rid of the libperl.dylib:
 230  
 231      # cd /System/Library/Perl/darwin/CORE
 232      # rm libperl.dylib
 233  
 234  Then delete every .bundle file found anywhere in the folders:
 235  
 236      /System/Library/Perl
 237      /Library/Perl
 238  
 239  You can find them for example by
 240  
 241      # find /System/Library/Perl /Library/Perl -name '*.bundle' -print
 242  
 243  After this you can either copy Perl from your operating system media
 244  (you will need at least the /System/Library/Perl and /usr/bin/perl),
 245  or rebuild Perl from the source code with C<Configure -Dprefix=/usr
 246  -Dusershrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
 247  works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
 248  settings were not quite right.
 249  
 250  "Pacifist" from CharlesSoft (L<http://www.charlessoft.com/>) is a nice
 251  way to extract the Perl binaries from the OS media, without having to
 252  reinstall the entire OS.
 253  
 254  
 255  =head1 AUTHOR
 256  
 257  This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
 258  and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>.
 259  The "Starting From Scratch" recipe was contributed by John Montbriand
 260  E<lt>montbriand@apple.comE<gt>.
 261  
 262  =head1 DATE
 263  
 264  Last modified 2006-02-24.