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