Penguin
Recent Changes
Blame: perlmodinstall(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of perlmodinstall(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLMODINSTALL
2 !!!PERLMODINSTALL
3 NAME
4 DESCRIPTION
5 PORTABILITY
6 HEY
7 AUTHOR
8 COPYRIGHT
9 ----
10 !!NAME
11
12
13 perlmodinstall - Installing CPAN Modules
14 !!DESCRIPTION
15
16
17 You can think of a module as the fundamental unit of
18 reusable Perl code; See perlmod for details. Whenever anyone
19 creates a chunk of Perl code that they think will be useful
20 to the world, they register as a Perl developer at
21 http://www.perl.com/CPAN/modules/04pause.html so that they
22 can then upload their code to CPAN .
23 CPAN is the Comprehensive Perl Archive
24 Network and can be accessed at http://www.perl.com/CPAN/, or
25 searched via http://cpan.perl.com/ and
26 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl
27 .
28
29
30 This documentation is for people who want to download
31 CPAN modules and install them on their own
32 computer.
33
34
35 __PREAMBLE__
36
37
38 You have a file ending in ''.tar.gz'' (or, less often,
39 ''.zip''). You know there's a tasty module inside. You
40 must now take four steps:
41
42
43 __DECOMPRESS__ the file
44
45
46 __UNPACK__ the file into a
47 directory
48
49
50 __BUILD__ the module (sometimes
51 unnecessary)
52
53
54 __INSTALL__ the module.
55
56
57 Here's how to perform each step for each operating system.
58 This is ''not'' a substitute for reading the
59 README and INSTALL files that
60 might have come with your module!
61
62
63 Also note that these instructions are tailored for
64 installing the module into your system's repository of Perl
65 modules. But you can install modules into any directory you
66 wish. For instance, where I say perl Makefile.PL,
67 you can substitute perl Makefile.PL
68 PREFIX=/my/perl_directory to install the modules into
69 /my/perl_directory. Then you can use the modules
70 from your Perl programs with use lib
71 or
72 sometimes just use
73 .
74
75
76 __If you're on Unix,__
77
78
79 You can use Andreas Koenig's CPAN module
80 (which comes standard with Perl, or can itself be downloaded
81 from http://www.perl.com/CPAN/modules/by-module/CPAN) to
82 automate the following steps, from DECOMPRESS
83 through INSTALL .
84
85
86 A. DECOMPRESS
87
88
89 Decompress the file with gzip -d
90 yourmodule.tar.gz
91
92
93 You can get gzip from
94 ftp://prep.ai.mit.edu/pub/gnu.
95
96
97 Or, you can combine this step with the next to save disk
98 space:
99
100
101 gzip -dc yourmodule.tar.gz tar -xof -
102 B. UNPACK
103
104
105 Unpack the result with tar -xof
106 yourmodule.tar
107
108
109 C. BUILD
110
111
112 Go into the newly-created directory and type:
113
114
115 perl Makefile.PL
116 make
117 make test
118 D. INSTALL
119
120
121 While still in that directory, type:
122
123
124 make install
125 Make sure you have appropriate permissions to install the module in your Perl 5 library directory. Often, you'll need to be root.
126
127
128 Perl maintains a record of all module installations. To look
129 at this list, simply type:
130
131
132 perldoc perllocal
133 That's all you need to do on Unix systems with dynamic linking. Most Unix systems have dynamic linking--if yours doesn't, or if for another reason you have a statically-linked perl, ''and'' the module requires compilation, you'll need to build a new Perl binary that includes the module. Again, you'll probably need to be root.
134
135
136 __If you're running Windows 95 or NT with
2 perry 137 the !ActiveState port of Perl__
1 perry 138
139
140 A. DECOMPRESS
141 You can use the shareware __Winzip__ program ( http://www.winzip.com ) to decompress and unpack modules.
142
143
144 B. UNPACK
2 perry 145 If you used !WinZip, this was already done for you.
1 perry 146
147
148 C. BUILD
149 Does the module require compilation (i.e. does it have files that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on your own. You can try compiling it yourself if you have a C compiler. If you're successful, consider uploading the resulting binary to CPAN for others to use. If it doesn't, go to INSTALL .
150
151
152 D. INSTALL
153 Copy the module into your Perl's ''lib'' directory. That'll be one of the directories you see when you type
154
155
156 perl -e 'print
157
158
159 __If you're running Windows 95 or NT with
160 the core Windows distribution of Perl,__
161
162
163 A. DECOMPRESS
164 When you download the module, make sure it ends in either ''.tar.gz'' or ''.zip''. Windows browsers sometimes download .tar.gz files as _tar.tar, because early versions of Windows prohibited more than one dot in a filename.
165
166
2 perry 167 You can use the shareware __!WinZip__ program (
1 perry 168 http://www.winzip.com ) to decompress and unpack
169 modules.
170
171
2 perry 172 Or, you can use !InfoZip's unzip utility (
1 perry 173 http://www.cdrom.com/pub/infozip/ ) to uncompress
174 .zip files; type unzip yourmodule.zip in
175 your shell.
176
177
178 Or, if you have a working tar and gzip,
179 you can type
180
181
182 gzip -cd yourmodule.tar.gz tar xvf -
183 in the shell to decompress yourmodule.tar.gz. This will UNPACK your module as well.
184
185
186 B. UNPACK
187 The methods in DECOMPRESS will have done this for you.
188
189
190 C. BUILD
191 Go into the newly-created directory and type:
192
193
194 perl Makefile.PL
195 dmake
196 dmake test
197 Depending on your perl configuration, dmake might not be available. You might have to substitute whatever perl -V:make says. (Usually, that will be nmake or make.)
198
199
200 D. INSTALL
201 While still in that directory, type:
202
203
204 dmake install
205
206
207 __If you're using a Macintosh,__
208
209
210 A. DECOMPRESS
211
212
213 First thing you should do is make sure you have the latest
214 __cpan-mac__ distribution (
215 http://www.cpan.org/authors/id/CNANDOR/ ), which has
216 utilities for doing all of the steps. Read the cpan-mac
217 directions carefully and install it. If you choose not to
218 use cpan-mac for some reason, there are alternatives listed
219 here.
220
221
222 After installing cpan-mac, drop the module archive on the
223 __untarzipme__ droplet, which will decompress and unpack
224 for you.
225
226
2 perry 227 __Or__, you can either use the shareware __!StuffIt
1 perry 228 Expander__ program ( http://www.aladdinsys.com/expander/ )
2 perry 229 in combination with __!DropStuff with Expander Enhancer__
1 perry 230 ( http://www.aladdinsys.com/dropstuff/ ) or the freeware
2 perry 231 __!MacGzip__ program (
1 perry 232 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html
233 ).
234
235
236 B. UNPACK
237
238
2 perry 239 If you're using untarzipme or !StuffIt, the archive should be
1 perry 240 extracted now. __Or__, you can use the freeware
241 __suntar__ or ''Tar'' (
2 perry 242 http://hyperarchive.lcs.mit.edu/!HyperArchive/Archive/cmp/
1 perry 243 ).
244
245
246 C. BUILD
247
248
249 Check the contents of the distribution. Read the module's
250 documentation, looking for reasons why you might have
2 perry 251 trouble using it with !MacPerl. Look for ''.xs'' and
1 perry 252 ''.c'' files, which normally denote that the distribution
253 must be compiled, and you cannot install it ``out of the
254 box.'' (See `` PORTABILITY ''.)
255
256
2 perry 257 If a module does not work on !MacPerl but should, or needs to
1 perry 258 be compiled, see if the module exists already as a port on
2 perry 259 the !MacPerl Module Porters site (http://pudge.net/mmp/). For
260 more information on doing XS with !MacPerl
1 perry 261 yourself, see Arved Sandstrom's XS tutorial
262 (http://macperl.com/depts/Tutorials/), and then consider
263 uploading your binary to the CPAN and
264 registering it on the MMP site.
265
266
267 D. INSTALL
268
269
270 If you are using cpan-mac, just drop the folder on the
271 __installme__ droplet, and use the module.
272
273
274 __Or__, if you aren't using cpan-mac, do some manual
275 labor.
276
277
278 Make sure the newlines for the modules are in Mac format,
279 not Unix format. If they are not then you might have
280 decompressed them incorrectly. Check your decompression and
281 unpacking utilities settings to make sure they are
282 translating text files properly.
283
284
285 As a last resort, you can use the perl
286 one-liner:
287
288
289 perl -i.bak -pe 's/(?:015)?012/015/g'
290 on the source files.
291
292
293 Then move the files (probably just the ''.pm'' files,
294 though there may be some additional ones, too; check the
295 module documentation) to their final destination: This will
296 most likely be in $ENV{MACPERL}site_lib: (i.e.,
2 perry 297 HD:!MacPerl folder:site_lib:). You can add new paths
1 perry 298 to the default @INC in the Preferences menu item in
2 perry 299 the !MacPerl application ($ENV{MACPERL}site_lib: is
1 perry 300 added automagically). Create whatever directory structures
301 are required (i.e., for Some::Module, create
302 $ENV{MACPERL}site_lib:Some: and put
303 Module.pm in that directory).
304
305
306 Then run the following script (or something like
307 it):
308
309
310 #!perl -w
2 perry 311 use !AutoSplit;
1 perry 312 my $dir =
313
314
315 __If you're on the DJGPP port of
316 DOS ,__
317
318
319 A. DECOMPRESS
320 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) will both uncompress and unpack.
321
322
323 B. UNPACK
324 See above.
325
326
327 C. BUILD
328 Go into the newly-created directory and type:
329
330
331 perl Makefile.PL
332 make
333 make test
334 You will need the packages mentioned in ''README .dos'' in the Perl distribution.
335
336
337 D. INSTALL
338 While still in that directory, type:
339
340
341 make install
342 You will need the packages mentioned in ''README .dos'' in the Perl distribution.
343
344
345 __If you're on OS/2 ,__
346
347
348 Get the EMX development suite and gzip/tar,
349 from either Hobbes ( http://hobbes.nmsu.edu ) or Leo (
350 http://www.leo.org ), and then follow the instructions for
351 Unix.
352
353
354 __If you're on VMS ,__
355
356
357 When downloading from CPAN , save your file
358 with a ''.tgz'' extension instead of ''.tar.gz''. All
359 other periods in the filename should be replaced with
360 underscores. For example, Your-Module-1.33.tar.gz
361 should be downloaded as
362 Your-Module-1_33.tgz.
363
364
365 A. DECOMPRESS
366
367
368 Type
369
370
371 gzip -d Your-Module.tgz
372 or, for zipped modules, type
373
374
375 unzip Your-Module.zip
376 Executables for gzip, zip, and VMStar ( Alphas: http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen: http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
377
378
379 gzip and tar are also available at
380 ftp://ftp.digital.com/pub/VMS.
381
382
383 Note that GNU 's gzip/gunzip is not the same
384 as Info-ZIP's zip/unzip package. The former is a simple
385 compression tool; the latter permits creation of multi-file
386 archives.
387
388
389 B. UNPACK
390
391
392 If you're using VMStar:
393
394
395 VMStar xf Your-Module.tar
396 Or, if you're fond of VMS command syntax:
397
398
399 tar/extract/verbose Your_Module.tar
400 C. BUILD
401
402
403 Make sure you have MMS (from Digital) or the
2 perry 404 freeware MMK ( available from !MadGoat at
1 perry 405 http://www.madgoat.com ). Then type this to create the
406 DESCRIP .MMS for the module:
407
408
409 perl Makefile.PL
410 Now you're ready to build:
411
412
413 mms
414 mms test
415 Substitute mmk for mms above if you're using MMK .
416
417
418 D. INSTALL
419
420
421 Type
422
423
424 mms install
425 Substitute mmk for mms above if you're using MMK .
426
427
428 __If you're on MVS__ ,
429
430
431 Introduce the ''.tar.gz'' file into an HFS
432 as binary; don't translate from ASCII to
433 EBCDIC .
434
435
436 A. DECOMPRESS
437
438
439 Decompress the file with C
440 You can get gzip from
441 http://www.s390.ibm.com/products/oe/bpxqp1.html.
442 B. UNPACK
443
444
445 Unpack the result with
446
447
448 pax -o to=IBM-1047,from=ISO8859-1 -r
449 The BUILD and INSTALL steps are identical to those for Unix. Some modules generate Makefiles that work better with GNU make, which is available from http://www.mks.com/s390/gnu/index.htm.
450 !!PORTABILITY
451
452
453 Note that not all modules will work with on all platforms.
454 See perlport for more information on portability issues.
455 Read the documentation to see if the module will work on
456 your system. There are basically three categories of modules
457 that will not work ``out of the box'' with all platforms
458 (with some possibility of overlap):
459
460
461 __Those that should, but don't.__ These need to be fixed;
462 consider contacting the author and possibly writing a
463 patch.
464
465
466 __Those that need to be compiled, where the target platform
467 doesn't have compilers readily available.__ (These modules
468 contain ''.xs'' or ''.c'' files, usually.) You might
469 be able to find existing binaries on the CPAN
470 or elsewhere, or you might want to try getting compilers and
471 building it yourself, and then release the binary for other
472 poor souls to use.
473
474
475 __Those that are targeted at a specific platform.__ (Such
476 as the Win32:: modules.) If the module is targeted
477 specifically at a platform other than yours, you're out of
478 luck, most likely.
479
480
481 Check the CPAN Testers if a module should
482 work with your platform but it doesn't behave as you'd
483 expect, or you aren't sure whether or not a module will work
484 under your platform. If the module you want isn't listed
485 there, you can test it yourself and let CPAN
486 Testers know, you can join CPAN Testers, or
487 you can request it be tested.
488
489
490 http://testers.cpan.org/
491 !!HEY
492
493
494 If you have any suggested changes for this page, let me
495 know. Please don't send me mail asking for help on how to
496 install your modules. There are too many modules, and too
497 few Orwants, for me to be able to answer or even acknowledge
498 all your questions. Contact the module author instead, or
499 post to comp.lang.perl.modules, or ask someone familiar with
500 Perl on your operating system.
501 !!AUTHOR
502
503
504 Jon Orwant
505
506
507 orwant@tpj.com
508
509
510 The Perl Journal, http://tpj.com
511
512
513 with invaluable help from Brandon Allbery, Charles Bailey,
514 Graham Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman,
515 Tom Horsley, Nick Ing-Simmons, Tuomas J. Lukka, Laszlo
516 Molnar, Chris Nandor, Alan Olsen, Peter Prymmer, Gurusamy
517 Sarathy, Christoph Spalinger, Dan Sugalski, Larry Virden,
518 and Ilya Zakharevich.
519
520
521 First version July 22, 1998
522
523
524 Last Modified August 22, 2000
525 !!COPYRIGHT
526
527
528 Copyright (C) 1998, 2000 Jon Orwant. All Rights
529 Reserved.
530
531
532 Permission is granted to make and distribute verbatim copies
533 of this documentation provided the copyright notice and this
534 permission notice are preserved on all copies.
535
536
537 Permission is granted to copy and distribute modified
538 versions of this documentation under the conditions for
539 verbatim copying, provided also that they are marked clearly
540 as modified versions, that the authors' names and title are
541 unchanged (though subtitles and additional authors' names
542 may be added), and that the entire resulting derived work is
543 distributed under the terms of a permission notice identical
544 to this one.
545
546
547 Permission is granted to copy and distribute translations of
548 this documentation into another language, under the above
549 conditions for modified versions.
550 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.