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
   9 of Perl code that they think will be useful to the world, they
  10 register as a Perl developer at
  11 http://www.perl.com/CPAN/modules/04pause.html so that they can then
  12 upload their code to CPAN.  CPAN is the Comprehensive Perl Archive
  13 Network and can be accessed at http://www.perl.com/CPAN/, or searched
  14 via http://cpan.perl.com/ and
  15 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
  16
  17 This documentation is for people who want to download CPAN modules
  18 and install them on their own computer.
  19
  20 =head2 PREAMBLE
  21
  22 You have a file ending in F<.tar.gz> (or, less often, F<.zip>).
  23 You know there's a tasty module inside.  You must now take four
  24 steps:
  25
  26 =over 5
  27
  28 =item B<DECOMPRESS> the file
  29
  30 =item B<UNPACK> the file into a directory
  31
  32 =item B<BUILD> the module (sometimes unnecessary)
  33
  34 =item B<INSTALL> the module.
  35
  36 =back
  37
  38 Here's how to perform each step for each operating system.  This is
  39 I<not> a substitute for reading the README and INSTALL files that
  40 might have come with your module!
  41
  42 Also note that these instructions are tailored for installing the
  43 module into your system's repository of Perl modules.  But you can
  44 install modules into any directory you wish.  For instance, where I
  45 say C<perl Makefile.PL>, you can substitute C<perl
  46 Makefile.PL PREFIX=/my/perl_directory> to install the modules
  47 into C</my/perl_directory>.  Then you can use the modules
  48 from your Perl programs with C<use lib
  49 "/my/perl_directory/lib/site_perl"> or sometimes just C<use
  50 "/my/perl_directory">.
  51
  52 =over 4
  53
  54 =item *
  55
  56 B<If you're on Unix,>
  57
  58 You can use Andreas Koenig's CPAN module
  59 (which comes standard with Perl, or can itself be downloaded
  60 from http://www.perl.com/CPAN/modules/by-module/CPAN)
  61 to automate the following steps, from DECOMPRESS through INSTALL.
  62
  63 A. DECOMPRESS
  64
  65 Decompress the file with C<gzip -d yourmodule.tar.gz>
  66
  67 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
  68
  69 Or, you can combine this step with the next to save disk space:
  70
  71      gzip -dc yourmodule.tar.gz | tar -xof -
  72
  73 B. UNPACK
  74
  75 Unpack the result with C<tar -xof yourmodule.tar>
  76
  77 C. BUILD
  78
  79 Go into the newly-created directory and type:
  80
  81       perl Makefile.PL
  82       make
  83       make test
  84
  85 D. INSTALL
  86
  87 While still in that directory, type:
  88
  89       make install
  90
  91 Make sure you have appropriate permissions to install the module
  92 in your Perl 5 library directory.  Often, you'll need to be root.
  93
  94 Perl maintains a record of all module installations.  To look at
  95 this list, simply type:
  96
  97       perldoc perllocal
  98
  99 That's all you need to do on Unix systems with dynamic linking.
 100 Most Unix systems have dynamic linking--if yours doesn't, or if for
 101 another reason you have a statically-linked perl, I<and> the
 102 module requires compilation, you'll need to build a new Perl binary
 103 that includes the module.  Again, you'll probably need to be root.
 104
 105 =item *
 106
 107 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
 108
 109    A. DECOMPRESS
 110
 111 You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
 112 decompress and unpack modules.
 113
 114    B. UNPACK
 115
 116 If you used WinZip, this was already done for you.
 117
 118    C. BUILD
 119
 120 Does the module require compilation (i.e. does it have files
 121 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
 122 your own.  You can try compiling it yourself if you have a C compiler.
 123 If you're successful, consider uploading the resulting binary to
 124 CPAN for others to use.  If it doesn't, go to INSTALL.
 125
 126    D. INSTALL
 127
 128 Copy the module into your Perl's I<lib> directory.  That'll be one
 129 of the directories you see when you type
 130
 131    perl -e 'print "@INC"'
 132
 133 =item *
 134
 135 B<If you're running Windows 95 or NT with the core Windows distribution of
 136 Perl,>
 137
 138    A. DECOMPRESS
 139
 140 When you download the module, make sure it ends in either
 141 F<.tar.gz> or F<.zip>.  Windows browsers sometimes
 142 download C<.tar.gz> files as C<_tar.tar>, because
 143 early versions of Windows prohibited more than one dot in a filename.
 144
 145 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
 146 decompress and unpack modules.
 147
 148 Or, you can use InfoZip's C<unzip> utility (
 149 http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
 150 C<unzip yourmodule.zip> in your shell.
 151
 152 Or, if you have a working C<tar> and C<gzip>, you can
 153 type
 154
 155    gzip -cd yourmodule.tar.gz | tar xvf -
 156
 157 in the shell to decompress C<yourmodule.tar.gz>.  This will
 158 UNPACK your module as well.
 159
 160    B. UNPACK
 161
 162 The methods in DECOMPRESS will have done this for you.
 163
 164    C. BUILD
 165
 166 Go into the newly-created directory and type:
 167
 168       perl Makefile.PL
 169       dmake
 170       dmake test
 171
 172 Depending on your perl configuration, C<dmake> might not be
 173 available.  You might have to substitute whatever C<perl
 174 -V:make> says. (Usually, that will be C<nmake> or
 175 C<make>.)
 176
 177    D. INSTALL
 178
 179 While still in that directory, type:
 180
 181       dmake install
 182
 183 =item *
 184
 185 B<If you're using a Macintosh,>
 186
 187 A. DECOMPRESS
 188
 189 First thing you should do is make sure you have the latest B<cpan-mac>
 190 distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has
 191 utilities for doing all of the steps.  Read the cpan-mac directions
 192 carefully and install it.  If you choose not to use cpan-mac
 193 for some reason, there are alternatives listed here.
 194
 195 After installing cpan-mac, drop the module archive on the
 196 B<untarzipme> droplet, which will decompress and unpack for you.
 197
 198 B<Or>, you can either use the shareware B<StuffIt Expander> program
 199 ( http://www.aladdinsys.com/expander/ )
 200 in combination with B<DropStuff with Expander Enhancer>
 201 ( http://www.aladdinsys.com/dropstuff/ )
 202 or the freeware B<MacGzip> program (
 203 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 204
 205 B. UNPACK
 206
 207 If you're using untarzipme or StuffIt, the archive should be extracted
 208 now.  B<Or>, you can use the freeware B<suntar> or I<Tar> (
 209 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
 210
 211 C. BUILD
 212
 213 Check the contents of the distribution.
 214 Read the module's documentation, looking for
 215 reasons why you might have trouble using it with MacPerl.  Look for
 216 F<.xs> and F<.c> files, which normally denote that the distribution
 217 must be compiled, and you cannot install it "out of the box."
 218 (See L<"PORTABILITY">.)
 219
 220 If a module does not work on MacPerl but should, or needs to be
 221 compiled, see if the module exists already as a port on the
 222 MacPerl Module Porters site (http://pudge.net/mmp/).
 223 For more information on doing XS with MacPerl yourself, see
 224 Arved Sandstrom's XS tutorial (http://macperl.com/depts/Tutorials/),
 225 and then consider uploading your binary to the CPAN and
 226 registering it on the MMP site.
 227
 228 D. INSTALL
 229
 230 If you are using cpan-mac, just drop the folder on the
 231 B<installme> droplet, and use the module.
 232
 233 B<Or>, if you aren't using cpan-mac, do some manual labor.
 234
 235 Make sure the newlines for the modules are in Mac format, not Unix format.
 236 If they are not then you might have decompressed them incorrectly.  Check
 237 your decompression and unpacking utilities settings to make sure they are
 238 translating text files properly.
 239
 240 As a last resort, you can use the perl one-liner:
 241
 242     perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
 243
 244 on the source files.
 245
 246 Then move the files (probably just the F<.pm> files, though there
 247 may be some additional ones, too; check the module documentation)
 248 to their final destination: This will
 249 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 250 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 251 the default C<@INC> in the Preferences menu item in the
 252 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 253 automagically).  Create whatever directory structures are required
 254 (i.e., for C<Some::Module>, create
 255 C<$ENV{MACPERL}site_lib:Some:> and put
 256 C<Module.pm> in that directory).
 257
 258 Then run the following script (or something like it):
 259
 260      #!perl -w
 261      use AutoSplit;
 262      my $dir = "${MACPERL}site_perl";
 263      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 264
 265 =item *
 266
 267 B<If you're on the DJGPP port of DOS,>
 268
 269    A. DECOMPRESS
 270
 271 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
 272 will both uncompress and unpack.
 273
 274    B. UNPACK
 275
 276 See above.
 277
 278    C. BUILD
 279
 280 Go into the newly-created directory and type:
 281
 282       perl Makefile.PL
 283       make
 284       make test
 285
 286 You will need the packages mentioned in F<README.dos>
 287 in the Perl distribution.
 288
 289    D. INSTALL
 290
 291 While still in that directory, type:
 292
 293      make install
 294
 295 You will need the packages mentioned in F<README.dos> in the Perl distribution.
 296
 297 =item *
 298
 299 B<If you're on OS/2,>
 300
 301 Get the EMX development suite and gzip/tar, from either Hobbes (
 302 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 303 the instructions for Unix.
 304
 305 =item *
 306
 307 B<If you're on VMS,>
 308
 309 When downloading from CPAN, save your file with a F<.tgz>
 310 extension instead of F<.tar.gz>.  All other periods in the
 311 filename should be replaced with underscores.  For example,
 312 C<Your-Module-1.33.tar.gz> should be downloaded as
 313 C<Your-Module-1_33.tgz>.
 314
 315 A. DECOMPRESS
 316
 317 Type
 318
 319     gzip -d Your-Module.tgz
 320
 321 or, for zipped modules, type
 322
 323     unzip Your-Module.zip
 324
 325 Executables for gzip, zip, and VMStar ( Alphas:
 326 http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
 327 http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
 328
 329 gzip and tar
 330 are also available at ftp://ftp.digital.com/pub/VMS.
 331
 332 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 333 package.  The former is a simple compression tool; the latter permits
 334 creation of multi-file archives.
 335
 336 B. UNPACK
 337
 338 If you're using VMStar:
 339
 340      VMStar xf Your-Module.tar
 341
 342 Or, if you're fond of VMS command syntax:
 343
 344      tar/extract/verbose Your_Module.tar
 345
 346 C. BUILD
 347
 348 Make sure you have MMS (from Digital) or the freeware MMK ( available from
 349 MadGoat at  http://www.madgoat.com ).  Then type this to create the
 350 DESCRIP.MMS for the module:
 351
 352     perl Makefile.PL
 353
 354 Now you're ready to build:
 355
 356     mms
 357     mms test
 358
 359 Substitute C<mmk> for C<mms> above if you're using MMK.
 360
 361 D. INSTALL
 362
 363 Type
 364
 365     mms install
 366
 367 Substitute C<mmk> for C<mms> above if you're using MMK.
 368
 369 =item *
 370
 371 B<If you're on MVS>,
 372
 373 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 374 ASCII to EBCDIC.
 375
 376 A. DECOMPRESS
 377
 378       Decompress the file with C<gzip -d yourmodule.tar.gz>
 379
 380       You can get gzip from
 381       http://www.s390.ibm.com/products/oe/bpxqp1.html.
 382
 383 B. UNPACK
 384
 385 Unpack the result with
 386
 387      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 388
 389 The BUILD and INSTALL steps are identical to those for Unix.  Some
 390 modules generate Makefiles that work better with GNU make, which is
 391 available from http://www.mks.com/s390/gnu/index.htm.
 392
 393 =back
 394
 395
 396 =head1 PORTABILITY
 397
 398 Note that not all modules will work with on all platforms.
 399 See L<perlport> for more information on portability issues.
 400 Read the documentation to see if the module will work on your
 401 system.  There are basically three categories
 402 of modules that will not work "out of the box" with all
 403 platforms (with some possibility of overlap):
 404
 405 =over 4
 406
 407 =item *
 408
 409 B<Those that should, but don't.>  These need to be fixed; consider
 410 contacting the author and possibly writing a patch.
 411
 412 =item *
 413
 414 B<Those that need to be compiled, where the target platform
 415 doesn't have compilers readily available.>  (These modules contain
 416 F<.xs> or F<.c> files, usually.)  You might be able to find
 417 existing binaries on the CPAN or elsewhere, or you might
 418 want to try getting compilers and building it yourself, and then
 419 release the binary for other poor souls to use.
 420
 421 =item *
 422
 423 B<Those that are targeted at a specific platform.>
 424 (Such as the Win32:: modules.)  If the module is targeted
 425 specifically at a platform other than yours, you're out
 426 of luck, most likely.
 427
 428 =back
 429
 430
 431
 432 Check the CPAN Testers if a module should work with your platform
 433 but it doesn't behave as you'd expect, or you aren't sure whether or
 434 not a module will work under your platform.  If the module you want
 435 isn't listed there, you can test it yourself and let CPAN Testers know,
 436 you can join CPAN Testers, or you can request it be tested.
 437
 438     http://testers.cpan.org/
 439
 440
 441 =head1 HEY
 442
 443 If you have any suggested changes for this page, let me know.  Please
 444 don't send me mail asking for help on how to install your modules.
 445 There are too many modules, and too few Orwants, for me to be able to
 446 answer or even acknowledge all your questions.  Contact the module
 447 author instead, or post to comp.lang.perl.modules, or ask someone
 448 familiar with Perl on your operating system.
 449
 450 =head1 AUTHOR
 451
 452 Jon Orwant
 453
 454 orwant@tpj.com
 455
 456 The Perl Journal, http://tpj.com
 457
 458 with invaluable help from Brandon Allbery, Charles Bailey, Graham
 459 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
 460 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
 461 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
 462 Sugalski, Larry Virden, and Ilya Zakharevich.
 463
 464 First version July 22, 1998
 465
 466 Last Modified August 22, 2000
 467
 468 =head1 COPYRIGHT
 469
 470 Copyright (C) 1998, 2000 Jon Orwant.  All Rights Reserved.
 471
 472 Permission is granted to make and distribute verbatim copies of this
 473 documentation provided the copyright notice and this permission notice are
 474 preserved on all copies.
 475
 476 Permission is granted to copy and distribute modified versions of this
 477 documentation under the conditions for verbatim copying, provided also
 478 that they are marked clearly as modified versions, that the authors'
 479 names and title are unchanged (though subtitles and additional
 480 authors' names may be added), and that the entire resulting derived
 481 work is distributed under the terms of a permission notice identical
 482 to this one.
 483
 484 Permission is granted to copy and distribute translations of this
 485 documentation into another language, under the above conditions for
 486 modified versions.