[Summary view] [Print] [Text view]

   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  If a module does not work on MacPerl but should, or needs to be
 204  compiled, see if the module exists already as a port on the
 205  MacPerl Module Porters site ( http://pudge.net/mmp/ ).
 206  For more information on doing XS with MacPerl yourself, see
 207  Arved Sandstrom's XS tutorial ( http://macperl.com/depts/Tutorials/ ),
 208  and then consider uploading your binary to the CPAN and
 209  registering it on the MMP site.
 210  
 211  D. INSTALL
 212  
 213  If you are using cpan-mac, just drop the folder on the
 214  B<installme> droplet, and use the module.
 215  
 216  B<Or>, if you aren't using cpan-mac, do some manual labor.
 217  
 218  Make sure the newlines for the modules are in Mac format, not Unix format.
 219  If they are not then you might have decompressed them incorrectly.  Check
 220  your decompression and unpacking utilities settings to make sure they are
 221  translating text files properly.
 222  
 223  As a last resort, you can use the perl one-liner:
 224  
 225      perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
 226  
 227  on the source files.
 228  
 229  Then move the files (probably just the F<.pm> files, though there
 230  may be some additional ones, too; check the module documentation)
 231  to their final destination: This will
 232  most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 233  C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 234  the default C<@INC> in the Preferences menu item in the
 235  MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 236  automagically).  Create whatever directory structures are required
 237  (i.e., for C<Some::Module>, create
 238  C<$ENV{MACPERL}site_lib:Some:> and put
 239  C<Module.pm> in that directory).
 240  
 241  Then run the following script (or something like it):
 242  
 243       #!perl -w
 244       use AutoSplit;
 245       my $dir = "$MACPERL}site_perl";
 246       autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 247  
 248  =item *
 249  
 250  B<If you're on the DJGPP port of DOS,>
 251  
 252     A. DECOMPRESS
 253  
 254  djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
 255  will both uncompress and unpack.
 256  
 257     B. UNPACK
 258  
 259  See above.
 260  
 261     C. BUILD
 262  
 263  Go into the newly-created directory and type:
 264  
 265        perl Makefile.PL
 266        make test
 267  
 268  You will need the packages mentioned in F<README.dos>
 269  in the Perl distribution.
 270  
 271     D. INSTALL
 272  
 273  While still in that directory, type:
 274  
 275       make install    
 276  
 277  You will need the packages mentioned in F<README.dos> in the Perl distribution.
 278  
 279  =item *
 280  
 281  B<If you're on OS/2,>
 282  
 283  Get the EMX development suite and gzip/tar, from either Hobbes (
 284  http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 285  the instructions for Unix.
 286  
 287  =item *
 288  
 289  B<If you're on VMS,>
 290  
 291  When downloading from CPAN, save your file with a C<.tgz>
 292  extension instead of C<.tar.gz>.  All other periods in the
 293  filename should be replaced with underscores.  For example,
 294  C<Your-Module-1.33.tar.gz> should be downloaded as
 295  C<Your-Module-1_33.tgz>.
 296  
 297  A. DECOMPRESS
 298  
 299  Type
 300  
 301      gzip -d Your-Module.tgz
 302  
 303  or, for zipped modules, type
 304  
 305      unzip Your-Module.zip
 306  
 307  Executables for gzip, zip, and VMStar:
 308  
 309      http://www.openvms.digital.com/freeware/
 310      http://www.crinoid.com/utils/
 311  
 312  and their source code:
 313  
 314      http://www.fsf.org/order/ftp.html
 315  
 316  Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 317  package.  The former is a simple compression tool; the latter permits
 318  creation of multi-file archives.
 319  
 320  B. UNPACK
 321  
 322  If you're using VMStar:
 323  
 324       VMStar xf Your-Module.tar
 325  
 326  Or, if you're fond of VMS command syntax:
 327  
 328       tar/extract/verbose Your_Module.tar
 329  
 330  C. BUILD
 331  
 332  Make sure you have MMS (from Digital) or the freeware MMK ( available
 333  from MadGoat at http://www.madgoat.com ).  Then type this to create
 334  the DESCRIP.MMS for the module:
 335  
 336      perl Makefile.PL
 337  
 338  Now you're ready to build:
 339  
 340      mms test
 341  
 342  Substitute C<mmk> for C<mms> above if you're using MMK.
 343  
 344  D. INSTALL
 345  
 346  Type
 347  
 348      mms install
 349  
 350  Substitute C<mmk> for C<mms> above if you're using MMK.
 351  
 352  =item *
 353  
 354  B<If you're on MVS>,
 355  
 356  Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 357  ASCII to EBCDIC.
 358  
 359  A. DECOMPRESS
 360  
 361  Decompress the file with C<gzip -d yourmodule.tar.gz>
 362  
 363  You can get gzip from
 364  http://www.s390.ibm.com/products/oe/bpxqp1.html
 365  
 366  B. UNPACK
 367  
 368  Unpack the result with
 369  
 370       pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 371  
 372  The BUILD and INSTALL steps are identical to those for Unix.  Some
 373  modules generate Makefiles that work better with GNU make, which is
 374  available from http://www.mks.com/s390/gnu/
 375  
 376  =back
 377  
 378  =head1 PORTABILITY
 379  
 380  Note that not all modules will work with on all platforms.
 381  See L<perlport> for more information on portability issues.
 382  Read the documentation to see if the module will work on your
 383  system.  There are basically three categories
 384  of modules that will not work "out of the box" with all
 385  platforms (with some possibility of overlap):
 386  
 387  =over 4
 388  
 389  =item *
 390  
 391  B<Those that should, but don't.>  These need to be fixed; consider
 392  contacting the author and possibly writing a patch.
 393  
 394  =item *
 395  
 396  B<Those that need to be compiled, where the target platform
 397  doesn't have compilers readily available.>  (These modules contain
 398  F<.xs> or F<.c> files, usually.)  You might be able to find
 399  existing binaries on the CPAN or elsewhere, or you might
 400  want to try getting compilers and building it yourself, and then
 401  release the binary for other poor souls to use.
 402  
 403  =item *
 404  
 405  B<Those that are targeted at a specific platform.>
 406  (Such as the Win32:: modules.)  If the module is targeted
 407  specifically at a platform other than yours, you're out
 408  of luck, most likely.
 409  
 410  =back
 411  
 412  
 413  
 414  Check the CPAN Testers if a module should work with your platform
 415  but it doesn't behave as you'd expect, or you aren't sure whether or
 416  not a module will work under your platform.  If the module you want
 417  isn't listed there, you can test it yourself and let CPAN Testers know,
 418  you can join CPAN Testers, or you can request it be tested.
 419  
 420      http://testers.cpan.org/
 421  
 422  
 423  =head1 HEY
 424  
 425  If you have any suggested changes for this page, let me know.  Please
 426  don't send me mail asking for help on how to install your modules.
 427  There are too many modules, and too few Orwants, for me to be able to
 428  answer or even acknowledge all your questions.  Contact the module
 429  author instead, or post to comp.lang.perl.modules, or ask someone
 430  familiar with Perl on your operating system.
 431  
 432  =head1 AUTHOR
 433  
 434  Jon Orwant
 435  
 436  orwant@medita.mit.edu
 437  
 438  with invaluable help from Chris Nandor, and valuable help from Brandon
 439  Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
 440  Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
 441  J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
 442  Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
 443  
 444  First version July 22, 1998; last revised November 21, 2001.
 445  
 446  =head1 COPYRIGHT
 447  
 448  Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
 449  
 450  Permission is granted to make and distribute verbatim copies of this
 451  documentation provided the copyright notice and this permission notice are
 452  preserved on all copies.
 453  
 454  Permission is granted to copy and distribute modified versions of this
 455  documentation under the conditions for verbatim copying, provided also
 456  that they are marked clearly as modified versions, that the authors'
 457  names and title are unchanged (though subtitles and additional
 458  authors' names may be added), and that the entire resulting derived
 459  work is distributed under the terms of a permission notice identical
 460  to this one.
 461  
 462  Permission is granted to copy and distribute translations of this
 463  documentation into another language, under the above conditions for
 464  modified versions.
 465