| 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 (5.8.8 as of this writing) builds without changes |
| 17 | under Mac OS X. Under the 10.4 "Tiger" release, all self-tests pass, |
| 18 | and all standard features are supported. |
| 19 | |
| 20 | Mac OS X releases prior to 10.3 "Panther" did not include a completely |
| 21 | thread-safe libc, so threading is not fully supported when Perl is built |
| 22 | for these releases. Also, earlier releases included a |
| 23 | somewhat buggy libdb, so some of the DB_File tests are known to fail on |
| 24 | those releases. |
| 25 | |
| 26 | |
| 27 | =head2 Installation Prefix |
| 28 | |
| 29 | The default installation location for this release uses the traditional |
| 30 | UNIX directory layout under /usr/local. This is the recommended location |
| 31 | for most users, and will leave the Apple-supplied Perl and its modules |
| 32 | undisturbed. |
| 33 | |
| 34 | Using an installation prefix of '/usr' will result in a directory layout |
| 35 | that mirrors that of Apple's default Perl, with core modules stored in |
| 36 | '/System/Library/Perl/${version}', CPAN modules stored in |
| 37 | '/Library/Perl/${version}', and the addition of |
| 38 | '/Network/Library/Perl/${version}' to @INC for modules that are stored |
| 39 | on a file server and used by many Macs. |
| 40 | |
| 41 | |
| 42 | =head2 libperl and Prebinding |
| 43 | |
| 44 | Mac OS X ships with a dynamically-loaded libperl, but the default for |
| 45 | this release is to compile a static libperl. The reason for this is |
| 46 | pre-binding. Dynamic libraries can be pre-bound to a specific address in |
| 47 | memory in order to decrease load time. To do this, one needs to be aware |
| 48 | of the location and size of all previously-loaded libraries. Apple |
| 49 | collects this information as part of their overall OS build process, and |
| 50 | thus has easy access to it when building Perl, but ordinary users would |
| 51 | need to go to a great deal of effort to obtain the information needed |
| 52 | for pre-binding. |
| 53 | |
| 54 | You can override the default and build a shared libperl if you wish |
| 55 | (S<Configure ... -Duseshrlib>), but the load time will be |
| 56 | significantly greater than either the static library, or Apple's |
| 57 | pre-bound dynamic library. |
| 58 | |
| 59 | |
| 60 | =head2 Updating Apple-supplied Perl |
| 61 | |
| 62 | Apple ships a threaded build of perl 5.8.6 with Mac OS 10.4.x, "Tiger". |
| 63 | In most cases, if you need a newer Perl, it is preferable to install it in some |
| 64 | other location, such as /usr/local or /opt, rather than overwriting the |
| 65 | system Perl. The default location (no -Dprefix=... specified when running |
| 66 | Configure) is /usr/local. |
| 67 | |
| 68 | If you find that you do need to update the system Perl, there is one |
| 69 | potential issue. If you upgrade using the default static libperl, you |
| 70 | will find that the dynamic libperl supplied by Apple will not be |
| 71 | deleted. If both libraries are present when an application that links |
| 72 | against libperl is built, ld will link against the dynamic library by |
| 73 | default. So, if you need to replace Apple's dynamic libperl with a |
| 74 | static libperl, you need to be sure to delete the older dynamic library |
| 75 | after you've installed the update. |
| 76 | |
| 77 | Note that this is only an issue when updating from an older build of the |
| 78 | same Perl version. If you're updating from (for example) 5.8.6 to 5.8.8, |
| 79 | this issue won't affect you. |
| 80 | |
| 81 | =head2 64-bit Perl |
| 82 | |
| 83 | By default, perl is built to use 32-bit integers and pointers. The hints file, |
| 84 | F<hints/darwin.sh>, provides experimental support for 64-bit integers |
| 85 | and pointers (on G5 processors only) when Configure is run with the |
| 86 | C<-Duse64bitall> option. Expect many compiler warnings and a number |
| 87 | of test failures. |
| 88 | |
| 89 | =head2 Intel processor support |
| 90 | |
| 91 | At the time of writing, the Perl developers have no knowledge of the |
| 92 | behaviour (or misbehaviour) of the Perl build process when hosted by |
| 93 | an Intel-based Macintosh. As far as we know, Apple ships Perl 5.8.6 |
| 94 | with Intel developer builds of Mac OS X, so we presume that there |
| 95 | are few or no problems in building that version of Perl. (The source |
| 96 | package used by Apple may be found at L<http://opendarwin.org/>.) |
| 97 | If you encounter problems in building a later version of Perl for an |
| 98 | Intel-based Macintosh, please file a bug report, if possible by using |
| 99 | the following command in the build directory: |
| 100 | |
| 101 | ./perl -Ilib utils/perlbug |
| 102 | |
| 103 | =head2 Universal binaries |
| 104 | |
| 105 | Apple's Xcode development tools, version 2.1 and later, provide |
| 106 | support for the creation of I<universal binaries>, which contain |
| 107 | code for both PowerPC and Intel architectures. (In the past, and on |
| 108 | other platforms, such executable files have been known as I<fat |
| 109 | binaries>.) Perl's build process currently provides no support for |
| 110 | the production of universal binaries. |
| 111 | |
| 112 | =head2 Known problems |
| 113 | |
| 114 | If you have installed extra libraries such as GDBM through Fink |
| 115 | (in other words, you have libraries under F</sw/lib>), or libdlcompat |
| 116 | to F</usr/local/lib>, you may need to be extra careful when running |
| 117 | Configure to not to confuse Configure and Perl about which libraries |
| 118 | to use. Being confused will show up for example as "dyld" errors about |
| 119 | symbol problems, for example during "make test". The safest bet is to run |
| 120 | Configure as |
| 121 | |
| 122 | Configure ... -Uloclibpth -Dlibpth=/usr/lib |
| 123 | |
| 124 | to make Configure look only into the system libraries. If you have some |
| 125 | extra library directories that you really want to use (such as newer |
| 126 | Berkeley DB libraries in pre-Panther systems), add those to the libpth: |
| 127 | |
| 128 | Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib' |
| 129 | |
| 130 | The default of building Perl statically may cause problems with complex |
| 131 | applications like Tk: in that case consider building shared Perl |
| 132 | |
| 133 | Configure ... -Duseshrplib |
| 134 | |
| 135 | but remember that there's a startup cost to pay in that case (see above |
| 136 | "libperl and Prebinding"). |
| 137 | |
| 138 | Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for |
| 139 | the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in |
| 140 | failures in the C<lib/locale> test. These failures have been supressed |
| 141 | in the current release of Perl by making the test ignore the broken locale. |
| 142 | If you need to use the eu_ES locale, you should contact Apple support. |
| 143 | |
| 144 | =head2 MacPerl |
| 145 | |
| 146 | Quite a bit has been written about MacPerl, the Perl distribution for |
| 147 | "Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it |
| 148 | runs in environment that's very different from that of UNIX, many things |
| 149 | are done differently in MacPerl. Modules are installed using a different |
| 150 | procedure, Perl itself is built differently, path names are different, |
| 151 | etc. |
| 152 | |
| 153 | From the perspective of a Perl programmer, Mac OS X is more like a |
| 154 | traditional UNIX than Classic MacOS. If you find documentation that |
| 155 | refers to a special procedure that's needed for MacOS that's drastically |
| 156 | different from the instructions provided for UNIX, the MacOS |
| 157 | instructions are quite often intended for MacPerl on Classic MacOS. In |
| 158 | that case, the correct procedure on Mac OS X is usually to follow the |
| 159 | UNIX instructions, rather than the MacPerl instructions. |
| 160 | |
| 161 | |
| 162 | =head2 Carbon |
| 163 | |
| 164 | MacPerl ships with a number of modules that are used to access the |
| 165 | classic MacOS toolbox. Many of these modules have been updated to use |
| 166 | Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the |
| 167 | "Mac::Carbon" module. |
| 168 | |
| 169 | |
| 170 | =head2 Cocoa |
| 171 | |
| 172 | There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge |
| 173 | module, included with Mac OS X, can be used by standalone scripts to |
| 174 | access Foundation (i.e. non-GUI) classes and objects. |
| 175 | |
| 176 | An alternative is CamelBones, a framework that allows access to both |
| 177 | Foundation and AppKit classes and objects, so that full GUI applications |
| 178 | can be built in Perl. CamelBones can be found on SourceForge, at |
| 179 | L<http://www.sourceforge.net/projects/camelbones/>. |
| 180 | |
| 181 | |
| 182 | =head1 Starting From Scratch |
| 183 | |
| 184 | Unfortunately it is not that difficult somehow manage to break one's |
| 185 | Mac OS X Perl rather severely. If all else fails and you want to |
| 186 | really, B<REALLY>, start from scratch and remove even your Apple Perl |
| 187 | installation (which has become corrupted somehow), the following |
| 188 | instructions should do it. B<Please think twice before following |
| 189 | these instructions: they are much like conducting brain surgery to |
| 190 | yourself. Without anesthesia.> We will B<not> come to fix your system |
| 191 | if you do this. |
| 192 | |
| 193 | First, get rid of the libperl.dylib: |
| 194 | |
| 195 | # cd /System/Library/Perl/darwin/CORE |
| 196 | # rm libperl.dylib |
| 197 | |
| 198 | Then delete every .bundle file found anywhere in the folders: |
| 199 | |
| 200 | /System/Library/Perl |
| 201 | /Library/Perl |
| 202 | |
| 203 | You can find them for example by |
| 204 | |
| 205 | # find /System/Library/Perl /Library/Perl -name '*.bundle' -print |
| 206 | |
| 207 | After this you can either copy Perl from your operating system CDs |
| 208 | (you will need at least the /System/Library/Perl and /usr/bin/perl), |
| 209 | or rebuild Perl from the source code with C<Configure -Dprefix=/usr |
| 210 | -Dusershrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl |
| 211 | works much better with Perl 5.8.1 and later, in Perl 5.8.0 the |
| 212 | settings were not quite right. |
| 213 | |
| 214 | |
| 215 | =head1 AUTHOR |
| 216 | |
| 217 | This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>, |
| 218 | and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>. |
| 219 | The "Starting From Scratch" recipe was contributed by John Montbriand |
| 220 | E<lt>montbriand@apple.comE<gt>. |
| 221 | |
| 222 | =head1 DATE |
| 223 | |
| 224 | Last modified 2005-11-07. |