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