pod/perlmodinstall.pod

   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.perl.com/CPAN/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.perl.com/CPAN/.
  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 I<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 C</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 Linux system,>
  69
  70 You can use Andreas Koenig's CPAN module
  71 ( http://www.perl.com/CPAN/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
  94       make test
  95
  96 or
  97
  98       perl Makefile.PL PREFIX=/my/perl_directory
  99
 100 to install it locally.  (Remember that if you do this, you'll have to
 101 put C<use lib "/my/perl_directory";> near the top of the program that
 102 is to use this module.
 103
 104 D. INSTALL
 105
 106 While still in that directory, type:
 107
 108       make install
 109
 110 Make sure you have the appropriate permissions to install the module
 111 in your Perl 5 library directory.  Often, you'll need to be root.
 112
 113 That's all you need to do on Unix systems with dynamic linking.
 114 Most Unix systems have dynamic linking -- if yours doesn't, or if for
 115 another reason you have a statically-linked perl, B<and> the
 116 module requires compilation, you'll need to build a new Perl binary
 117 that includes the module.  Again, you'll probably need to be root.
 118
 119 =item *
 120
 121 B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
 122
 123 First, type C<ppm> from a shell and see whether ActiveState's PPM
 124 repository has your module.  If so, you can install it with C<ppm> and
 125 you won't have to bother with any of the other steps here.  You might
 126 be able to use the CPAN instructions from the "Unix or Linux" section
 127 above as well; give it a try.  Otherwise, you'll have to follow the
 128 steps below.
 129
 130    A. DECOMPRESS
 131
 132 You can use the shareware Winzip ( http://www.winzip.com ) to
 133 decompress and unpack modules.
 134
 135    B. UNPACK
 136
 137 If you used WinZip, this was already done for you.
 138
 139    C. BUILD
 140
 141 Does the module require compilation (i.e. does it have files that end
 142 in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it doesn't, go to INSTALL.
 143 If it does, life is now officially tough for you, because you have to
 144 compile the module yourself -- no easy feat on Windows.  You'll need
 145 the C<nmake> utility, available at
 146 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.
 147
 148    D. INSTALL
 149
 150 Copy the module into your Perl's I<lib> directory.  That'll be one
 151 of the directories you see when you type
 152
 153    perl -e 'print "@INC"'
 154
 155 =item *
 156
 157 B<If you're using a Macintosh,>
 158
 159
 160 A. DECOMPRESS
 161
 162 First, make sure you have the latest B<cpan-mac> distribution (
 163 http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
 164 doing all of the steps.  Read the cpan-mac directions carefully and
 165 install it.  If you choose not to use cpan-mac for some reason, there
 166 are alternatives listed here.
 167
 168 After installing cpan-mac, drop the module archive on the
 169 B<untarzipme> droplet, which will decompress and unpack for you.
 170
 171 B<Or>, you can either use the shareware B<StuffIt Expander> program
 172 ( http://www.aladdinsys.com/expander/ )
 173 in combination with B<DropStuff with Expander Enhancer>
 174 ( http://www.aladdinsys.com/dropstuff/ )
 175 or the freeware B<MacGzip> program (
 176 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 177
 178 B. UNPACK
 179
 180 If you're using untarzipme or StuffIt, the archive should be extracted
 181 now.  B<Or>, you can use the freeware B<suntar> or I<Tar> (
 182 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
 183
 184 C. BUILD
 185
 186 Check the contents of the distribution.
 187 Read the module's documentation, looking for
 188 reasons why you might have trouble using it with MacPerl.  Look for
 189 F<.xs> and F<.c> files, which normally denote that the distribution
 190 must be compiled, and you cannot install it "out of the box."
 191 (See L<"PORTABILITY">.)
 192
 193 If a module does not work on MacPerl but should, or needs to be
 194 compiled, see if the module exists already as a port on the
 195 MacPerl Module Porters site (http://pudge.net/mmp/).
 196 For more information on doing XS with MacPerl yourself, see
 197 Arved Sandstrom's XS tutorial (http://macperl.com/depts/Tutorials/),
 198 and then consider uploading your binary to the CPAN and
 199 registering it on the MMP site.
 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.simtel.net/pub/simtelnet/gnu/djgpp/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
 257       make test
 258
 259 You will need the packages mentioned in C<Readme.dos>
 260 in the Perl distribution.
 261
 262    D. INSTALL
 263
 264 While still in that directory, type:
 265
 266      make install
 267
 268 You will need the packages mentioned in Readme.dos in the Perl distribution.
 269
 270 =item *
 271
 272 B<If you're on OS/2,>
 273
 274 Get the EMX development suite and gzip/tar, from either Hobbes (
 275 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 276 the instructions for Unix.
 277
 278 =item *
 279
 280 B<If you're on VMS,>
 281
 282 When downloading from CPAN, save your file with a C<.tgz>
 283 extension instead of C<.tar.gz>.  All other periods in the
 284 filename should be replaced with underscores.  For example,
 285 C<Your-Module-1.33.tar.gz> should be downloaded as
 286 C<Your-Module-1_33.tgz>.
 287
 288 A. DECOMPRESS
 289
 290 Type
 291
 292     gzip -d Your-Module.tgz
 293
 294 or, for zipped modules, type
 295
 296     unzip Your-Module.zip
 297
 298 Executables for gzip, zip, and VMStar ( Alphas:
 299 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
 300 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
 301
 302 gzip and tar
 303 are also available at ftp://ftp.digital.com/pub/VMS.
 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 from MadGoat at  http://www.madgoat.com ).  Then type this to create the
 322 DESCRIP.MMS for the module:
 323
 324     perl Makefile.PL
 325
 326 Now you're ready to build:
 327
 328     mms
 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 .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/index.htm.
 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, or post to comp.lang.perl.modules, or ask someone
 419 familiar with Perl on your operating system.
 420
 421 =head1 AUTHOR
 422
 423 Jon Orwant
 424
 425 orwant@tpj.com
 426
 427 The Perl Journal, http://tpj.com
 428
 429 with invaluable help from Chris Nandor, and valuable help from Brandon
 430 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
 431 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
 432 J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
 433 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
 434
 435 First version July 22, 1998; last revised November 21, 2001.
 436
 437 =head1 COPYRIGHT
 438
 439 Copyright (C) 1998, 2001 Jon Orwant.  All Rights Reserved.
 440
 441 Permission is granted to make and distribute verbatim copies of this
 442 documentation provided the copyright notice and this permission notice are
 443 preserved on all copies.
 444
 445 Permission is granted to copy and distribute modified versions of this
 446 documentation under the conditions for verbatim copying, provided also
 447 that they are marked clearly as modified versions, that the authors'
 448 names and title are unchanged (though subtitles and additional
 449 authors' names may be added), and that the entire resulting derived
 450 work is distributed under the terms of a permission notice identical
 451 to this one.
 452
 453 Permission is granted to copy and distribute translations of this
 454 documentation into another language, under the above conditions for
 455 modified versions.
 456