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