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