Remove C variables (and a parameter!) now unused since -P bit the dust.
[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 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 orwant@medita.mit.edu
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