| 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.1-RC3 as of this writing) builds without changes |
| 17 | under Mac OS X. Under the 10.3 "Panther" release, all self-tests pass, |
| 18 | and all standard features are supported. |
| 19 | |
| 20 | Earlier Mac OS X releases did not include a completely thread-safe libc, |
| 21 | so threading is not fully supported. Also, earlier releases included a |
| 22 | somewhat buggy libdb, so some of the DB_File tests are known to fail on |
| 23 | 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 libperl and Prebinding |
| 42 | |
| 43 | Mac OS X ships with a dynamically-loaded libperl, but the default for |
| 44 | this release is to compile a static libperl. The reason for this is |
| 45 | pre-binding. Dynamic libraries can be pre-bound to a specific address in |
| 46 | memory in order to decrease load time. To do this, one needs to be aware |
| 47 | of the location and size of all previously-loaded libraries. Apple |
| 48 | collects this information as part of their overall OS build process, and |
| 49 | thus has easy access to it when building Perl, but ordinary users would |
| 50 | need to go to a great deal of effort to obtain the information needed |
| 51 | for pre-binding. |
| 52 | |
| 53 | You can override the default and build a shared libperl if you wish |
| 54 | (S<Configure ... -Duseshrlib>), but the load time will be |
| 55 | significantly greater than either the static library, or Apple's |
| 56 | pre-bound dynamic library. |
| 57 | |
| 58 | |
| 59 | =head2 Updating Panther |
| 60 | |
| 61 | As of this writing, the latest Perl release that has been tested and |
| 62 | approved for inclusion in the 10.3 "Panther" release of Mac OS X is |
| 63 | 5.8.1 RC3. It is currently unknown whether the final 5.8.1 release will |
| 64 | be made in time to be tested and included with Panther. |
| 65 | |
| 66 | If the final release of Perl 5.8.1 is not made in time to be included |
| 67 | with Panther, it is recommended that you wait for an official Apple |
| 68 | update to the OS, rather than attempting to update it yourself. In most |
| 69 | cases, if you need a newer Perl, it is preferable to install it in some |
| 70 | other location, such as /usr/local or /opt, rather than overwriting the |
| 71 | system Perl. The default location (no -Dprefix=... specified when running |
| 72 | Configure) is /usr/local. |
| 73 | |
| 74 | If you find that you do need to update the system Perl, there is one |
| 75 | potential issue. If you upgrade using the default static libperl, you |
| 76 | will find that the dynamic libperl supplied by Apple will not be |
| 77 | deleted. If both libraries are present when an application that links |
| 78 | against libperl is built, ld will link against the dynamic library by |
| 79 | default. So, if you need to replace Apple's dynamic libperl with a |
| 80 | static libperl, you need to be sure to delete the older dynamic library |
| 81 | after you've installed the update. |
| 82 | |
| 83 | Note that this is only an issue when updating from an older build of the |
| 84 | same Perl version. If you're updating from (for example) 5.8.1 to 5.8.2, |
| 85 | this issue won't affect you. |
| 86 | |
| 87 | |
| 88 | =head2 Known problems |
| 89 | |
| 90 | If you have installed extra libraries such as GDBM through Fink |
| 91 | (in other words, you have libraries under F</sw/lib>), or libdlcompat |
| 92 | to F</usr/local/lib>, you may need to be extra careful when running |
| 93 | Configure to not to confuse Configure and Perl about which libraries |
| 94 | to use. Being confused will show up for example as "dyld" errors about |
| 95 | symbol problems, for example during "make test". The safest bet is to run |
| 96 | Configure as |
| 97 | |
| 98 | Configure ... -Uloclibpth -Dlibpth=/usr/lib |
| 99 | |
| 100 | to make Configure look only into the system libraries. If you have some |
| 101 | extra library directories that you really want to use (such as newer |
| 102 | Berkeley DB libraries in pre-Panther systems), add those to the libpth: |
| 103 | |
| 104 | Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib' |
| 105 | |
| 106 | The default of building Perl statically may cause problems with complex |
| 107 | applications like Tk: in that case consider building shared Perl |
| 108 | |
| 109 | Configure ... -Duseshrplib |
| 110 | |
| 111 | but remember that there's a startup cost to pay in that case (see above |
| 112 | "libperl and Prebinding"). |
| 113 | |
| 114 | |
| 115 | =head2 MacPerl |
| 116 | |
| 117 | Quite a bit has been written about MacPerl, the Perl distribution for |
| 118 | "Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it |
| 119 | runs in environment that's very different from that of UNIX, many things |
| 120 | are done differently in MacPerl. Modules are installed using a different |
| 121 | procedure, Perl itself is built differently, path names are different, |
| 122 | etc. |
| 123 | |
| 124 | From the perspective of a Perl programmer, Mac OS X is more like a |
| 125 | traditional UNIX than Classic MacOS. If you find documentation that |
| 126 | refers to a special procedure that's needed for MacOS that's drastically |
| 127 | different from the instructions provided for UNIX, the MacOS |
| 128 | instructions are quite often intended for MacPerl on Classic MacOS. In |
| 129 | that case, the correct procedure on Mac OS X is usually to follow the |
| 130 | UNIX instructions, rather than the MacPerl instructions. |
| 131 | |
| 132 | |
| 133 | =head2 Carbon |
| 134 | |
| 135 | MacPerl ships with a number of modules that are used to access the |
| 136 | classic MacOS toolbox. Many of these modules have been updated to use |
| 137 | Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the |
| 138 | "Mac::Carbon" module. |
| 139 | |
| 140 | |
| 141 | =head2 Cocoa |
| 142 | |
| 143 | There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge |
| 144 | module, included with Mac OS X, can be used by standalone scripts to |
| 145 | access Foundation (i.e. non-GUI) classes and objects. |
| 146 | |
| 147 | An alternative is CamelBones, a framework that allows access to both |
| 148 | Foundation and AppKit classes and objects, so that full GUI applications |
| 149 | can be built in Perl. CamelBones can be found on SourceForge, at |
| 150 | L<http://www.sourceforge.net/projects/camelbones/>. |
| 151 | |
| 152 | |
| 153 | =head1 Starting From Scratch |
| 154 | |
| 155 | Unfortunately it is not that difficult somehow manage to break one's |
| 156 | Mac OS X Perl rather severely. If all else fails and you want to |
| 157 | really, B<REALLY>, start from scratch and remove even your Apple Perl |
| 158 | installation (which has become corrupted somehow), the following |
| 159 | instructions should do it. B<Please think twice before following |
| 160 | these instructions: they are much like conducting brain surgery to |
| 161 | yourself. Without anesthesia.> We will B<not> come to fix your system |
| 162 | if you do this. |
| 163 | |
| 164 | First, get rid of the libperl.dylib: |
| 165 | |
| 166 | # cd /System/Library/Perl/darwin/CORE |
| 167 | # rm libperl.dylib |
| 168 | |
| 169 | Then delete every .bundle file found anywhere in the folders: |
| 170 | |
| 171 | /System/Library/Perl |
| 172 | /Library/Perl |
| 173 | |
| 174 | You can find them for example by |
| 175 | |
| 176 | # find /System/Library/Perl /Library/Perl -name '*.bundle' -print |
| 177 | |
| 178 | After this you can either copy Perl from your operating system CDs |
| 179 | (you will need at least the /System/Library/Perl and /usr/bin/perl), |
| 180 | or rebuild Perl from the source code with C<Configure -Dprefix=/usr |
| 181 | -Dusershrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl |
| 182 | works much better with Perl 5.8.1 and later, in Perl 5.8.0 the |
| 183 | settings were not quite right. |
| 184 | |
| 185 | |
| 186 | =head1 AUTHOR |
| 187 | |
| 188 | This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>. |
| 189 | The "Starting From Scratch" recipe was contributed by John Montbriand |
| 190 | E<lt>montbriand@apple.comE<gt>. |
| 191 | |
| 192 | =head1 DATE |
| 193 | |
| 194 | Last modified 2003-09-08. |