X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmodinstall.pod;h=57f62a5cd54f5b9dad481aa46a0390498ecb7e83;hb=1e6da01743571311bdbed539271d576c28f4c2ec;hp=1c65f1c3e18d14f89d4537a88fb759b2f89aebc7;hpb=637e912262e4072f5d3143e5aa8a2f745dc0c7ea;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod index 1c65f1c..57f62a5 100644 --- a/pod/perlmodinstall.pod +++ b/pod/perlmodinstall.pod @@ -5,21 +5,23 @@ perlmodinstall - Installing CPAN Modules =head1 DESCRIPTION You can think of a module as the fundamental unit of reusable Perl -code; see L for details. Whenever anyone creates a chunk of -Perl code that they think will be useful to the world, they register -as a Perl developer at http://www.perl.com/CPAN/modules/04pause.html -so that they can then upload their code to the CPAN. The CPAN is the -Comprehensive Perl Archive Network and can be accessed at -http://www.perl.com/CPAN/. +code; See L for details. Whenever anyone creates a chunk +of Perl code that they think will be useful to the world, they +register as a Perl developer at +http://www.perl.com/CPAN/modules/04pause.html so that they can then +upload their code to CPAN. CPAN is the Comprehensive Perl Archive +Network and can be accessed at http://www.perl.com/CPAN/, or searched +via http://cpan.perl.com/ and +http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl . This documentation is for people who want to download CPAN modules and install them on their own computer. =head2 PREAMBLE -You have a file ending in .tar.gz (or, less often, .zip). You know -there's a tasty module inside. There are four steps you must now -take: +You have a file ending in F<.tar.gz> (or, less often, F<.zip>). +You know there's a tasty module inside. You must now take four +steps: =over 5 @@ -44,8 +46,8 @@ say C, you can substitute C to install the modules into C. Then you can use the modules from your Perl programs with C or sometimes just C. +"/my/perl_directory/lib/site_perl"> or sometimes just C. =over 4 @@ -54,7 +56,8 @@ from your Perl programs with C You can use Andreas Koenig's CPAN module -( http://www.perl.com/CPAN/modules/by-module/CPAN ) +(which comes standard with Perl, or can itself be downloaded +from http://www.perl.com/CPAN/modules/by-module/CPAN) to automate the following steps, from DECOMPRESS through INSTALL. A. DECOMPRESS @@ -85,12 +88,17 @@ While still in that directory, type: make install -Make sure you have the appropriate permissions to install the module +Make sure you have appropriate permissions to install the module in your Perl 5 library directory. Often, you'll need to be root. +Perl maintains a record of all module installations. To look at +this list, simply type: + + perldoc perllocal + That's all you need to do on Unix systems with dynamic linking. -Most Unix systems have dynamic linking -- if yours doesn't, or if for -another reason you have a statically-linked perl, B the +Most Unix systems have dynamic linking--if yours doesn't, or if for +another reason you have a statically-linked perl, I the module requires compilation, you'll need to build a new Perl binary that includes the module. Again, you'll probably need to be root. @@ -100,7 +108,7 @@ B A. DECOMPRESS -You can use the shareware Winzip ( http://www.winzip.com ) to +You can use the shareware B program ( http://www.winzip.com ) to decompress and unpack modules. B. UNPACK @@ -112,7 +120,7 @@ If you used WinZip, this was already done for you. Does the module require compilation (i.e. does it have files that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on your own. You can try compiling it yourself if you have a C compiler. -If you're successful, consider uploading the resulting binary to the +If you're successful, consider uploading the resulting binary to CPAN for others to use. If it doesn't, go to INSTALL. D. INSTALL @@ -129,17 +137,16 @@ B or C<.zip>. Windows browsers sometimes +F<.tar.gz> or F<.zip>. Windows browsers sometimes download C<.tar.gz> files as C<_tar.tar>, because early versions of Windows prohibited more than one dot in a filename. -You can use the shareware WinZip ( http://www.winzip.com ) to +You can use the shareware B program ( http://www.winzip.com ) to decompress and unpack modules. Or, you can use InfoZip's C utility ( -http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress -C<.zip> files; type C in -your shell. +http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type +C in your shell. Or, if you have a working C and C, you can type @@ -151,7 +158,7 @@ UNPACK your module as well. B. UNPACK -All of the methods in DECOMPRESS will have done this for you. +The methods in DECOMPRESS will have done this for you. C. BUILD @@ -178,16 +185,26 @@ B A. DECOMPRESS -You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in -combination with I -(shareware), or the freeware MacGzip ( +In general, all Macintosh decompression utilities mentioned here +can be found in the Info-Mac Hyperarchive +( http://hyperarchive.lcs.mit.edu/HyperArchive.html ). +Specifically the "Compress & Translate" listing +( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ). + + +You can either use the shareware B program +( http://www.aladdinsys.com/expander/ ) +in combination with I +( http://www.aladdinsys.com/dropstuff/ ) +or the freeware B program ( http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ). + B. UNPACK If you're using DropStuff or Stuffit, you can just extract the tar -archive. Otherwise, you can use the freeware I ( -http://www.cirfid.unibo.it/~speranza ). +archive. Otherwise, you can use the freeware B or I ( +http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ). C. BUILD @@ -197,9 +214,9 @@ Does the module require compilation? Overview: You need MPW and a combination of new and old CodeWarrior compilers for MPW and libraries. Makefiles created for building under -MPW use the Metrowerks compilers. It's most likely possible to build +MPW use Metrowerks compilers. It's most likely possible to build without other compilers, but it has not been done successfully, to our -knowledge. Read the documentation in MacPerl: Power and Ease ( +knowledge. Read the documentation in I ( http://www.ptf.com/macperl/ ) on porting/building extensions, or find an existing precompiled binary, or hire someone to build it for you. @@ -212,6 +229,16 @@ mail to mac-perl-request@iis.ee.ethz.ch. D. INSTALL Make sure the newlines for the modules are in Mac format, not Unix format. +If they are not then you might have decompressed them incorrectly. Check +your decompression and unpacking utilities settings to make sure they are +translating text files properly. + +As a last resort, you can use the perl one-liner: + + perl -i.bak -pe 's/(?:\015)?\012/\015/g' + +on the source files. + Move the files manually into the correct folders. Move the files to their final destination: This will @@ -255,7 +282,7 @@ Go into the newly-created directory and type: make make test -You will need the packages mentioned in C +You will need the packages mentioned in F in the Perl distribution. D. INSTALL @@ -263,8 +290,8 @@ in the Perl distribution. While still in that directory, type: make install - -You will need the packages mentioned in Readme.dos in the Perl distribution. + +You will need the packages mentioned in F in the Perl distribution. =item * @@ -278,8 +305,8 @@ the instructions for Unix. B -When downloading from CPAN, save your file with a C<.tgz> -extension instead of C<.tar.gz>. All other periods in the +When downloading from CPAN, save your file with a F<.tgz> +extension instead of F<.tar.gz>. All other periods in the filename should be replaced with underscores. For example, C should be downloaded as C. @@ -295,8 +322,8 @@ or, for zipped modules, type unzip Your-Module.zip Executables for gzip, zip, and VMStar ( Alphas: -http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen: -http://www.openvms.digital.com/cd/000TOOLS/VAX/ ). +http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen: +http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ). gzip and tar are also available at ftp://ftp.digital.com/pub/VMS. @@ -341,7 +368,7 @@ Substitute C for C above if you're using MMK. B, -Introduce the .tar.gz file into an HFS as binary; don't translate from +Introduce the F<.tar.gz> file into an HFS as binary; don't translate from ASCII to EBCDIC. A. DECOMPRESS