From: Jarkko Hietaniemi Date: Thu, 22 Nov 2001 03:08:00 +0000 (+0000) Subject: perlmodinstall 2.01 from Jon Orwant. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b3539c74f8792e5b6cd751bc81b0916c44ee6648;p=p5sagit%2Fp5-mst-13.2.git perlmodinstall 2.01 from Jon Orwant. p4raw-id: //depot/perl@13184 --- diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod index ea28725..ccc6cd6 100644 --- a/pod/perlmodinstall.pod +++ b/pod/perlmodinstall.pod @@ -5,23 +5,32 @@ 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.cpan.org/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.cpan.org/, or searched -via http://cpan.perl.com/ and -http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl . +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/. 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 F<.tar.gz> (or, less often, F<.zip>). -You know there's a tasty module inside. You must now take four -steps: +First, are you sure that the module isn't already on your system? Try +C. (Replace "Foo" with the name of the module; for +instance, C. + +If you don't see an error message, you have the module. (If you do +see an error message, it's still possible you have the module, but +that it's not in your path, which you can display with C.) For the remainder of this document, we'll assume +that you really honestly truly lack an installed module, but have +found it on the CPAN. + +So now 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: =over 5 @@ -40,31 +49,33 @@ I a substitute for reading the README and INSTALL files that might have come with your module! Also note that these instructions are tailored for installing the -module into your system's repository of Perl modules. But you can +module into your system's repository of Perl modules -- but you can install modules into any directory you wish. For instance, where I -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. +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. If you're on a system +that requires superuser/root access to install modules into the +directories you see when you type C, you'll +want to install them into a local directory (such as your home +directory) and use this approach. =over 4 =item * -B +B -You can use Andreas Koenig's CPAN module -(which comes standard with Perl, or can itself be downloaded -from http://www.cpan.org/modules/by-module/CPAN) +You can use Andreas Koenig's CPAN module +( http://www.perl.com/CPAN/modules/by-module/CPAN ) to automate the following steps, from DECOMPRESS through INSTALL. -A. DECOMPRESS +A. DECOMPRESS Decompress the file with C -You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. +You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. Or, you can combine this step with the next to save disk space: @@ -82,33 +93,43 @@ Go into the newly-created directory and type: make make test +or + + perl Makefile.PL PREFIX=/my/perl_directory + +to install it locally. (Remember that if you do this, you'll have to +put C near the top of the program that +is to use this module. + D. INSTALL While still in that directory, type: make install -Make sure you have appropriate permissions to install the module +Make sure you have the 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, I the +Most Unix systems have dynamic linking -- if yours doesn't, or if for +another reason you have a statically-linked perl, B 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. =item * -B +B + +First, type C from a shell and see whether ActiveState's PPM +repository has your module. If so, you can install it with C and +you won't have to bother with any of the other steps here. You might +be able to use the CPAN instructions from the "Unix or Linux" section +above as well; give it a try. Otherwise, you'll have to follow the +steps below. A. DECOMPRESS -You can use the shareware B program ( http://www.winzip.com ) to +You can use the shareware Winzip ( http://www.winzip.com ) to decompress and unpack modules. B. UNPACK @@ -117,80 +138,32 @@ If you used WinZip, this was already done for you. C. BUILD -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 -CPAN for others to use. If it doesn't, go to INSTALL. +Does the module require compilation (i.e. does it have files that end +in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it doesn't, go to INSTALL. +If it does, life is now officially tough for you, because you have to +compile the module yourself -- no easy feat on Windows. You'll need +the C utility, available at +ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe. D. INSTALL Copy the module into your Perl's I directory. That'll be one -of the directories you see when you type +of the directories you see when you type perl -e 'print "@INC"' =item * -B - - A. DECOMPRESS - -When you download the module, make sure it ends in either -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 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/ ) to uncompress C<.zip> files; type -C in your shell. - -Or, if you have a working C and C, you can -type - - gzip -cd yourmodule.tar.gz | tar xvf - - -in the shell to decompress C. This will -UNPACK your module as well. - - B. UNPACK - -The methods in DECOMPRESS will have done this for you. - - C. BUILD - -Go into the newly-created directory and type: - - perl Makefile.PL - dmake - dmake test - -Depending on your perl configuration, C might not be -available. You might have to substitute whatever C says. (Usually, that will be C or -C.) - - D. INSTALL - -While still in that directory, type: - - dmake install - -=item * - B + A. DECOMPRESS -First thing you should do is make sure you have the latest B -distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has -utilities for doing all of the steps. Read the cpan-mac directions -carefully and install it. If you choose not to use cpan-mac -for some reason, there are alternatives listed here. +First, make sure you have the latest B distribution ( +http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for +doing all of the steps. Read the cpan-mac directions carefully and +install it. If you choose not to use cpan-mac for some reason, there +are alternatives listed here. After installing cpan-mac, drop the module archive on the B droplet, which will decompress and unpack for you. @@ -269,7 +242,7 @@ B A. DECOMPRESS djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) -will both uncompress and unpack. +will both uncompress and unpack. B. UNPACK @@ -283,16 +256,16 @@ Go into the newly-created directory and type: make make test -You will need the packages mentioned in F +You will need the packages mentioned in C in the Perl distribution. D. INSTALL While still in that directory, type: - make install - -You will need the packages mentioned in F in the Perl distribution. + make install + +You will need the packages mentioned in Readme.dos in the Perl distribution. =item * @@ -306,25 +279,25 @@ the instructions for Unix. B -When downloading from CPAN, save your file with a F<.tgz> -extension instead of F<.tar.gz>. All other periods in the +When downloading from CPAN, save your file with a C<.tgz> +extension instead of C<.tar.gz>. All other periods in the filename should be replaced with underscores. For example, C should be downloaded as C. A. DECOMPRESS -Type +Type gzip -d Your-Module.tgz -or, for zipped modules, type +or, for zipped modules, type unzip Your-Module.zip Executables for gzip, zip, and VMStar ( Alphas: -http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen: -http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ). +http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen: +http://www.openvms.digital.com/cd/000TOOLS/VAX/ ). gzip and tar are also available at ftp://ftp.digital.com/pub/VMS. @@ -343,11 +316,10 @@ Or, if you're fond of VMS command syntax: tar/extract/verbose Your_Module.tar -C. BUILD +C. BUILD -Make sure you have MMS (from Digital) or the freeware MMK ( available from -MadGoat at http://www.madgoat.com ). Then type this to create the -DESCRIP.MMS for the module: +Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at http://www.madgoat.com ). Then type this to create the +DESCRIP.MMS for the module: perl Makefile.PL @@ -360,7 +332,7 @@ Substitute C for C above if you're using MMK. D. INSTALL -Type +Type mms install @@ -370,19 +342,19 @@ Substitute C for C above if you're using MMK. B, -Introduce the F<.tar.gz> file into an HFS as binary; don't translate from +Introduce the .tar.gz file into an HFS as binary; don't translate from ASCII to EBCDIC. -A. DECOMPRESS +A. DECOMPRESS Decompress the file with C - You can get gzip from + You can get gzip from http://www.s390.ibm.com/products/oe/bpxqp1.html. B. UNPACK -Unpack the result with +Unpack the result with pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar @@ -392,7 +364,6 @@ available from http://www.mks.com/s390/gnu/index.htm. =back - =head1 PORTABILITY Note that not all modules will work with on all platforms. @@ -449,25 +420,23 @@ familiar with Perl on your operating system. =head1 AUTHOR -Jon Orwant +Jon Orwant orwant@tpj.com The Perl Journal, http://tpj.com -with invaluable help from Brandon Allbery, Charles Bailey, Graham -Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley, -Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan -Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan -Sugalski, Larry Virden, and Ilya Zakharevich. +with invaluable help from Chris Nandor, and valuable help from Brandon +Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko +Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas +J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy, +Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich. -First version July 22, 1998 - -Last Modified August 22, 2000 +First version July 22, 1998; last revised November 21, 2001. =head1 COPYRIGHT -Copyright (C) 1998, 2000 Jon Orwant. All Rights Reserved. +Copyright (C) 1998, 2001 Jon Orwant. All Rights Reserved. Permission is granted to make and distribute verbatim copies of this documentation provided the copyright notice and this permission notice are @@ -484,3 +453,4 @@ to this one. Permission is granted to copy and distribute translations of this documentation into another language, under the above conditions for modified versions. +