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