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.perl.com/CPAN/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.perl.com/CPAN/.
  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 You have a file ending in .tar.gz (or, less often, .zip).  You know
  21 there's a tasty module inside.  There are four steps you must now
  22 take:
  23
  24 =over 5
  25
  26 =item B<DECOMPRESS> the file
  27
  28 =item B<UNPACK> the file into a directory
  29
  30 =item B<BUILD> the module (sometimes unnecessary)
  31
  32 =item B<INSTALL> the module.
  33
  34 =back
  35
  36 Here's how to perform each step for each operating system.  This is
  37 I<not> a substitute for reading the README and INSTALL files that
  38 might have come with your module!
  39
  40 Also note that these instructions are tailored for installing the
  41 module into your system's repository of Perl modules.  But you can
  42 install modules into any directory you wish.  For instance, where I
  43 say C<perl Makefile.PL>, you can substitute C<perl
  44 Makefile.PL PREFIX=/my/perl_directory> to install the modules
  45 into C</my/perl_directory>.  Then you can use the modules
  46 from your Perl programs with C<use lib
  47 "/my/perl_directory/lib/site_perl";> or sometimes just C<use
  48 "/my/perl_directory";>.
  49
  50 =over 4
  51
  52 =item *
  53
  54 B<If you're on Unix,>
  55
  56 You can use Andreas Koenig's CPAN module
  57 ( http://www.perl.com/CPAN/modules/by-module/CPAN )
  58 to automate the following steps, from DECOMPRESS through INSTALL.
  59
  60 A. DECOMPRESS
  61
  62 Decompress the file with C<gzip -d yourmodule.tar.gz>
  63
  64 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
  65
  66 Or, you can combine this step with the next to save disk space:
  67
  68      gzip -dc yourmodule.tar.gz | tar -xof -
  69
  70 B. UNPACK
  71
  72 Unpack the result with C<tar -xof yourmodule.tar>
  73
  74 C. BUILD
  75
  76 Go into the newly-created directory and type:
  77
  78       perl Makefile.PL
  79       make
  80       make test
  81
  82 D. INSTALL
  83
  84 While still in that directory, type:
  85
  86       make install
  87
  88 Make sure you have the appropriate permissions to install the module
  89 in your Perl 5 library directory.  Often, you'll need to be root.
  90
  91 That's all you need to do on Unix systems with dynamic linking.
  92 Most Unix systems have dynamic linking -- if yours doesn't, or if for
  93 another reason you have a statically-linked perl, B<and> the
  94 module requires compilation, you'll need to build a new Perl binary
  95 that includes the module.  Again, you'll probably need to be root.
  96
  97 =item *
  98
  99 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
 100
 101    A. DECOMPRESS
 102
 103 You can use the shareware Winzip ( http://www.winzip.com ) to
 104 decompress and unpack modules.
 105
 106    B. UNPACK
 107
 108 If you used WinZip, this was already done for you.
 109
 110    C. BUILD
 111
 112 Does the module require compilation (i.e. does it have files
 113 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
 114 your own.  You can try compiling it yourself if you have a C compiler.
 115 If you're successful, consider uploading the resulting binary to the
 116 CPAN for others to use.  If it doesn't, go to INSTALL.
 117
 118    D. INSTALL
 119
 120 Copy the module into your Perl's I<lib> directory.  That'll be one
 121 of the directories you see when you type
 122
 123    perl -e 'print "@INC"'
 124
 125 =item *
 126
 127 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
 128
 129    A. DECOMPRESS
 130
 131 When you download the module, make sure it ends in either
 132 C<.tar.gz> or C<.zip>.  Windows browsers sometimes
 133 download C<.tar.gz> files as C<_tar.tar>, because
 134 early versions of Windows prohibited more than one dot in a filename.
 135
 136 You can use the shareware WinZip ( http://www.winzip.com ) to
 137 decompress and unpack modules.
 138
 139 Or, you can use InfoZip's C<unzip> utility (
 140 http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
 141 C<.zip> files; type C<unzip yourmodule.zip> in
 142 your shell.
 143
 144 Or, if you have a working C<tar> and C<gzip>, you can
 145 type
 146
 147    gzip -cd yourmodule.tar.gz | tar xvf -
 148
 149 in the shell to decompress C<yourmodule.tar.gz>.  This will
 150 UNPACK your module as well.
 151
 152    B. UNPACK
 153
 154 All of the methods in DECOMPRESS will have done this for you.
 155
 156    C. BUILD
 157
 158 Go into the newly-created directory and type:
 159
 160       perl Makefile.PL
 161       dmake
 162       dmake test
 163
 164 Depending on your perl configuration, C<dmake> might not be
 165 available.  You might have to substitute whatever C<perl
 166 -V:make> says. (Usually, that will be C<nmake> or
 167 C<make>.)
 168
 169    D. INSTALL
 170
 171 While still in that directory, type:
 172
 173       dmake install
 174
 175 =item *
 176
 177 B<If you're using a Macintosh,>
 178
 179 A. DECOMPRESS
 180
 181 In general, all Macintosh decompression utilities mentioned here
 182 can be found in the Info-Mac Hyperarchive
 183 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
 184 Specificly the "Commpress & Translate" listing
 185 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
 186
 187
 188 You can either use the shareware StuffIt Expander
 189 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/stuffit-expander-401.hqx )
 190 in combination with I<DropStuff with Expander Enhancer>
 191 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/drop-stuff-with-ee-40.hqx )
 192 or the freeware MacGzip (
 193 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 194
 195
 196 B. UNPACK
 197
 198 If you're using DropStuff or Stuffit, you can just extract the tar
 199 archive.  Otherwise, you can use the freeware I<suntar>
 200 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/suntar-221.hqx )
 201 or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/tar-40b.hqx ).
 202
 203 C. BUILD
 204
 205 Does the module require compilation?
 206
 207 1. If it does,
 208
 209 Overview: You need MPW and a combination of new and old CodeWarrior
 210 compilers for MPW and libraries.  Makefiles created for building under
 211 MPW use the Metrowerks compilers.  It's most likely possible to build
 212 without other compilers, but it has not been done successfully, to our
 213 knowledge.  Read the documentation in MacPerl: Power and Ease (
 214 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
 215 an existing precompiled binary, or hire someone to build it for you.
 216
 217 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
 218 to build it for you.  To subscribe to the mac-perl mailing list, send
 219 mail to mac-perl-request@iis.ee.ethz.ch.
 220
 221 2. If the module doesn't require compilation, go to INSTALL.
 222
 223 D. INSTALL
 224
 225 Make sure the newlines for the modules are in Mac format, not Unix format.
 226 If they are not then you might have decompressed them incorrectly.  Check
 227 your decompression and unpacking utilities settings to make sure they are
 228 translating text files properly.
 229 As a last resort, you can use the perl one-liner:  perl -i.bak -pe
 230 's/(?:\015)?\012/\015/g' <filenames> on the source files.
 231
 232 Move the files manually into the correct folders.
 233
 234 Move the files to their final destination: This will
 235 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 236 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 237 the default C<@INC> in the Preferences menu item in the
 238 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 239 automagically).  Create whatever directory structures are required
 240 (i.e., for C<Some::Module>, create
 241 C<$ENV{MACPERL}site_lib:Some:> and put
 242 C<Module.pm> in that directory).
 243
 244 Run the following script (or something like it):
 245
 246      #!perl -w
 247      use AutoSplit;
 248      my $dir = "${MACPERL}site_perl";
 249      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 250
 251 Eventually there should be a way to automate the installation process; some
 252 solutions exist, but none are ready for the general public yet.
 253
 254 =item *
 255
 256 B<If you're on the DJGPP port of DOS,>
 257
 258    A. DECOMPRESS
 259
 260 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
 261 will both uncompress and unpack.
 262
 263    B. UNPACK
 264
 265 See above.
 266
 267    C. BUILD
 268
 269 Go into the newly-created directory and type:
 270
 271       perl Makefile.PL
 272       make
 273       make test
 274
 275 You will need the packages mentioned in C<Readme.dos>
 276 in the Perl distribution.
 277
 278    D. INSTALL
 279
 280 While still in that directory, type:
 281
 282      make install
 283
 284 You will need the packages mentioned in Readme.dos in the Perl distribution.
 285
 286 =item *
 287
 288 B<If you're on OS/2,>
 289
 290 Get the EMX development suite and gzip/tar, from either Hobbes (
 291 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 292 the instructions for Unix.
 293
 294 =item *
 295
 296 B<If you're on VMS,>
 297
 298 When downloading from CPAN, save your file with a C<.tgz>
 299 extension instead of C<.tar.gz>.  All other periods in the
 300 filename should be replaced with underscores.  For example,
 301 C<Your-Module-1.33.tar.gz> should be downloaded as
 302 C<Your-Module-1_33.tgz>.
 303
 304 A. DECOMPRESS
 305
 306 Type
 307
 308     gzip -d Your-Module.tgz
 309
 310 or, for zipped modules, type
 311
 312     unzip Your-Module.zip
 313
 314 Executables for gzip, zip, and VMStar ( Alphas:
 315 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
 316 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
 317
 318 gzip and tar
 319 are also available at ftp://ftp.digital.com/pub/VMS.
 320
 321 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 322 package.  The former is a simple compression tool; the latter permits
 323 creation of multi-file archives.
 324
 325 B. UNPACK
 326
 327 If you're using VMStar:
 328
 329      VMStar xf Your-Module.tar
 330
 331 Or, if you're fond of VMS command syntax:
 332
 333      tar/extract/verbose Your_Module.tar
 334
 335 C. BUILD
 336
 337 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
 338 DESCRIP.MMS for the module:
 339
 340     perl Makefile.PL
 341
 342 Now you're ready to build:
 343
 344     mms
 345     mms test
 346
 347 Substitute C<mmk> for C<mms> above if you're using MMK.
 348
 349 D. INSTALL
 350
 351 Type
 352
 353     mms install
 354
 355 Substitute C<mmk> for C<mms> above if you're using MMK.
 356
 357 =item *
 358
 359 B<If you're on MVS>,
 360
 361 Introduce the .tar.gz file into an HFS as binary; don't translate from
 362 ASCII to EBCDIC.
 363
 364 A. DECOMPRESS
 365
 366       Decompress the file with C<gzip -d yourmodule.tar.gz>
 367
 368       You can get gzip from
 369       http://www.s390.ibm.com/products/oe/bpxqp1.html.
 370
 371 B. UNPACK
 372
 373 Unpack the result with
 374
 375      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 376
 377 The BUILD and INSTALL steps are identical to those for Unix.  Some
 378 modules generate Makefiles that work better with GNU make, which is
 379 available from http://www.mks.com/s390/gnu/index.htm.
 380
 381 =back
 382
 383 =head1 HEY
 384
 385 If you have any suggested changes for this page, let me know.  Please
 386 don't send me mail asking for help on how to install your modules.
 387 There are too many modules, and too few Orwants, for me to be able to
 388 answer or even acknowledge all your questions.  Contact the module
 389 author instead, or post to comp.lang.perl.modules, or ask someone
 390 familiar with Perl on your operating system.
 391
 392 =head1 AUTHOR
 393
 394 Jon Orwant
 395
 396 orwant@tpj.com
 397
 398 The Perl Journal, http://tpj.com
 399
 400 with invaluable help from Brandon Allbery, Charles Bailey, Graham
 401 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
 402 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
 403 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
 404 Sugalski, Larry Virden, and Ilya Zakharevich.
 405
 406 July 22, 1998
 407
 408 =head1 COPYRIGHT
 409
 410 Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
 411
 412 Permission is granted to make and distribute verbatim copies of this
 413 documentation provided the copyright notice and this permission notice are
 414 preserved on all copies.
 415
 416 Permission is granted to copy and distribute modified versions of this
 417 documentation under the conditions for verbatim copying, provided also
 418 that they are marked clearly as modified versions, that the authors'
 419 names and title are unchanged (though subtitles and additional
 420 authors' names may be added), and that the entire resulting derived
 421 work is distributed under the terms of a permission notice identical
 422 to this one.
 423
 424 Permission is granted to copy and distribute translations of this
 425 documentation into another language, under the above conditions for
 426 modified versions.
 427