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 Perl,>
 136
 137    A. DECOMPRESS
 138
 139 When you download the module, make sure it ends in either
 140 F<.tar.gz> or F<.zip>.  Windows browsers sometimes
 141 download C<.tar.gz> files as C<_tar.tar>, because
 142 early versions of Windows prohibited more than one dot in a filename.
 143
 144 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
 145 decompress and unpack modules.
 146
 147 Or, you can use InfoZip's C<unzip> utility (
 148 http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
 149 C<unzip yourmodule.zip> in your shell.
 150
 151 Or, if you have a working C<tar> and C<gzip>, you can
 152 type
 153
 154    gzip -cd yourmodule.tar.gz | tar xvf -
 155
 156 in the shell to decompress C<yourmodule.tar.gz>.  This will
 157 UNPACK your module as well.
 158
 159    B. UNPACK
 160
 161 The methods in DECOMPRESS will have done this for you.
 162
 163    C. BUILD
 164
 165 Go into the newly-created directory and type:
 166
 167       perl Makefile.PL
 168       dmake
 169       dmake test
 170
 171 Depending on your perl configuration, C<dmake> might not be
 172 available.  You might have to substitute whatever C<perl
 173 -V:make> says. (Usually, that will be C<nmake> or
 174 C<make>.)
 175
 176    D. INSTALL
 177
 178 While still in that directory, type:
 179
 180       dmake install
 181
 182 =item *
 183
 184 B<If you're using a Macintosh,>
 185
 186 A. DECOMPRESS
 187
 188 In general, all Macintosh decompression utilities mentioned here
 189 can be found in the Info-Mac Hyperarchive
 190 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
 191 Specifically the "Compress & Translate" listing
 192 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
 193
 194
 195 You can either use the shareware B<StuffIt Expander> program
 196 ( http://www.aladdinsys.com/expander/ )
 197 in combination with I<DropStuff with Expander Enhancer>
 198 ( http://www.aladdinsys.com/dropstuff/ )
 199 or the freeware B<MacGzip> program (
 200 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 201
 202
 203 B. UNPACK
 204
 205 If you're using DropStuff or Stuffit, you can just extract the tar
 206 archive.  Otherwise, you can use the freeware B<suntar> or I<Tar> (
 207 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
 208
 209 C. BUILD
 210
 211 Does the module require compilation?
 212
 213 1. If it does,
 214
 215 Overview: You need MPW and a combination of new and old CodeWarrior
 216 compilers for MPW and libraries.  Makefiles created for building under
 217 MPW use Metrowerks compilers.  It's most likely possible to build
 218 without other compilers, but it has not been done successfully, to our
 219 knowledge.  Read the documentation in I<MacPerl: Power and Ease> (
 220 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
 221 an existing precompiled binary, or hire someone to build it for you.
 222
 223 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
 224 to build it for you.  To subscribe to the mac-perl mailing list, send
 225 mail to mac-perl-request@iis.ee.ethz.ch.
 226
 227 2. If the module doesn't require compilation, go to INSTALL.
 228
 229 D. INSTALL
 230
 231 Make sure the newlines for the modules are in Mac format, not Unix format.
 232 If they are not then you might have decompressed them incorrectly.  Check
 233 your decompression and unpacking utilities settings to make sure they are
 234 translating text files properly.
 235
 236 As a last resort, you can use the perl one-liner:
 237
 238     perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
 239
 240 on the source files.
 241
 242 Move the files manually into the correct folders.
 243
 244 Move the files to their final destination: This will
 245 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 246 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 247 the default C<@INC> in the Preferences menu item in the
 248 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 249 automagically).  Create whatever directory structures are required
 250 (i.e., for C<Some::Module>, create
 251 C<$ENV{MACPERL}site_lib:Some:> and put
 252 C<Module.pm> in that directory).
 253
 254 Run the following script (or something like it):
 255
 256      #!perl -w
 257      use AutoSplit;
 258      my $dir = "${MACPERL}site_perl";
 259      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 260
 261 Eventually there should be a way to automate the installation process; some
 262 solutions exist, but none are ready for the general public yet.
 263
 264 =item *
 265
 266 B<If you're on the DJGPP port of DOS,>
 267
 268    A. DECOMPRESS
 269
 270 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
 271 will both uncompress and unpack.
 272
 273    B. UNPACK
 274
 275 See above.
 276
 277    C. BUILD
 278
 279 Go into the newly-created directory and type:
 280
 281       perl Makefile.PL
 282       make
 283       make test
 284
 285 You will need the packages mentioned in F<README.dos>
 286 in the Perl distribution.
 287
 288    D. INSTALL
 289
 290 While still in that directory, type:
 291
 292      make install
 293
 294 You will need the packages mentioned in F<README.dos> in the Perl distribution.
 295
 296 =item *
 297
 298 B<If you're on OS/2,>
 299
 300 Get the EMX development suite and gzip/tar, from either Hobbes (
 301 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 302 the instructions for Unix.
 303
 304 =item *
 305
 306 B<If you're on VMS,>
 307
 308 When downloading from CPAN, save your file with a F<.tgz>
 309 extension instead of F<.tar.gz>.  All other periods in the
 310 filename should be replaced with underscores.  For example,
 311 C<Your-Module-1.33.tar.gz> should be downloaded as
 312 C<Your-Module-1_33.tgz>.
 313
 314 A. DECOMPRESS
 315
 316 Type
 317
 318     gzip -d Your-Module.tgz
 319
 320 or, for zipped modules, type
 321
 322     unzip Your-Module.zip
 323
 324 Executables for gzip, zip, and VMStar ( Alphas:
 325 http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
 326 http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
 327
 328 gzip and tar
 329 are also available at ftp://ftp.digital.com/pub/VMS.
 330
 331 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 332 package.  The former is a simple compression tool; the latter permits
 333 creation of multi-file archives.
 334
 335 B. UNPACK
 336
 337 If you're using VMStar:
 338
 339      VMStar xf Your-Module.tar
 340
 341 Or, if you're fond of VMS command syntax:
 342
 343      tar/extract/verbose Your_Module.tar
 344
 345 C. BUILD
 346
 347 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
 348 DESCRIP.MMS for the module:
 349
 350     perl Makefile.PL
 351
 352 Now you're ready to build:
 353
 354     mms
 355     mms test
 356
 357 Substitute C<mmk> for C<mms> above if you're using MMK.
 358
 359 D. INSTALL
 360
 361 Type
 362
 363     mms install
 364
 365 Substitute C<mmk> for C<mms> above if you're using MMK.
 366
 367 =item *
 368
 369 B<If you're on MVS>,
 370
 371 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 372 ASCII to EBCDIC.
 373
 374 A. DECOMPRESS
 375
 376       Decompress the file with C<gzip -d yourmodule.tar.gz>
 377
 378       You can get gzip from
 379       http://www.s390.ibm.com/products/oe/bpxqp1.html.
 380
 381 B. UNPACK
 382
 383 Unpack the result with
 384
 385      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 386
 387 The BUILD and INSTALL steps are identical to those for Unix.  Some
 388 modules generate Makefiles that work better with GNU make, which is
 389 available from http://www.mks.com/s390/gnu/index.htm.
 390
 391 =back
 392
 393 =head1 HEY
 394
 395 If you have any suggested changes for this page, let me know.  Please
 396 don't send me mail asking for help on how to install your modules.
 397 There are too many modules, and too few Orwants, for me to be able to
 398 answer or even acknowledge all your questions.  Contact the module
 399 author instead, or post to comp.lang.perl.modules, or ask someone
 400 familiar with Perl on your operating system.
 401
 402 =head1 AUTHOR
 403
 404 Jon Orwant
 405
 406 orwant@tpj.com
 407
 408 The Perl Journal, http://tpj.com
 409
 410 with invaluable help from Brandon Allbery, Charles Bailey, Graham
 411 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
 412 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
 413 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
 414 Sugalski, Larry Virden, and Ilya Zakharevich.
 415
 416 July 22, 1998
 417
 418 =head1 COPYRIGHT
 419
 420 Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
 421
 422 Permission is granted to make and distribute verbatim copies of this
 423 documentation provided the copyright notice and this permission notice are
 424 preserved on all copies.
 425
 426 Permission is granted to copy and distribute modified versions of this
 427 documentation under the conditions for verbatim copying, provided also
 428 that they are marked clearly as modified versions, that the authors'
 429 names and title are unchanged (though subtitles and additional
 430 authors' names may be added), and that the entire resulting derived
 431 work is distributed under the terms of a permission notice identical
 432 to this one.
 433
 434 Permission is granted to copy and distribute translations of this
 435 documentation into another language, under the above conditions for
 436 modified versions.
 437