1=head1 NAME 2 3perlmodinstall - Installing CPAN Modules 4 5=head1 DESCRIPTION 6 7You can think of a module as the fundamental unit of reusable Perl 8code; see L<perlmod> for details. Whenever anyone creates a chunk of 9Perl code that they think will be useful to the world, they register 10as a Perl developer at L<https://www.cpan.org/modules/04pause.html> 11so that they can then upload their code to the CPAN. The CPAN is the 12Comprehensive Perl Archive Network and can be accessed at 13L<https://www.cpan.org/> , and searched at L<https://metacpan.org/> . 14 15This documentation is for people who want to download CPAN modules 16and install them on their own computer. 17 18=head2 PREAMBLE 19 20First, are you sure that the module isn't already on your system? Try 21C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for 22instance, C<perl -MCGI::Carp -e 1>.) 23 24If you don't see an error message, you have the module. (If you do 25see an error message, it's still possible you have the module, but 26that it's not in your path, which you can display with C<perl -e 27"print qq(@INC)">.) For the remainder of this document, we'll assume 28that you really honestly truly lack an installed module, but have 29found it on the CPAN. 30 31So now you have a file ending in .tar.gz (or, less often, .zip). You 32know there's a tasty module inside. There are four steps you must now 33take: 34 35=over 5 36 37=item B<DECOMPRESS> the file 38 39=item B<UNPACK> the file into a directory 40 41=item B<BUILD> the module (sometimes unnecessary) 42 43=item B<INSTALL> the module. 44 45=back 46 47Here's how to perform each step for each operating system. This is 48<not> a substitute for reading the README and INSTALL files that 49might have come with your module! 50 51Also note that these instructions are tailored for installing the 52module into your system's repository of Perl modules, but you can 53install modules into any directory you wish. For instance, where I 54say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL 55PREFIX=/my/perl_directory> to install the modules into 56F</my/perl_directory>. Then you can use the modules from your Perl 57programs with C<use lib "/my/perl_directory/lib/site_perl";> or 58sometimes just C<use "/my/perl_directory";>. If you're on a system 59that requires superuser/root access to install modules into the 60directories you see when you type C<perl -e "print qq(@INC)">, you'll 61want to install them into a local directory (such as your home 62directory) and use this approach. 63 64=over 4 65 66=item * 67 68B<If you're on a Unix or Unix-like system,> 69 70You can use Andreas Koenig's CPAN module 71( L<https://metacpan.org/release/CPAN> ) 72to automate the following steps, from DECOMPRESS through INSTALL. 73 74A. DECOMPRESS 75 76Decompress the file with C<gzip -d yourmodule.tar.gz> 77 78You can get gzip from L<ftp://prep.ai.mit.edu/pub/gnu/> 79 80Or, you can combine this step with the next to save disk space: 81 82 gzip -dc yourmodule.tar.gz | tar -xf - 83 84B. UNPACK 85 86Unpack the result with C<tar -xf yourmodule.tar> 87 88C. BUILD 89 90Go into the newly-created directory and type: 91 92 perl Makefile.PL 93 make test 94 95or 96 97 perl Makefile.PL PREFIX=/my/perl_directory 98 99to install it locally. (Remember that if you do this, you'll have to 100put C<use lib "/my/perl_directory";> near the top of the program that 101is to use this module. 102 103D. INSTALL 104 105While still in that directory, type: 106 107 make install 108 109Make sure you have the appropriate permissions to install the module 110in your Perl 5 library directory. Often, you'll need to be root. 111 112That's all you need to do on Unix systems with dynamic linking. 113Most Unix systems have dynamic linking. If yours doesn't, or if for 114another reason you have a statically-linked perl, B<and> the 115module requires compilation, you'll need to build a new Perl binary 116that includes the module. Again, you'll probably need to be root. 117 118=item * 119 120B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),> 121 122First, type C<ppm> from a shell and see whether ActiveState's PPM 123repository has your module. If so, you can install it with C<ppm> and 124you won't have to bother with any of the other steps here. You might 125be able to use the CPAN instructions from the "Unix or Linux" section 126above as well; give it a try. Otherwise, you'll have to follow the 127steps below. 128 129 A. DECOMPRESS 130 131You can use the 132open source 7-zip ( L<https://www.7-zip.org/> ) 133or the shareware Winzip ( L<https://www.winzip.com> ) to 134decompress and unpack modules. 135 136 B. UNPACK 137 138If you used WinZip, this was already done for you. 139 140 C. BUILD 141 142You'll need the C<nmake> utility, available at 143L<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe> 144or dmake, available on CPAN. 145L<https://metacpan.org/release/dmake> 146 147Does the module require compilation (i.e. does it have files that end 148in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now 149officially tough for you, because you have to compile the module 150yourself (no easy feat on Windows). You'll need a compiler such as 151Visual C++. Alternatively, you can download a pre-built PPM package 152from ActiveState. 153L<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/> 154 155Go into the newly-created directory and type: 156 157 perl Makefile.PL 158 nmake test 159 160 161 D. INSTALL 162 163While still in that directory, type: 164 165 nmake install 166 167=item * 168 169B<If you're on the DJGPP port of DOS,> 170 171 A. DECOMPRESS 172 173djtarx ( L<ftp://ftp.delorie.com/pub/djgpp/current/v2/> ) 174will both uncompress and unpack. 175 176 B. UNPACK 177 178See above. 179 180 C. BUILD 181 182Go into the newly-created directory and type: 183 184 perl Makefile.PL 185 make test 186 187You will need the packages mentioned in F<README.dos> 188in the Perl distribution. 189 190 D. INSTALL 191 192While still in that directory, type: 193 194 make install 195 196You will need the packages mentioned in F<README.dos> in the Perl distribution. 197 198=item * 199 200B<If you're on OS/2,> 201 202Get the EMX development suite and gzip/tar from Hobbes ( 203L<http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d> ), and then follow 204the instructions for Unix. 205 206=item * 207 208B<If you're on VMS,> 209 210When downloading from CPAN, save your file with a C<.tgz> 211extension instead of C<.tar.gz>. All other periods in the 212filename should be replaced with underscores. For example, 213C<Your-Module-1.33.tar.gz> should be downloaded as 214C<Your-Module-1_33.tgz>. 215 216A. DECOMPRESS 217 218Type 219 220 gzip -d Your-Module.tgz 221 222or, for zipped modules, type 223 224 unzip Your-Module.zip 225 226Executables for gzip, zip, and VMStar: 227 228 http://www.hp.com/go/openvms/freeware/ 229 230and their source code: 231 232 http://www.fsf.org/order/ftp.html 233 234Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip 235package. The former is a simple compression tool; the latter permits 236creation of multi-file archives. 237 238B. UNPACK 239 240If you're using VMStar: 241 242 VMStar xf Your-Module.tar 243 244Or, if you're fond of VMS command syntax: 245 246 tar/extract/verbose Your_Module.tar 247 248C. BUILD 249 250Make sure you have MMS (from Digital) or the freeware MMK ( available 251from MadGoat at L<http://www.madgoat.com> ). Then type this to create 252the DESCRIP.MMS for the module: 253 254 perl Makefile.PL 255 256Now you're ready to build: 257 258 mms test 259 260Substitute C<mmk> for C<mms> above if you're using MMK. 261 262D. INSTALL 263 264Type 265 266 mms install 267 268Substitute C<mmk> for C<mms> above if you're using MMK. 269 270=item * 271 272B<If you're on MVS>, 273 274Introduce the F<.tar.gz> file into an HFS as binary; don't translate from 275ASCII to EBCDIC. 276 277A. DECOMPRESS 278 279Decompress the file with C<gzip -d yourmodule.tar.gz> 280 281You can get gzip from 282L<http://www.s390.ibm.com/products/oe/bpxqp1.html> 283 284B. UNPACK 285 286Unpack the result with 287 288 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar 289 290The BUILD and INSTALL steps are identical to those for Unix. Some 291modules generate Makefiles that work better with GNU make, which is 292available from L<http://www.mks.com/s390/gnu/> 293 294=back 295 296=head1 PORTABILITY 297 298Note that not all modules will work with on all platforms. 299See L<perlport> for more information on portability issues. 300Read the documentation to see if the module will work on your 301system. There are basically three categories 302of modules that will not work "out of the box" with all 303platforms (with some possibility of overlap): 304 305=over 4 306 307=item * 308 309B<Those that should, but don't.> These need to be fixed; consider 310contacting the author and possibly writing a patch. 311 312=item * 313 314B<Those that need to be compiled, where the target platform 315doesn't have compilers readily available.> (These modules contain 316F<.xs> or F<.c> files, usually.) You might be able to find 317existing binaries on the CPAN or elsewhere, or you might 318want to try getting compilers and building it yourself, and then 319release the binary for other poor souls to use. 320 321=item * 322 323B<Those that are targeted at a specific platform.> 324(Such as the Win32:: modules.) If the module is targeted 325specifically at a platform other than yours, you're out 326of luck, most likely. 327 328=back 329 330 331 332Check the CPAN Testers if a module should work with your platform 333but it doesn't behave as you'd expect, or you aren't sure whether or 334not a module will work under your platform. If the module you want 335isn't listed there, you can test it yourself and let CPAN Testers know, 336you can join CPAN Testers, or you can request it be tested. 337 338 https://cpantesters.org/ 339 340 341=head1 HEY 342 343If you have any suggested changes for this page, let me know. Please 344don't send me mail asking for help on how to install your modules. 345There are too many modules, and too few Orwants, for me to be able to 346answer or even acknowledge all your questions. Contact the module 347author instead, ask someone familiar with Perl on your operating 348system, or if all else fails, file a ticket at L<https://rt.cpan.org/>. 349 350=head1 AUTHOR 351 352Jon Orwant 353 354orwant@medita.mit.edu 355 356with invaluable help from Chris Nandor, and valuable help from Brandon 357Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko 358Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas 359J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy, 360Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich. 361 362First version July 22, 1998; last revised November 21, 2001. 363 364=head1 COPYRIGHT 365 366Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved. 367 368This document may be distributed under the same terms as Perl itself. 369