| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLMACOSX 1" |
| 58 |
.TH PERLMACOSX 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlmacosx \- Perl under Mac OS X |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
This document briefly describes Perl under Mac OS X. |
| 68 |
.PP |
| 69 |
.Vb 7 |
| 70 |
\& curl \-O https://www.cpan.org/src/perl\-5.40.1.tar.gz |
| 71 |
\& tar \-xzf perl\-5.40.1.tar.gz |
| 72 |
\& cd perl\-5.40.1 |
| 73 |
\& ./Configure \-des \-Dprefix=/usr/local/ |
| 74 |
\& make |
| 75 |
\& make test |
| 76 |
\& sudo make install |
| 77 |
.Ve |
| 78 |
.SH DESCRIPTION |
| 79 |
.IX Header "DESCRIPTION" |
| 80 |
The latest Perl release (5.40.1 as of this writing) builds without changes |
| 81 |
under all versions of Mac OS X from 10.3 "Panther" onwards. |
| 82 |
.PP |
| 83 |
In order to build your own version of Perl you will need 'make', |
| 84 |
which is part of Apple's developer tools \- also known as Xcode. From |
| 85 |
Mac OS X 10.7 "Lion" onwards, it can be downloaded separately as the |
| 86 |
\&'Command Line Tools' bundle directly from <https://developer.apple.com/downloads/> |
| 87 |
(you will need a free account to log in), or as a part of the Xcode suite, |
| 88 |
freely available at the App Store. Xcode is a pretty big app, so |
| 89 |
unless you already have it or really want it, you are advised to get the |
| 90 |
\&'Command Line Tools' bundle separately from the link above. If you want |
| 91 |
to do it from within Xcode, go to Xcode \-> Preferences \-> Downloads and |
| 92 |
select the 'Command Line Tools' option. |
| 93 |
.PP |
| 94 |
Between Mac OS X 10.3 "Panther" and 10.6 "Snow Leopard", the 'Command |
| 95 |
Line Tools' bundle was called 'unix tools', and was usually supplied |
| 96 |
with Mac OS install DVDs. |
| 97 |
.PP |
| 98 |
Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a |
| 99 |
completely thread-safe libc, so threading is not fully supported. Also, |
| 100 |
earlier releases included a buggy libdb, so some of the DB_File tests |
| 101 |
are known to fail on those releases. |
| 102 |
.SS "Installation Prefix" |
| 103 |
.IX Subsection "Installation Prefix" |
| 104 |
The default installation location for this release uses the traditional |
| 105 |
UNIX directory layout under /usr/local. This is the recommended location |
| 106 |
for most users, and will leave the Apple-supplied Perl and its modules |
| 107 |
undisturbed. |
| 108 |
.PP |
| 109 |
Using an installation prefix of '/usr' will result in a directory layout |
| 110 |
that mirrors that of Apple's default Perl, with core modules stored in |
| 111 |
\&'/System/Library/Perl/${version}', CPAN modules stored in |
| 112 |
\&'/Library/Perl/${version}', and the addition of |
| 113 |
\&'/Network/Library/Perl/${version}' to \f(CW@INC\fR for modules that are stored |
| 114 |
on a file server and used by many Macs. |
| 115 |
.SS "SDK support" |
| 116 |
.IX Subsection "SDK support" |
| 117 |
First, export the path to the SDK into the build environment: |
| 118 |
.PP |
| 119 |
.Vb 1 |
| 120 |
\& export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk |
| 121 |
.Ve |
| 122 |
.PP |
| 123 |
Please make sure the SDK version (i.e. the numbers right before '.sdk') |
| 124 |
matches your system's (in this case, Mac OS X 10.8 "Mountain Lion"), as it is |
| 125 |
possible to have more than one SDK installed. Also make sure the path exists |
| 126 |
in your system, and if it doesn't please make sure the SDK is properly |
| 127 |
installed, as it should come with the 'Command Line Tools' bundle mentioned |
| 128 |
above. Finally, if you have an older Mac OS X (10.6 "Snow Leopard" and below) |
| 129 |
running Xcode 4.2 or lower, the SDK path might be something like |
| 130 |
\&\f(CW\*(Aq/Developer/SDKs/MacOSX10.3.9.sdk\*(Aq\fR. |
| 131 |
.PP |
| 132 |
You can use the SDK by exporting some additions to Perl's 'ccflags' and '..flags' |
| 133 |
config variables: |
| 134 |
.PP |
| 135 |
.Vb 5 |
| 136 |
\& ./Configure \-Accflags="\-nostdinc \-B$SDK/usr/include/gcc \e |
| 137 |
\& \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include \e |
| 138 |
\& \-F$SDK/System/Library/Frameworks" \e |
| 139 |
\& \-Aldflags="\-Wl,\-syslibroot,$SDK" \e |
| 140 |
\& \-de |
| 141 |
.Ve |
| 142 |
.SS "Universal Binary support" |
| 143 |
.IX Subsection "Universal Binary support" |
| 144 |
Note: From Mac OS X 10.6 "Snow Leopard" onwards, Apple only supports |
| 145 |
Intel-based hardware. This means you can safely skip this section unless |
| 146 |
you have an older Apple computer running on ppc or wish to create a perl |
| 147 |
binary with backwards compatibility. |
| 148 |
.PP |
| 149 |
You can compile perl as a universal binary (built for both ppc and intel). |
| 150 |
In Mac OS X 10.4 "Tiger", you must export the 'u' variant of the SDK: |
| 151 |
.PP |
| 152 |
.Vb 1 |
| 153 |
\& export SDK=/Developer/SDKs/MacOSX10.4u.sdk |
| 154 |
.Ve |
| 155 |
.PP |
| 156 |
Mac OS X 10.5 "Leopard" and above do not require the 'u' variant. |
| 157 |
.PP |
| 158 |
In addition to the compiler flags used to select the SDK, also add the flags |
| 159 |
for creating a universal binary: |
| 160 |
.PP |
| 161 |
.Vb 6 |
| 162 |
\& ./Configure \-Accflags="\-arch i686 \-arch ppc \-nostdinc \e |
| 163 |
\& \-B$SDK/usr/include/gcc \e |
| 164 |
\& \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include \e |
| 165 |
\& \-F$SDK/System/Library/Frameworks" \e |
| 166 |
\& \-Aldflags="\-arch i686 \-arch ppc \-Wl,\-syslibroot,$SDK" \e |
| 167 |
\& \-de |
| 168 |
.Ve |
| 169 |
.PP |
| 170 |
Keep in mind that these compiler and linker settings will also be used when |
| 171 |
building CPAN modules. For XS modules to be compiled as a universal binary, any |
| 172 |
libraries it links to must also be universal binaries. The system libraries that |
| 173 |
Apple includes with the 10.4u SDK are all universal, but user-installed libraries |
| 174 |
may need to be re-installed as universal binaries. |
| 175 |
.SS "64\-bit PPC support" |
| 176 |
.IX Subsection "64-bit PPC support" |
| 177 |
Follow the instructions in \fIINSTALL\fR to build perl with support for 64\-bit |
| 178 |
integers (\f(CW\*(C`use64bitint\*(C'\fR) or both 64\-bit integers and 64\-bit addressing |
| 179 |
(\f(CW\*(C`use64bitall\*(C'\fR). In the latter case, the resulting binary will run only |
| 180 |
on G5\-based hosts. |
| 181 |
.PP |
| 182 |
Support for 64\-bit addressing is experimental: some aspects of Perl may be |
| 183 |
omitted or buggy. Note the messages output by \fIConfigure\fR for further |
| 184 |
information. Please use <https://github.com/Perl/perl5/issues> to submit a |
| 185 |
problem report in the event that you encounter difficulties. |
| 186 |
.PP |
| 187 |
When building 64\-bit modules, it is your responsibility to ensure that linked |
| 188 |
external libraries and frameworks provide 64\-bit support: if they do not, |
| 189 |
module building may appear to succeed, but attempts to use the module will |
| 190 |
result in run-time dynamic linking errors, and subsequent test failures. |
| 191 |
You can use \f(CW\*(C`file\*(C'\fR to discover the architectures supported by a library: |
| 192 |
.PP |
| 193 |
.Vb 4 |
| 194 |
\& $ file libgdbm.3.0.0.dylib |
| 195 |
\& libgdbm.3.0.0.dylib: Mach\-O fat file with 2 architectures |
| 196 |
\& libgdbm.3.0.0.dylib (for architecture ppc): Mach\-O dynamically linked shared library ppc |
| 197 |
\& libgdbm.3.0.0.dylib (for architecture ppc64): Mach\-O 64\-bit dynamically linked shared library ppc64 |
| 198 |
.Ve |
| 199 |
.PP |
| 200 |
Note that this issue precludes the building of many Macintosh-specific CPAN |
| 201 |
modules (\f(CW\*(C`Mac::*\*(C'\fR), as the required Apple frameworks do not provide PPC64 |
| 202 |
support. Similarly, downloads from Fink or Darwinports are unlikely to provide |
| 203 |
64\-bit support; the libraries must be rebuilt from source with the appropriate |
| 204 |
compiler and linker flags. For further information, see Apple's |
| 205 |
\&\fI64\-Bit Transition Guide\fR at |
| 206 |
<https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/64bitPorting/transition/transition.html>. |
| 207 |
.SS "libperl and Prebinding" |
| 208 |
.IX Subsection "libperl and Prebinding" |
| 209 |
Mac OS X ships with a dynamically-loaded libperl, but the default for |
| 210 |
this release is to compile a static libperl. The reason for this is |
| 211 |
pre-binding. Dynamic libraries can be pre-bound to a specific address in |
| 212 |
memory in order to decrease load time. To do this, one needs to be aware |
| 213 |
of the location and size of all previously-loaded libraries. Apple |
| 214 |
collects this information as part of their overall OS build process, and |
| 215 |
thus has easy access to it when building Perl, but ordinary users would |
| 216 |
need to go to a great deal of effort to obtain the information needed |
| 217 |
for pre-binding. |
| 218 |
.PP |
| 219 |
You can override the default and build a shared libperl if you wish |
| 220 |
(Configure\ ...\ \-Duseshrplib). |
| 221 |
.PP |
| 222 |
With Mac OS X 10.4 "Tiger" and newer, there is almost no performance |
| 223 |
penalty for non-prebound libraries. Earlier releases will suffer a greater |
| 224 |
load time than either the static library, or Apple's pre-bound dynamic library. |
| 225 |
.SS "Updating Apple's Perl" |
| 226 |
.IX Subsection "Updating Apple's Perl" |
| 227 |
In a word \- don't, at least not without a *very* good reason. Your scripts |
| 228 |
can just as easily begin with "#!/usr/local/bin/perl" as with |
| 229 |
"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as |
| 230 |
part of installation packages and such have generally only been tested |
| 231 |
with the /usr/bin/perl that's installed by Apple. |
| 232 |
.PP |
| 233 |
If you find that you do need to update the system Perl, one issue worth |
| 234 |
keeping in mind is the question of static vs. dynamic libraries. If you |
| 235 |
upgrade using the default static libperl, you will find that the dynamic |
| 236 |
libperl supplied by Apple will not be deleted. If both libraries are |
| 237 |
present when an application that links against libperl is built, ld will |
| 238 |
link against the dynamic library by default. So, if you need to replace |
| 239 |
Apple's dynamic libperl with a static libperl, you need to be sure to |
| 240 |
delete the older dynamic library after you've installed the update. |
| 241 |
.SS "Known problems" |
| 242 |
.IX Subsection "Known problems" |
| 243 |
If you have installed extra libraries such as GDBM through Fink |
| 244 |
(in other words, you have libraries under \fI/sw/lib\fR), or libdlcompat |
| 245 |
to \fI/usr/local/lib\fR, you may need to be extra careful when running |
| 246 |
Configure to not to confuse Configure and Perl about which libraries |
| 247 |
to use. Being confused will show up for example as "dyld" errors about |
| 248 |
symbol problems, for example during "make test". The safest bet is to run |
| 249 |
Configure as |
| 250 |
.PP |
| 251 |
.Vb 1 |
| 252 |
\& Configure ... \-Uloclibpth \-Dlibpth=/usr/lib |
| 253 |
.Ve |
| 254 |
.PP |
| 255 |
to make Configure look only into the system libraries. If you have some |
| 256 |
extra library directories that you really want to use (such as newer |
| 257 |
Berkeley DB libraries in pre-Panther systems), add those to the libpth: |
| 258 |
.PP |
| 259 |
.Vb 1 |
| 260 |
\& Configure ... \-Uloclibpth \-Dlibpth=\*(Aq/usr/lib /opt/lib\*(Aq |
| 261 |
.Ve |
| 262 |
.PP |
| 263 |
The default of building Perl statically may cause problems with complex |
| 264 |
applications like Tk: in that case consider building shared Perl |
| 265 |
.PP |
| 266 |
.Vb 1 |
| 267 |
\& Configure ... \-Duseshrplib |
| 268 |
.Ve |
| 269 |
.PP |
| 270 |
but remember that there's a startup cost to pay in that case (see above |
| 271 |
"libperl and Prebinding"). |
| 272 |
.PP |
| 273 |
Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for |
| 274 |
the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in |
| 275 |
failures in the \fIlib/locale\fR test. These failures have been suppressed |
| 276 |
in the current release of Perl by making the test ignore the broken locale. |
| 277 |
If you need to use the eu_ES locale, you should contact Apple support. |
| 278 |
.SS Cocoa |
| 279 |
.IX Subsection "Cocoa" |
| 280 |
There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge |
| 281 |
module, included with Mac OS X, can be used by standalone scripts to |
| 282 |
access Foundation (i.e. non-GUI) classes and objects. |
| 283 |
.PP |
| 284 |
An alternative is CamelBones, a framework that allows access to both |
| 285 |
Foundation and AppKit classes and objects, so that full GUI applications |
| 286 |
can be built in Perl. CamelBones can be found on SourceForge, at |
| 287 |
<https://www.sourceforge.net/projects/camelbones/>. |
| 288 |
.SH "Starting From Scratch" |
| 289 |
.IX Header "Starting From Scratch" |
| 290 |
Unfortunately it is not that difficult somehow manage to break one's |
| 291 |
Mac OS X Perl rather severely. If all else fails and you want to |
| 292 |
really, \fBREALLY\fR, start from scratch and remove even your Apple Perl |
| 293 |
installation (which has become corrupted somehow), the following |
| 294 |
instructions should do it. \fBPlease think twice before following |
| 295 |
these instructions: they are much like conducting brain surgery to |
| 296 |
yourself. Without anesthesia.\fR We will \fBnot\fR come to fix your system |
| 297 |
if you do this. |
| 298 |
.PP |
| 299 |
First, get rid of the libperl.dylib: |
| 300 |
.PP |
| 301 |
.Vb 2 |
| 302 |
\& # cd /System/Library/Perl/darwin/CORE |
| 303 |
\& # rm libperl.dylib |
| 304 |
.Ve |
| 305 |
.PP |
| 306 |
Then delete every .bundle file found anywhere in the folders: |
| 307 |
.PP |
| 308 |
.Vb 2 |
| 309 |
\& /System/Library/Perl |
| 310 |
\& /Library/Perl |
| 311 |
.Ve |
| 312 |
.PP |
| 313 |
You can find them for example by |
| 314 |
.PP |
| 315 |
.Vb 1 |
| 316 |
\& # find /System/Library/Perl /Library/Perl \-name \*(Aq*.bundle\*(Aq \-print |
| 317 |
.Ve |
| 318 |
.PP |
| 319 |
After this you can either copy Perl from your operating system media |
| 320 |
(you will need at least the /System/Library/Perl and /usr/bin/perl), |
| 321 |
or rebuild Perl from the source code with \f(CW\*(C`Configure \-Dprefix=/usr |
| 322 |
\&\-Duseshrplib\*(C'\fR NOTE: the \f(CW\*(C`\-Dprefix=/usr\*(C'\fR to replace the system Perl |
| 323 |
works much better with Perl 5.8.1 and later, in Perl 5.8.0 the |
| 324 |
settings were not quite right. |
| 325 |
.PP |
| 326 |
"Pacifist" from CharlesSoft (<https://www.charlessoft.com/>) is a nice |
| 327 |
way to extract the Perl binaries from the OS media, without having to |
| 328 |
reinstall the entire OS. |
| 329 |
.SH AUTHOR |
| 330 |
.IX Header "AUTHOR" |
| 331 |
This README was written by Sherm Pendley <sherm@dot\-app.org>, |
| 332 |
and subsequently updated by Dominic Dunlop <[email protected]> |
| 333 |
and Breno G. de Oliveira <[email protected]>. The "Starting From Scratch" |
| 334 |
recipe was contributed by John Montbriand <[email protected]>. |
| 335 |
.SH DATE |
| 336 |
.IX Header "DATE" |
| 337 |
Last modified 2013\-04\-29. |