home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / pod / perlmodinstall.pod < prev    next >
Text File  |  2000-03-18  |  12KB  |  438 lines

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