contrib/perl5/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:
 230
 231         perl -i.bak -pe 's/(?:\015)?\012/\015/g' filenames
 232
 233 on the source files.
 234
 235 Move the files manually into the correct folders.
 236
 237 Move the files to their final destination: This will
 238 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
 239 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
 240 the default C<@INC> in the Preferences menu item in the
 241 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
 242 automagically).  Create whatever directory structures are required
 243 (i.e., for C<Some::Module>, create
 244 C<$ENV{MACPERL}site_lib:Some:> and put
 245 C<Module.pm> in that directory).
 246
 247 Run the following script (or something like it):
 248
 249      #!perl -w
 250      use AutoSplit;
 251      my $dir = "${MACPERL}site_perl";
 252      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
 253
 254 Eventually there should be a way to automate the installation process; some
 255 solutions exist, but none are ready for the general public yet.
 256
 257 =item *
 258
 259 B<If you're on the DJGPP port of DOS,>
 260
 261    A. DECOMPRESS
 262
 263 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
 264 will both uncompress and unpack.
 265
 266    B. UNPACK
 267
 268 See above.
 269
 270    C. BUILD
 271
 272 Go into the newly-created directory and type:
 273
 274       perl Makefile.PL
 275       make
 276       make test
 277
 278 You will need the packages mentioned in C<Readme.dos>
 279 in the Perl distribution.
 280
 281    D. INSTALL
 282
 283 While still in that directory, type:
 284
 285      make install
 286
 287 You will need the packages mentioned in Readme.dos in the Perl distribution.
 288
 289 =item *
 290
 291 B<If you're on OS/2,>
 292
 293 Get the EMX development suite and gzip/tar, from either Hobbes (
 294 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
 295 the instructions for Unix.
 296
 297 =item *
 298
 299 B<If you're on VMS,>
 300
 301 When downloading from CPAN, save your file with a C<.tgz>
 302 extension instead of C<.tar.gz>.  All other periods in the
 303 filename should be replaced with underscores.  For example,
 304 C<Your-Module-1.33.tar.gz> should be downloaded as
 305 C<Your-Module-1_33.tgz>.
 306
 307 A. DECOMPRESS
 308
 309 Type
 310
 311     gzip -d Your-Module.tgz
 312
 313 or, for zipped modules, type
 314
 315     unzip Your-Module.zip
 316
 317 Executables for gzip, zip, and VMStar ( Alphas:
 318 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
 319 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
 320
 321 gzip and tar
 322 are also available at ftp://ftp.digital.com/pub/VMS.
 323
 324 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
 325 package.  The former is a simple compression tool; the latter permits
 326 creation of multi-file archives.
 327
 328 B. UNPACK
 329
 330 If you're using VMStar:
 331
 332      VMStar xf Your-Module.tar
 333
 334 Or, if you're fond of VMS command syntax:
 335
 336      tar/extract/verbose Your_Module.tar
 337
 338 C. BUILD
 339
 340 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
 341 DESCRIP.MMS for the module:
 342
 343     perl Makefile.PL
 344
 345 Now you're ready to build:
 346
 347     mms
 348     mms test
 349
 350 Substitute C<mmk> for C<mms> above if you're using MMK.
 351
 352 D. INSTALL
 353
 354 Type
 355
 356     mms install
 357
 358 Substitute C<mmk> for C<mms> above if you're using MMK.
 359
 360 =item *
 361
 362 B<If you're on MVS>,
 363
 364 Introduce the .tar.gz file into an HFS as binary; don't translate from
 365 ASCII to EBCDIC.
 366
 367 A. DECOMPRESS
 368
 369       Decompress the file with C<gzip -d yourmodule.tar.gz>
 370
 371       You can get gzip from
 372       http://www.s390.ibm.com/products/oe/bpxqp1.html.
 373
 374 B. UNPACK
 375
 376 Unpack the result with
 377
 378      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
 379
 380 The BUILD and INSTALL steps are identical to those for Unix.  Some
 381 modules generate Makefiles that work better with GNU make, which is
 382 available from http://www.mks.com/s390/gnu/index.htm.
 383
 384 =back
 385
 386 =head1 HEY
 387
 388 If you have any suggested changes for this page, let me know.  Please
 389 don't send me mail asking for help on how to install your modules.
 390 There are too many modules, and too few Orwants, for me to be able to
 391 answer or even acknowledge all your questions.  Contact the module
 392 author instead, or post to comp.lang.perl.modules, or ask someone
 393 familiar with Perl on your operating system.
 394
 395 =head1 AUTHOR
 396
 397 Jon Orwant
 398
 399 orwant@tpj.com
 400
 401 The Perl Journal, http://tpj.com
 402
 403 with invaluable help from Brandon Allbery, Charles Bailey, Graham
 404 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
 405 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
 406 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
 407 Sugalski, Larry Virden, and Ilya Zakharevich.
 408
 409 July 22, 1998
 410
 411 =head1 COPYRIGHT
 412
 413 Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
 414
 415 Permission is granted to make and distribute verbatim copies of this
 416 documentation provided the copyright notice and this permission notice are
 417 preserved on all copies.
 418
 419 Permission is granted to copy and distribute modified versions of this
 420 documentation under the conditions for verbatim copying, provided also
 421 that they are marked clearly as modified versions, that the authors'
 422 names and title are unchanged (though subtitles and additional
 423 authors' names may be added), and that the entire resulting derived
 424 work is distributed under the terms of a permission notice identical
 425 to this one.
 426
 427 Permission is granted to copy and distribute translations of this
 428 documentation into another language, under the above conditions for
 429 modified versions.
 430