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