1PERLMODINSTALL(1)      Perl Programmers Reference Guide      PERLMODINSTALL(1)
2
3
4

NAME

6       perlmodinstall - Installing CPAN Modules
7

DESCRIPTION

9       You can think of a module as the fundamental unit of reusable Perl
10       code; see perlmod for details.  Whenever anyone creates a chunk of Perl
11       code that they think will be useful to the world, they register as a
12       Perl developer at http://www.cpan.org/modules/04pause.html so that they
13       can then upload their code to the CPAN.  The CPAN is the Comprehensive
14       Perl Archive Network and can be accessed at http://www.cpan.org/ , and
15       searched at http://search.cpan.org/ .
16
17       This documentation is for people who want to download CPAN modules and
18       install them on their own computer.
19
20   PREAMBLE
21       First, are you sure that the module isn't already on your system?  Try
22       "perl -MFoo -e 1".  (Replace "Foo" with the name of the module; for
23       instance, "perl -MCGI::Carp -e 1".
24
25       If you don't see an error message, you have the module.  (If you do see
26       an error message, it's still possible you have the module, but that
27       it's not in your path, which you can display with "perl -e "print
28       qq(@INC)"".)  For the remainder of this document, we'll assume that you
29       really honestly truly lack an installed module, but have found it on
30       the CPAN.
31
32       So now you have a file ending in .tar.gz (or, less often, .zip).  You
33       know there's a tasty module inside.  There are four steps you must now
34       take:
35
36       DECOMPRESS the file
37       UNPACK the file into a directory
38       BUILD the module (sometimes unnecessary)
39       INSTALL the module.
40
41       Here's how to perform each step for each operating system.  This is
42       <not> a substitute for reading the README and INSTALL files that might
43       have come with your module!
44
45       Also note that these instructions are tailored for installing the
46       module into your system's repository of Perl modules, but you can
47       install modules into any directory you wish.  For instance, where I say
48       "perl Makefile.PL", you can substitute "perl Makefile.PL
49       PREFIX=/my/perl_directory" to install the modules into
50       "/my/perl_directory".  Then you can use the modules from your Perl
51       programs with "use lib "/my/perl_directory/lib/site_perl";" or
52       sometimes just "use "/my/perl_directory";".  If you're on a system that
53       requires superuser/root access to install modules into the directories
54       you see when you type "perl -e "print qq(@INC)"", you'll want to
55       install them into a local directory (such as your home directory) and
56       use this approach.
57
58       ·   If you're on a Unix or Unix-like system,
59
60           You can use Andreas Koenig's CPAN module (
61           http://www.cpan.org/modules/by-module/CPAN ) to automate the
62           following steps, from DECOMPRESS through INSTALL.
63
64           A. DECOMPRESS
65
66           Decompress the file with "gzip -d yourmodule.tar.gz"
67
68           You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
69
70           Or, you can combine this step with the next to save disk space:
71
72                gzip -dc yourmodule.tar.gz | tar -xof -
73
74           B. UNPACK
75
76           Unpack the result with "tar -xof yourmodule.tar"
77
78           C. BUILD
79
80           Go into the newly-created directory and type:
81
82                 perl Makefile.PL
83                 make test
84
85           or
86
87                 perl Makefile.PL PREFIX=/my/perl_directory
88
89           to install it locally.  (Remember that if you do this, you'll have
90           to put "use lib "/my/perl_directory";" near the top of the program
91           that is to use this module.
92
93           D. INSTALL
94
95           While still in that directory, type:
96
97                 make install
98
99           Make sure you have the appropriate permissions to install the
100           module in your Perl 5 library directory.  Often, you'll need to be
101           root.
102
103           That's all you need to do on Unix systems with dynamic linking.
104           Most Unix systems have dynamic linking. If yours doesn't, or if for
105           another reason you have a statically-linked perl, and the module
106           requires compilation, you'll need to build a new Perl binary that
107           includes the module.  Again, you'll probably need to be root.
108
109       ·   If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)
110
111           First, type "ppm" from a shell and see whether ActiveState's PPM
112           repository has your module.  If so, you can install it with "ppm"
113           and you won't have to bother with any of the other steps here.  You
114           might be able to use the CPAN instructions from the "Unix or Linux"
115           section above as well; give it a try.  Otherwise, you'll have to
116           follow the steps below.
117
118              A. DECOMPRESS
119
120           You can use the shareware Winzip ( http://www.winzip.com ) to
121           decompress and unpack modules.
122
123              B. UNPACK
124
125           If you used WinZip, this was already done for you.
126
127              C. BUILD
128
129           You'll need the "nmake" utility, available at
130           http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
131           or dmake, available on CPAN.  http://search.cpan.org/dist/dmake/
132
133           Does the module require compilation (i.e. does it have files that
134           end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, life is now
135           officially tough for you, because you have to compile the module
136           yourself (no easy feat on Windows).  You'll need a compiler such as
137           Visual C++.  Alternatively, you can download a pre-built PPM
138           package from ActiveState.
139           http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
140
141           Go into the newly-created directory and type:
142
143                 perl Makefile.PL
144                 nmake test
145
146
147              D. INSTALL
148
149           While still in that directory, type:
150
151                 nmake install
152
153       ·   If you're using a Macintosh with "Classic" MacOS and MacPerl,
154
155           A. DECOMPRESS
156
157           First, make sure you have the latest cpan-mac distribution (
158           http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
159           doing all of the steps.  Read the cpan-mac directions carefully and
160           install it.  If you choose not to use cpan-mac for some reason,
161           there are alternatives listed here.
162
163           After installing cpan-mac, drop the module archive on the
164           untarzipme droplet, which will decompress and unpack for you.
165
166           Or, you can either use the shareware StuffIt Expander program (
167           http://my.smithmicro.com/mac/stuffit/ ) or the freeware MacGzip
168           program (
169           http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
170
171           B. UNPACK
172
173           If you're using untarzipme or StuffIt, the archive should be
174           extracted now.  Or, you can use the freeware suntar or Tar (
175           http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
176
177           C. BUILD
178
179           Check the contents of the distribution.  Read the module's
180           documentation, looking for reasons why you might have trouble using
181           it with MacPerl.  Look for .xs and .c files, which normally denote
182           that the distribution must be compiled, and you cannot install it
183           "out of the box."  (See "PORTABILITY".)
184
185           D. INSTALL
186
187           If you are using cpan-mac, just drop the folder on the installme
188           droplet, and use the module.
189
190           Or, if you aren't using cpan-mac, do some manual labor.
191
192           Make sure the newlines for the modules are in Mac format, not Unix
193           format.  If they are not then you might have decompressed them
194           incorrectly.  Check your decompression and unpacking utilities
195           settings to make sure they are translating text files properly.
196
197           As a last resort, you can use the perl one-liner:
198
199               perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
200
201           on the source files.
202
203           Then move the files (probably just the .pm files, though there may
204           be some additional ones, too; check the module documentation) to
205           their final destination: This will most likely be in
206           "$ENV{MACPERL}site_lib:" (i.e., "HD:MacPerl folder:site_lib:").
207           You can add new paths to the default @INC in the Preferences menu
208           item in the MacPerl application ("$ENV{MACPERL}site_lib:" is added
209           automagically).  Create whatever directory structures are required
210           (i.e., for "Some::Module", create "$ENV{MACPERL}site_lib:Some:" and
211           put "Module.pm" in that directory).
212
213           Then run the following script (or something like it):
214
215                #!perl -w
216                use AutoSplit;
217                my $dir = "${MACPERL}site_perl";
218                autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
219
220       ·   If you're on the DJGPP port of DOS,
221
222              A. DECOMPRESS
223
224           djtarx ( ftp://ftp.delorie.com/pub/djgpp/current/v2/ ) will both
225           uncompress and unpack.
226
227              B. UNPACK
228
229           See above.
230
231              C. BUILD
232
233           Go into the newly-created directory and type:
234
235                 perl Makefile.PL
236                 make test
237
238           You will need the packages mentioned in README.dos in the Perl
239           distribution.
240
241              D. INSTALL
242
243           While still in that directory, type:
244
245                make install
246
247           You will need the packages mentioned in README.dos in the Perl
248           distribution.
249
250       ·   If you're on OS/2,
251
252           Get the EMX development suite and gzip/tar, from either Hobbes (
253           http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then
254           follow the instructions for Unix.
255
256       ·   If you're on VMS,
257
258           When downloading from CPAN, save your file with a ".tgz" extension
259           instead of ".tar.gz".  All other periods in the filename should be
260           replaced with underscores.  For example, "Your-Module-1.33.tar.gz"
261           should be downloaded as "Your-Module-1_33.tgz".
262
263           A. DECOMPRESS
264
265           Type
266
267               gzip -d Your-Module.tgz
268
269           or, for zipped modules, type
270
271               unzip Your-Module.zip
272
273           Executables for gzip, zip, and VMStar:
274
275               http://www.hp.com/go/openvms/freeware/
276
277           and their source code:
278
279               http://www.fsf.org/order/ftp.html
280
281           Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
282           package.  The former is a simple compression tool; the latter
283           permits creation of multi-file archives.
284
285           B. UNPACK
286
287           If you're using VMStar:
288
289                VMStar xf Your-Module.tar
290
291           Or, if you're fond of VMS command syntax:
292
293                tar/extract/verbose Your_Module.tar
294
295           C. BUILD
296
297           Make sure you have MMS (from Digital) or the freeware MMK (
298           available from MadGoat at http://www.madgoat.com ).  Then type this
299           to create the DESCRIP.MMS for the module:
300
301               perl Makefile.PL
302
303           Now you're ready to build:
304
305               mms test
306
307           Substitute "mmk" for "mms" above if you're using MMK.
308
309           D. INSTALL
310
311           Type
312
313               mms install
314
315           Substitute "mmk" for "mms" above if you're using MMK.
316
317       ·   If you're on MVS,
318
319           Introduce the .tar.gz file into an HFS as binary; don't translate
320           from ASCII to EBCDIC.
321
322           A. DECOMPRESS
323
324           Decompress the file with "gzip -d yourmodule.tar.gz"
325
326           You can get gzip from
327           http://www.s390.ibm.com/products/oe/bpxqp1.html
328
329           B. UNPACK
330
331           Unpack the result with
332
333                pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
334
335           The BUILD and INSTALL steps are identical to those for Unix.  Some
336           modules generate Makefiles that work better with GNU make, which is
337           available from http://www.mks.com/s390/gnu/
338

PORTABILITY

340       Note that not all modules will work with on all platforms.  See
341       perlport for more information on portability issues.  Read the
342       documentation to see if the module will work on your system.  There are
343       basically three categories of modules that will not work "out of the
344       box" with all platforms (with some possibility of overlap):
345
346       ·   Those that should, but don't.  These need to be fixed; consider
347           contacting the author and possibly writing a patch.
348
349       ·   Those that need to be compiled, where the target platform doesn't
350           have compilers readily available.  (These modules contain .xs or .c
351           files, usually.)  You might be able to find existing binaries on
352           the CPAN or elsewhere, or you might want to try getting compilers
353           and building it yourself, and then release the binary for other
354           poor souls to use.
355
356       ·   Those that are targeted at a specific platform.  (Such as the
357           Win32:: modules.)  If the module is targeted specifically at a
358           platform other than yours, you're out of luck, most likely.
359
360       Check the CPAN Testers if a module should work with your platform but
361       it doesn't behave as you'd expect, or you aren't sure whether or not a
362       module will work under your platform.  If the module you want isn't
363       listed there, you can test it yourself and let CPAN Testers know, you
364       can join CPAN Testers, or you can request it be tested.
365
366           http://testers.cpan.org/
367

HEY

369       If you have any suggested changes for this page, let me know.  Please
370       don't send me mail asking for help on how to install your modules.
371       There are too many modules, and too few Orwants, for me to be able to
372       answer or even acknowledge all your questions.  Contact the module
373       author instead, or post to comp.lang.perl.modules, or ask someone
374       familiar with Perl on your operating system.
375

AUTHOR

377       Jon Orwant
378
379       orwant@medita.mit.edu
380
381       with invaluable help from Chris Nandor, and valuable help from Brandon
382       Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
383       Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
384       Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
385       Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
386
387       First version July 22, 1998; last revised November 21, 2001.
388
390       Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
391
392       This document may be distributed under the same terms as Perl itself.
393
394
395
396perl v5.16.3                      2013-03-04                 PERLMODINSTALL(1)
Impressum