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 L<https://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 L<https://www.cpan.org/> , and searched at L<https://metacpan.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 ( L<https://metacpan.org/release/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 L<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
 132 open source 7-zip ( L<https://www.7-zip.org/> )
 133 or the shareware Winzip ( L<https://www.winzip.com> ) to
 134 decompress and unpack modules.
 135
 136    B. UNPACK
 137
 138 If you used WinZip, this was already done for you.
 139
 140    C. BUILD
 141
 142 You'll need the C<nmake> utility, available at
 143 L<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe>
 144 or dmake, available on CPAN.
 145 L<https://search.cpan.org/dist/dmake/>
 146
 147 Does the module require compilation (i.e. does it have files that end
 148 in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, life is now
 149 officially tough for you, because you have to compile the module
 150 yourself (no easy feat on Windows).  You'll need a compiler such as
 151 Visual C++.  Alternatively, you can download a pre-built PPM package
 152 from ActiveState.
 153 L<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
 154
 155 Go into the newly-created directory and type:
 156
 157       perl Makefile.PL
 158       nmake test
 159
 160
 161    D. INSTALL
 162
 163 While still in that directory, type:
 164
 165       nmake install
 166
 167 =item *
 168
 169 B<If you're on the DJGPP port of DOS,>
 170
 171    A. DECOMPRESS
 172
 173 djtarx ( L<ftp://ftp.delorie.com/pub/djgpp/current/v2/> )
 174 will both uncompress and unpack.
 175
 176    B. UNPACK
 177
 178 See above.
 179
 180    C. BUILD
 181
 182 Go into the newly-created directory and type:
 183
 184       perl Makefile.PL
 185       make test
 186
 187 You will need the packages mentioned in F<README.dos>
 188 in the Perl distribution.
 189
 190    D. INSTALL
 191
 192 While still in that directory, type:
 193
 194      make install
 195
 196 You will need the packages mentioned in F<README.dos> in the Perl distribution.
 197
 198 =item *
 199
 200 B<If you're on OS/2,>
 201
 202 Get the EMX development suite and gzip/tar from Hobbes (
 203 L<http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d> ), and then follow
 204 the instructions for Unix.
 205
 206 =item *
 207
 208 B<If you're on VMS,>
 209
 210 When downloading from CPAN, save your file with a C<.tgz>
 211 extension instead of C<.tar.gz>.  All other periods in the
 212 filename should be replaced with underscores.  For example,
 213 C<Your-Module-1.33.tar.gz> should be downloaded as
 214 C<Your-Module-1_33.tgz>.
 215
 216 A. DECOMPRESS
 217
 218 Type
 219
 220     gzip -d Your-Module.tgz
 221
 222 or, for zipped modules, type
 223
 224     unzip Your-Module.zip
 225
 226 Executables for gzip, zip, and VMStar:
 227
 228     http://www.hp.com/go/openvms/freeware/
 229
 230 and their source code:
 231
 232     http://www.fsf.org/order/ftp.html
 233
 234 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 235 package.  The former is a simple compression tool; the latter permits
 236 creation of multi-file archives.
 237
 238 B. UNPACK
 239
 240 If you're using VMStar:
 241
 242      VMStar xf Your-Module.tar
 243
 244 Or, if you're fond of VMS command syntax:
 245
 246      tar/extract/verbose Your_Module.tar
 247
 248 C. BUILD
 249
 250 Make sure you have MMS (from Digital) or the freeware MMK ( available
 251 from MadGoat at L<http://www.madgoat.com> ).  Then type this to create
 252 the DESCRIP.MMS for the module:
 253
 254     perl Makefile.PL
 255
 256 Now you're ready to build:
 257
 258     mms test
 259
 260 Substitute C<mmk> for C<mms> above if you're using MMK.
 261
 262 D. INSTALL
 263
 264 Type
 265
 266     mms install
 267
 268 Substitute C<mmk> for C<mms> above if you're using MMK.
 269
 270 =item *
 271
 272 B<If you're on MVS>,
 273
 274 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 275 ASCII to EBCDIC.
 276
 277 A. DECOMPRESS
 278
 279 Decompress the file with C<gzip -d yourmodule.tar.gz>
 280
 281 You can get gzip from
 282 L<http://www.s390.ibm.com/products/oe/bpxqp1.html>
 283
 284 B. UNPACK
 285
 286 Unpack the result with
 287
 288      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 289
 290 The BUILD and INSTALL steps are identical to those for Unix.  Some
 291 modules generate Makefiles that work better with GNU make, which is
 292 available from L<http://www.mks.com/s390/gnu/>
 293
 294 =back
 295
 296 =head1 PORTABILITY
 297
 298 Note that not all modules will work with on all platforms.
 299 See L<perlport> for more information on portability issues.
 300 Read the documentation to see if the module will work on your
 301 system.  There are basically three categories
 302 of modules that will not work "out of the box" with all
 303 platforms (with some possibility of overlap):
 304
 305 =over 4
 306
 307 =item *
 308
 309 B<Those that should, but don't.>  These need to be fixed; consider
 310 contacting the author and possibly writing a patch.
 311
 312 =item *
 313
 314 B<Those that need to be compiled, where the target platform
 315 doesn't have compilers readily available.>  (These modules contain
 316 F<.xs> or F<.c> files, usually.)  You might be able to find
 317 existing binaries on the CPAN or elsewhere, or you might
 318 want to try getting compilers and building it yourself, and then
 319 release the binary for other poor souls to use.
 320
 321 =item *
 322
 323 B<Those that are targeted at a specific platform.>
 324 (Such as the Win32:: modules.)  If the module is targeted
 325 specifically at a platform other than yours, you're out
 326 of luck, most likely.
 327
 328 =back
 329
 330
 331
 332 Check the CPAN Testers if a module should work with your platform
 333 but it doesn't behave as you'd expect, or you aren't sure whether or
 334 not a module will work under your platform.  If the module you want
 335 isn't listed there, you can test it yourself and let CPAN Testers know,
 336 you can join CPAN Testers, or you can request it be tested.
 337
 338     https://cpantesters.org/
 339
 340
 341 =head1 HEY
 342
 343 If you have any suggested changes for this page, let me know.  Please
 344 don't send me mail asking for help on how to install your modules.
 345 There are too many modules, and too few Orwants, for me to be able to
 346 answer or even acknowledge all your questions.  Contact the module
 347 author instead, ask someone familiar with Perl on your operating
 348 system, or if all else fails, file a ticket at L<https://rt.cpan.org/>.
 349
 350 =head1 AUTHOR
 351
 352 Jon Orwant
 353
 354 orwant@medita.mit.edu
 355
 356 with invaluable help from Chris Nandor, and valuable help from Brandon
 357 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
 358 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
 359 J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
 360 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
 361
 362 First version July 22, 1998; last revised November 21, 2001.
 363
 364 =head1 COPYRIGHT
 365
 366 Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
 367
 368 This document may be distributed under the same terms as Perl itself.