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