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