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