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.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 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 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://www.aladdinsys.com/expander/ )
 183 in combination with B<DropStuff with Expander Enhancer>
 184 ( http://www.aladdinsys.com/dropstuff/ )
 185 or the freeware B<MacGzip> program (
 186 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 187
 188 B. UNPACK
 189
 190 If you're using untarzipme or StuffIt, the archive should be extracted
 191 now.  B<Or>, you can use the freeware B<suntar> or I<Tar> (
 192 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
 193
 194 C. BUILD
 195
 196 Check the contents of the distribution.
 197 Read the module's documentation, looking for
 198 reasons why you might have trouble using it with MacPerl.  Look for
 199 F<.xs> and F<.c> files, which normally denote that the distribution
 200 must be compiled, and you cannot install it "out of the box."
 201 (See L<"PORTABILITY">.)
 202
 203 D. INSTALL
 204
 205 If you are using cpan-mac, just drop the folder on the
 206 B<installme> droplet, and use the module.
 207
 208 B<Or>, if you aren't using cpan-mac, do some manual labor.
 209
 210 Make sure the newlines for the modules are in Mac format, not Unix format.
 211 If they are not then you might have decompressed them incorrectly.  Check
 212 your decompression and unpacking utilities settings to make sure they are
 213 translating text files properly.
 214
 215 As a last resort, you can use the perl one-liner:
 216
 217     perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
 218
 219 on the source files.
 220
 221 Then move the files (probably just the F<.pm> files, though there
 222 may be some additional ones, too; check the module documentation)
 223 to their final destination: This will
 224 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 225 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 226 the default C<@INC> in the Preferences menu item in the
 227 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 228 automagically).  Create whatever directory structures are required
 229 (i.e., for C<Some::Module>, create
 230 C<$ENV{MACPERL}site_lib:Some:> and put
 231 C<Module.pm> in that directory).
 232
 233 Then run the following script (or something like it):
 234
 235      #!perl -w
 236      use AutoSplit;
 237      my $dir = "${MACPERL}site_perl";
 238      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 239
 240 =item *
 241
 242 B<If you're on the DJGPP port of DOS,>
 243
 244    A. DECOMPRESS
 245
 246 djtarx ( ftp://ftp.delorie.com/pub/djgpp/current/v2/ )
 247 will both uncompress and unpack.
 248
 249    B. UNPACK
 250
 251 See above.
 252
 253    C. BUILD
 254
 255 Go into the newly-created directory and type:
 256
 257       perl Makefile.PL
 258       make test
 259
 260 You will need the packages mentioned in F<README.dos>
 261 in the Perl distribution.
 262
 263    D. INSTALL
 264
 265 While still in that directory, type:
 266
 267      make install
 268
 269 You will need the packages mentioned in F<README.dos> in the Perl distribution.
 270
 271 =item *
 272
 273 B<If you're on OS/2,>
 274
 275 Get the EMX development suite and gzip/tar, from either Hobbes (
 276 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 277 the instructions for Unix.
 278
 279 =item *
 280
 281 B<If you're on VMS,>
 282
 283 When downloading from CPAN, save your file with a C<.tgz>
 284 extension instead of C<.tar.gz>.  All other periods in the
 285 filename should be replaced with underscores.  For example,
 286 C<Your-Module-1.33.tar.gz> should be downloaded as
 287 C<Your-Module-1_33.tgz>.
 288
 289 A. DECOMPRESS
 290
 291 Type
 292
 293     gzip -d Your-Module.tgz
 294
 295 or, for zipped modules, type
 296
 297     unzip Your-Module.zip
 298
 299 Executables for gzip, zip, and VMStar:
 300
 301     http://www.hp.com/go/openvms/freeware/
 302
 303 and their source code:
 304
 305     http://www.fsf.org/order/ftp.html
 306
 307 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 308 package.  The former is a simple compression tool; the latter permits
 309 creation of multi-file archives.
 310
 311 B. UNPACK
 312
 313 If you're using VMStar:
 314
 315      VMStar xf Your-Module.tar
 316
 317 Or, if you're fond of VMS command syntax:
 318
 319      tar/extract/verbose Your_Module.tar
 320
 321 C. BUILD
 322
 323 Make sure you have MMS (from Digital) or the freeware MMK ( available
 324 from MadGoat at http://www.madgoat.com ).  Then type this to create
 325 the DESCRIP.MMS for the module:
 326
 327     perl Makefile.PL
 328
 329 Now you're ready to build:
 330
 331     mms test
 332
 333 Substitute C<mmk> for C<mms> above if you're using MMK.
 334
 335 D. INSTALL
 336
 337 Type
 338
 339     mms install
 340
 341 Substitute C<mmk> for C<mms> above if you're using MMK.
 342
 343 =item *
 344
 345 B<If you're on MVS>,
 346
 347 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 348 ASCII to EBCDIC.
 349
 350 A. DECOMPRESS
 351
 352 Decompress the file with C<gzip -d yourmodule.tar.gz>
 353
 354 You can get gzip from
 355 http://www.s390.ibm.com/products/oe/bpxqp1.html
 356
 357 B. UNPACK
 358
 359 Unpack the result with
 360
 361      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 362
 363 The BUILD and INSTALL steps are identical to those for Unix.  Some
 364 modules generate Makefiles that work better with GNU make, which is
 365 available from http://www.mks.com/s390/gnu/
 366
 367 =back
 368
 369 =head1 PORTABILITY
 370
 371 Note that not all modules will work with on all platforms.
 372 See L<perlport> for more information on portability issues.
 373 Read the documentation to see if the module will work on your
 374 system.  There are basically three categories
 375 of modules that will not work "out of the box" with all
 376 platforms (with some possibility of overlap):
 377
 378 =over 4
 379
 380 =item *
 381
 382 B<Those that should, but don't.>  These need to be fixed; consider
 383 contacting the author and possibly writing a patch.
 384
 385 =item *
 386
 387 B<Those that need to be compiled, where the target platform
 388 doesn't have compilers readily available.>  (These modules contain
 389 F<.xs> or F<.c> files, usually.)  You might be able to find
 390 existing binaries on the CPAN or elsewhere, or you might
 391 want to try getting compilers and building it yourself, and then
 392 release the binary for other poor souls to use.
 393
 394 =item *
 395
 396 B<Those that are targeted at a specific platform.>
 397 (Such as the Win32:: modules.)  If the module is targeted
 398 specifically at a platform other than yours, you're out
 399 of luck, most likely.
 400
 401 =back
 402
 403
 404
 405 Check the CPAN Testers if a module should work with your platform
 406 but it doesn't behave as you'd expect, or you aren't sure whether or
 407 not a module will work under your platform.  If the module you want
 408 isn't listed there, you can test it yourself and let CPAN Testers know,
 409 you can join CPAN Testers, or you can request it be tested.
 410
 411     http://testers.cpan.org/
 412
 413
 414 =head1 HEY
 415
 416 If you have any suggested changes for this page, let me know.  Please
 417 don't send me mail asking for help on how to install your modules.
 418 There are too many modules, and too few Orwants, for me to be able to
 419 answer or even acknowledge all your questions.  Contact the module
 420 author instead, or post to comp.lang.perl.modules, or ask someone
 421 familiar with Perl on your operating system.
 422
 423 =head1 AUTHOR
 424
 425 Jon Orwant
 426
 427 orwant@medita.mit.edu
 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, 2002, 2003 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