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