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.cpan.org/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.cpan.org/ , and searched at http://search.cpan.org/ .
|
---|
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 | First, are you sure that the module isn't already on your system? Try
|
---|
21 | C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
|
---|
22 | instance, C<perl -MCGI::Carp -e 1>.
|
---|
23 |
|
---|
24 | If you don't see an error message, you have the module. (If you do
|
---|
25 | see an error message, it's still possible you have the module, but
|
---|
26 | that it's not in your path, which you can display with C<perl -e
|
---|
27 | "print qq(@INC)">.) For the remainder of this document, we'll assume
|
---|
28 | that you really honestly truly lack an installed module, but have
|
---|
29 | found it on the CPAN.
|
---|
30 |
|
---|
31 | So now you have a file ending in .tar.gz (or, less often, .zip). You
|
---|
32 | know there's a tasty module inside. There are four steps you must now
|
---|
33 | take:
|
---|
34 |
|
---|
35 | =over 5
|
---|
36 |
|
---|
37 | =item B<DECOMPRESS> the file
|
---|
38 |
|
---|
39 | =item B<UNPACK> the file into a directory
|
---|
40 |
|
---|
41 | =item B<BUILD> the module (sometimes unnecessary)
|
---|
42 |
|
---|
43 | =item B<INSTALL> the module.
|
---|
44 |
|
---|
45 | =back
|
---|
46 |
|
---|
47 | Here's how to perform each step for each operating system. This is
|
---|
48 | <not> a substitute for reading the README and INSTALL files that
|
---|
49 | might have come with your module!
|
---|
50 |
|
---|
51 | Also note that these instructions are tailored for installing the
|
---|
52 | module into your system's repository of Perl modules -- but you can
|
---|
53 | install modules into any directory you wish. For instance, where I
|
---|
54 | say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL
|
---|
55 | PREFIX=/my/perl_directory> to install the modules into
|
---|
56 | C</my/perl_directory>. Then you can use the modules from your Perl
|
---|
57 | programs with C<use lib "/my/perl_directory/lib/site_perl";> or
|
---|
58 | sometimes just C<use "/my/perl_directory";>. If you're on a system
|
---|
59 | that requires superuser/root access to install modules into the
|
---|
60 | directories you see when you type C<perl -e "print qq(@INC)">, you'll
|
---|
61 | want to install them into a local directory (such as your home
|
---|
62 | directory) and use this approach.
|
---|
63 |
|
---|
64 | =over 4
|
---|
65 |
|
---|
66 | =item *
|
---|
67 |
|
---|
68 | B<If you're on a Unix or Unix-like system,>
|
---|
69 |
|
---|
70 | You can use Andreas Koenig's CPAN module
|
---|
71 | ( http://www.cpan.org/modules/by-module/CPAN )
|
---|
72 | to automate the following steps, from DECOMPRESS through INSTALL.
|
---|
73 |
|
---|
74 | A. DECOMPRESS
|
---|
75 |
|
---|
76 | Decompress the file with C<gzip -d yourmodule.tar.gz>
|
---|
77 |
|
---|
78 | You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
|
---|
79 |
|
---|
80 | Or, you can combine this step with the next to save disk space:
|
---|
81 |
|
---|
82 | gzip -dc yourmodule.tar.gz | tar -xof -
|
---|
83 |
|
---|
84 | B. UNPACK
|
---|
85 |
|
---|
86 | Unpack the result with C<tar -xof yourmodule.tar>
|
---|
87 |
|
---|
88 | C. BUILD
|
---|
89 |
|
---|
90 | Go into the newly-created directory and type:
|
---|
91 |
|
---|
92 | perl Makefile.PL
|
---|
93 | make test
|
---|
94 |
|
---|
95 | or
|
---|
96 |
|
---|
97 | perl Makefile.PL PREFIX=/my/perl_directory
|
---|
98 |
|
---|
99 | to install it locally. (Remember that if you do this, you'll have to
|
---|
100 | put C<use lib "/my/perl_directory";> near the top of the program that
|
---|
101 | is to use this module.
|
---|
102 |
|
---|
103 | D. INSTALL
|
---|
104 |
|
---|
105 | While still in that directory, type:
|
---|
106 |
|
---|
107 | make install
|
---|
108 |
|
---|
109 | Make sure you have the appropriate permissions to install the module
|
---|
110 | in your Perl 5 library directory. Often, you'll need to be root.
|
---|
111 |
|
---|
112 | That's all you need to do on Unix systems with dynamic linking.
|
---|
113 | Most Unix systems have dynamic linking -- if yours doesn't, or if for
|
---|
114 | another reason you have a statically-linked perl, B<and> the
|
---|
115 | module requires compilation, you'll need to build a new Perl binary
|
---|
116 | that includes the module. Again, you'll probably need to be root.
|
---|
117 |
|
---|
118 | =item *
|
---|
119 |
|
---|
120 | B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
|
---|
121 |
|
---|
122 | First, type C<ppm> from a shell and see whether ActiveState's PPM
|
---|
123 | repository has your module. If so, you can install it with C<ppm> and
|
---|
124 | you won't have to bother with any of the other steps here. You might
|
---|
125 | be able to use the CPAN instructions from the "Unix or Linux" section
|
---|
126 | above as well; give it a try. Otherwise, you'll have to follow the
|
---|
127 | steps below.
|
---|
128 |
|
---|
129 | A. DECOMPRESS
|
---|
130 |
|
---|
131 | You can use the shareware Winzip ( http://www.winzip.com ) to
|
---|
132 | decompress and unpack modules.
|
---|
133 |
|
---|
134 | B. UNPACK
|
---|
135 |
|
---|
136 | If you used WinZip, this was already done for you.
|
---|
137 |
|
---|
138 | C. BUILD
|
---|
139 |
|
---|
140 | You'll need the C<nmake> utility, available at
|
---|
141 | http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
|
---|
142 | or dmake, available on CPAN.
|
---|
143 | http://search.cpan.org/dist/dmake/
|
---|
144 |
|
---|
145 | Does the module require compilation (i.e. does it have files that end
|
---|
146 | in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
|
---|
147 | officially tough for you, because you have to compile the module
|
---|
148 | yourself -- no easy feat on Windows. You'll need a compiler such as
|
---|
149 | Visual C++. Alternatively, you can download a pre-built PPM package
|
---|
150 | from ActiveState.
|
---|
151 | http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
|
---|
152 |
|
---|
153 | Go into the newly-created directory and type:
|
---|
154 |
|
---|
155 | perl Makefile.PL
|
---|
156 | nmake test
|
---|
157 |
|
---|
158 |
|
---|
159 | D. INSTALL
|
---|
160 |
|
---|
161 | While still in that directory, type:
|
---|
162 |
|
---|
163 | nmake install
|
---|
164 |
|
---|
165 | =item *
|
---|
166 |
|
---|
167 | B<If you're using a Macintosh with "Classic" MacOS and MacPerl,>
|
---|
168 |
|
---|
169 |
|
---|
170 | A. DECOMPRESS
|
---|
171 |
|
---|
172 | First, make sure you have the latest B<cpan-mac> distribution (
|
---|
173 | http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
|
---|
174 | doing all of the steps. Read the cpan-mac directions carefully and
|
---|
175 | install it. If you choose not to use cpan-mac for some reason, there
|
---|
176 | are alternatives listed here.
|
---|
177 |
|
---|
178 | After installing cpan-mac, drop the module archive on the
|
---|
179 | B<untarzipme> droplet, which will decompress and unpack for you.
|
---|
180 |
|
---|
181 | B<Or>, you can either use the shareware B<StuffIt Expander> program
|
---|
182 | ( http://www.aladdinsys.com/expander/ )
|
---|
183 | in combination with B<DropStuff with Expander Enhancer>
|
---|
184 | ( http://www.aladdinsys.com/dropstuff/ )
|
---|
185 | or the freeware B<MacGzip> program (
|
---|
186 | http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
|
---|
187 |
|
---|
188 | B. UNPACK
|
---|
189 |
|
---|
190 | If you're using untarzipme or StuffIt, the archive should be extracted
|
---|
191 | now. B<Or>, you can use the freeware B<suntar> or I<Tar> (
|
---|
192 | http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
|
---|
193 |
|
---|
194 | C. BUILD
|
---|
195 |
|
---|
196 | Check the contents of the distribution.
|
---|
197 | Read the module's documentation, looking for
|
---|
198 | reasons why you might have trouble using it with MacPerl. Look for
|
---|
199 | F<.xs> and F<.c> files, which normally denote that the distribution
|
---|
200 | must be compiled, and you cannot install it "out of the box."
|
---|
201 | (See L<"PORTABILITY">.)
|
---|
202 |
|
---|
203 | If a module does not work on MacPerl but should, or needs to be
|
---|
204 | compiled, see if the module exists already as a port on the
|
---|
205 | MacPerl Module Porters site ( http://pudge.net/mmp/ ).
|
---|
206 | For more information on doing XS with MacPerl yourself, see
|
---|
207 | Arved Sandstrom's XS tutorial ( http://macperl.com/depts/Tutorials/ ),
|
---|
208 | and then consider uploading your binary to the CPAN and
|
---|
209 | registering it on the MMP site.
|
---|
210 |
|
---|
211 | D. INSTALL
|
---|
212 |
|
---|
213 | If you are using cpan-mac, just drop the folder on the
|
---|
214 | B<installme> droplet, and use the module.
|
---|
215 |
|
---|
216 | B<Or>, if you aren't using cpan-mac, do some manual labor.
|
---|
217 |
|
---|
218 | Make sure the newlines for the modules are in Mac format, not Unix format.
|
---|
219 | If they are not then you might have decompressed them incorrectly. Check
|
---|
220 | your decompression and unpacking utilities settings to make sure they are
|
---|
221 | translating text files properly.
|
---|
222 |
|
---|
223 | As a last resort, you can use the perl one-liner:
|
---|
224 |
|
---|
225 | perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
|
---|
226 |
|
---|
227 | on the source files.
|
---|
228 |
|
---|
229 | Then move the files (probably just the F<.pm> files, though there
|
---|
230 | may be some additional ones, too; check the module documentation)
|
---|
231 | to their final destination: This will
|
---|
232 | most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
|
---|
233 | C<HD:MacPerl folder:site_lib:>). You can add new paths to
|
---|
234 | the default C<@INC> in the Preferences menu item in the
|
---|
235 | MacPerl application (C<$ENV{MACPERL}site_lib:> is added
|
---|
236 | automagically). Create whatever directory structures are required
|
---|
237 | (i.e., for C<Some::Module>, create
|
---|
238 | C<$ENV{MACPERL}site_lib:Some:> and put
|
---|
239 | C<Module.pm> in that directory).
|
---|
240 |
|
---|
241 | Then run the following script (or something like it):
|
---|
242 |
|
---|
243 | #!perl -w
|
---|
244 | use AutoSplit;
|
---|
245 | my $dir = "${MACPERL}site_perl";
|
---|
246 | autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
|
---|
247 |
|
---|
248 | =item *
|
---|
249 |
|
---|
250 | B<If you're on the DJGPP port of DOS,>
|
---|
251 |
|
---|
252 | A. DECOMPRESS
|
---|
253 |
|
---|
254 | djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
|
---|
255 | will both uncompress and unpack.
|
---|
256 |
|
---|
257 | B. UNPACK
|
---|
258 |
|
---|
259 | See above.
|
---|
260 |
|
---|
261 | C. BUILD
|
---|
262 |
|
---|
263 | Go into the newly-created directory and type:
|
---|
264 |
|
---|
265 | perl Makefile.PL
|
---|
266 | make test
|
---|
267 |
|
---|
268 | You will need the packages mentioned in F<README.dos>
|
---|
269 | in the Perl distribution.
|
---|
270 |
|
---|
271 | D. INSTALL
|
---|
272 |
|
---|
273 | While still in that directory, type:
|
---|
274 |
|
---|
275 | make install
|
---|
276 |
|
---|
277 | You will need the packages mentioned in F<README.dos> in the Perl distribution.
|
---|
278 |
|
---|
279 | =item *
|
---|
280 |
|
---|
281 | B<If you're on OS/2,>
|
---|
282 |
|
---|
283 | Get the EMX development suite and gzip/tar, from either Hobbes (
|
---|
284 | http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
|
---|
285 | the instructions for Unix.
|
---|
286 |
|
---|
287 | =item *
|
---|
288 |
|
---|
289 | B<If you're on VMS,>
|
---|
290 |
|
---|
291 | When downloading from CPAN, save your file with a C<.tgz>
|
---|
292 | extension instead of C<.tar.gz>. All other periods in the
|
---|
293 | filename should be replaced with underscores. For example,
|
---|
294 | C<Your-Module-1.33.tar.gz> should be downloaded as
|
---|
295 | C<Your-Module-1_33.tgz>.
|
---|
296 |
|
---|
297 | A. DECOMPRESS
|
---|
298 |
|
---|
299 | Type
|
---|
300 |
|
---|
301 | gzip -d Your-Module.tgz
|
---|
302 |
|
---|
303 | or, for zipped modules, type
|
---|
304 |
|
---|
305 | unzip Your-Module.zip
|
---|
306 |
|
---|
307 | Executables for gzip, zip, and VMStar:
|
---|
308 |
|
---|
309 | http://www.openvms.digital.com/freeware/
|
---|
310 | http://www.crinoid.com/utils/
|
---|
311 |
|
---|
312 | and their source code:
|
---|
313 |
|
---|
314 | http://www.fsf.org/order/ftp.html
|
---|
315 |
|
---|
316 | Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
|
---|
317 | package. The former is a simple compression tool; the latter permits
|
---|
318 | creation of multi-file archives.
|
---|
319 |
|
---|
320 | B. UNPACK
|
---|
321 |
|
---|
322 | If you're using VMStar:
|
---|
323 |
|
---|
324 | VMStar xf Your-Module.tar
|
---|
325 |
|
---|
326 | Or, if you're fond of VMS command syntax:
|
---|
327 |
|
---|
328 | tar/extract/verbose Your_Module.tar
|
---|
329 |
|
---|
330 | C. BUILD
|
---|
331 |
|
---|
332 | Make sure you have MMS (from Digital) or the freeware MMK ( available
|
---|
333 | from MadGoat at http://www.madgoat.com ). Then type this to create
|
---|
334 | the DESCRIP.MMS for the module:
|
---|
335 |
|
---|
336 | perl Makefile.PL
|
---|
337 |
|
---|
338 | Now you're ready to build:
|
---|
339 |
|
---|
340 | mms test
|
---|
341 |
|
---|
342 | Substitute C<mmk> for C<mms> above if you're using MMK.
|
---|
343 |
|
---|
344 | D. INSTALL
|
---|
345 |
|
---|
346 | Type
|
---|
347 |
|
---|
348 | mms install
|
---|
349 |
|
---|
350 | Substitute C<mmk> for C<mms> above if you're using MMK.
|
---|
351 |
|
---|
352 | =item *
|
---|
353 |
|
---|
354 | B<If you're on MVS>,
|
---|
355 |
|
---|
356 | Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
|
---|
357 | ASCII to EBCDIC.
|
---|
358 |
|
---|
359 | A. DECOMPRESS
|
---|
360 |
|
---|
361 | Decompress the file with C<gzip -d yourmodule.tar.gz>
|
---|
362 |
|
---|
363 | You can get gzip from
|
---|
364 | http://www.s390.ibm.com/products/oe/bpxqp1.html
|
---|
365 |
|
---|
366 | B. UNPACK
|
---|
367 |
|
---|
368 | Unpack the result with
|
---|
369 |
|
---|
370 | pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
|
---|
371 |
|
---|
372 | The BUILD and INSTALL steps are identical to those for Unix. Some
|
---|
373 | modules generate Makefiles that work better with GNU make, which is
|
---|
374 | available from http://www.mks.com/s390/gnu/
|
---|
375 |
|
---|
376 | =back
|
---|
377 |
|
---|
378 | =head1 PORTABILITY
|
---|
379 |
|
---|
380 | Note that not all modules will work with on all platforms.
|
---|
381 | See L<perlport> for more information on portability issues.
|
---|
382 | Read the documentation to see if the module will work on your
|
---|
383 | system. There are basically three categories
|
---|
384 | of modules that will not work "out of the box" with all
|
---|
385 | platforms (with some possibility of overlap):
|
---|
386 |
|
---|
387 | =over 4
|
---|
388 |
|
---|
389 | =item *
|
---|
390 |
|
---|
391 | B<Those that should, but don't.> These need to be fixed; consider
|
---|
392 | contacting the author and possibly writing a patch.
|
---|
393 |
|
---|
394 | =item *
|
---|
395 |
|
---|
396 | B<Those that need to be compiled, where the target platform
|
---|
397 | doesn't have compilers readily available.> (These modules contain
|
---|
398 | F<.xs> or F<.c> files, usually.) You might be able to find
|
---|
399 | existing binaries on the CPAN or elsewhere, or you might
|
---|
400 | want to try getting compilers and building it yourself, and then
|
---|
401 | release the binary for other poor souls to use.
|
---|
402 |
|
---|
403 | =item *
|
---|
404 |
|
---|
405 | B<Those that are targeted at a specific platform.>
|
---|
406 | (Such as the Win32:: modules.) If the module is targeted
|
---|
407 | specifically at a platform other than yours, you're out
|
---|
408 | of luck, most likely.
|
---|
409 |
|
---|
410 | =back
|
---|
411 |
|
---|
412 |
|
---|
413 |
|
---|
414 | Check the CPAN Testers if a module should work with your platform
|
---|
415 | but it doesn't behave as you'd expect, or you aren't sure whether or
|
---|
416 | not a module will work under your platform. If the module you want
|
---|
417 | isn't listed there, you can test it yourself and let CPAN Testers know,
|
---|
418 | you can join CPAN Testers, or you can request it be tested.
|
---|
419 |
|
---|
420 | http://testers.cpan.org/
|
---|
421 |
|
---|
422 |
|
---|
423 | =head1 HEY
|
---|
424 |
|
---|
425 | If you have any suggested changes for this page, let me know. Please
|
---|
426 | don't send me mail asking for help on how to install your modules.
|
---|
427 | There are too many modules, and too few Orwants, for me to be able to
|
---|
428 | answer or even acknowledge all your questions. Contact the module
|
---|
429 | author instead, or post to comp.lang.perl.modules, or ask someone
|
---|
430 | familiar with Perl on your operating system.
|
---|
431 |
|
---|
432 | =head1 AUTHOR
|
---|
433 |
|
---|
434 | Jon Orwant
|
---|
435 |
|
---|
436 | [email protected]
|
---|
437 |
|
---|
438 | with invaluable help from Chris Nandor, and valuable help from Brandon
|
---|
439 | Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
|
---|
440 | Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
|
---|
441 | J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
|
---|
442 | Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
|
---|
443 |
|
---|
444 | First version July 22, 1998; last revised November 21, 2001.
|
---|
445 |
|
---|
446 | =head1 COPYRIGHT
|
---|
447 |
|
---|
448 | Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
|
---|
449 |
|
---|
450 | Permission is granted to make and distribute verbatim copies of this
|
---|
451 | documentation provided the copyright notice and this permission notice are
|
---|
452 | preserved on all copies.
|
---|
453 |
|
---|
454 | Permission is granted to copy and distribute modified versions of this
|
---|
455 | documentation under the conditions for verbatim copying, provided also
|
---|
456 | that they are marked clearly as modified versions, that the authors'
|
---|
457 | names and title are unchanged (though subtitles and additional
|
---|
458 | authors' names may be added), and that the entire resulting derived
|
---|
459 | work is distributed under the terms of a permission notice identical
|
---|
460 | to this one.
|
---|
461 |
|
---|
462 | Permission is granted to copy and distribute translations of this
|
---|
463 | documentation into another language, under the above conditions for
|
---|
464 | modified versions.
|
---|
465 |
|
---|