Change 14064 by pudge@pudge-mobile on 2002/01/04 20:13:36
A few doc updates from bleadperl
Affected files ...
.... //depot/maint-5.6/macperl/pod/perlmodinstall.pod#2 edit
.... //depot/maint-5.6/macperl/pod/perlport.pod#7 edit
Differences ...
==== //depot/maint-5.6/macperl/pod/perlmodinstall.pod#2 (text) ====
Index: perl/pod/perlmodinstall.pod
--- perl/pod/perlmodinstall.pod.~1~ Fri Jan 4 13:30:05 2002
+++ perl/pod/perlmodinstall.pod Fri Jan 4 13:30:05 2002
@@ -5,23 +5,32 @@
=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 CPAN. CPAN is the Comprehensive Perl Archive
-Network and can be accessed at http://www.perl.com/CPAN/, or searched
-via http://cpan.perl.com/ and
-http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
+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.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
+http://www.cpan.org/ , and searched at http://search.cpan.org/ .
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 F<.tar.gz> (or, less often, F<.zip>).
-You know there's a tasty module inside. You must now take four
-steps:
+First, are you sure that the module isn't already on your system? Try
+C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
+instance, C<perl -MCGI::Carp -e 1>.
+
+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 C<perl -e
+"print qq(@INC)">.) 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.
+
+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:
=over 5
@@ -36,28 +45,30 @@
=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
+<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
+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">.
+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";>. If you're on a system
+that requires superuser/root access to install modules into the
+directories you see when you type C<perl -e "print qq(@INC)">, you'll
+want to install them into a local directory (such as your home
+directory) and use this approach.
=over 4
=item *
-B<If you're on Unix,>
+B<If you're on a Unix or Linux system,>
You can use Andreas Koenig's CPAN module
-(which comes standard with Perl, or can itself be downloaded
-from http://www.perl.com/CPAN/modules/by-module/CPAN)
+( http://www.cpan.org/modules/by-module/CPAN )
to automate the following steps, from DECOMPRESS through INSTALL.
A. DECOMPRESS
@@ -82,33 +93,43 @@
make
make test
+or
+
+ perl Makefile.PL PREFIX=/my/perl_directory
+
+to install it locally. (Remember that if you do this, you'll have to
+put C<use lib "/my/perl_directory";> near the top of the program that
+is to use this module.
+
D. INSTALL
While still in that directory, type:
make install
-Make sure you have appropriate permissions to install the module
+Make sure you have the appropriate permissions to install the module
in your Perl 5 library directory. Often, you'll need to be root.
-Perl maintains a record of all module installations. To look at
-this list, simply type:
-
- perldoc perllocal
-
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, I<and> the
+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>
+B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
+
+First, type C<ppm> from a shell and see whether ActiveState's PPM
+repository has your module. If so, you can install it with C<ppm> 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.
A. DECOMPRESS
-You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
+You can use the shareware Winzip ( http://www.winzip.com ) to
decompress and unpack modules.
B. UNPACK
@@ -117,11 +138,12 @@
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
-CPAN for others to use. If it doesn't, go to INSTALL.
+Does the module require compilation (i.e. does it have files that end
+in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it doesn't, go to INSTALL.
+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
+the C<nmake> utility, available at
+ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.
D. INSTALL
@@ -132,65 +154,16 @@
=item *
-B<If you're running Windows 95 or NT with the core Windows distribution of
-Perl,>
+B<If you're using a Macintosh,>
- A. DECOMPRESS
-When you download the module, make sure it ends in either
-F<.tar.gz> or F<.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 B<WinZip> program ( http://www.winzip.com ) to
-decompress and unpack modules.
-
-Or, you can use InfoZip's C<unzip> utility (
-http://www.cdrom.com/pub/infozip/ ) 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
-
-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
-First thing you should do is make sure you have the latest B<cpan-mac>
-distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has
-utilities for doing all of the steps. Read the cpan-mac directions
-carefully and install it. If you choose not to use cpan-mac
-for some reason, there are alternatives listed here.
+First, make sure you have the latest B<cpan-mac> distribution (
+http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
+doing all of the steps. Read the cpan-mac directions carefully and
+install it. If you choose not to use cpan-mac for some reason, there
+are alternatives listed here.
After installing cpan-mac, drop the module archive on the
B<untarzipme> droplet, which will decompress and unpack for you.
@@ -290,7 +263,7 @@
While still in that directory, type:
- make install
+ make install
You will need the packages mentioned in F<README.dos> in the Perl distribution.
@@ -306,8 +279,8 @@
B<If you're on VMS,>
-When downloading from CPAN, save your file with a F<.tgz>
-extension instead of F<.tar.gz>. All other periods in the
+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>.
@@ -322,12 +295,14 @@
unzip Your-Module.zip
-Executables for gzip, zip, and VMStar ( Alphas:
-http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
-http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
+Executables for gzip, zip, and VMStar:
+
+ http://www.openvms.digital.com/freeware/
+ http://www.crinoid.com/utils/
+
+and their source code:
-gzip and tar
-are also available at ftp://ftp.digital.com/pub/VMS.
+ http://www.fsf.org/order/ftp.html
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
@@ -345,9 +320,9 @@
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:
+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
@@ -375,10 +350,10 @@
A. DECOMPRESS
- Decompress the file with C<gzip -d yourmodule.tar.gz>
+Decompress the file with C<gzip -d yourmodule.tar.gz>
- You can get gzip from
- http://www.s390.ibm.com/products/oe/bpxqp1.html.
+You can get gzip from
+http://www.s390.ibm.com/products/oe/bpxqp1.html
B. UNPACK
@@ -392,7 +367,6 @@
=back
-
=head1 PORTABILITY
Note that not all modules will work with on all platforms.
@@ -455,19 +429,17 @@
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.
+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.
-First version July 22, 1998
-
-Last Modified August 22, 2000
+First version July 22, 1998; last revised November 21, 2001.
=head1 COPYRIGHT
-Copyright (C) 1998, 2000 Jon Orwant. All Rights Reserved.
+Copyright (C) 1998, 2001 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
@@ -484,3 +456,4 @@
Permission is granted to copy and distribute translations of this
documentation into another language, under the above conditions for
modified versions.
+
==== //depot/maint-5.6/macperl/pod/perlport.pod#7 (text) ====
Index: perl/pod/perlport.pod
--- perl/pod/perlport.pod.~1~ Fri Jan 4 13:30:05 2002
+++ perl/pod/perlport.pod Fri Jan 4 13:30:05 2002
@@ -267,6 +267,13 @@
separator, or go native and use C<.> for path separator and C<:> to
signal filesystems and disk names.
+Don't assume UNIX filesystem access semantics: that read, write,
+and execute are all the permissions there are, and even if they exist,
+that their semantics (for example what do r, w, and x mean on
+a directory) are the UNIX ones. The various UNIX/POSIX compatibility
+layers usually try to make interfaces like chmod() work, but sometimes
+there simply is no good mapping.
+
If all this is intimidating, have no (well, maybe only a little)
fear. There are modules that can help. The File::Spec modules
provide methods to do the Right Thing on whatever platform happens
@@ -423,13 +430,13 @@
The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
even on all Unix platforms.
-Do not use either the bare result of C<pack("N", 10, 20, 30, 40)>
-or bare v-strings (such as C<v10.20.30.40>) or to represent
-IPv4 addresses: both forms just pack the four bytes into network order.
-That this would be equal to the C language C<in_addr> struct (which is
-what the socket code internally uses) is not guaranteed. To be
-portable use the routines of the Socket extension, such as
-C<inet_aton()>, C<inet_ntoa()>, and C<sockaddr_in()>.
+Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
+bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
+both forms just pack the four bytes into network order. That this
+would be equal to the C language C<in_addr> struct (which is what the
+socket code internally uses) is not guaranteed. To be portable use
+the routines of the Socket extension, such as C<inet_aton()>,
+C<inet_ntoa()>, and C<sockaddr_in()>.
The rule of thumb for portable code is: Do it all in portable Perl, or
use a module (that may internally implement it with platform-specific
@@ -538,13 +545,31 @@
Most multi-user platforms provide basic levels of security, usually
implemented at the filesystem level. Some, however, do
-not--unfortunately. Thus the notion of user id, or "home" directory,
+not-- unfortunately. Thus the notion of user id, or "home" directory,
or even the state of being logged-in, may be unrecognizable on many
platforms. If you write programs that are security-conscious, it
is usually best to know what type of system you will be running
under so that you can write code explicitly for that platform (or
class of platforms).
+Don't assume the UNIX filesystem access semantics: the operating
+system or the filesystem may be using some ACL systems, which are
+richer languages than the usual rwx. Even if the rwx exist,
+their semantics might be different.
+
+(From security viewpoint testing for permissions before attempting to
+do something is silly anyway: if one tries this, there is potential
+for race conditions-- someone or something might change the
+permissions between the permissions check and the actual operation.
+Just try the operation.)
+
+Don't assume the UNIX user and group semantics: especially, don't
+expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
+for switching identities (or memberships).
+
+Don't assume set-uid and set-gid semantics. (And even if you do,
+think twice: set-uid and set-gid are a known can of security worms.)
+
=head2 Style
For those times when it is necessary to have platform-specific code,
@@ -559,7 +584,7 @@
programs to aid in the testing, or when (as noted above) the tests
assume certain things about the filesystem and paths. Be careful
not to depend on a specific output style for errors, such as when
-checking C<$!> after an system call. Some platforms expect a certain
+checking C<$!> after a system call. Some platforms expect a certain
output format, and perl on those platforms may have been adjusted
accordingly. Most specifically, don't anchor a regex when testing
an error value.
@@ -1416,6 +1441,17 @@
Does not automatically flush output handles on some platforms.
(SunOS, Solaris, HP-UX)
+=item exit EXPR
+
+=item exit
+
+Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
+mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
+with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
+function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
+(C<1>); this mapping cannot be overridden. Any other argument to exit()
+is used directly as Perl's exit status. (VMS)
+
=item fcntl FILEHANDLE,FUNCTION,SCALAR
Not implemented. (Win32, VMS)
@@ -1559,17 +1595,6 @@
Not implemented. (Plan9, Win32)
-=item exit EXPR
-
-=item exit
-
-Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
-mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
-with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
-function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
-(C<1>); this mapping cannot be overridden. Any other argument to exit()
-is used directly as Perl's exit status. (VMS)
-
=item getsockopt SOCKET,LEVEL,OPTNAME
Not implemented. (Plan9)
@@ -1658,11 +1683,11 @@
=item select RBITS,WBITS,EBITS,TIMEOUT
-Only implemented on sockets. (Win32)
+Only implemented on sockets. (Win32, VMS)
Only reliable on sockets. (S<RISC OS>)
-Note that the C<socket FILEHANDLE> form is generally portable.
+Note that the C<select FILEHANDLE> form is generally portable.
=item semctl ID,SEMNUM,CMD,ARG
@@ -1823,7 +1848,7 @@
=item utime LIST
-Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
+Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
May not behave as expected. Behavior depends on the C runtime
library's implementation of utime(), and the filesystem being
@@ -1937,7 +1962,7 @@
As of early 2001 (the Perl releases 5.6.1 and 5.7.1), the following
platforms are able to build Perl from the standard source code
-distribution available at http://www.perl.com/CPAN/src/index.html
+distribution available at http://www.cpan.org/src/index.html
AIX
AmigaOS
@@ -2063,7 +2088,7 @@
Netware
The following platforms have their own source code distributions and
-binaries available via http://www.perl.com/CPAN/ports/index.html:
+binaries available via http://www.cpan.org/ports/index.html:
Perl release
@@ -2072,7 +2097,7 @@
Tandem Guardian 5.004
The following platforms have only binaries available via
-http://www.perl.com/CPAN/ports/index.html :
+http://www.cpan.org/ports/index.html :
Perl release
@@ -2083,7 +2108,7 @@
Although we do suggest that you always build your own Perl from
the source code, both for maximal configurability and for security,
in case you are in a hurry you can check
-http://www.perl.com/CPAN/ports/index.html for binary distributions.
+http://www.cpan.org/ports/index.html for binary distributions.
=head1 SEE ALSO
End of Patch.
