X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmodinstall.pod;h=c89b381cd99704b9fd14b7ae2f4142e976cf1183;hb=638ae6a920b7c2e92acd61b1d1e320b675c647c7;hp=ea287256203a1ae6394185d5dcf7bd0997049292;hpb=a93751fa40b15f424f91bba70d1533c6b4024e42;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod index ea28725..c89b381 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.cpan.org/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.cpan.org/ , and searched at http://search.cpan.org/ . 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 @@ -36,28 +45,30 @@ steps: =back Here's how to perform each step for each operating system. This is -I a substitute for reading the README and INSTALL files that + 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) +( http://www.cpan.org/modules/by-module/CPAN ) to automate the following steps, from DECOMPRESS through INSTALL. A. DECOMPRESS @@ -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,11 +138,12 @@ 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 @@ -132,65 +154,16 @@ of the directories you see when you type =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. @@ -290,7 +263,7 @@ in the Perl distribution. While still in that directory, type: - make install + make install You will need the packages mentioned in F in the Perl distribution. @@ -306,8 +279,8 @@ 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. @@ -322,12 +295,14 @@ 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/ ). +Executables for gzip, zip, and VMStar: + + http://www.openvms.digital.com/freeware/ + http://www.crinoid.com/utils/ -gzip and tar -are also available at ftp://ftp.digital.com/pub/VMS. +and their source code: + + http://www.fsf.org/order/ftp.html Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip package. The former is a simple compression tool; the latter permits @@ -345,9 +320,9 @@ Or, if you're fond of VMS command syntax: 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 @@ -375,10 +350,10 @@ ASCII to EBCDIC. A. DECOMPRESS - Decompress the file with C +Decompress the file with C - You can get gzip from - http://www.s390.ibm.com/products/oe/bpxqp1.html. +You can get gzip from +http://www.s390.ibm.com/products/oe/bpxqp1.html B. UNPACK @@ -392,7 +367,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. @@ -455,19 +429,17 @@ 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, 2002 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 +456,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. +