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