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