add perlmodinstall, regen perltoc

p4raw-id: //depot/perl@1642

1 files changed, 407 insertions, 0 deletions

diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod
new file mode 100644
index 0000000000..6eda8ecce9
--- /dev/null
+++ b/pod/perlmodinstall.pod
@@ -0,0 +1,407 @@
+=head1 NAME
+
+perlmodinstall - Installing CPAN Modules
+
+=head1 DESCRIPTION
+
+You can think of a module as the fundamental unit of reusable Perl
+code; see L<perlmod> for details.  Whenever anyone creates a chunk of
+Perl code that they think will be useful to the world, they register
+as a Perl developer at http://www.perl.com/CPAN/modules/04pause.html
+so that they can then upload their code to the CPAN.  The CPAN is the
+Comprehensive Perl Archive Network and can be accessed at
+http://www.perl.com/CPAN/.
+
+This documentation is for people who want to download CPAN modules
+and install them on their own computer.
+
+=head2 PREAMBLE
+
+You have a file ending in .tar.gz (or, less often, .zip).  You know
+there's a tasty module inside.  There are four steps you must now
+take:
+
+=over 5
+
+=item B<DECOMPRESS> the file
+=item B<UNPACK> the file into a directory
+=item B<BUILD> the module (sometimes unnecessary)
+=item B<INSTALL> the module.
+
+=back
+
+Here's how to perform each step for each operating system.  This is
+I<not> a substitute for reading the README and INSTALL files that
+might have come with your module!
+
+Also note that these instructions are tailored for installing the
+module into your system's repository of Perl modules.  But you can
+install modules into any directory you wish.  For instance, where I
+say C<perl Makefile.PL>, you can substitute C<perl
+Makefile.PL PREFIX=/my/perl_directory> to install the modules
+into C</my/perl_directory>.  Then you can use the modules
+from your Perl programs with C<use lib
+"/my/perl_directory/lib/site_perl";> or sometimes just C<use
+"/my/perl_directory";>.  
+
+=over 4
+
+=item *
+
+B<If you're on Unix,>
+
+You can use Andreas Koenig's CPAN module 
+( http://www.perl.com/CPAN/modules/by-module/CPAN ) 
+to automate the following steps, from DECOMPRESS through INSTALL.
+
+A. DECOMPRESS 
+
+Decompress the file with C<gzip -d yourmodule.tar.gz>
+
+You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. 
+
+Or, you can combine this step with the next to save disk space:
+
+     gzip -dc yourmodule.tar.gz | tar -xof -
+
+B. UNPACK
+
+Unpack the result with C<tar -xof yourmodule.tar>
+
+C. BUILD
+
+Go into the newly-created directory and type:
+
+      perl Makefile.PL
+      make
+      make test
+
+D. INSTALL
+
+While still in that directory, type:
+
+      make install
+
+Make sure you have the appropriate permissions to install the module
+in your Perl 5 library directory.  Often, you'll need to be root.
+
+That's all you need to do on Unix systems with dynamic linking.
+Most Unix systems have dynamic linking -- if yours doesn't, or if for
+another reason you have a statically-linked perl, B<and> the
+module requires compilation, you'll need to build a new Perl binary
+that includes the module.  Again, you'll probably need to be root.
+
+=item *
+
+B<If you're running Windows 95 or NT with the ActiveState port of Perl>
+
+   A. DECOMPRESS
+
+You can use the shareware Winzip ( http://www.winzip.com ) to
+decompress and unpack modules.
+
+   B. UNPACK
+
+If you used WinZip, this was already done for you.
+
+   C. BUILD
+
+Does the module require compilation (i.e. does it have files
+that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
+your own.  You can try compiling it yourself if you have a C compiler.
+If you're successful, consider uploading the resulting binary to the
+CPAN for others to use.  If it doesn't, go to INSTALL.
+
+   D. INSTALL
+
+Copy the module into your Perl's I<lib> directory.  That'll be one
+of the directories you see when you type 
+
+   perl -e 'print "@INC"'
+
+=item *
+
+B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
+
+   A. DECOMPRESS
+
+When you download the module, make sure it ends in either
+C<.tar.gz> or C<.zip>.  Windows browsers sometimes
+download C<.tar.gz> files as C<_tar.tar>, because
+early versions of Windows prohibited more than one dot in a filename.
+
+You can use the shareware WinZip ( http://www.winzip.com ) to
+decompress and unpack modules.
+
+Or, you can use InfoZip's C<unzip> utility (
+http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
+C<.zip> files; type C<unzip yourmodule.zip> in
+your shell.
+
+Or, if you have a working C<tar> and C<gzip>, you can
+type
+
+   gzip -cd yourmodule.tar.gz | tar xvf -
+
+in the shell to decompress C<yourmodule.tar.gz>.  This will
+UNPACK your module as well.
+
+   B. UNPACK
+
+All of the methods in DECOMPRESS will have done this for you.
+
+   C. BUILD
+
+Go into the newly-created directory and type:
+
+      perl Makefile.PL
+      dmake
+      dmake test
+
+Depending on your perl configuration, C<dmake> might not be
+available.  You might have to substitute whatever C<perl
+-V:make> says. (Usually, that will be C<nmake> or
+C<make>.)
+
+   D. INSTALL
+
+While still in that directory, type:
+
+      dmake install
+
+=item *
+
+B<If you're using a Macintosh,>
+
+A. DECOMPRESS
+
+You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in
+combination with I<DropStuff with Expander Enhancer>
+(shareware), or the freeware MacGzip (
+http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
+
+B. UNPACK
+
+If you're using DropStuff or Stuffit, you can just extract the tar
+archive.  Otherwise, you can use the freeware I<suntar> (
+http://www.cirfid.unibo.it/~speranza ).
+
+C. BUILD
+
+Does the module require compilation? 
+
+1. If it does,
+
+Overview: You need MPW and a combination of new and old CodeWarrior
+compilers for MPW and libraries.  Makefiles created for building under
+MPW use the Metrowerks compilers.  It's most likely possible to build
+without other compilers, but it has not been done successfully, to our
+knowledge.  Read the documentation in MacPerl: Power and Ease (
+http://www.ptf.com/macperl/ ) on porting/building extensions, or find
+an existing precompiled binary, or hire someone to build it for you.
+
+Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
+to build it for you.  To subscribe to the mac-perl mailing list, send
+mail to mac-perl-request@iis.ee.ethz.ch.
+
+2. If the module doesn't require compilation, go to INSTALL.
+
+D. INSTALL
+
+Make sure the newlines for the modules are in Mac format, not Unix format.
+Move the files manually into the correct folders.
+
+Move the files to their final destination: This will
+most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
+C<HD:MacPerl folder:site_lib:>).  You can add new paths to
+the default C<@INC> in the Preferences menu item in the
+MacPerl application (C<$ENV{MACPERL}site_lib:> is added
+automagically).  Create whatever directory structures are required
+(i.e., for C<Some::Module>, create
+C<$ENV{MACPERL}site_lib:Some:> and put
+C<Module.pm> in that directory).
+
+Run the following script (or something like it):
+
+     #!perl -w
+     use AutoSplit;
+     my $dir = "${MACPERL}site_perl";
+     autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
+
+Eventually there should be a way to automate the installation process; some
+solutions exist, but none are ready for the general public yet.
+
+=item *
+
+B<If you're on the DJGPP port of DOS,>
+
+   A. DECOMPRESS
+
+djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
+will both uncompress and unpack.  
+
+   B. UNPACK
+
+See above.
+
+   C. BUILD
+
+Go into the newly-created directory and type:
+
+      perl Makefile.PL
+      make
+      make test
+
+You will need the packages mentioned in C<Readme.dos>
+in the Perl distribution.
+
+   D. INSTALL
+
+While still in that directory, type:
+
+     make install	
+     
+You will need the packages mentioned in Readme.dos in the Perl distribution.
+
+=item *
+
+B<If you're on OS/2,>
+
+Get the EMX development suite and gzip/tar, from either Hobbes (
+http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
+the instructions for Unix.
+
+=item *
+
+B<If you're on VMS,>
+
+When downloading from CPAN, save your file with a C<.tgz>
+extension instead of C<.tar.gz>.  All other periods in the
+filename should be replaced with underscores.  For example,
+C<Your-Module-1.33.tar.gz> should be downloaded as
+C<Your-Module-1_33.tgz>.
+
+A. DECOMPRESS
+
+Type 
+
+    gzip -d Your-Module.tgz
+
+or, for zipped modules, type 
+
+    unzip Your-Module.zip
+
+Executables for gzip, zip, and VMStar ( Alphas:
+http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
+http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).  
+
+gzip and tar
+are also available at ftp://ftp.digital.com/pub/VMS.
+
+Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
+package.  The former is a simple compression tool; the latter permits
+creation of multi-file archives.
+
+B. UNPACK
+
+If you're using VMStar:
+
+     VMStar xf Your-Module.tar
+
+Or, if you're fond of VMS command syntax:
+
+     tar/extract/verbose Your_Module.tar
+
+C. BUILD 
+
+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
+DESCRIP.MMS for the module: 
+
+    perl Makefile.PL
+
+Now you're ready to build:
+
+    mms
+    mms test
+
+Substitute C<mmk> for C<mms> above if you're using MMK.
+
+D. INSTALL
+
+Type 
+
+    mms install
+
+Substitute C<mmk> for C<mms> above if you're using MMK.
+
+=item *
+
+B<If you're on MVS>,
+
+Introduce the .tar.gz file into an HFS as binary; don't translate from
+ASCII to EBCDIC.
+
+A. DECOMPRESS 
+
+      Decompress the file with C<gzip -d yourmodule.tar.gz>
+
+      You can get gzip from 
+      http://www.s390.ibm.com/products/oe/bpxqp1.html.
+
+B. UNPACK
+
+Unpack the result with 
+
+     pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
+
+The BUILD and INSTALL steps are identical to those for Unix.  Some
+modules generate Makefiles that work better with GNU make, which is
+available from http://www.mks.com/s390/gnu/index.htm.
+
+=back
+
+=head1 HEY
+
+If you have any suggested changes for this page, let me know.  Please
+don't send me mail asking for help on how to install your modules.
+There are too many modules, and too few Orwants, for me to be able to
+answer or even acknowledge all your questions.  Contact the module
+author instead, or post to comp.lang.perl.modules, or ask someone
+familiar with Perl on your operating system.
+
+=head1 AUTHOR
+
+Jon Orwant 
+
+orwant@tpj.com
+
+The Perl Journal, http://tpj.com
+
+with invaluable help from Brandon Allbery, Charles Bailey, Graham
+Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
+Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
+Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
+Sugalski, Larry Virden, and Ilya Zakharevich.
+
+July 22, 1998
+
+=head1 COPYRIGHT
+
+Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
+
+Permission is granted to make and distribute verbatim copies of this
+documentation provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+documentation under the conditions for verbatim copying, provided also
+that they are marked clearly as modified versions, that the authors'
+names and title are unchanged (though subtitles and additional
+authors' names may be added), and that the entire resulting derived
+work is distributed under the terms of a permission notice identical
+to this one.
+
+Permission is granted to copy and distribute translations of this
+documentation into another language, under the above conditions for
+modified versions.
+