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