diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlmodinstall.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlmodinstall.1 | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlmodinstall.1 b/upstream/mageia-cauldron/man1/perlmodinstall.1 new file mode 100644 index 00000000..09805279 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlmodinstall.1 @@ -0,0 +1,400 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLMODINSTALL 1" +.TH PERLMODINSTALL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlmodinstall \- Installing CPAN Modules +.SH DESCRIPTION +.IX Header "DESCRIPTION" +You can think of a module as the fundamental unit of reusable Perl +code; see 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 <https://www.cpan.org/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 +<https://www.cpan.org/> , and searched at <https://metacpan.org/> . +.PP +This documentation is for people who want to download CPAN modules +and install them on their own computer. +.SS PREAMBLE +.IX Subsection "PREAMBLE" +First, are you sure that the module isn't already on your system? Try +\&\f(CW\*(C`perl \-MFoo \-e 1\*(C'\fR. (Replace "Foo" with the name of the module; for +instance, \f(CW\*(C`perl \-MCGI::Carp \-e 1\*(C'\fR.) +.PP +If you don't see an error message, you have the module. (If you do +see an error message, it's still possible you have the module, but +that it's not in your path, which you can display with \f(CWperl \-e +"print qq(@INC)"\fR.) For the remainder of this document, we'll assume +that you really honestly truly lack an installed module, but have +found it on the CPAN. +.PP +So now 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: +.IP "\fBDECOMPRESS\fR the file" 5 +.IX Item "DECOMPRESS the file" +.PD 0 +.IP "\fBUNPACK\fR the file into a directory" 5 +.IX Item "UNPACK the file into a directory" +.IP "\fBBUILD\fR the module (sometimes unnecessary)" 5 +.IX Item "BUILD the module (sometimes unnecessary)" +.IP "\fBINSTALL\fR the module." 5 +.IX Item "INSTALL the module." +.PD +.PP +Here's how to perform each step for each operating system. This is +<not> a substitute for reading the README and INSTALL files that +might have come with your module! +.PP +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 \f(CW\*(C`perl Makefile.PL\*(C'\fR, you can substitute \f(CW\*(C`perl Makefile.PL +PREFIX=/my/perl_directory\*(C'\fR to install the modules into +\&\fI/my/perl_directory\fR. Then you can use the modules from your Perl +programs with \f(CW\*(C`use lib "/my/perl_directory/lib/site_perl";\*(C'\fR or +sometimes just \f(CW\*(C`use "/my/perl_directory";\*(C'\fR. If you're on a system +that requires superuser/root access to install modules into the +directories you see when you type \f(CW\*(C`perl \-e "print qq(@INC)"\*(C'\fR, you'll +want to install them into a local directory (such as your home +directory) and use this approach. +.IP \(bu 4 +\&\fBIf you're on a Unix or Unix-like system,\fR +.Sp +You can use Andreas Koenig's CPAN module +( <https://metacpan.org/release/CPAN> ) +to automate the following steps, from DECOMPRESS through INSTALL. +.Sp +A. DECOMPRESS +.Sp +Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR +.Sp +You can get gzip from <ftp://prep.ai.mit.edu/pub/gnu/> +.Sp +Or, you can combine this step with the next to save disk space: +.Sp +.Vb 1 +\& gzip \-dc yourmodule.tar.gz | tar \-xof \- +.Ve +.Sp +B. UNPACK +.Sp +Unpack the result with \f(CW\*(C`tar \-xof yourmodule.tar\*(C'\fR +.Sp +C. BUILD +.Sp +Go into the newly-created directory and type: +.Sp +.Vb 2 +\& perl Makefile.PL +\& make test +.Ve +.Sp +or +.Sp +.Vb 1 +\& perl Makefile.PL PREFIX=/my/perl_directory +.Ve +.Sp +to install it locally. (Remember that if you do this, you'll have to +put \f(CW\*(C`use lib "/my/perl_directory";\*(C'\fR near the top of the program that +is to use this module. +.Sp +D. INSTALL +.Sp +While still in that directory, type: +.Sp +.Vb 1 +\& make install +.Ve +.Sp +Make sure you have the appropriate permissions to install the module +in your Perl 5 library directory. Often, you'll need to be root. +.Sp +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, \fBand\fR 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. +.IP \(bu 4 +\&\fBIf you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),\fR +.Sp +First, type \f(CW\*(C`ppm\*(C'\fR from a shell and see whether ActiveState's PPM +repository has your module. If so, you can install it with \f(CW\*(C`ppm\*(C'\fR and +you won't have to bother with any of the other steps here. You might +be able to use the CPAN instructions from the "Unix or Linux" section +above as well; give it a try. Otherwise, you'll have to follow the +steps below. +.Sp +.Vb 1 +\& A. DECOMPRESS +.Ve +.Sp +You can use the +open source 7\-zip ( <https://www.7\-zip.org/> ) +or the shareware Winzip ( <https://www.winzip.com> ) to +decompress and unpack modules. +.Sp +.Vb 1 +\& B. UNPACK +.Ve +.Sp +If you used WinZip, this was already done for you. +.Sp +.Vb 1 +\& C. BUILD +.Ve +.Sp +You'll need either \f(CW\*(C`nmake\*(C'\fR or \f(CW\*(C`gmake\*(C'\fR. +.Sp +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, life is now +officially tough for you, because you have to compile the module +yourself (no easy feat on Windows). You'll need a compiler such as +Visual C++. Alternatively, you can download a pre-built PPM package +from ActiveState. +<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/> +.Sp +Go into the newly-created directory and type: +.Sp +.Vb 2 +\& perl Makefile.PL +\& nmake test +\& +\& +\& D. INSTALL +.Ve +.Sp +While still in that directory, type: +.Sp +.Vb 1 +\& nmake install +.Ve +.IP \(bu 4 +\&\fBIf you're on OS/2,\fR +.Sp +Get the EMX development suite and gzip/tar from Hobbes ( +<http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2/dev/emx/v0.9d> ), and then follow +the instructions for Unix. +.IP \(bu 4 +\&\fBIf you're on VMS,\fR +.Sp +When downloading from CPAN, save your file with a \f(CW\*(C`.tgz\*(C'\fR +extension instead of \f(CW\*(C`.tar.gz\*(C'\fR. All other periods in the +filename should be replaced with underscores. For example, +\&\f(CW\*(C`Your\-Module\-1.33.tar.gz\*(C'\fR should be downloaded as +\&\f(CW\*(C`Your\-Module\-1_33.tgz\*(C'\fR. +.Sp +A. DECOMPRESS +.Sp +Type +.Sp +.Vb 1 +\& gzip \-d Your\-Module.tgz +.Ve +.Sp +or, for zipped modules, type +.Sp +.Vb 1 +\& unzip Your\-Module.zip +.Ve +.Sp +Executables for gzip, zip, and VMStar: +.Sp +.Vb 1 +\& http://www.hp.com/go/openvms/freeware/ +.Ve +.Sp +and their source code: +.Sp +.Vb 1 +\& http://www.fsf.org/order/ftp.html +.Ve +.Sp +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. +.Sp +B. UNPACK +.Sp +If you're using VMStar: +.Sp +.Vb 1 +\& VMStar xf Your\-Module.tar +.Ve +.Sp +Or, if you're fond of VMS command syntax: +.Sp +.Vb 1 +\& tar/extract/verbose Your_Module.tar +.Ve +.Sp +C. BUILD +.Sp +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: +.Sp +.Vb 1 +\& perl Makefile.PL +.Ve +.Sp +Now you're ready to build: +.Sp +.Vb 1 +\& mms test +.Ve +.Sp +Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK. +.Sp +D. INSTALL +.Sp +Type +.Sp +.Vb 1 +\& mms install +.Ve +.Sp +Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK. +.IP \(bu 4 +\&\fBIf you're on MVS\fR, +.Sp +Introduce the \fI.tar.gz\fR file into an HFS as binary; don't translate from +ASCII to EBCDIC. +.Sp +A. DECOMPRESS +.Sp +Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR +.Sp +You can get gzip from +<http://www.s390.ibm.com/products/oe/bpxqp1.html> +.Sp +B. UNPACK +.Sp +Unpack the result with +.Sp +.Vb 1 +\& pax \-o to=IBM\-1047,from=ISO8859\-1 \-r < yourmodule.tar +.Ve +.Sp +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/> +.SH PORTABILITY +.IX Header "PORTABILITY" +Note that not all modules will work with on all platforms. +See perlport for more information on portability issues. +Read the documentation to see if the module will work on your +system. There are basically three categories +of modules that will not work "out of the box" with all +platforms (with some possibility of overlap): +.IP \(bu 4 +\&\fBThose that should, but don't.\fR These need to be fixed; consider +contacting the author and possibly writing a patch. +.IP \(bu 4 +\&\fBThose that need to be compiled, where the target platform +doesn't have compilers readily available.\fR (These modules contain +\&\fI.xs\fR or \fI.c\fR files, usually.) You might be able to find +existing binaries on the CPAN or elsewhere, or you might +want to try getting compilers and building it yourself, and then +release the binary for other poor souls to use. +.IP \(bu 4 +\&\fBThose that are targeted at a specific platform.\fR +(Such as the Win32:: modules.) If the module is targeted +specifically at a platform other than yours, you're out +of luck, most likely. +.PP +Check the CPAN Testers if a module should work with your platform +but it doesn't behave as you'd expect, or you aren't sure whether or +not a module will work under your platform. If the module you want +isn't listed there, you can test it yourself and let CPAN Testers know, +you can join CPAN Testers, or you can request it be tested. +.PP +.Vb 1 +\& https://cpantesters.org/ +.Ve +.SH HEY +.IX Header "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, ask someone familiar with Perl on your operating +system, or if all else fails, file a ticket at <https://rt.cpan.org/>. +.SH AUTHOR +.IX Header "AUTHOR" +Jon Orwant +.PP +orwant@medita.mit.edu +.PP +with invaluable help from Chris Nandor, and valuable help from Brandon +Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko +Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas +J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy, +Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich. +.PP +First version July 22, 1998; last revised November 21, 2001. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved. +.PP +This document may be distributed under the same terms as Perl itself. |