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