diff options
Diffstat (limited to 'upstream/debian-unstable/man1/perlmacosx.1')
| -rw-r--r-- | upstream/debian-unstable/man1/perlmacosx.1 | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/perlmacosx.1 b/upstream/debian-unstable/man1/perlmacosx.1 new file mode 100644 index 00000000..0bb91a7c --- /dev/null +++ b/upstream/debian-unstable/man1/perlmacosx.1 @@ -0,0 +1,337 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLMACOSX 1" +.TH PERLMACOSX 1 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlmacosx \- Perl under Mac OS X +.SH SYNOPSIS +.IX Header "SYNOPSIS" +This document briefly describes Perl under Mac OS X. +.PP +.Vb 7 +\& curl \-O https://www.cpan.org/src/perl\-5.38.2.tar.gz +\& tar \-xzf perl\-5.38.2.tar.gz +\& cd perl\-5.38.2 +\& ./Configure \-des \-Dprefix=/usr/local/ +\& make +\& make test +\& sudo make install +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The latest Perl release (5.38.2 as of this writing) builds without changes +under all versions of Mac OS X from 10.3 "Panther" onwards. +.PP +In order to build your own version of Perl you will need 'make', +which is part of Apple's developer tools \- also known as Xcode. From +Mac OS X 10.7 "Lion" onwards, it can be downloaded separately as the +\&'Command Line Tools' bundle directly from <https://developer.apple.com/downloads/> +(you will need a free account to log in), or as a part of the Xcode suite, +freely available at the App Store. Xcode is a pretty big app, so +unless you already have it or really want it, you are advised to get the +\&'Command Line Tools' bundle separately from the link above. If you want +to do it from within Xcode, go to Xcode \-> Preferences \-> Downloads and +select the 'Command Line Tools' option. +.PP +Between Mac OS X 10.3 "Panther" and 10.6 "Snow Leopard", the 'Command +Line Tools' bundle was called 'unix tools', and was usually supplied +with Mac OS install DVDs. +.PP +Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a +completely thread-safe libc, so threading is not fully supported. Also, +earlier releases included a buggy libdb, so some of the DB_File tests +are known to fail on those releases. +.SS "Installation Prefix" +.IX Subsection "Installation Prefix" +The default installation location for this release uses the traditional +UNIX directory layout under /usr/local. This is the recommended location +for most users, and will leave the Apple-supplied Perl and its modules +undisturbed. +.PP +Using an installation prefix of '/usr' will result in a directory layout +that mirrors that of Apple's default Perl, with core modules stored in +\&'/System/Library/Perl/${version}', CPAN modules stored in +\&'/Library/Perl/${version}', and the addition of +\&'/Network/Library/Perl/${version}' to \f(CW@INC\fR for modules that are stored +on a file server and used by many Macs. +.SS "SDK support" +.IX Subsection "SDK support" +First, export the path to the SDK into the build environment: +.PP +.Vb 1 +\& export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk +.Ve +.PP +Please make sure the SDK version (i.e. the numbers right before '.sdk') +matches your system's (in this case, Mac OS X 10.8 "Mountain Lion"), as it is +possible to have more than one SDK installed. Also make sure the path exists +in your system, and if it doesn't please make sure the SDK is properly +installed, as it should come with the 'Command Line Tools' bundle mentioned +above. Finally, if you have an older Mac OS X (10.6 "Snow Leopard" and below) +running Xcode 4.2 or lower, the SDK path might be something like +\&\f(CW\*(Aq/Developer/SDKs/MacOSX10.3.9.sdk\*(Aq\fR. +.PP +You can use the SDK by exporting some additions to Perl's 'ccflags' and '..flags' +config variables: +.PP +.Vb 5 +\& ./Configure \-Accflags="\-nostdinc \-B$SDK/usr/include/gcc \e +\& \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include \e +\& \-F$SDK/System/Library/Frameworks" \e +\& \-Aldflags="\-Wl,\-syslibroot,$SDK" \e +\& \-de +.Ve +.SS "Universal Binary support" +.IX Subsection "Universal Binary support" +Note: From Mac OS X 10.6 "Snow Leopard" onwards, Apple only supports +Intel-based hardware. This means you can safely skip this section unless +you have an older Apple computer running on ppc or wish to create a perl +binary with backwards compatibility. +.PP +You can compile perl as a universal binary (built for both ppc and intel). +In Mac OS X 10.4 "Tiger", you must export the 'u' variant of the SDK: +.PP +.Vb 1 +\& export SDK=/Developer/SDKs/MacOSX10.4u.sdk +.Ve +.PP +Mac OS X 10.5 "Leopard" and above do not require the 'u' variant. +.PP +In addition to the compiler flags used to select the SDK, also add the flags +for creating a universal binary: +.PP +.Vb 6 +\& ./Configure \-Accflags="\-arch i686 \-arch ppc \-nostdinc \e +\& \-B$SDK/usr/include/gcc \e +\& \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include \e +\& \-F$SDK/System/Library/Frameworks" \e +\& \-Aldflags="\-arch i686 \-arch ppc \-Wl,\-syslibroot,$SDK" \e +\& \-de +.Ve +.PP +Keep in mind that these compiler and linker settings will also be used when +building CPAN modules. For XS modules to be compiled as a universal binary, any +libraries it links to must also be universal binaries. The system libraries that +Apple includes with the 10.4u SDK are all universal, but user-installed libraries +may need to be re-installed as universal binaries. +.SS "64\-bit PPC support" +.IX Subsection "64-bit PPC support" +Follow the instructions in \fIINSTALL\fR to build perl with support for 64\-bit +integers (\f(CW\*(C`use64bitint\*(C'\fR) or both 64\-bit integers and 64\-bit addressing +(\f(CW\*(C`use64bitall\*(C'\fR). In the latter case, the resulting binary will run only +on G5\-based hosts. +.PP +Support for 64\-bit addressing is experimental: some aspects of Perl may be +omitted or buggy. Note the messages output by \fIConfigure\fR for further +information. Please use <https://github.com/Perl/perl5/issues> to submit a +problem report in the event that you encounter difficulties. +.PP +When building 64\-bit modules, it is your responsibility to ensure that linked +external libraries and frameworks provide 64\-bit support: if they do not, +module building may appear to succeed, but attempts to use the module will +result in run-time dynamic linking errors, and subsequent test failures. +You can use \f(CW\*(C`file\*(C'\fR to discover the architectures supported by a library: +.PP +.Vb 4 +\& $ file libgdbm.3.0.0.dylib +\& libgdbm.3.0.0.dylib: Mach\-O fat file with 2 architectures +\& libgdbm.3.0.0.dylib (for architecture ppc): Mach\-O dynamically linked shared library ppc +\& libgdbm.3.0.0.dylib (for architecture ppc64): Mach\-O 64\-bit dynamically linked shared library ppc64 +.Ve +.PP +Note that this issue precludes the building of many Macintosh-specific CPAN +modules (\f(CW\*(C`Mac::*\*(C'\fR), as the required Apple frameworks do not provide PPC64 +support. Similarly, downloads from Fink or Darwinports are unlikely to provide +64\-bit support; the libraries must be rebuilt from source with the appropriate +compiler and linker flags. For further information, see Apple's +\&\fI64\-Bit Transition Guide\fR at +<https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/64bitPorting/transition/transition.html>. +.SS "libperl and Prebinding" +.IX Subsection "libperl and Prebinding" +Mac OS X ships with a dynamically-loaded libperl, but the default for +this release is to compile a static libperl. The reason for this is +pre-binding. Dynamic libraries can be pre-bound to a specific address in +memory in order to decrease load time. To do this, one needs to be aware +of the location and size of all previously-loaded libraries. Apple +collects this information as part of their overall OS build process, and +thus has easy access to it when building Perl, but ordinary users would +need to go to a great deal of effort to obtain the information needed +for pre-binding. +.PP +You can override the default and build a shared libperl if you wish +(Configure\ ...\ \-Duseshrplib). +.PP +With Mac OS X 10.4 "Tiger" and newer, there is almost no performance +penalty for non-prebound libraries. Earlier releases will suffer a greater +load time than either the static library, or Apple's pre-bound dynamic library. +.SS "Updating Apple's Perl" +.IX Subsection "Updating Apple's Perl" +In a word \- don't, at least not without a *very* good reason. Your scripts +can just as easily begin with "#!/usr/local/bin/perl" as with +"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as +part of installation packages and such have generally only been tested +with the /usr/bin/perl that's installed by Apple. +.PP +If you find that you do need to update the system Perl, one issue worth +keeping in mind is the question of static vs. dynamic libraries. If you +upgrade using the default static libperl, you will find that the dynamic +libperl supplied by Apple will not be deleted. If both libraries are +present when an application that links against libperl is built, ld will +link against the dynamic library by default. So, if you need to replace +Apple's dynamic libperl with a static libperl, you need to be sure to +delete the older dynamic library after you've installed the update. +.SS "Known problems" +.IX Subsection "Known problems" +If you have installed extra libraries such as GDBM through Fink +(in other words, you have libraries under \fI/sw/lib\fR), or libdlcompat +to \fI/usr/local/lib\fR, you may need to be extra careful when running +Configure to not to confuse Configure and Perl about which libraries +to use. Being confused will show up for example as "dyld" errors about +symbol problems, for example during "make test". The safest bet is to run +Configure as +.PP +.Vb 1 +\& Configure ... \-Uloclibpth \-Dlibpth=/usr/lib +.Ve +.PP +to make Configure look only into the system libraries. If you have some +extra library directories that you really want to use (such as newer +Berkeley DB libraries in pre-Panther systems), add those to the libpth: +.PP +.Vb 1 +\& Configure ... \-Uloclibpth \-Dlibpth=\*(Aq/usr/lib /opt/lib\*(Aq +.Ve +.PP +The default of building Perl statically may cause problems with complex +applications like Tk: in that case consider building shared Perl +.PP +.Vb 1 +\& Configure ... \-Duseshrplib +.Ve +.PP +but remember that there's a startup cost to pay in that case (see above +"libperl and Prebinding"). +.PP +Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for +the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in +failures in the \fIlib/locale\fR test. These failures have been suppressed +in the current release of Perl by making the test ignore the broken locale. +If you need to use the eu_ES locale, you should contact Apple support. +.SS Cocoa +.IX Subsection "Cocoa" +There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge +module, included with Mac OS X, can be used by standalone scripts to +access Foundation (i.e. non-GUI) classes and objects. +.PP +An alternative is CamelBones, a framework that allows access to both +Foundation and AppKit classes and objects, so that full GUI applications +can be built in Perl. CamelBones can be found on SourceForge, at +<https://www.sourceforge.net/projects/camelbones/>. +.SH "Starting From Scratch" +.IX Header "Starting From Scratch" +Unfortunately it is not that difficult somehow manage to break one's +Mac OS X Perl rather severely. If all else fails and you want to +really, \fBREALLY\fR, start from scratch and remove even your Apple Perl +installation (which has become corrupted somehow), the following +instructions should do it. \fBPlease think twice before following +these instructions: they are much like conducting brain surgery to +yourself. Without anesthesia.\fR We will \fBnot\fR come to fix your system +if you do this. +.PP +First, get rid of the libperl.dylib: +.PP +.Vb 2 +\& # cd /System/Library/Perl/darwin/CORE +\& # rm libperl.dylib +.Ve +.PP +Then delete every .bundle file found anywhere in the folders: +.PP +.Vb 2 +\& /System/Library/Perl +\& /Library/Perl +.Ve +.PP +You can find them for example by +.PP +.Vb 1 +\& # find /System/Library/Perl /Library/Perl \-name \*(Aq*.bundle\*(Aq \-print +.Ve +.PP +After this you can either copy Perl from your operating system media +(you will need at least the /System/Library/Perl and /usr/bin/perl), +or rebuild Perl from the source code with \f(CW\*(C`Configure \-Dprefix=/usr +\&\-Duseshrplib\*(C'\fR NOTE: the \f(CW\*(C`\-Dprefix=/usr\*(C'\fR to replace the system Perl +works much better with Perl 5.8.1 and later, in Perl 5.8.0 the +settings were not quite right. +.PP +"Pacifist" from CharlesSoft (<https://www.charlessoft.com/>) is a nice +way to extract the Perl binaries from the OS media, without having to +reinstall the entire OS. +.SH AUTHOR +.IX Header "AUTHOR" +This README was written by Sherm Pendley <sherm@dot\-app.org>, +and subsequently updated by Dominic Dunlop <domo@computer.org> +and Breno G. de Oliveira <garu@cpan.org>. The "Starting From Scratch" +recipe was contributed by John Montbriand <montbriand@apple.com>. +.SH DATE +.IX Header "DATE" +Last modified 2013\-04\-29. |