README.vms and related updates (from Peter Prymmer <pvhp@best.com>)
[p5sagit/p5-mst-13.2.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
9 of Perl code that they think will be useful to the world, they
10 register as a Perl developer at
11 http://www.perl.com/CPAN/modules/04pause.html so that they can then
12 upload their code to CPAN.  CPAN is the Comprehensive Perl Archive
13 Network and can be accessed at http://www.perl.com/CPAN/, or searched
14 via http://cpan.perl.com/ and
15 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
16
17 This documentation is for people who want to download CPAN modules
18 and install them on their own computer.
19
20 =head2 PREAMBLE
21
22 You have a file ending in F<.tar.gz> (or, less often, F<.zip>).
23 You know there's a tasty module inside.  You must now take four
24 steps:
25
26 =over 5
27
28 =item B<DECOMPRESS> the file
29
30 =item B<UNPACK> the file into a directory
31
32 =item B<BUILD> the module (sometimes unnecessary)
33
34 =item B<INSTALL> the module.
35
36 =back
37
38 Here's how to perform each step for each operating system.  This is
39 I<not> a substitute for reading the README and INSTALL files that
40 might have come with your module!
41
42 Also note that these instructions are tailored for installing the
43 module into your system's repository of Perl modules.  But you can
44 install modules into any directory you wish.  For instance, where I
45 say C<perl Makefile.PL>, you can substitute C<perl
46 Makefile.PL PREFIX=/my/perl_directory> to install the modules
47 into C</my/perl_directory>.  Then you can use the modules
48 from your Perl programs with C<use lib
49 "/my/perl_directory/lib/site_perl"> or sometimes just C<use
50 "/my/perl_directory">.  
51
52 =over 4
53
54 =item *
55
56 B<If you're on Unix,>
57
58 You can use Andreas Koenig's CPAN module 
59 (which comes standard with Perl, or can itself be downloaded
60 from http://www.perl.com/CPAN/modules/by-module/CPAN) 
61 to automate the following steps, from DECOMPRESS through INSTALL.
62
63 A. DECOMPRESS 
64
65 Decompress the file with C<gzip -d yourmodule.tar.gz>
66
67 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. 
68
69 Or, you can combine this step with the next to save disk space:
70
71      gzip -dc yourmodule.tar.gz | tar -xof -
72
73 B. UNPACK
74
75 Unpack the result with C<tar -xof yourmodule.tar>
76
77 C. BUILD
78
79 Go into the newly-created directory and type:
80
81       perl Makefile.PL
82       make
83       make test
84
85 D. INSTALL
86
87 While still in that directory, type:
88
89       make install
90
91 Make sure you have appropriate permissions to install the module
92 in your Perl 5 library directory.  Often, you'll need to be root.
93
94 That's all you need to do on Unix systems with dynamic linking.
95 Most Unix systems have dynamic linking--if yours doesn't, or if for
96 another reason you have a statically-linked perl, I<and> the
97 module requires compilation, you'll need to build a new Perl binary
98 that includes the module.  Again, you'll probably need to be root.
99
100 =item *
101
102 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
103
104    A. DECOMPRESS
105
106 You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
107 decompress and unpack modules.
108
109    B. UNPACK
110
111 If you used WinZip, this was already done for you.
112
113    C. BUILD
114
115 Does the module require compilation (i.e. does it have files
116 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
117 your own.  You can try compiling it yourself if you have a C compiler.
118 If you're successful, consider uploading the resulting binary to
119 CPAN for others to use.  If it doesn't, go to INSTALL.
120
121    D. INSTALL
122
123 Copy the module into your Perl's I<lib> directory.  That'll be one
124 of the directories you see when you type 
125
126    perl -e 'print "@INC"'
127
128 =item *
129
130 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
131
132    A. DECOMPRESS
133
134 When you download the module, make sure it ends in either
135 F<.tar.gz> or F<.zip>.  Windows browsers sometimes
136 download C<.tar.gz> files as C<_tar.tar>, because
137 early versions of Windows prohibited more than one dot in a filename.
138
139 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
140 decompress and unpack modules.
141
142 Or, you can use InfoZip's C<unzip> utility (
143 http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
144 C<.zip> files; type C<unzip yourmodule.zip> in
145 your shell.
146
147 Or, if you have a working C<tar> and C<gzip>, you can
148 type
149
150    gzip -cd yourmodule.tar.gz | tar xvf -
151
152 in the shell to decompress C<yourmodule.tar.gz>.  This will
153 UNPACK your module as well.
154
155    B. UNPACK
156
157 The methods in DECOMPRESS will have done this for you.
158
159    C. BUILD
160
161 Go into the newly-created directory and type:
162
163       perl Makefile.PL
164       dmake
165       dmake test
166
167 Depending on your perl configuration, C<dmake> might not be
168 available.  You might have to substitute whatever C<perl
169 -V:make> says. (Usually, that will be C<nmake> or
170 C<make>.)
171
172    D. INSTALL
173
174 While still in that directory, type:
175
176       dmake install
177
178 =item *
179
180 B<If you're using a Macintosh,>
181
182 A. DECOMPRESS
183
184 In general, all Macintosh decompression utilities mentioned here
185 can be found in the Info-Mac Hyperarchive
186 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
187 Specificly the "Commpress & Translate" listing
188 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
189
190
191 You can either use the shareware B<StuffIt Expander> program
192 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/stuffit-expander-401.hqx ) 
193 in combination with I<DropStuff with Expander Enhancer>
194 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/drop-stuff-with-ee-40.hqx ) 
195 or the freeware B<MacGzip> program (
196 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
197
198
199 B. UNPACK
200
201 If you're using DropStuff or Stuffit, you can just extract the tar
202 archive.  Otherwise, you can use the freeware B<suntar> 
203 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/suntar-221.hqx )
204 or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/tar-40b.hqx ).
205
206 C. BUILD
207
208 Does the module require compilation? 
209
210 1. If it does,
211
212 Overview: You need MPW and a combination of new and old CodeWarrior
213 compilers for MPW and libraries.  Makefiles created for building under
214 MPW use Metrowerks compilers.  It's most likely possible to build
215 without other compilers, but it has not been done successfully, to our
216 knowledge.  Read the documentation in I<MacPerl: Power and Ease> (
217 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
218 an existing precompiled binary, or hire someone to build it for you.
219
220 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
221 to build it for you.  To subscribe to the mac-perl mailing list, send
222 mail to mac-perl-request@iis.ee.ethz.ch.
223
224 2. If the module doesn't require compilation, go to INSTALL.
225
226 D. INSTALL
227
228 Make sure the newlines for the modules are in Mac format, not Unix format.
229 If they are not then you might have decompressed them incorrectly.  Check
230 your decompression and unpacking utilities settings to make sure they are
231 translating text files properly.
232
233 As a last resort, you can use the perl one-liner:  
234
235     perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames> 
236
237 on the source files.
238
239 Move the files manually into the correct folders.
240
241 Move the files to their final destination: This will
242 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
243 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
244 the default C<@INC> in the Preferences menu item in the
245 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
246 automagically).  Create whatever directory structures are required
247 (i.e., for C<Some::Module>, create
248 C<$ENV{MACPERL}site_lib:Some:> and put
249 C<Module.pm> in that directory).
250
251 Run the following script (or something like it):
252
253      #!perl -w
254      use AutoSplit;
255      my $dir = "${MACPERL}site_perl";
256      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
257
258 Eventually there should be a way to automate the installation process; some
259 solutions exist, but none are ready for the general public yet.
260
261 =item *
262
263 B<If you're on the DJGPP port of DOS,>
264
265    A. DECOMPRESS
266
267 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
268 will both uncompress and unpack.  
269
270    B. UNPACK
271
272 See above.
273
274    C. BUILD
275
276 Go into the newly-created directory and type:
277
278       perl Makefile.PL
279       make
280       make test
281
282 You will need the packages mentioned in F<README.dos>
283 in the Perl distribution.
284
285    D. INSTALL
286
287 While still in that directory, type:
288
289      make install       
290      
291 You will need the packages mentioned in F<README.dos> in the Perl distribution.
292
293 =item *
294
295 B<If you're on OS/2,>
296
297 Get the EMX development suite and gzip/tar, from either Hobbes (
298 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
299 the instructions for Unix.
300
301 =item *
302
303 B<If you're on VMS,>
304
305 When downloading from CPAN, save your file with a F<.tgz>
306 extension instead of F<.tar.gz>.  All other periods in the
307 filename should be replaced with underscores.  For example,
308 C<Your-Module-1.33.tar.gz> should be downloaded as
309 C<Your-Module-1_33.tgz>.
310
311 A. DECOMPRESS
312
313 Type 
314
315     gzip -d Your-Module.tgz
316
317 or, for zipped modules, type 
318
319     unzip Your-Module.zip
320
321 Executables for gzip, zip, and VMStar ( Alphas:
322 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
323 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).  
324
325 gzip and tar
326 are also available at ftp://ftp.digital.com/pub/VMS.
327
328 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
329 package.  The former is a simple compression tool; the latter permits
330 creation of multi-file archives.
331
332 B. UNPACK
333
334 If you're using VMStar:
335
336      VMStar xf Your-Module.tar
337
338 Or, if you're fond of VMS command syntax:
339
340      tar/extract/verbose Your_Module.tar
341
342 C. BUILD 
343
344 Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at  http://www.madgoat.com ).  Then type this to create the
345 DESCRIP.MMS for the module: 
346
347     perl Makefile.PL
348
349 Now you're ready to build:
350
351     mms
352     mms test
353
354 Substitute C<mmk> for C<mms> above if you're using MMK.
355
356 D. INSTALL
357
358 Type 
359
360     mms install
361
362 Substitute C<mmk> for C<mms> above if you're using MMK.
363
364 =item *
365
366 B<If you're on MVS>,
367
368 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
369 ASCII to EBCDIC.
370
371 A. DECOMPRESS 
372
373       Decompress the file with C<gzip -d yourmodule.tar.gz>
374
375       You can get gzip from 
376       http://www.s390.ibm.com/products/oe/bpxqp1.html.
377
378 B. UNPACK
379
380 Unpack the result with 
381
382      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
383
384 The BUILD and INSTALL steps are identical to those for Unix.  Some
385 modules generate Makefiles that work better with GNU make, which is
386 available from http://www.mks.com/s390/gnu/index.htm.
387
388 =back
389
390 =head1 HEY
391
392 If you have any suggested changes for this page, let me know.  Please
393 don't send me mail asking for help on how to install your modules.
394 There are too many modules, and too few Orwants, for me to be able to
395 answer or even acknowledge all your questions.  Contact the module
396 author instead, or post to comp.lang.perl.modules, or ask someone
397 familiar with Perl on your operating system.
398
399 =head1 AUTHOR
400
401 Jon Orwant 
402
403 orwant@tpj.com
404
405 The Perl Journal, http://tpj.com
406
407 with invaluable help from Brandon Allbery, Charles Bailey, Graham
408 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
409 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
410 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
411 Sugalski, Larry Virden, and Ilya Zakharevich.
412
413 July 22, 1998
414
415 =head1 COPYRIGHT
416
417 Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
418
419 Permission is granted to make and distribute verbatim copies of this
420 documentation provided the copyright notice and this permission notice are
421 preserved on all copies.
422
423 Permission is granted to copy and distribute modified versions of this
424 documentation under the conditions for verbatim copying, provided also
425 that they are marked clearly as modified versions, that the authors'
426 names and title are unchanged (though subtitles and additional
427 authors' names may be added), and that the entire resulting derived
428 work is distributed under the terms of a permission notice identical
429 to this one.
430
431 Permission is granted to copy and distribute translations of this
432 documentation into another language, under the above conditions for
433 modified versions.
434