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