Perl Kit, Version 5

             Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006 by Larry Wall and others

			    All rights reserved.

    This program is free software; you can redistribute it and/or modify
    it under the terms of either:

	a) the GNU General Public License as published by the Free
	Software Foundation; either version 1, or (at your option) any
	later version, or

	b) the "Artistic License" which comes with this Kit.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
    the GNU General Public License or the Artistic License for more details.

    You should have received a copy of the Artistic License with this
    Kit, in the file named "Artistic".  If not, I'll be glad to provide one.

    You should also have received a copy of the GNU General Public License
    along with this program in the file named "Copying". If not, write to the
    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    02111-1307, USA or visit their web page on the internet at
    http://www.gnu.org/copyleft/gpl.html.

    For those of you that choose to use the GNU General Public License,
    my interpretation of the GNU General Public License is that no Perl
    script falls under the terms of the GPL unless you explicitly put
    said script under the terms of the GPL yourself.  Furthermore, any
    object code linked with perl does not automatically fall under the
    terms of the GPL, provided such object code only adds definitions
    of subroutines and variables, and does not otherwise impair the
    resulting interpreter from executing any standard Perl script.  I
    consider linking in C subroutines in this manner to be the moral
    equivalent of defining subroutines in the Perl language itself.  You
    may sell such an object file as proprietary provided that you provide
    or offer to provide the Perl source, as specified by the GNU General
    Public License.  (This is merely an alternate way of specifying input
    to the program.)  You may also sell a binary produced by the dumping of
    a running Perl script that belongs to you, provided that you provide or
    offer to provide the Perl source as specified by the GPL.  (The
    fact that a Perl interpreter and your code are in the same binary file
    is, in this case, a form of mere aggregation.)  This is my interpretation
    of the GPL.  If you still have concerns or difficulties understanding
    my intent, feel free to contact me.  Of course, the Artistic License
    spells all this out for your protection, so you may prefer to use that.

--------------------------------------------------------------------------

Perl is a language that combines some of the features of C, sed, awk
and shell.  See the manual page for more hype.  There are also many Perl
books available, covering a wide variety of topics, from various publishers.
See pod/perlbook.pod for more information.

Please read all the directions below before you proceed any further, and
then follow them carefully.

Installation

1) Detailed instructions are in the file "INSTALL", which you should
read if you are either installing on a system resembling Unix
or porting perl to another platform.  For non-Unix platforms, see the
corresponding README.

2) Read the manual entries before running perl.

3) IMPORTANT!  Help save the world!  Communicate any problems and suggested
patches to perlbug@perl.org so we can keep the world in sync.
If you have a problem, there's someone else out there who either has had
or will have the same problem.  See the section on "Reporting Problems"
in the INSTALL file.

The latest versions of perl are always available on the various CPAN
(Comprehensive Perl Archive Network) sites around the world.
See http://www.cpan.org/src/ .


Just a personal note:  I want you to know that I create nice things like this
because it pleases the Author of my story.  If this bothers you, then your
notion of Authorship needs some revision.  But you can use perl anyway. :-)

							The author.

The following information about Perl and the year 2000 is a modified
version of the information that can be found in the Frequently Asked
Question (FAQ) documents.

Does Perl have a year 2000 problem?  Is Perl Y2K compliant?

Short answer: No, Perl does not have a year 2000 problem.  Yes,
       Perl is Y2K compliant (whatever that means).  The
       programmers you've hired to use it, however, probably are
       not.  If you want perl to complain when your programmers
       create programs with certain types of possible year 2000
       problems, a build option allows you to turn on warnings.

Long answer: The question belies a true understanding of the
       issue.  Perl is just as Y2K compliant as your pencil
       --no more, and no less.  Can you use your pencil to write
       a non-Y2K-compliant memo?  Of course you can.  Is that
       the pencil's fault?  Of course it isn't.

       The date and time functions supplied with perl (gmtime and
       localtime) supply adequate information to determine the
       year well beyond 2000 (2038 is when trouble strikes for
       32-bit machines).  The year returned by these functions
       when used in a list context is the year minus 1900.  For
       years between 1910 and 1999 this happens to be a 2-digit
       decimal number. To avoid the year 2000 problem simply do
       not treat the year as a 2-digit number.  It isn't.

       When gmtime() and localtime() are used in scalar context
       they return a timestamp string that contains a fully-
       expanded year.  For example, $timestamp =
       gmtime(1005613200) sets $timestamp to "Tue Nov 13 01:00:00
       2001".  There's no year 2000 problem here.

       That doesn't mean that Perl can't be used to create non-
       Y2K compliant programs.  It can.  But so can your pencil.
       It's the fault of the user, not the language.  At the risk
       of inflaming the NRA: ``Perl doesn't break Y2K, people
       do.''  See http://language.perl.com/news/y2k.html for a
       longer exposition.

       If you want perl to warn you when it sees a program which
       concatenates a number with the string "19" -- a common
       indication of a year 2000 problem -- build perl using the
       Configure option  "-Accflags=-DPERL_Y2KWARN".
       (See the file INSTALL for more information about building
       perl.)

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.aix - Perl version 5 on IBM Unix (AIX) systems

=head1 DESCRIPTION

This document describes various features of IBM's Unix operating
system (AIX) that will affect how Perl version 5 (hereafter just Perl)
is compiled and/or runs.

=head2 Compiling Perl 5 on AIX

When compiling Perl, you must use an ANSI C compiler. AIX does not ship
an ANSI compliant C-compiler with AIX by default, but binary builds of
gcc for AIX are widely available.

At the moment of writing, AIX supports two different native C compilers,
for which you have to pay: B<xlC> and B<vac>. If you decide to use either
of these two (which is quite a lot easier than using gcc), be sure to
upgrade to the latest available patch level. Currently:

    xlC.C     3.1.4.10 or 3.6.6.0 or 4.0.2.2 or 5.0.2.9 or 6.0.0.3
    vac.C     4.4.0.3  or 5.0.2.6 or 6.0.0.1

note that xlC has the OS version in the name as of version 4.0.2.0, so
you will find xlC.C for AIX-5.0 as package

    xlC.aix50.rte   5.0.2.0 or 6.0.0.3

subversions are not the same "latest" on all OS versions. For example,
the latest xlC-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.

Perl can be compiled with either IBM's ANSI C compiler or with gcc.
The former is recommended, as not only can it compile Perl with no
difficulty, but also can take advantage of features listed later that
require the use of IBM compiler-specific command-line flags.

The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler
optimization bugs that affect compiling perl.c and regcomp.c,
respectively.  If Perl's configuration detects those compiler patch
levels, optimization is turned off for the said source code files.
Upgrading to at least 5.0.2.0 is recommended.

If you decide to use gcc, make sure your installation is recent and
complete, and be sure to read the Perl README file for more gcc-specific
details. Please report any hoops you had to jump through to the development
team.

=head2 OS level

Before installing the patches to the IBM C-compiler you need to know the
level of patching for the Operating System. IBM's command 'oslevel' will
show the base, but is not always complete (in this example oslevel shows
4.3.NULL, whereas the system might run most of 4.3.THREE):

    # oslevel
    4.3.0.0
    # lslpp -l | grep 'bos.rte '
    bos.rte           4.3.3.75  COMMITTED  Base Operating System Runtime
    bos.rte            4.3.2.0  COMMITTED  Base Operating System Runtime
    #

The same might happen to AIX 5.1 or other OS levels. As a side note, perl
cannot be built without bos.adt.syscalls and bos.adt.libm installed

    # lslpp -l | egrep "syscalls|libm"
    bos.adt.libm      5.1.0.25  COMMITTED  Base Application Development
    bos.adt.syscalls  5.1.0.36  COMMITTED  System Calls Application
    #

=head2 Building Dynamic Extensions on AIX

AIX supports dynamically loadable objects as well as shared libraries.
Shared libraries by convention end with the suffix .a, which is a bit
misleading, as an archive can contain static as well as dynamic members.
For perl dynamically loaded objects we use the .so suffix also used on
many other platforms.

Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3
or newer Perl uses the AIX native dynamic loading interface in the so
called runtime linking mode instead of the emulated interface that was
used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and
earlier.  This change does break backward compatibility with compiled
modules from earlier perl releases.  The change was made to make Perl
more compliant with other applications like Apache/mod_perl which are
using the AIX native interface. This change also enables the use of C++
code with static constructors and destructors in perl extensions, which
was not possible using the emulated interface.

=head2 The IBM ANSI C Compiler

All defaults for Configure can be used.

If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions
will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0,
but vac 5.0.2.6 or up is highly recommended. Note that since IBM has
removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these
versions should be considered obsolete.

Here's a brief lead of how to upgrade the compiler to the latest
level.  Of course this is subject to changes.  You can only upgrade
versions from ftp-available updates if the first three digit groups
are the same (in where you can skip intermediate unlike the patches
in the developer snapshots of perl), or to one version up where the
"base" is available.  In other words, the AIX compiler patches are
cumulative.

 vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
 xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not available)

 # ftp ftp.software.ibm.com
 Connected to service.boulder.ibm.com.
 : welcome message ...
 Name (ftp.software.ibm.com:merijn): anonymous
 331 Guest login ok, send your complete e-mail address as password.
 Password:
 ... accepted login stuff
 ftp> cd /aix/fixes/v4/
 ftp> dir other other.ll
 output to local-file: other.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> dir xlc xlc.ll
 output to local-file: xlc.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> bye
 ... goodbye messages
 # ls -l *.ll
 -rw-rw-rw-   1 merijn   system    1169432 Nov  2 17:29 other.ll
 -rw-rw-rw-   1 merijn   system      29170 Nov  2 17:29 xlc.ll

On AIX 4.2 using xlC, we continue:

 # lslpp -l | fgrep 'xlC.C '
   xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
   xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
 # grep 'xlC.C.3.1.4.*.bff' xlc.ll
 -rw-r--r--   1 45776101 1        6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
 -rw-rw-r--   1 45776101 1        6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
 -rw-r--r--   1 45776101 1        6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
 -rw-r--r--   1 45776101 1        6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
 -rw-r--r--   1 45776101 1        6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
 -rw-rw-r--   1 45776101 1        6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
 -rw-rw-r--   1 45776101 1        6188032 May 22 1997  xlC.C.3.1.4.6.bff
 -rw-rw-r--   1 45776101 1        6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
 -rw-rw-r--   1 45776101 1        6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
 -rw-rw-r--   1 45776101 1        6169600 May 27 1998  xlC.C.3.1.4.9.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
 #

On AIX 4.3 using vac, we continue:

 # lslpp -l | grep 'vac.C '
  vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
  vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
 # grep 'vac.C.5.0.2.*.bff' other.ll
 -rw-rw-r--   1 45776101 1        13592576 Apr 16 2001  vac.C.5.0.2.0.bff
 -rw-rw-r--   1 45776101 1        14133248 Apr  9 2002  vac.C.5.0.2.3.bff
 -rw-rw-r--   1 45776101 1        14173184 May 20 2002  vac.C.5.0.2.4.bff
 -rw-rw-r--   1 45776101 1        14192640 Nov 22 2002  vac.C.5.0.2.6.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
 #

Likewise on all other OS levels. Then execute the following command, and
fill in its choices

 # smit install_update
  -> Install and Update from LATEST Available Software
  * INPUT device / directory for software [ vac.C.5.0.2.6.bff    ]
  [ OK ]
  [ OK ]

Follow the messages ... and you're done.

If you like a more web-like approach, a good start point can be
http://www14.software.ibm.com/webapp/download/downloadaz.jsp and click
"C for AIX", and follow the instructions.

=head2 The usenm option

If linking miniperl

 cc -o miniperl ... miniperlmain.o opmini.o perl.o ... -lm -lc ...

causes error like this

 ld: 0711-317 ERROR: Undefined symbol: .aintl
 ld: 0711-317 ERROR: Undefined symbol: .copysignl
 ld: 0711-317 ERROR: Undefined symbol: .syscall
 ld: 0711-317 ERROR: Undefined symbol: .eaccess
 ld: 0711-317 ERROR: Undefined symbol: .setresuid
 ld: 0711-317 ERROR: Undefined symbol: .setresgid
 ld: 0711-317 ERROR: Undefined symbol: .setproctitle
 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.

you could retry with

 make realclean
 rm config.sh
 ./Configure -Dusenm ...

which makes Configure to use the C<nm> tool when scanning for library
symbols, which usually is not done in AIX.

Related to this, you probably should not use the C<-r> option of
Configure in AIX, because that affects of how the C<nm> tool is used.

=head2 Using GNU's gcc for building perl

Using gcc-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box,
as do recent gcc-2.9 builds available directly from IBM as part of their
Linux compatibility packages, available here:

  http://www.ibm.com/servers/aix/products/aixos/linux/

=head2 Using Large Files with Perl

Should yield no problems.

=head2 Threaded Perl

Threads seem to work OK, though at the moment not all tests pass when
threads are used in combination with 64-bit configurations.

You may get a warning when doing a threaded build:

  "pp_sys.c", line 4640.39: 1506-280 (W) Function argument assignment between types "unsigned char*" and "const void*" is not allowed.

The exact line number may vary, but if the warning (W) comes from a line
line this

  hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);

in the "pp_ghostent" function, you may ignore it safely.  The warning
is caused by the reentrant variant of gethostbyaddr() having a slightly
different prototype than its non-reentrant variant, but the difference
is not really significant here.

=head2 64-bit Perl

If your AIX is installed with 64-bit support, you can expect 64-bit
configurations to work. In combination with threads some tests might
still fail.

=head2 AIX 4.2 and extensions using C++ with statics

In AIX 4.2 Perl extensions that use C++ functions that use statics
may have problems in that the statics are not getting initialized.
In newer AIX releases this has been solved by linking Perl with
the libC_r library, but unfortunately in AIX 4.2 the said library
has an obscure bug where the various functions related to time
(such as time() and gettimeofday()) return broken values, and
therefore in AIX 4.2 Perl is not linked against the libC_r.

=head1 AUTHOR

H.Merijn Brand <h.m.brand@xs4all.nl>

=head1 DATE

Version 0.0.6: 23 Dec 2002

=cut

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

=head1 NAME

perlamiga - Perl under Amiga OS

=head1 NOTE

B<Perl 5.8.0 cannot be built in AmigaOS.  You can use either the
maintenance release Perl 5.6.1 or the development release Perl 5.7.2
in AmigaOS.  See L</"PERL 5.8.0 BROKEN IN AMIGAOS"> if you want to help
fixing this problem.>

=head1 SYNOPSIS

One can read this document in the following formats:

	man perlamiga
	multiview perlamiga.guide

to list some (not all may be available simultaneously), or it may
be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.

A recent version of perl for the Amiga can be found at the Geek Gadgets
section of the Aminet:

      http://www.aminet.net/~aminet/dev/gg/index.html

=cut

Contents

 perlamiga - Perl under Amiga OS

       NAME
       SYNOPSIS
       DESCRIPTION
         -  Prerequisites
         -  Starting Perl programs under AmigaOS
         -  Shortcomings of Perl under AmigaOS
       INSTALLATION
       Accessing documentation
         -  Manpages
         -  HTML
         -  GNU info files
         -  LaTeX docs
       BUILD
         -  Build Prerequisites
         -  Getting the perl source
         -  Application of the patches
         -  Making
         -  Testing
         -  Installing the built perl
       AUTHOR
       SEE ALSO

=head1 DESCRIPTION

=head2 Prerequisites for Compiling Perl on AmigaOS

=over 6

=item B<Unix emulation for AmigaOS: ixemul.library>

You need the Unix emulation for AmigaOS, whose most important part is
B<ixemul.library>. For a minimum setup, get the latest versions
of the following packages from the Aminet archives
( http://www.aminet.net/~aminet/ ):

	ixemul-bin
	ixemul-env-bin
	pdksh-bin

Note also that this is a minimum setup; you might want to add other
packages of B<ADE> (the I<Amiga Developers Environment>).

=item B<Version of Amiga OS>

You need at the very least AmigaOS version 2.0. Recommended is version 3.1.

=back

=head2 Starting Perl programs under AmigaOS

Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
same way as on any other platform, by

	perl foo arg1 arg2 arg3

If you want to specify perl options C<-my_opts> to the perl itself (as
opposed to your program), use

	perl -my_opts foo arg1 arg2 arg3

Alternately, you can try to get a replacement for the system's B<Execute>
command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
of your scripts. Then you can invoke your scripts like under UNIX with

	foo arg1 arg2 arg3

(Note that having *nixish full path to perl F</usr/bin/perl> is not
necessary, F<perl> would be enough, but having full path would make it
easier to use your script under *nix.)

=head2 Shortcomings of Perl under AmigaOS

Perl under AmigaOS lacks some features of perl under UNIX because of
deficiencies in the UNIX-emulation, most notably:

=over 6

=item *

fork()

=item *

some features of the UNIX filesystem regarding link count and file dates

=item *

inplace operation (the -i switch) without backup file

=item *

umask() works, but the correct permissions are only set when the file is
finally close()d

=back

=head1 INSTALLATION

Change to the installation directory (most probably ADE:), and
extract the binary distribution:

lha -mraxe x perl-$VERSION-bin.lha

or

tar xvzpf perl-$VERSION-bin.tgz

(Of course you need lha or tar and gunzip for this.)

For installation of the Unix emulation, read the appropriate docs.

=head1 Accessing documentation

=head2 Manpages for Perl on AmigaOS

If you have C<man> installed on your system, and you installed perl
manpages, use something like this:

	man perlfunc
	man less
	man ExtUtils.MakeMaker

to access documentation for different components of Perl. Start with

	man perl

Note: You have to modify your man.conf file to search for manpages
in the /ade/lib/perl5/man/man3 directory, or the man pages for the
perl library will not be found.

Note that dot (F<.>) is used as a package separator for documentation
for packages, and as usual, sometimes you need to give the section - C<3>
above - to avoid shadowing by the I<less(1) manpage>.


=head2 Perl HTML Documentation on AmigaOS

If you have some WWW browser available, you can build B<HTML> docs.
Cd to directory with F<.pod> files, and do like this

	cd /ade/lib/perl5/pod
	pod2html

After this you can direct your browser the file F<perl.html> in this
directory, and go ahead with reading docs.

Alternatively you may be able to get these docs prebuilt from C<CPAN>.

=head2 Perl GNU Info Files on AmigaOS

Users of C<Emacs> would appreciate it very much, especially with
C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
or, alternately, prebuilt info pages.

=head2 Perl LaTeX Documentation on AmigaOS

Can be constructed using C<pod2latex>.

=head1 BUILDING PERL ON AMIGAOS

Here we discuss how to build Perl under AmigaOS.

=head2 Build Prerequisites for Perl on AmigaOS

You need to have the latest B<ixemul> (Unix emulation for Amiga)
from Aminet.

=head2 Getting the Perl Source for AmigaOS

You can either get the latest perl-for-amiga source from Ninemoons
and extract it with:

  tar xvzpf perl-$VERSION-src.tgz

or get the official source from CPAN:

  http://www.cpan.org/src/5.0

Extract it like this

  tar xvzpf perl-$VERSION.tar.gz

You will see a message about errors while extracting F<Configure>. This
is normal and expected. (There is a conflict with a similarly-named file
F<configure>, but it causes no harm.)

=head2 Making Perl on AmigaOS

Remember to use a hefty wad of stack (I use 2000000)

  sh configure.gnu --prefix=/gg

Now type

  make depend

Now!

  make

=head2 Testing Perl on AmigaOS

Now run

  make test

Some tests will be skipped because they need the fork() function:

F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>, F<lib/open3.t>,
F<lib/io_pipe.t>, F<lib/io_sock.t>

=head2 Installing the built Perl on AmigaOS

Run

  make install

=head1 PERL 5.8.0 BROKEN IN AMIGAOS

As told above, Perl 5.6.1 was still good in AmigaOS, as was 5.7.2.
After Perl 5.7.2 (change #11423, see the Changes file, and the file
pod/perlhack.pod for how to get the individual changes) Perl dropped
its internal support for vfork(), and that was very probably the step
that broke AmigaOS (since the ixemul library has only vfork).
The build finally fails when the ext/DynaLoader is being built, and
PERL ends up as "0" in the produced Makefile, trying to run "0" does
not quite work.  Also, executing miniperl in backticks seems to
generate nothing: very probably related to the (v)fork problems.
B<Fixing the breakage requires someone quite familiar with the ixemul
library, and how one is supposed to run external commands in AmigaOS
without fork().>

=head1 AUTHORS

Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
Jan-Erik Karlsson, trg@privat.utfors.se

=head1 SEE ALSO

perl(1).

=cut

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.apollo - Perl version 5 on Apollo DomainOS

=head1 DESCRIPTION

The following tests are known to fail as of Perl 5.005_03:

comp/decl..........FAILED at test 0
op/write...........FAILED at test 0
lib/filefind.......FAILED at test 2
lib/io_udp.........FAILED at test 2
lib/findbin........stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 162
stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 163
FAILED at test 1

=head1 AUTHOR

Johann Klasek <jk@auto.tuwien.ac.at>

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.beos - Perl version 5.8+ on BeOS

=head1 DESCRIPTION

This file contains instructions how to build Perl under BeOS and lists
known problems.

=head1 BUILD AND INSTALL

=head2 Requirements

I have built and tested Perl 5.8.6 and 5.9.1 under BeOS R5 x86 net server.
I can't say anything with regard to PPC. Since Perl 5.8.0 had been released
for BeOS BONE, I suspect, there is a good chance, that it still compiles on
a BONE system. The only change I've made, that affects BONE systems is the
recognition of whether it is a BONE system or not in C<hints/beos.sh>. Now
network socket support should remain enabled on BONE systems. This might
as well break the build, though.

As more recent versions of autoconf require flock() support, I wrote a flock()
emulation (flock_server) and released it on BeBits:

	http://www.bebits.com/app/4030

If you want to build a Perl with flock() support, you have to install this
package first.

=head2 Configure

With flock() support:

	CFLAGS=-I/path/to/flock/server/headers ./configure.gnu \
		--prefix=/boot/home/config

Replace C</path/to/flock/server/headers> with the path to the directory
containing the C<flock.h> header.

Without flock() support:

	./configure.gnu --prefix=/boot/home/config

=head2 Build

With flock() support:

	make LDLOADLIBS="-lnet -lflock"

Without flock() support:

	make LDLOADLIBS="-lnet"

C<-lnet> is needed on net server systems only and if the compiler doesn't
add it automatically (Be's R5 gcc does, Oliver Tappe's gcc 2.95.3 does not).

=head2 Install

Install all perl files:

	make install

Create a symlink for libperl:

	cd ~/config/lib; ln -s perl5/5.8.6/BePC-beos/CORE/libperl.so .

Replace C<5.8.6> with your respective version of Perl.

=head1 KNOWN PROBLEMS

=over 4

=item *

Network socket support is disabled for BeOS R5 net server. I didn't dare yet
to try enabling it and see what problems occur.

=item *

The LFS (large file support) tests (C<t/op/lfs> and C<xt/Fcntl/t/syslfs>) are
disabled as seeking beyond 2 GB is broken according to jhi@iki.fi who was the
last one checking the BeOS port and updating this file before me. Haven't
checked this myself.

=item *

The C<t/io/fflush> test fails at #6. As far as I can tell, this is caused by
a bug in the BeOS pipes implementation that occurs when starting other child
processes. In the particular test case a C<system("perl -e 0")> flushes the
stdout pipe of another child process.

=item *

The C<ext/POSIX/t/waitpid> test fails at #1. After all child processes are
gone BeOS' waitpid(-1,...) returns 0 instead of -1 (as it should). No idea
how to fix this.

=back

=head1 CONTACT

For BeOS specifics problems feel free to mail to:
Ingo Weinhold <bonefish@cs.tu-berlin.de>

Last update: 2004-12-16

This document is written in pod format hence there are punctuation
characters in odd places.  Do not worry, you've apparently got the
ASCII->EBCDIC translation worked out correctly.  You can read more
about pod in pod/perlpod.pod or the short summary in the INSTALL file.

=head1 NAME

README.BS2000 - building and installing Perl for BS2000.

=head1 SYNOPSIS

This document will help you Configure, build, test and install Perl
on BS2000 in the POSIX subsystem.

=head1 DESCRIPTION

This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
V3.1A or later.  It may work on other versions, but we started porting
and testing it with 3.1A and are currently using Version V4.0A.

You may need the following GNU programs in order to install perl:

=head2 gzip on BS2000

We used version 1.2.4, which could be installed out of the box with
one failure during 'make check'.

=head2 bison on BS2000

The yacc coming with BS2000 POSIX didn't work for us.  So we had to
use bison.  We had to make a few changes to perl in order to use the
pure (reentrant) parser of bison.  We used version 1.25, but we had to
add a few changes due to EBCDIC.  See below for more details
concerning yacc.

=head2 Unpacking Perl Distribution on BS2000

To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
filesystem (we used the mountpoint /usr/local/ascii for this).  Now
you extract the archive in the ASCII filesystem without
I/O-conversion:

cd /usr/local/ascii
export IO_CONVERSION=NO
gunzip < /usr/local/src/perl.tar.gz | pax -r

You may ignore the error message for the first element of the archive
(this doesn't look like a tar archive / skipping to next file...),
it's only the directory which will be created automatically anyway.

After extracting the archive you copy the whole directory tree to your
EBCDIC filesystem.  B<This time you use I/O-conversion>:

cd /usr/local/src
IO_CONVERSION=YES
cp -r /usr/local/ascii/perl5.005_02 ./

=head2 Compiling Perl on BS2000

There is a "hints" file for BS2000 called hints.posix-bc (because
posix-bc is the OS name given by `uname`) that specifies the correct
values for most things.  The major problem is (of course) the EBCDIC
character set.  We have german EBCDIC version.

Because of our problems with the native yacc we used GNU bison to
generate a pure (=reentrant) parser for perly.y.  So our yacc is
really the following script:

-----8<-----/usr/local/bin/yacc-----8<-----
#! /usr/bin/sh

# Bison as a reentrant yacc:

# save parameters:
params=""
while [[ $# -gt 1 ]]; do
    params="$params $1"
    shift
done

# add flag %pure_parser:

tmpfile=/tmp/bison.$$.y
echo %pure_parser > $tmpfile
cat $1 >> $tmpfile

# call bison:

echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)"
/usr/local/bin/bison --yacc $params $tmpfile

# cleanup:

rm -f $tmpfile
-----8<----------8<-----

We still use the normal yacc for a2p.y though!!!  We made a softlink
called byacc to distinguish between the two versions:

ln -s /usr/bin/yacc /usr/local/bin/byacc

We build perl using GNU make.  We tried the native make once and it
worked too.

=head2 Testing Perl on BS2000

We still got a few errors during C<make test>.  Some of them are the
result of using bison.  Bison prints I<parser error> instead of I<syntax
error>, so we may ignore them.  The following list shows
our errors, your results may differ:

op/numconvert.......FAILED tests 1409-1440
op/regexp...........FAILED tests 483, 496
op/regexp_noamp.....FAILED tests 483, 496
pragma/overload.....FAILED tests 152-153, 170-171
pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
lib/bigfloat........FAILED tests 351-352, 355
lib/bigfltpm........FAILED tests 354-355, 358
lib/complex.........FAILED tests 267, 487
lib/dumper..........FAILED tests 43, 45
Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.

=head2 Installing Perl on BS2000

We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
installing the documentation.


=head2 Using Perl in the Posix-Shell of BS2000

BS2000 POSIX doesn't support the shebang notation
(C<#!/usr/local/bin/perl>), so you have to use the following lines
instead:

: # use perl
    eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
        if $running_under_some_shell;

=head2 Using Perl in "native" BS2000

We don't have much experience with this yet, but try the following:

Copy your Perl executable to a BS2000 LLM using bs2cp:

C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>

Now you can start it with the following (SDF) command:

C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>

First you get the BS2000 commandline prompt ('*').  Here you may enter
your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
double backslash!) or C<-w> and the name of your Perl script.
Filenames starting with C</> are searched in the Posix filesystem,
others are searched in the BS2000 filesystem.  You may even use
wildcards if you put a C<%> in front of your filename (e.g. C<-w
checkfiles.pl %*.c>).  Read your C/C++ manual for additional
possibilities of the commandline prompt (look for
PARAMETER-PROMPTING).

=head2 Floating point anomalies on BS2000

There appears to be a bug in the floating point implementation on BS2000 POSIX
systems such that calling int() on the product of a number and a small
magnitude number is not the same as calling int() on the quotient of
that number and a large magnitude number.  For example, in the following
Perl code:

    my $x = 100000.0;
    my $y = int($x * 1e-5) * 1e5; # '0'
    my $z = int($x / 1e+5) * 1e5;  # '100000'
    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000

Although one would expect the quantities $y and $z to be the same and equal
to 100000 they will differ and instead will be 0 and 100000 respectively.

=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions

Since version 5.8 Perl uses the new PerlIO on BS2000.  This enables
you using different encodings per IO channel.  For example you may use

    use Encode;
    open($f, ">:encoding(ascii)", "test.ascii");
    print $f "Hello World!\n";
    open($f, ">:encoding(posix-bc)", "test.ebcdic");
    print $f "Hello World!\n";
    open($f, ">:encoding(latin1)", "test.latin1");
    print $f "Hello World!\n";
    open($f, ">:encoding(utf8)", "test.utf8");
    print $f "Hello World!\n";

to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
this example identical to normal EBCDIC).  See the documentation of
Encode::PerlIO for details.

As the PerlIO layer uses raw IO internally, all this totally ignores
the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
environment variable.  If you want to get the old behavior, that the
BS2000 IO functions determine conversion depending on the filesystem
PerlIO still is your friend.  You use IO_CONVERSION as usual and tell
Perl, that it should use the native IO layer:

    export IO_CONVERSION=YES
    export PERLIO=stdio

Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
partitions.  See the documentation of PerlIO (without C<Encode::>!)
for further posibilities.

=head1 AUTHORS

Thomas Dorner

=head1 SEE ALSO

L<INSTALL>, L<perlport>.

=head2 Mailing list

If you are interested in the VM/ESA, z/OS (formerly known as OS/390)
and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
To subscribe, send an empty message to perl-mvs-subscribe@perl.org.

See also:

    http://lists.perl.org/showlist.cgi?name=perl-mvs

There are web archives of the mailing list at:

    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
    http://archive.develooper.com/perl-mvs@perl.org/

=head1 HISTORY

This document was originally written by Thomas Dorner for the 5.005
release of Perl.

This document was podified for the 5.6 release of perl 11 July 2000.

=cut

If you read this file _as_is_, just ignore the funny characters you
see.  It is written in the POD format (see pod/perlpod.pod) which is
specifically designed to be readable as is.

=head1 NAME

perlce - Perl for WinCE

=head1 DESCRIPTION

This file gives the instructions for building Perl5.8 and above for
WinCE.  Please read and understand the terms under which this
software is distributed.

=head1 BUILD

This section describes the steps to be performed to build PerlCE.
You may find additional and newer information about building perl
for WinCE using following URL:

  http://perlce.sourceforge.net

There should also be pre-built binaries there.

Don't be confused by large size of downloaded distribution or constructed
binaries: entire distribution could be large for WinCE ideology, but
you may strip it at your wish and use only required parts.

=head2 Tools & SDK

For compiling, you need following:

=over 4

=item * Microsoft Embedded Visual Tools

=item * Microsoft Visual C++

=item * Rainer Keuchel's celib-sources

=item * Rainer Keuchel's console-sources

=back

Needed source files can be downloaded via:
www.rainer-keuchel.de/wince/dirlist.html

=head2 Make

Please pay attention that starting from 5.8.0 miniperl *is* built
and it facilitates in further building process. This means that
in addition to compiler installation for mobile device you also need
to have Microsoft Visual C++ installed as well.

On the bright side, you do not need to edit any files from ./win32
subdirectory. Normally you only need to edit ./wince/compile.bat
to reflect your system and run it.

File ./wince/compile.bat is actually a wrapper to call
nmake -f makefile.ce with appropriate parameters and it accepts extra
parameters and forwards them to "nmake" command as additional
arguments. You should pass target this way.

To prepare distribution you need to do following:

=over 4

=item * go to ./wince subdirectory

=item * edit file compile.bat

=item * run
  compile.bat

=item * run
  compile.bat dist

=back

makefile.ce has CROSS_NAME macro, and it is used further to refer to
your cross-compilation scheme. You could assign a name to it, but this
is not necessary, because by default it is assigned after your machine
configuration name, such as "wince-sh3-hpc-wce211", and this is enough
to distinguish different builds at the same time. This option could be
handy for several different builds on same platform to perform, say,
threaded build. In a following example we assume that all required
environment variables are set properly for C cross-compiler (a special
*.bat file could fit perfectly to this purpose) and your compile.bat
has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300".

  compile.bat
  compile.bat dist
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define"
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist

If all goes okay and no errors during a build, you'll get two independent
distributions: "wince-mips-pocket-wce300" and "mips-wce300-thr".

Target 'dist' prepares distribution file set. Target 'zipdist' performs
same as 'dist' but additionally compresses distribution files into zip
archive.

NOTE: during a build there could be created a number (or one) of Config.pm
for cross-compilation ("foreign" Config.pm) and those are hidden inside
../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to
note, there should be *no* Config.pm for host miniperl.
If you'll get an error that perl could not find Config.pm somewhere in building
process this means something went wrong. Most probably you forgot to
specify a cross-compilation when invoking miniperl.exe to Makefile.PL
When building an extension for cross-compilation your command line should
look like

  ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL

or just

  ..\miniperl.exe -I..\lib -MCross Makefile.PL

to refer a cross-compilation that was created last time.


If you decided to build with fcrypt.c file, please refer to README.win32
file, as long as all legal considerations and steps to do are exactly same
in this case.

All questions related to building for WinCE devices could be asked in
perlce-users@lists.sourceforge.net mailing list.

=head1 ACKNOWLEDGEMENTS

The port for Win32 was used as a reference.

=head1 AUTHORS

Rainer Keuchel (keuchel@netwave.de)
Vadim Konovalov (vkonovalov@spb.lucent.com)

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

The following documentation is written in EUC-CN encoding.

�������һ������ֱ༭����������ļ�, ������������ص�ע���ַ�.
����ļ����� POD (�����ļ���ʽ) д��; ���ָ�ʽ��Ϊ��������ֱ���Ķ�,
���ر���Ƶ�. ���ڴ˸�ʽ�Ľ�һ����Ϣ, ��ο� perlpod �����ļ�.

=head1 NAME

perlcn - �������� Perl ָ��

=head1 DESCRIPTION

��ӭ���� Perl �����!

�� 5.8.0 �濪ʼ, Perl �߱������Ƶ� Unicode (ͳһ��) ֧Ԯ,
Ҳ����֧Ԯ�����������ϵ����ı��뷽ʽ; CJK (���պ�) �������е�һ����.
Unicode �ǹ����Եı�׼, ��ͼ�������������е��ַ�: ��������, ��������,
�Լ����߼��һ�� (ϣ����, ��������, ��������, ϣ������, ӡ����,
ӡ�ذ���, �ȵ�). ��Ҳ�����˶�����ҵϵͳ��ƽ̨ (�� PC �������).

Perl ������ Unicode ���в���. ���ʾ Perl �ڲ����ַ������ݿ��� Unicode
��ʾ; Perl �ĺ�ʽ����� (���������ʾʽ�ȶ�) Ҳ�ܶ� Unicode ���в���.
�����뼰���ʱ, Ϊ�˴����� Unicode ֮ǰ�ı��뷽ʽ��ŵ�����, Perl
�ṩ�� Encode ���ģ��, �����������׵ض�ȡ��д����еı�������.

Encode ����ģ��֧Ԯ���м������ĵı��뷽ʽ ('gb2312' ��ʾ 'euc-cn'):

    euc-cn	Unix �����ַ���, Ҳ�����׳ƵĹ�����
    gb2312-raw	δ������� (�ͱ���) GB2312 �ַ���
    gb12345	δ��������й��÷������ı���
    iso-ir-165	GB2312 + GB6345 + GB8565 + �����ַ�
    cp936	����ҳ 936, Ҳ������ 'GBK' (���������) ָ��
    hz		7 �����ݳ�ʽ GB2312 ����

������˵, �� EUC-CN ����ĵ���ת�� Unicode, �����������ָ��:

    perl -Mencoding=euc-cn,STDOUT,utf8 -pe1 < file.euc-cn > file.utf8

Perl Ҳ�ڸ��� "piconv", һ֧��ȫ�� Perl д�ɵ��ַ�ת�����߳���, �÷�����:

    piconv -f euc-cn -t utf8 < file.euc-cn > file.utf8
    piconv -f utf8 -t euc-cn < file.utf8 > file.euc-cn

����, ���� encoding ģ��, ���������д�����ַ�Ϊ��λ�ij�����, ������ʾ:

    #!/usr/bin/env perl
    # ���� euc-cn �ִ�����; ��׼����뼰��׼������Ϊ euc-cn ����
    use encoding 'euc-cn', STDIN => 'euc-cn', STDOUT => 'euc-cn';
    print length("����");	     #  2 (˫���ű�ʾ�ַ�)
    print length('����');	     #  4 (�����ű�ʾ�ֽ�)
    print index("׻׻�̻�", "�׻�"); # -1 (�����������ַ���)
    print index('׻׻�̻�', '�׻�'); #  1 (�ӵڶ����ֽڿ�ʼ)

�����һ��������, "׻" �ĵڶ����ֽ��� "׻" �ĵ�һ���ֽڽ�ϳ� EUC-CN
��� "��"; "׻" �ĵڶ����ֽ����� "��" �ĵ�һ���ֽڽ�ϳ� "��".
��������ǰ EUC-CN ��ȶԴ����ϳ���������.

=head2 ��������ı���

�����Ҫ��������ı���, ���Դ� CPAN (L<http://www.cpan.org/>) ����
Encode::HanExtra ģ��. ��Ŀǰ�ṩ���б��뷽ʽ:

    gb18030	�����������, ������������

����, Encode::HanConvert ģ�����ṩ�˼�ת���õ����ֱ���:

    big5-simp	Big5 ���������� Unicode �������Ļ�ת
    gbk-trad	GBK ���������� Unicode �������Ļ�ת

������ GBK �� Big5 ֮�以ת, ��ο���ģ���ڸ��� b2g.pl �� g2b.pl ��֧����,
���ڳ�����ʹ������д��:

    use Encode::HanConvert;
    $euc_cn = big5_to_gb($big5); # �� Big5 תΪ GBK
    $big5 = gb_to_big5($euc_cn); # �� GBK תΪ Big5

=head2 ��һ������Ϣ

��ο� Perl �ڸ��Ĵ���˵���ļ� (����ȫ����Ӣ��д��), ��ѧϰ�������
Perl ��֪ʶ, �Լ� Unicode ��ʹ�÷�ʽ. ����, �ⲿ����Դ�൱�ḻ:

=head2 �ṩ Perl ��Դ����ַ

=over 4

=item L<http://www.perl.com/>

Perl ����ҳ (��ŷ����˾ά��)

=item L<http://www.cpan.org/>

Perl �ۺϵ���� (Comprehensive Perl Archive Network)

=item L<http://lists.perl.org/>

Perl �ʵ���̳һ��

=back

=head2 ѧϰ Perl ����ַ

=over 4

=item L<http://www.oreilly.com.cn/html/perl.html>

�������İ��ŷ���� Perl ���

=back

=head2 Perl ʹ���߼���

=over 4

=item L<http://www.pm.org/groups/asia.shtml#China>

�й� Perl �ƹ���һ��

=back

=head2 Unicode �����ַ

=over 4

=item L<http://www.unicode.org/>

Unicode ѧ��ѧ�� (Unicode ��׼���ƶ���)

=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>

Unix/Linux �ϵ� UTF-8 �� Unicode �����

=back

=head1 SEE ALSO

L<Encode>, L<Encode::CN>, L<encoding>, L<perluniintro>, L<perlunicode>

=head1 AUTHORS

Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>

Autrijus Tang (���ں�) E<lt>autrijus@autrijus.orgE<gt>

=cut

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see pod/perlpod.pod) which is
specially designed to be readable as is.

=head1 NAME

README.cygwin - Perl for Cygwin

=head1 SYNOPSIS

This document will help you configure, make, test and install Perl
on Cygwin.  This document also describes features of Cygwin that will
affect how Perl behaves at runtime.

B<NOTE:> There are pre-built Perl packages available for Cygwin and a
version of Perl is provided in the normal Cygwin install.  If you do
not need to customize the configuration, consider using one of those
packages.


=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN

=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)

The Cygwin tools are ports of the popular GNU development tools for Win32
platforms.  They run thanks to the Cygwin library which provides the UNIX
system calls and environment these programs expect.  More information
about this project can be found at:

  http://www.cygwin.com/

A recent net or commercial release of Cygwin is required.

At the time this document was last updated, Cygwin 1.5.2 was current.


=head2 Cygwin Configuration

While building Perl some changes may be necessary to your Cygwin setup so
that Perl builds cleanly.  These changes are B<not> required for normal
Perl usage.

B<NOTE:> The binaries that are built will run on all Win32 versions.
They do not depend on your host system (Win9x/WinME, WinNT/Win2K)
or your Cygwin configuration (I<ntea>, I<ntsec>, binary/text mounts).
The only dependencies come from hard-coded pathnames like C</usr/local>.
However, your host system and Cygwin configuration will affect Perl's
runtime behavior (see L</"TEST">).

=over 4

=item * C<PATH>

Set the C<PATH> environment variable so that Configure finds the Cygwin
versions of programs.  Any Windows directories should be removed or
moved to the end of your C<PATH>.

=item * I<nroff>

If you do not have I<nroff> (which is part of the I<groff> package),
Configure will B<not> prompt you to install I<man> pages.

=item * Permissions

On WinNT with either the I<ntea> or I<ntsec> C<CYGWIN> settings, directory
and file permissions may not be set correctly.  Since the build process
creates directories and files, to be safe you may want to run a
C<chmod -R +w *> on the entire Perl source tree.

Also, it is a well known WinNT "feature" that files created by a login
that is a member of the I<Administrators> group will be owned by the
I<Administrators> group.  Depending on your umask, you may find that you
can not write to files that you just created (because you are no longer
the owner).  When using the I<ntsec> C<CYGWIN> setting, this is not an
issue because it "corrects" the ownership to what you would expect on
a UNIX system.

=back

=head1 CONFIGURE PERL ON CYGWIN

The default options gathered by Configure with the assistance of
F<hints/cygwin.sh> will build a Perl that supports dynamic loading
(which requires a shared F<libperl.dll>).

This will run Configure and keep a record:

  ./Configure 2>&1 | tee log.configure

If you are willing to accept all the defaults run Configure with B<-de>.
However, several useful customizations are available.

=head2 Stripping Perl Binaries on Cygwin

It is possible to strip the EXEs and DLLs created by the build process.
The resulting binaries will be significantly smaller.  If you want the
binaries to be stripped, you can either add a B<-s> option when Configure
prompts you,

  Any additional ld flags (NOT including libraries)? [none] -s
  Any special flags to pass to gcc to use dynamic linking? [none] -s
  Any special flags to pass to ld2 to create a dynamically loaded library?
  [none] -s

or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
near the end of the file.

=head2 Optional Libraries for Perl on Cygwin

Several Perl functions and modules depend on the existence of
some optional libraries.  Configure will find them if they are
installed in one of the directories listed as being used for library
searches.  Pre-built packages for most of these are available from
the Cygwin installer.

=over 4

=item * C<-lcrypt>

The crypt package distributed with Cygwin is a Linux compatible 56-bit
DES crypt port by Corinna Vinschen.

Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.

The DES based Ultra Fast Crypt port was done by Alexey Truhan:

  ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz

NOTE: There are various export restrictions on DES implementations,
see the glibc README for more details.

The MD5 port was done by Andy Piper:

  ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz

=item * C<-lgdbm> (C<use GDBM_File>)

GDBM is available for Cygwin.

NOTE: The GDBM library only works on NTFS partitions.

=item * C<-ldb> (C<use DB_File>)

BerkeleyDB is available for Cygwin.

NOTE: The BerkeleyDB library only completely works on NTFS partitions.

=item * C<-lcygipc> (C<use IPC::SysV>)

A port of SysV IPC is available for Cygwin.

NOTE: This has B<not> been extensively tested.  In particular,
C<d_semctl_semun> is undefined because it fails a Configure test
and on Win9x the I<shm*()> functions seem to hang.  It also creates
a compile time dependency because F<perl.h> includes F<<sys/ipc.h>>
and F<<sys/sem.h>> (which will be required in the future when compiling
CPAN modules). CURRENTLY NOT SUPPORTED!

=item * C<-lutil>

Included with the standard Cygwin netrelease is the inetutils package
which includes libutil.a.

=back

=head2 Configure-time Options for Perl on Cygwin

The F<INSTALL> document describes several Configure-time options.  Some of
these will work with Cygwin, others are not yet possible.  Also, some of
these are experimental.  You can either select an option when Configure
prompts you or you can define (undefine) symbols on the command line.

=over 4

=item * C<-Uusedl>

Undefining this symbol forces Perl to be compiled statically.

=item * C<-Uusemymalloc>

By default Perl uses the C<malloc()> included with the Perl source.  If you
want to force Perl to build with the system C<malloc()> undefine this symbol.

=item * C<-Uuseperlio>

Undefining this symbol disables the PerlIO abstraction.  PerlIO is now the
default; it is not recommended to disable PerlIO.

=item * C<-Dusemultiplicity>

Multiplicity is required when embedding Perl in a C program and using
more than one interpreter instance.  This works with the Cygwin port.

=item * C<-Duse64bitint>

By default Perl uses 32 bit integers.  If you want to use larger 64
bit integers, define this symbol.

=item * C<-Duselongdouble>

I<gcc> supports long doubles (12 bytes).  However, several additional
long double math functions are necessary to use them within Perl
(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
strtold>).
These are B<not> yet available with Cygwin.

=item * C<-Dusethreads>

POSIX threads are implemented in Cygwin, define this symbol if you want
a threaded perl.

=item * C<-Duselargefiles>

Cygwin uses 64-bit integers for internal size and position calculations,
this will be correctly detected and defined by Configure.

=item * C<-Dmksymlinks>

Use this to build perl outside of the source tree.  This works with Cygwin.
Details can be found in the F<INSTALL> document.  This is the recommended
way to build perl from sources.

=back

=head2 Suspicious Warnings on Cygwin

You may see some messages during Configure that seem suspicious.

=over 4

=item * I<dlsym()>

I<ld2> is needed to build dynamic libraries, but it does not exist
when C<dlsym()> checking occurs (it is not created until C<make> runs).
You will see the following message:

  Checking whether your C<dlsym()> needs a leading underscore ...
  ld2: not found
  I can't compile and run the test program.
  I'm guessing that dlsym doesn't need a leading underscore.

Since the guess is correct, this is not a problem.

=item * Win9x and C<d_eofnblk>

Win9x does not correctly report C<EOF> with a non-blocking read on a
closed pipe.  You will see the following messages:

  But it also returns -1 to signal EOF, so be careful!
  WARNING: you can't distinguish between EOF and no data!

  *** WHOA THERE!!! ***
      The recommended value for $d_eofnblk on this machine was "define"!
      Keep the recommended value? [y]

At least for consistency with WinNT, you should keep the recommended
value.

=item * Compiler/Preprocessor defines

The following error occurs because of the Cygwin C<#define> of
C<_LONG_DOUBLE>:

  Guessing which symbols your C compiler and preprocessor define...
  try.c:<line#>: missing binary operator

This failure does not seem to cause any problems.  With older gcc
versions, "parse error" is reported instead of "missing binary
operator".

=back

=head1 MAKE ON CYGWIN

Simply run I<make> and wait:

  make 2>&1 | tee log.make

=head2 Errors on Cygwin

Errors like these are normal:

  ...
  make: [extra.pods] Error 1 (ignored)
  ...
  make: [extras.make] Error 1 (ignored)

=head2 ld2 on Cygwin

During C<make>, I<ld2> will be created and installed in your $installbin
directory (where you said to put public executables).  It does not
wait until the C<make install> process to install the I<ld2> script,
this is because the remainder of the C<make> refers to I<ld2> without
fully specifying its path and does this from multiple subdirectories.
The assumption is that $installbin is in your current C<PATH>.  If this
is not the case C<make> will fail at some point.  If this happens,
just manually copy I<ld2> from the source directory to somewhere in
your C<PATH>.

=head1 TEST ON CYGWIN

There are two steps to running the test suite:

  make test 2>&1 | tee log.make-test

  cd t;./perl harness 2>&1 | tee ../log.harness

The same tests are run both times, but more information is provided when
running as C<./perl harness>.

Test results vary depending on your host system and your Cygwin
configuration.  If a test can pass in some Cygwin setup, it is always
attempted and explainable test failures are documented.  It is possible
for Perl to pass all the tests, but it is more likely that some tests
will fail for one of the reasons listed below.

=head2 File Permissions on Cygwin

UNIX file permissions are based on sets of mode bits for
{read,write,execute} for each {user,group,other}.  By default Cygwin
only tracks the Win32 read-only attribute represented as the UNIX file
user write bit (files are always readable, files are executable if they
have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are
always readable and executable).  On WinNT with the I<ntea> C<CYGWIN>
setting, the additional mode bits are stored as extended file attributes.
On WinNT with the I<ntsec> C<CYGWIN> setting, permissions use the standard
WinNT security descriptors and access control lists.  Without one of
these options, these tests will fail (listing not updated yet):

  Failed Test           List of failed
  ------------------------------------
  io/fs.t               5, 7, 9-10
  lib/anydbm.t          2
  lib/db-btree.t        20
  lib/db-hash.t         16
  lib/db-recno.t        18
  lib/gdbm.t            2
  lib/ndbm.t            2
  lib/odbm.t            2
  lib/sdbm.t            2
  op/stat.t             9, 20 (.tmp not an executable extension)

=head2 NDBM_File and ODBM_File do not work on FAT filesystems

Do not use NDBM_File or ODBM_File on FAT filesystem.  They can be
built on a FAT filesystem, but many tests will fail:

 ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1-2 4 16-71
 ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
 ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
 ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7-11
 ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1-4
 run/fresh_perl.t                          97    1   1.03%  91

If you intend to run only on FAT (or if using AnyDBM_File on FAT),
run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
NDBM_File and ODBM_File being built.

With NTFS (and CYGWIN=ntsec), there should be no problems even if
perl was built on FAT.

=head2 C<fork()> failures in io_* tests

A C<fork()> failure may result in the following tests failing:

  ext/IO/lib/IO/t/io_multihomed.t
  ext/IO/lib/IO/t/io_sock.t
  ext/IO/lib/IO/t/io_unix.t

See comment on fork in L<Miscellaneous> below.

=head1 Specific features of the Cygwin port

=head2 Script Portability on Cygwin

Cygwin does an outstanding job of providing UNIX-like semantics on top of
Win32 systems.  However, in addition to the items noted above, there are
some differences that you should know about.  This is a very brief guide
to portability, more information can be found in the Cygwin documentation.

=over 4

=item * Pathnames

Cygwin pathnames can be separated by forward (F</>) or backward (F<\\>)
slashes.  They may also begin with drive letters (F<C:>) or Universal
Naming Codes (F<//UNC>).  DOS device names (F<aux>, F<con>, F<prn>,
F<com*>, F<lpt?>, F<nul>) are invalid as base filenames.  However, they
can be used in extensions (e.g., F<hello.aux>).  Names may contain all
printable characters except these:

  : * ? " < > |

File names are case insensitive, but case preserving.  A pathname that
contains a backslash or drive letter is a Win32 pathname (and not subject
to the translations applied to POSIX style pathnames).

=item * Text/Binary

When a file is opened it is in either text or binary mode.  In text mode
a file is subject to CR/LF/Ctrl-Z translations.  With Cygwin, the default
mode for an C<open()> is determined by the mode of the mount that underlies
the file.  Perl provides a C<binmode()> function to set binary mode on files
that otherwise would be treated as text.  C<sysopen()> with the C<O_TEXT>
flag sets text mode on files that otherwise would be treated as binary:

    sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)

C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
mode.

The text/binary issue is covered at length in the Cygwin documentation.

=item * PerlIO

PerlIO overrides the default Cygwin Text/Binary behaviour.  A file will
always treated as binary, regardless which mode of the mount it lives on,
just like it is in UNIX.  So CR/LF translation needs to be requested in
either the C<open()> call like this:

  open(FH, ">:crlf", "out.txt");

which will do conversion from LF to CR/LF on the output, or in the
environment settings (add this to your .bashrc):

  export PERLIO=crlf

which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
on every output generated by perl.

=item * F<.exe>

The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe>
extension transparent by looking for F<foo.exe> when you ask for F<foo>
(unless a F<foo> also exists).  Cygwin does not require a F<.exe>
extension, but I<gcc> adds it automatically when building a program.
However, when accessing an executable as a normal file (e.g., I<cp>
in a makefile) the F<.exe> is not transparent.  The I<install> included
with Cygwin automatically appends a F<.exe> when necessary.

=item * cygwin vs. windows process ids

Cygwin processes have their own pid, which is different from the
underlying windows pid.  Most posix compliant Proc functions expect
the cygwin pid, but several Win32::Process functions expect the
winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
the winpid.  Use C<Cygwin::winpid_to_pid()> and C<Cygwin::winpid_to_pid()>
to translate between them.

=item * C<chown()>

On WinNT C<chown()> can change a file's user and group IDs.  On Win9x C<chown()>
is a no-op, although this is appropriate since there is no security model.

=item * Miscellaneous

File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
returns C<ENOSYS>.

Win9x can not C<rename()> an open file (although WinNT can).

The Cygwin C<chroot()> implementation has holes (it can not restrict file
access by native Win32 programs).

Inplace editing C<perl -i> of files doesn't work without doing a backup
of the file being edited C<perl -i.bak> because of windowish restrictions,
therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
without specifying a backup extension.

Using C<fork()> after loading multiple dlls may fail with an internal cygwin
error like the following:

  C:\CYGWIN\BIN\PERL.EXE: *** couldn't allocate memory 0x10000(4128768) for 'C:\CYGWIN\LIB\PERL5\5.6.1\CYGWIN-MULTI\AUTO\SOCKET\SOCKET.DLL' alignment, Win32 error 8

    200 [main] perl 377147 sync_with_child: child -395691(0xB8) died before initialization with status code 0x1
   1370 [main] perl 377147 sync_with_child: *** child state child loading dlls

Use the rebase utility to resolve the conflicting dll addresses.  The
rebase package is included in the Cygwin netrelease.  Use setup.exe from
F<http://www.cygwin.com/setup.exe> to install it and run rebaseall.

=back

=head2 Prebuilt methods:

=over 4

=item C<Cwd::cwd>

Returns current working directory.

=item C<Cygwin::pid_to_winpid>

Translates a cygwin pid to the corresponding Windows pid (which may or
may not be the same).

=item C<Cygwin::winpid_to_pid>

Translates a Windows pid to the corresponding cygwin pid (if any).

=back

=head1 INSTALL PERL ON CYGWIN

This will install Perl, including I<man> pages.

  make install 2>&1 | tee log.make-install

NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
you to install I<perl> into F</usr/bin>.

You may need to be I<Administrator> to run C<make install>.  If you
are not, you must have write access to the directories in question.

Information on installing the Perl documentation in HTML format can be
found in the F<INSTALL> document.

=head1 MANIFEST ON CYGWIN

These are the files in the Perl release that contain references to Cygwin.
These very brief notes attempt to explain the reason for all conditional
code.  Hopefully, keeping this up to date will allow the Cygwin port to
be kept as clean as possible (listing not updated yet).

=over 4

=item Documentation

  INSTALL README.cygwin README.win32 MANIFEST
  Changes Changes5.005 Changes5.004 Changes5.6
  pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
  pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
  pod/perlhist.pod pod/perlmodlib.pod perl/buildtoc pod/perltoc.pod

=item Build, Configure, Make, Install

  cygwin/Makefile.SHs
  cygwin/ld2.in
  cygwin/perlld.in
  ext/IPC/SysV/hints/cygwin.pl
  ext/NDBM_File/hints/cygwin.pl
  ext/ODBM_File/hints/cygwin.pl
  hints/cygwin.sh
  Configure             - help finding hints from uname,
                          shared libperl required for dynamic loading
  Makefile.SH           - linklibperl
  Porting/patchls       - cygwin in port list
  installman            - man pages with :: translated to .
  installperl           - install dll/ld2/perlld, install to pods
  makedepend.SH         - uwinfix

=item Tests

  t/io/tell.t           - binmode
  t/lib/b.t             - ignore Cwd from os_extras
  t/lib/glob-basic.t    - Win32 directory list access differs from read mode
  t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
  t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
                          (cache manager sometimes preserves ctime of file
                          previously created and deleted), no -u (setuid)
  t/lib/cygwin.t	- builtin cygwin function tests

=item Compiled Perl Source

  EXTERN.h              - __declspec(dllimport)
  XSUB.h                - __declspec(dllexport)
  cygwin/cygwin.c       - os_extras (getcwd, spawn, Cygwin::winpid_to_pid,
                          Cygwin::pid_to_winpid)
  perl.c                - os_extras
  perl.h                - binmode
  doio.c                - win9x can not rename a file when it is open
  pp_sys.c              - do not define h_errno, pp_system with spawn
  util.c                - use setenv

=item Compiled Module Source

  ext/POSIX/POSIX.xs    - tzname defined externally
  ext/SDBM_File/sdbm/pair.c
                        - EXTCONST needs to be redefined from EXTERN.h
  ext/SDBM_File/sdbm/sdbm.c
                        - binary open

=item Perl Modules/Scripts

  lib/Cwd.pm            - hook to internal Cwd::cwd
  lib/ExtUtils/MakeMaker.pm
                        - require MM_Cygwin.pm
  lib/ExtUtils/MM_Cygwin.pm
                        - canonpath, cflags, manifypods, perl_archive
  lib/File/Find.pm      - on remote drives stat() always sets st_nlink to 1
  lib/File/Spec/Unix.pm - preserve //unc
  lib/File/Temp.pm      - no directory sticky bit
  lib/perl5db.pl        - use stdin not /dev/tty
  utils/perldoc.PL      - version comment

=back

=head1 BUGS ON CYGWIN

Support for swapping real and effective user and group IDs is incomplete.
On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
However, additional Cygwin calls for manipulating WinNT access tokens
and security contexts are required.

=head1 AUTHORS

Charles Wilson <cwilson@ece.gatech.edu>,
Eric Fifer <egf7@columbia.edu>,
alexander smishlajev <als@turnhere.com>,
Steven Morlock <newspost@morlock.net>,
Sebastien Barre <Sebastien.Barre@utc.fr>,
Teun Burgers <burgers@ecn.nl>,
Gerrit P. Haase <gp@familiehaase.de>.

=head1 HISTORY

Last updated: 2005-02-11

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

=head1 NAME

perldgux - Perl under DG/UX.

=head1 SYNOPSIS

One can read this document in the following formats:

        man perldgux
        view perl perldgux
        explorer perldgux.html
        info perldgux

to list some (not all may be available simultaneously), or it may
be read I<as is>: as F<README.dgux>.

=cut

Contents

 perldgux - Perl under DG/UX.

      NAME
      SYNOPSIS
      DESCRIPTION
      BUILD
         -  Non-threaded Case
         -  Threaded Case
         -  Testing
         -  Installing the built perl
      AUTHOR
      SEE ALSO

=head1 DESCRIPTION

Perl 5.7/8.x for DG/UX ix86 R4.20MU0x

=head1 BUILDING PERL ON DG/UX

=head2 Non-threaded Perl on DG/UX

Just run ./Configure script from the top directory.
Then give "make" to compile.

=head2 Threaded Perl on DG/UX

If you are using as compiler GCC-2.95.x rev(DG/UX)
an easy solution for configuring perl in your DG/UX
machine is to run the command:

./Configure -Dusethreads -Duseithreads -Dusedevel -des

This will automatically accept all the defaults and
in particular /usr/local/ as installation directory.
Note that GCC-2.95.x rev(DG/UX) knows the switch
-pthread which allows it to link correctly DG/UX's
-lthread library.

If you want to change the installation directory or
have a standard DG/UX with C compiler GCC-2.7.2.x
then you have no choice than to do an interactive
build by issuing the command:

./Configure -Dusethreads -Duseithreads

In particular with GCC-2.7.2.x accept all the defaults
and *watch* out for the message:

    Any additional ld flags (NOT including libraries)? [ -pthread]

Instead of -pthread put here -lthread. CGCC-2.7.2.x
that comes with the DG/UX OS does NOT know the -pthread
switch. So your build will fail if you choose the defaults.
After configuration is done correctly give "make" to compile.

=head2 Testing Perl on DG/UX

Issuing a "make test" will run all the tests.
If the test lib/ftmp-security gives you as a result
something like

    lib/ftmp-security....File::Temp::_gettemp:
    Parent directory (/tmp/) is not safe (sticky bit not set
    when world writable?) at lib/ftmp-security.t line 100

don't panic and just set the sticky bit in your /tmp
directory by doing the following as root:

cd /
chmod +t /tmp (=set the sticky bit to /tmp).

Then rerun the tests. This time all must be OK.

=head2 Installing the built perl on DG/UX

Run the command "make install"

=head1 AUTHOR

Takis Psarogiannakopoulos
Universirty of Cambridge
Centre for Mathematical Sciences
Department of Pure Mathematics
Wilberforce road
Cambridge CB3 0WB , UK
email <takis@XFree86.Org>

=head1 SEE ALSO

perl(1).

=cut

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

=head1 NAME

perldos - Perl under DOS, W31, W95.

=head1 SYNOPSIS

These are instructions for building Perl under DOS (or w??), using
DJGPP v2.03 or later.  Under w95 long filenames are supported.

=head1 DESCRIPTION

Before you start, you should glance through the README file
found in the top-level directory where the Perl distribution
was extracted.  Make sure you read and understand the terms under
which this software is being distributed.

This port currently supports MakeMaker (the set of modules that
is used to build extensions to perl).  Therefore, you should be
able to build and install most extensions found in the CPAN sites.

Detailed instructions on how to build and install perl extension
modules, including XS-type modules, is included.  See 'BUILDING AND
INSTALLING MODULES'.

=head2 Prerequisites for Compiling Perl on DOS

=over 4

=item DJGPP

DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit,
protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible
operating systems, by DJ Delorie <dj@delorie.com> and friends.

For more details (FAQ), check out the home of DJGPP at:

        http://www.delorie.com/djgpp/

If you have questions about DJGPP, try posting to the DJGPP newsgroup:
comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.

You can find the full DJGPP distribution on any SimTel.Net mirror all over
the world. Like:

        ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2*

You need the following files to build perl (or add new modules):

        v2/djdev203.zip
        v2gnu/bnu2112b.zip
        v2gnu/gcc2953b.zip
        v2gnu/bsh204b.zip
        v2gnu/mak3791b.zip
        v2gnu/fil40b.zip
        v2gnu/sed3028b.zip
        v2gnu/txt20b.zip
        v2gnu/dif272b.zip
        v2gnu/grep24b.zip
        v2gnu/shl20jb.zip
        v2gnu/gwk306b.zip
        v2misc/csdpmi5b.zip

or possibly any newer version.

=item Pthreads

Thread support is not tested in this version of the djgpp perl.

=back

=head2 Shortcomings of Perl under DOS

Perl under DOS lacks some features of perl under UNIX because of
deficiencies in the UNIX-emulation, most notably:

=over 4

=item *

fork() and pipe()

=item *

some features of the UNIX filesystem regarding link count and file dates

=item *

in-place operation is a little bit broken with short filenames

=item *

sockets

=back

=head2 Building Perl on DOS

=over 4

=item *

Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want
to use long file names under w95 and also to get Perl to pass all its
tests, don't forget to use

        set LFN=y
        set FNCASE=y

before unpacking the archive.

=item *

Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
directory.

        ln -s bash.exe sh.exe

[If you have the recommended version of bash for DJGPP, this is already
done for you.]

And make the C<SHELL> environment variable point to this F<sh.exe>:

        set SHELL=c:/djgpp/bin/sh.exe (use full path name!)

You can do this in F<djgpp.env> too. Add this line BEFORE any section
definition:

        +SHELL=%DJDIR%/bin/sh.exe

=item *

If you have F<split.exe> and F<gsplit.exe> in your path, then rename
F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.

[If you have the recommended versions of djdev, shell utilities and
gawk, all these are already done for you, and you will not need to do
anything.]

=item *

Chdir to the djgpp subdirectory of perl toplevel and type the following
commands:

        set FNCASE=y
        configure.bat

This will do some preprocessing then run the Configure script for you.
The Configure script is interactive, but in most cases you just need to
press ENTER.  The "set" command ensures that DJGPP preserves the letter
case of file names when reading directories.  If you already issued this
set command when unpacking the archive, and you are in the same DOS
session as when you unpacked the archive, you don't have to issue the
set command again.  This command is necessary *before* you start to
(re)configure or (re)build perl in order to ensure both that perl builds
correctly and that building XS-type modules can succeed.  See the DJGPP
info entry for "_preserve_fncase" for more information:

        info libc alphabetical _preserve_fncase

If the script says that your package is incomplete, and asks whether
to continue, just answer with Y (this can only happen if you don't use
long filenames or forget to issue "set FNCASE=y" first).

When Configure asks about the extensions, I suggest IO and Fcntl,
and if you want database handling then SDBM_File or GDBM_File
(you need to install gdbm for this one). If you want to use the
POSIX extension (this is the default), make sure that the stack
size of your F<cc1.exe> is at least 512kbyte (you can check this
with: C<stubedit cc1.exe>).

You can use the Configure script in non-interactive mode too.
When I built my F<perl.exe>, I used something like this:

        configure.bat -des

You can find more info about Configure's command line switches in
the F<INSTALL> file.

When the script ends, and you want to change some values in the
generated F<config.sh> file, then run

        sh Configure -S

after you made your modifications.

IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
environment variable before running the script:

        set CONFIG=

=item *

Now you can compile Perl. Type:

        make

=back

=head2 Testing Perl on DOS

Type:

        make test

If you're lucky you should see "All tests successful". But there can be
a few failed subtests (less than 5 hopefully) depending on some external
conditions (e.g. some subtests fail under linux/dosemu or plain dos
with short filenames only).

=head2 Installation of Perl on DOS

Type:

        make install

This will copy the newly compiled perl and libraries into your DJGPP
directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
goes under C<($DJDIR)/lib/perl5/pod>.

=head1 BUILDING AND INSTALLING MODULES ON DOS

=head2 Building Prerequisites for Perl on DOS

For building and installing non-XS modules, all you need is a working
perl under DJGPP.  Non-XS modules do not require re-linking the perl
binary, and so are simpler to build and install.

XS-type modules do require re-linking the perl binary, because part of
an XS module is written in "C", and has to be linked together with the
perl binary to be executed.  This is required because perl under DJGPP
is built with the "static link" option, due to the lack of "dynamic
linking" in the DJGPP environment.

Because XS modules require re-linking of the perl binary, you need both
the perl binary distribution and the perl source distribution to build
an XS extension module.  In addition, you will have to have built your
perl binary from the source distribution so that all of the components
of the perl binary are available for the required link step.

=head2 Unpacking CPAN Modules on DOS

First, download the module package from CPAN (e.g., the "Comma Separated
Value" text package, Text-CSV-0.01.tar.gz).  Then expand the contents of
the package into some location on your disk.  Most CPAN modules are
built with an internal directory structure, so it is usually safe to
expand it in the root of your DJGPP installation.  Some people prefer to
locate source trees under /usr/src (i.e., C<($DJDIR)/usr/src>), but you may
put it wherever seems most logical to you, *EXCEPT* under the same
directory as your perl source code.  There are special rules that apply
to modules which live in the perl source tree that do not apply to most
of the modules in CPAN.

Unlike other DJGPP packages, which are normal "zip" files, most CPAN
module packages are "gzipped tarballs".  Recent versions of WinZip will
safely unpack and expand them, *UNLESS* they have zero-length files.  It
is a known WinZip bug (as of v7.0) that it will not extract zero-length
files.

From the command line, you can use the djtar utility provided with DJGPP
to unpack and expand these files.  For example:

        C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz

This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling
it with the source for this module.

=head2 Building Non-XS Modules on DOS

To build a non-XS module, you can use the standard module-building
instructions distributed with perl modules.

    perl Makefile.PL
    make
    make test
    make install

This is sufficient because non-XS modules install only ".pm" files and
(sometimes) pod and/or man documentation.  No re-linking of the perl
binary is needed to build, install or use non-XS modules.

=head2 Building XS Modules on DOS

To build an XS module, you must use the standard module-building
instructions distributed with perl modules *PLUS* three extra
instructions specific to the DJGPP "static link" build environment.

    set FNCASE=y
    perl Makefile.PL
    make
    make perl
    make test
    make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe
    make install

The first extra instruction sets DJGPP's FNCASE environment variable so
that the new perl binary which you must build for an XS-type module will
build correctly.  The second extra instruction re-builds the perl binary
in your module directory before you run "make test", so that you are
testing with the new module code you built with "make".  The third extra
instruction installs the perl binary from your module directory into the
standard DJGPP binary directory, C<($DJDIR)/bin>, replacing your
previous perl binary.

Note that the MAP_TARGET value *must* have the ".exe" extension or you
will not create a "perl.exe" to replace the one in C<($DJDIR)/bin>.

When you are done, the XS-module install process will have added information
to your "perllocal" information telling that the perl binary has been replaced,
and what module was installed.  You can view this information at any time
by using the command:

        perl -S perldoc perllocal

=head1 AUTHOR

Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se> [Installing/building perl]

Peter J. Farley III F<pjfarley@banet.net> [Building/installing modules]

=head1 SEE ALSO

perl(1).

=cut

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see pod/perlpod.pod) which is
specially designed to be readable as is.

=head1 NAME

README.epoc - Perl for EPOC

=head1 SYNOPSIS

Perl 5 README file for the EPOC Release 5 operating system.

=head1 INTRODUCTION

EPOC is an OS for palmtops and mobile phones. For more informations look at:
http://www.symbian.com/

This is a port of perl to the epocemx SDK by Eberhard Mattes, which
itself uses the SDK by symbian. Essentially epocemx it is a POSIX
look alike environment for the EPOC OS.  For more information look at:
http://epocemx.sourceforge.net/

perl and epocemx runs on Epoc Release 5 machines: Psion 5mx, 5mx Pro,
Psion Revo, Psion Netbook and on the Ericsson M128. It may run on Epoc
Release 3 Hardware (Series 5 classic), too. For more information about
this hardware please refer to http://www.psion.com/

Vendors which like to have support for their devices are free to send
me a sample.

=head1 INSTALLING PERL ON EPOC

You can download a ready-to-install version from
http://www.oflebbe.de/oflebbe/perl/

You will need at least ~6MB free space in order to install and run perl.

Please install the emxusr.sis package from
http://epocemx.sourceforge.net/ first.

Install perl.sis on the EPOC machine. If you do not know how to do
that, consult your PsiWin documentation.

Perl itself and its standard library is using 4 MB disk space.
Unicode support and some other modules are left out. (For details,
please look into epoc/createpkg.pl). If you like to use these modules,
you are free to copy them from a current perl release.

=head1 STARTING PERL ON EPOC

Please use the epocemx shell to start perl. perl integrates with the
conventions of epocemx.

=head2 Editors on Epoc

A suitable text editor can be downloaded from symbian
http://www.symbian.com/developer/downloads/files/editor.zip

=head2 Features of Perl on Epoc

The built-in function EPOC::getcwd returns the current directory.

=head2 Restrictions of Perl on Epoc

Features are left out, because of restrictions of the POSIX support in
EPOC:

=over 4

=item *

socket IO is only implemented poorly. You can only use sysread and
syswrite on them. The commands read, write, print, <> do not work for
sockets. This may change iff epocemx supports sockets.

=item *

kill, alarm and signals. Do not try to use them. This may be
impossible to implement on EPOC.

=item *

select is missing.

=item *

binmode does not exist. (No CR LF to LF translation for text files)

=item *

EPOC does not handle the notion of current drive and current
directory very well (i.e. not at all, but it tries hard to emulate
one). See PATH.

=item *

Heap is limited to 4MB.

=item *

Dynamic loading is not implemented.

=back

=head2 Compiling Perl 5 on the EPOC cross compiling environment

Sorry, this is far too short.

=over 4

=item *

You will need the epocemx SDK from Eberhard Mattes.

=item *

Get the Perl sources from your nearest CPAN site.

=item *

Unpack the sources.

=item *

Build a native perl from this sources... Make sure to save the
miniperl executable as miniperl.native.

Start again from scratch

      cp epoc/* .
      ./Configure -S
      make
      cp miniperl.native miniperl
      touch miniperl.exe
      make
      perl createpkg.pl

      emxsis perl.pkg perl.sis

=back

=head1 SUPPORT STATUS OF PERL ON EPOC

I'm offering this port "as is". You can ask me questions, but I can't
guarantee I'll be able to answer them. Since the port to epocemx is
quite new, please check the web for updates first.

Very special thanks to Eberhard Mattes for epocemx.

=head1 AUTHOR

Olaf Flebbe <olaf@oflebbe.de>
http://www.oflebbe.de/oflebbe/perl/

=head1 LAST UPDATE

2003-01-18

=cut

If you read this file _as_is_, just ignore the funny characters you
see.  It is written in the POD format (see pod/perlpod.pod) which is
specifically designed to be readable as is.

=head1 NAME

README.freebsd - Perl version 5 on FreeBSD systems

=head1 DESCRIPTION

This document describes various features of FreeBSD that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 FreeBSD core dumps from readdir_r with ithreads

When perl is configured to use ithreads, it will use re-entrant library calls
in preference to non-re-entrant versions.  There is a bug in FreeBSD's
C<readdir_r> function in versions 4.5 and earlier that can cause a SEGV when
reading large directories. A patch for FreeBSD libc is available
(see http://www.freebsd.org/cgi/query-pr.cgi?pr=misc/30631 )
which has been integrated into FreeBSD 4.6.

=head2 $^X doesn't always contain a full path in FreeBSD

perl 5.8.0 sets C<$^X> where possible to a full path by asking the operating
system. On FreeBSD the full path of the perl interpreter is found by reading
the symlink F</proc/curproc/file>. There is a bug on FreeBSD, where the
result of reading this symlink is can be wrong in certain circumstances
(see http://www.freebsd.org/cgi/query-pr.cgi?pr=35703 ).
In these cases perl will fall back to the old behaviour of using C's
argv[0] value for C<$^X>.

=head2 Perl will no longer be part of "base FreeBSD"

Not as bad as it sounds--what this means is that Perl will no longer be
part of the B<kernel build system> of FreeBSD.  Perl will still very
probably be part of the "default install", and in any case the latest
version will be in the ports system.  The first FreeBSD version this
change will affect is 5.0, all 4.n versions will keep the status quo.

=head1 AUTHOR

Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic
and Tim Bunce.

Please report any errors, updates, or suggestions to F<perlbug@perl.org>.

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems

=head1 DESCRIPTION

This document describes various features of HP's Unix operating system
(HP-UX) that will affect how Perl version 5 (hereafter just Perl) is
compiled and/or runs.

=head2 Using perl as shipped with HP-UX

Application release September 2001, HP-UX 11.00 is the first to ship
with Perl. By the time it was perl-5.6.1 in /opt/perl. The first
occurrence is on CD 5012-7954 and can be installed using

  swinstall -s /cdrom perl

assuming you have mounted that CD on /cdrom. In this version the
following modules were installed:

  ActivePerl::DocTools-0.04   HTML::Parser-3.19   XML::DOM-1.25
  Archive::Tar-0.072          HTML::Tagset-3.03   XML::Parser-2.27
  Compress::Zlib-1.08         MIME::Base64-2.11   XML::Simple-1.05
  Convert::ASN1-0.10          Net-1.07            XML::XPath-1.09
  Digest::MD5-2.11            PPM-2.1.5           XML::XSLT-0.32
  File::CounterFile-0.12      SOAP::Lite-0.46     libwww-perl-5.51
  Font::AFM-1.18              Storable-1.011      libxml-perl-0.07
  HTML-Tree-3.11              URI-1.11            perl-ldap-0.23

The build was a portable hppa-1.1 multithread build that supports large
files compiled with gcc-2.9-hppa-991112

If you perform a new installation, then Perl will be installed
automatically.

More recent (preinstalled) HP-UX systems have more recent versions of
Perl and the updated modules.

=head2 Using perl from HP's porting centre

HP porting centre tries very hard to keep up with customer demand and
release updates from the Open Source community. Having precompiled
Perl binaries available is obvious.

The HP porting centres are limited in what systems they are allowed
to port to and they usually choose the two most recent OS versions
available. This means that at the moment of writing, there are only
HP-UX 11.11 (pa-risc 2.0) and HP-UX 11.23 (Itanium 2) ports available
on the porting centres.

HP has asked the porting centre to move Open Source binaries
from /opt to /usr/local, so binaries produced since the start
of July 2002 are located in /usr/local.

One of HP porting centres URL's is http://hpux.connect.org.uk/
The port currently available is built with GNU gcc.

=head2 Compiling Perl 5 on HP-UX

When compiling Perl, you must use an ANSI C compiler.  The C compiler
that ships with all HP-UX systems is a K&R compiler that should only be
used to build new kernels.

Perl can be compiled with either HP's ANSI C compiler or with gcc.  The
former is recommended, as not only can it compile Perl with no
difficulty, but also can take advantage of features listed later that
require the use of HP compiler-specific command-line flags.

If you decide to use gcc, make sure your installation is recent and
complete, and be sure to read the Perl INSTALL file for more gcc-specific
details.

=head2 PA-RISC

HP's current Unix systems run on its own Precision Architecture
(PA-RISC) chip.  HP-UX used to run on the Motorola MC68000 family of
chips, but any machine with this chip in it is quite obsolete and this
document will not attempt to address issues for compiling Perl on the
Motorola chipset.

The most recent version of PA-RISC at the time of this document's last
update is 2.0. HP PA-RISC systems are usually refered to with model
description "HP 9000".

A complete list of models at the time the OS was built is in the file
/usr/sam/lib/mo/sched.models. The first column corresponds to the last
part of the output of the "model" command.  The second column is the
PA-RISC version and the third column is the exact chip type used.
(Start browsing at the bottom to prevent confusion ;-)

  # model
  9000/800/L1000-44
  # grep L1000-44 /usr/sam/lib/mo/sched.models
  L1000-44        2.0     PA8500

=head2 Portability Between PA-RISC Versions

An executable compiled on a PA-RISC 2.0 platform will not execute on a
PA-RISC 1.1 platform, even if they are running the same version of
HP-UX.  If you are building Perl on a PA-RISC 2.0 platform and want that
Perl to also run on a PA-RISC 1.1, the compiler flags +DAportable and
+DS32 should be used.

It is no longer possible to compile PA-RISC 1.0 executables on either
the PA-RISC 1.1 or 2.0 platforms.  The command-line flags are accepted,
but the resulting executable will not run when transferred to a PA-RISC
1.0 system.

=head2 PA-RISC 1.0

The original version of PA-RISC, HP no longer sells any system with this chip.

The following systems contained PA-RISC 1.0 chips:

  600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850,
  852, 855, 860, 865, 870, 890

=head2 PA-RISC 1.1

An upgrade to the PA-RISC design, it shipped for many years in many different
system.

The following systems contain with PA-RISC 1.1 chips:

  705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 744, 745,
  747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
  813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
  851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
  B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
  C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
  D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
  G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
  I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
  K420, S700i, S715, S744, S760, T500, T520

=head2 PA-RISC 2.0

The most recent upgrade to the PA-RISC design, it added support for
64-bit integer data.

As of the date of this document's last update, the following systems
contain PA-RISC 2.0 chips:

  700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
  893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
  C180, C180+, C180-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
  D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
  J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260-EG, K270, K360,
  K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000,
  L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
  T600, V2000, V2200, V2250, V2500, V2600

Just before HP took over Compaq, some systems were renamed. the link
that contained the explanation is dead, so here's a short summary:

  HP 9000 A-Class servers, now renamed HP Server rp2400 series.
  HP 9000 L-Class servers, now renamed HP Server rp5400 series.
  HP 9000 N-Class servers, now renamed HP Server rp7400.

  rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
  rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
  rp7410, rp7420, rp8400, rp8420, Superdome

The current naming convention is:

  aadddd
  ||||`+- 00 - 99 relative capacity & newness (upgrades, etc.)
  |||`--- unique number for each architecture to ensure different
  |||     systems do not have the same numbering across
  |||     architectures
  ||`---- 1 - 9 identifies family and/or relative positioning
  ||
  |`----- c = ia32 (cisc)
  |       p = pa-risc
  |       x = ia-64 (Itanium & Itanium 2)
  |       h = housing
  `------ t = tower
          r = rack optimized
          s = super scalable
          b = blade
          sa = appliance

=head2 Itanium Processor Family and HP-UX

HP-UX also runs on the new Itanium processor.  This requires the use
of a different version of HP-UX (currently 11.23 or 11i v2), and with
the exception of a few differences detailed below and in later sections,
Perl should compile with no problems.

Although PA-RISC binaries can run on Itanium systems, you should not
attempt to use a PA-RISC version of Perl on an Itanium system.  This is
because shared libraries created on an Itanium system cannot be loaded
while running a PA-RISC executable.

HP Itanium 2 systems are usually refered to with model description
"HP Integrity".

=head2 Itanium & Itanium 2

HP also ships servers with the 128-bit Itanium processor(s). As of the
date of this document's last update, the following systems contain
Itanium or Itanium 2 chips (this is very likely to be out of date):

  BL60p, rx1600, rx1620, rx2600, rx2600hptc, rx2620, rx4610, rx4640,
  rx5670, rx7620, rx8620, rx9610

To see all about your machine, type

  # model
  ia64 hp server rx2600
  # /usr/contrib/bin/machinfo

=head2 Building Dynamic Extensions on HP-UX

HP-UX supports dynamically loadable libraries (shared libraries).
Shared libraries end with the suffix .sl.  On Itanium systems,
they end with the suffix .so.

Shared libraries created on a platform using a particular PA-RISC
version are not usable on platforms using an earlier PA-RISC version by
default.  However, this backwards compatibility may be enabled using the
same +DAportable compiler flag (with the same PA-RISC 1.0 caveat
mentioned above).

Shared libraries created on an Itanium platform cannot be loaded on
a PA-RISC platform.  Shared libraries created on a PA-RISC platform
can only be loaded on an Itanium platform if it is a PA-RISC executable
that is attempting to load the PA-RISC library.  A PA-RISC shared
library cannot be loaded into an Itanium executable nor vice-versa.

To create a shared library, the following steps must be performed:

  1. Compile source modules with +z or +Z flag to create a .o module
     which contains Position-Independent Code (PIC).  The linker will
     tell you in the next step if +Z was needed.
     (For gcc, the appropriate flag is -fpic or -fPIC.)

  2. Link the shared library using the -b flag.  If the code calls
     any functions in other system libraries (e.g., libm), it must
     be included on this line.

(Note that these steps are usually handled automatically by the extension's
Makefile).

If these dependent libraries are not listed at shared library creation
time, you will get fatal "Unresolved symbol" errors at run time when the
library is loaded.

You may create a shared library that refers to another library, which
may be either an archive library or a shared library.  If this second
library is a shared library, this is called a "dependent library".  The
dependent library's name is recorded in the main shared library, but it
is not linked into the shared library.  Instead, it is loaded when the
main shared library is loaded.  This can cause problems if you build an
extension on one system and move it to another system where the
libraries may not be located in the same place as on the first system.

If the referred library is an archive library, then it is treated as a
simple collection of .o modules (all of which must contain PIC).  These
modules are then linked into the shared library.

Note that it is okay to create a library which contains a dependent
library that is already linked into perl.

Some extensions, like DB_File and Compress::Zlib use/require prebuilt
libraries for the perl extensions/modules to work. If these libraries
are built using the default configuration, it might happen that you
run into an error like "invalid loader fixup" during load phase.
HP is aware of this problem.  Search the HP-UX cxx-dev forums for
discussions about the subject.  The short answer is that B<everything>
(all libraries, everything) must be compiled with C<+z> or C<+Z> to be
PIC (position independent code).  (For gcc, that would be
C<-fpic> or C<-fPIC>).  In HP-UX 11.00 or newer the linker
error message should tell the name of the offending object file.

A more general approach is to intervene manually, as with an example for
the DB_File module, which requires SleepyCat's libdb.sl:

  # cd .../db-3.2.9/build_unix
  # vi Makefile
  ... add +Z to all cflags to create shared objects
  CFLAGS=         -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
		  -I/usr/local/include -I/usr/include/X11R6
  CXXFLAGS=       -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
		  -I/usr/local/include -I/usr/include/X11R6

  # make clean
  # make
  # mkdir tmp
  # cd tmp
  # ar x ../libdb.a
  # ld -b -o libdb-3.2.sl *.o
  # mv libdb-3.2.sl /usr/local/lib
  # rm *.o
  # cd /usr/local/lib
  # rm -f libdb.sl
  # ln -s libdb-3.2.sl libdb.sl

  # cd .../DB_File-1.76
  # make distclean
  # perl Makefile.PL
  # make
  # make test
  # make install

As of db-4.2.x it is no longer needed to do this by hand. Sleepycat
has changed the configuration process to add +z on HP-UX automatically.

  # cd .../db-4.2.25/build_unix
  # env CFLAGS=+DA2.0w LDFLAGS=+DA2.0w ../dist/configure

should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.

It is no longer possible to link PA-RISC 1.0 shared libraries (even
though the command-line flags are still present).

PA-RISC and Itanium object files are not interchangeable.  Although
you may be able to use ar to create an archive library of PA-RISC
object files on an Itanium system, you cannot link against it using
an Itanium link editor.

=head2 The HP ANSI C Compiler

When using this compiler to build Perl, you should make sure that the
flag -Aa is added to the cpprun and cppstdin variables in the config.sh
file (though see the section on 64-bit perl below). If you are using a
recent version of the Perl distribution, these flags are set automatically.

=head2 The GNU C Compiler

When you are going to use the GNU C compiler (gcc), and you don't have
gcc yet, you can either build it yourself from the sources (available
from e.g. http://www.gnu.ai.mit.edu/software/gcc/releases.html) or fetch
a prebuilt binary from the HP porting center. There are two places where
gcc prebuilds can be fetched; the first and best (for HP-UX 11 only) is
http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,547,00.html
the second is http://hpux.cs.utah.edu/hppd/hpux/Gnu/ where you can also
find the GNU binutils package. (Browse through the list, because there
are often multiple versions of the same package available).

Above mentioned distributions are depots. H.Merijn Brand has made prebuilt
gcc binaries available on http://mirrors.develooper.com/hpux/ and/or
http://www.cmve.net/~merijn/ for HP-UX 10.20, HP-UX 11.00, and HP-UX 11.11
(HP-UX 11i) in both 32- and 64-bit versions. These are bzipped tar archives
that also include recent GNU binutils and GNU gdb.  Read the instructions
on that page to rebuild gcc using itself.

On PA-RISC you need a different compiler for 32-bit applications and for
64-bit applications. On PA-RISC, 32-bit objects and 64-bit objects do
not mix. Period. There is no different behaviour for HP C-ANSI-C or GNU
gcc. So if you require your perl binary to use 64-bit libraries, like
Oracle-64bit, you MUST build a 64-bit perl.

Building a 64-bit capable gcc on PA-RISC from source is possible only when
you have the HP C-ANSI C compiler or an already working 64-bit binary of
gcc available. Best performance for perl is achieved with HP's native
compiler.

=head2 Using Large Files with Perl on HP-UX

Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
may be created and manipulated.  Three separate methods of doing this
are available.  Of these methods, the best method for Perl is to compile
using the -Duselargefiles flag to Configure.  This causes Perl to be
compiled using structures and functions in which these are 64 bits wide,
rather than 32 bits wide.  (Note that this will only work with HP's ANSI
C compiler.  If you want to compile Perl using gcc, you will have to get
a version of the compiler that supports 64-bit operations. See above for
where to find it.)

There are some drawbacks to this approach.  One is that any extension
which calls any file-manipulating C function will need to be recompiled
(just follow the usual "perl Makefile.PL; make; make test; make install"
procedure).

The list of functions that will need to recompiled is:
creat,		fgetpos,	fopen,
freopen,	fsetpos,	fstat,
fstatvfs,	fstatvfsdev,	ftruncate,
ftw,		lockf,		lseek,
lstat,		mmap,		nftw,
open,		prealloc,	stat,
statvfs,	statvfsdev,	tmpfile,
truncate,	getrlimit,	setrlimit

Another drawback is only valid for Perl versions before 5.6.0.  This
drawback is that the seek and tell functions (both the builtin version
and POSIX module version) will not perform correctly.

It is strongly recommended that you use this flag when you run
Configure.  If you do not do this, but later answer the question about
large files when Configure asks you, you may get a configuration that
cannot be compiled, or that does not function as expected.

=head2 Threaded Perl on HP-UX

It is possible to compile a version of threaded Perl on any version of
HP-UX before 10.30, but it is strongly suggested that you be running on
HP-UX 11.00 at least.

To compile Perl with threads, add -Dusethreads to the arguments of
Configure.  Verify that the -D_POSIX_C_SOURCE=199506L compiler flag is
automatically added to the list of flags.  Also make sure that -lpthread
is listed before -lc in the list of libraries to link Perl with. The
hints provided for HP-UX during Configure will try very hard to get
this right for you.

HP-UX versions before 10.30 require a separate installation of a POSIX
threads library package. Two examples are the HP DCE package, available
on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
April 1999 (B3920-13941)" or the Freely available PTH package, available
on H.Merijn's site (http://mirrors.develooper.com/hpux/).

If you are going to use the HP DCE package, the library used for threading
is /usr/lib/libcma.sl, but there have been multiple updates of that
library over time. Perl will build with the first version, but it
will not pass the test suite. Older Oracle versions might be a compelling
reason not to update that library, otherwise please find a newer version
in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672

reformatted output:

  d3:/usr/lib 106 > what libcma-*.1
  libcma-00000.1:
     HP DCE/9000 1.5               Module: libcma.sl (Export)
                                   Date: Apr 29 1996 22:11:24
  libcma-19739.1:
     HP DCE/9000 1.5 PHSS_19739-40 Module: libcma.sl (Export)
                                   Date: Sep  4 1999 01:59:07
  libcma-20608.1:
     HP DCE/9000 1.5 PHSS_20608    Module: libcma.1 (Export)
                                   Date: Dec  8 1999 18:41:23
  libcma-23672.1:
     HP DCE/9000 1.5 PHSS_23672    Module: libcma.1 (Export)
                                   Date: Apr  9 2001 10:01:06
  d3:/usr/lib 107 >

If you choose for the PTH package, use swinstall to install pth in
the default location (/opt/pth), and then make symbolic links to the
libraries from /usr/lib

  # cd /usr/lib
  # ln -s /opt/pth/lib/libpth* .

For building perl to support Oracle, it needs to be linked with libcl
and libpthread. So even if your perl is an unthreaded build, these
libraries might be required. See "Oracle on HP-UX" below.

=head2 64-bit Perl on HP-UX

Beginning with HP-UX 11.00, programs compiled under HP-UX can take
advantage of the LP64 programming environment (LP64 means Longs and
Pointers are 64 bits wide), in which scalar variables will be able
to hold numbers larger than 2^32 with complete precision.  Perl has
proven to be consistent and reliable in 64bit mode since 5.8.1 on
all HP-UX 11.xx.

As of the date of this document, Perl is fully 64-bit compliant on
HP-UX 11.00 and up for both cc- and gcc builds. If you are about to
build a 64-bit perl with GNU gcc, please read the gcc section carefully.

Should a user have the need for compiling Perl in the LP64 environment,
use the -Duse64bitall flag to Configure.  This will force Perl to be
compiled in a pure LP64 environment (with the +DD64 flag for HP C-ANSI-C,
with no additional options for GNU gcc 64-bit on PA-RISC, and with
-mlp64 for GNU gcc on Itanium).
If you want to compile Perl using gcc, you will have to get a version of
the compiler that supports 64-bit operations.)

You can also use the -Duse64bitint flag to Configure.  Although there
are some minor differences between compiling Perl with this flag versus
the -Duse64bitall flag, they should not be noticeable from a Perl user's
perspective. When configuring -Duse64bitint using a 64bit gcc on a
pa-risc architecture, -Duse64bitint is silently promoted to -Duse64bitall.

In both cases, it is strongly recommended that you use these flags when
you run Configure.  If you do not use do this, but later answer the
questions about 64-bit numbers when Configure asks you, you may get a
configuration that cannot be compiled, or that does not function as
expected.

=head2 Oracle on HP-UX

Using perl to connect to Oracle databases through DBI and DBD::Oracle
has caused a lot of people many headaches. Read README.hpux in the
DBD::Oracle for much more information. The reason to mention it here
is that Oracle requires a perl built with libcl and libpthread, the
latter even when perl is build without threads. Building perl using
all defaults, but still enabling to build DBD::Oracle later on can be
achieved using

  Configure -A prepend:libswanted='cl pthread ' ...

Do not forget the space before the trailing quote.

Also note that this does not (yet) work with all configurations,
it is known to fail with 64-bit versions of GCC.

=head2 GDBM and Threads on HP-UX

If you attempt to compile Perl with threads on an 11.X system and also
link in the GDBM library, then Perl will immediately core dump when it
starts up.  The only workaround at this point is to relink the GDBM
library under 11.X, then relink it into Perl.

=head2 NFS filesystems and utime(2) on HP-UX

If you are compiling Perl on a remotely-mounted NFS filesystem, the test
io/fs.t may fail on test #18.  This appears to be a bug in HP-UX and no
fix is currently available.

=head2 perl -P and // and HP-UX

If HP-UX Perl is compiled with flags that will cause problems if the
-P flag of Perl (preprocess Perl code with the C preprocessor before
perl sees it) is used.  The problem is that C<//>, being a C++-style
until-end-of-line comment, will disappear along with the remainder
of the line.  This means that common Perl constructs like

  s/foo//;

will turn into illegal code

  s/foo

The workaround is to use some other quoting separator than C<"/">,
like for example C<"!">:

  s!foo!!;

=head2 HP-UX Kernel Parameters (maxdsiz) for Compiling Perl

By default, HP-UX comes configured with a maximum data segment size of
64MB.  This is too small to correctly compile Perl with the maximum
optimization levels.  You can increase the size of the maxdsiz kernel
parameter through the use of SAM.

When using the GUI version of SAM, click on the Kernel Configuration
icon, then the Configurable Parameters icon.  Scroll down and select
the maxdsiz line.  From the Actions menu, select the Modify Configurable
Parameter item.  Insert the new formula into the Formula/Value box.
Then follow the instructions to rebuild your kernel and reboot your
system.

In general, a value of 256MB (or "256*1024*1024") is sufficient for
Perl to compile at maximum optimization.

=head1 nss_delete core dump from op/pwent or op/grent

You may get a bus error core dump from the op/pwent or op/grent
tests. If compiled with -g you will see a stack trace much like
the following:

  #0  0xc004216c in  () from /usr/lib/libc.2
  #1  0xc00d7550 in __nss_src_state_destr () from /usr/lib/libc.2
  #2  0xc00d7768 in __nss_src_state_destr () from /usr/lib/libc.2
  #3  0xc00d78a8 in nss_delete () from /usr/lib/libc.2
  #4  0xc01126d8 in endpwent () from /usr/lib/libc.2
  #5  0xd1950 in Perl_pp_epwent () from ./perl
  #6  0x94d3c in Perl_runops_standard () from ./perl
  #7  0x23728 in S_run_body () from ./perl
  #8  0x23428 in perl_run () from ./perl
  #9  0x2005c in main () from ./perl

The key here is the C<nss_delete> call.  One workaround for this
bug seems to be to create add to the file F</etc/nsswitch.conf>
(at least) the following lines

  group: files
  passwd: files

Whether you are using NIS does not matter.  Amazingly enough,
the same bug also affects Solaris.

=head1 AUTHOR

Jeff Okamoto <okamoto@corp.hp.com>
H.Merijn Brand <h.m.brand@xs4all.nl>

With much assistance regarding shared libraries from Marc Sabatella.

=head1 DATE

Version 0.7.6: 2005-12-20

=cut

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.hurd - Perl version 5 on Hurd

=head1 DESCRIPTION

If you want to use Perl on the Hurd, I recommend using the Debian
GNU/Hurd distribution ( see http://www.debian.org/ ), even if an
official, stable release has not yet been made.  The old "gnu-0.2"
binary distribution will most certainly have additional problems.

=head2 Known Problems with Perl on Hurd

The Perl test suite may still report some errors on the Hurd.  The
"lib/anydbm" and "pragma/warnings" tests will almost certainly fail.
Both failures are not really specific to the Hurd, as indicated by the
test suite output.

The socket tests may fail if the network is not configured.  You have
to make "/hurd/pfinet" the translator for "/servers/socket/2", giving
it the right arguments.  Try "/hurd/pfinet --help" for more
information.

Here are the statistics for Perl 5.005_62 on my system:

 Failed Test  Status Wstat Total Fail  Failed  List of failed
 -------------------------------------------------------------------------
 lib/anydbm.t                 12    1   8.33%  12
 pragma/warnings             333    1   0.30%  215

 8 tests and 24 subtests skipped.
 Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed, 99.98% okay.

There are quite a few systems out there that do worse!

However, since I am running a very recent Hurd snapshot, in which a lot of
bugs that were exposed by the Perl test suite have been fixed, you may
encounter more failures.  Likely candidates are: "op/stat", "lib/io_pipe",
"lib/io_sock", "lib/io_udp" and "lib/time".

In any way, if you're seeing failures beyond those mentioned in this
document, please consider upgrading to the latest Hurd before reporting
the failure as a bug.

=head1 AUTHOR

Mark Kettenis <kettenis@gnu.org>

Last Updated: Fri, 29 Oct 1999 22:50:30 +0200

If you read this file _as_is_, just ignore the funny characters you
see.  It is written in the POD format (see pod/perlpod.pod) which is
specifically designed to be readable as is.

=head1 NAME

README.irix - Perl version 5 on Irix systems

=head1 DESCRIPTION

This document describes various features of Irix that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 Building 32-bit Perl in Irix

Use

	sh Configure -Dcc='cc -n32'

to compile Perl 32-bit.  Don't bother with -n32 unless you have 7.1
or later compilers (use cc -version to check).

(Building 'cc -n32' is the default.)

=head2 Building 64-bit Perl in Irix

Use

	sh Configure -Dcc='cc -64' -Duse64bitint

This requires require a 64-bit MIPS CPU (R8000, R10000, ...)

You can also use

	sh Configure -Dcc='cc -64' -Duse64bitall

but that makes no difference compared with the -Duse64bitint because
of the C<cc -64>.

You can also do

	sh Configure -Dcc='cc -n32' -Duse64bitint

to use long longs for the 64-bit integer type, in case you don't
have a 64-bit CPU.

If you are using gcc, just

	sh Configure -Dcc=gcc -Duse64bitint

should be enough, the Configure should automatically probe for the
correct 64-bit settings.

=head2 About Compiler Versions of Irix

Some Irix cc versions, e.g. 7.3.1.1m (try cc -version) have been known
to have issues (coredumps) when compiling perl.c.  If you've used
-OPT:fast_io=ON and this happens, try removing it.  If that fails, or
you didn't use that, then try adjusting other optimization options
(-LNO, -INLINE, -O3 to -O2, etcetera).  The compiler bug has been
reported to SGI.  (Allen Smith <easmith@beatrice.rutgers.edu>)

=head2 Linker Problems in Irix

If you get complaints about so_locations then search in the file
hints/irix_6.sh for "lddflags" and do the suggested adjustments.
(David Billinghurst <David.Billinghurst@riotinto.com.au>)

=head2 Malloc in Irix

Do not try to use Perl's malloc, this will lead into very mysterious
errors (especially with -Duse64bitall).

=head2 Building with threads in Irix

Run Configure with -Duseithreads which will configure Perl with
the new Perl 5.8.0 "interpreter threads", see L<threads>.

The old Perl 5.005 threads is obsolete, unmaintained, and its use is
discouraged.  If you really want it, run Configure with the
-Dusethreads -Duse5005threads options as described in INSTALL.

For either thread model and for Irix 6.2, you have to have the
following patches installed:

        1404 Irix 6.2 Posix 1003.1b man pages
        1645 Irix 6.2 & 6.3 POSIX header file updates
        2000 Irix 6.2 Posix 1003.1b support modules
        2254 Pthread library fixes
        2401 6.2 all platform kernel rollup

B<IMPORTANT>: Without patch 2401, a kernel bug in Irix 6.2 will cause
your machine to panic and crash when running threaded perl.  Irix 6.3
and later are okay.

    Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
    pthreads patches information.

=head2 Irix 5.3

While running Configure and when building, you are likely to get
quite a few of these warnings:

  ld:
  The shared object /usr/lib/libm.so did not resolve any symbols.
        You may want to remove it from your link line.

Ignore them: in IRIX 5.3 there is no way to quieten ld about this.

During compilation you will see this warning from toke.c:

  uopt: Warning: Perl_yylex: this procedure not optimized because it
        exceeds size threshold; to optimize this procedure, use -Olimit option
        with value >= 4252.

Ignore the warning.

In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3)
the following failures are known.

 Failed Test                  Stat Wstat Total Fail  Failed  List of Failed
 --------------------------------------------------------------------------
 ../ext/List/Util/t/shuffle.t    0   139    ??   ??       %  ??
 ../lib/Math/Trig.t            255 65280    29   12  41.38%  24-29
 ../lib/sort.t                   0   138   119   72  60.50%  48-119
 56 tests and 474 subtests skipped.
 Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed, 99.90% okay.

They are suspected to be compiler errors (at least the shuffle.t
failure is known from some IRIX 6 setups) and math library errors
(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
further fixes for the IRIX are unlikely.  If you can get gcc for 5.3,
you could try that, too, since gcc in IRIX 6 is a known workaround for
at least the shuffle.t and sort.t failures.

=head1 AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>

Please report any errors, updates, or suggestions to F<perlbug@perl.org>.

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

The following documentation is written in euc-jp encoding.

=head1 NAME

perljp - ���ܸ� Perl ������

=head1 ����

Perl �������ؤ褦����!

Perl 5.8.0 ��ꡢUnicode���ݡ��Ȥ������˶������졢���η�̥�ƥ�ʸ���ʳ���ʸ�������ɤΥ��ݡ��Ȥ� CJK (���졢���ܸ졢�ϥ���)��ޤ�Ʋä��ޤ�����Unicode���������ʸ�����Ĥ�ʸ�������ɤǰ������Ȥ��ܻؤ���ɸ�൬�ʤǤ��ꡢ�줫�������Ϥ��ޤ����δ֤�ʸ���ʥ��ꥷ��ʸ�������꡼��ʸ��������ӥ�ʸ�����إ֥饤ʸ�����ǥ��������ʥ�����ʸ�����ʤɤʤɡˤ䡢����ޤǤ�OS�٥�������ȼ������Ƥ���ʸ��(PC�����Macintosh)�����Ǥ˴ޤޤ�Ƥ��ޤ���

Perl ���Ȥ� Unicode ��ư��ޤ���Perl ������ץ����ʸ�����ƥ�������ɽ���� Unicode ������Ȥ��Ƥ��ޤ��������������ϤΤ���ˤϡ�����ޤǻȤ��Ƥ������ޤ��ޤ�ʸ�������ɤ��б�����⥸�塼�롢�� Encode �פ�ɸ����������Ƥ��ꡢUnicode �Ȥ�����ʸ�������ɤ�����Ѵ����ñ�˹Ԥ���褦�ˤʤäƤ��ޤ���

�������� Encode �����ݡ��Ȥ���ʸ�������ɤϰʲ��ΤȤ���Ǥ���

  7bit-jis      AdobeStandardEncoding AdobeSymbol       AdobeZdingbat
  ascii             big5              big5-hkscs        cp1006
  cp1026            cp1047            cp1250            cp1251
  cp1252            cp1253            cp1254            cp1255
  cp1256            cp1257            cp1258            cp37
  cp424             cp437             cp500             cp737
  cp775             cp850             cp852             cp855
  cp856             cp857             cp860             cp861
  cp862             cp863             cp864             cp865
  cp866             cp869             cp874             cp875
  cp932             cp936             cp949             cp950
  dingbats          euc-cn            euc-jp            euc-kr
  gb12345-raw       gb2312-raw        gsm0338           hp-roman8
  hz                iso-2022-jp       iso-2022-jp-1     iso-8859-1
  iso-8859-10       iso-8859-11       iso-8859-13       iso-8859-14
  iso-8859-15       iso-8859-16       iso-8859-2        iso-8859-3
  iso-8859-4        iso-8859-5        iso-8859-6        iso-8859-7
  iso-8859-8        iso-8859-9        iso-ir-165        jis0201-raw
  jis0208-raw       jis0212-raw       johab             koi8-f
  koi8-r            koi8-u            ksc5601-raw       MacArabic
  MacCentralEurRoman  MacChineseSimp    MacChineseTrad    MacCroatian
  MacCyrillic       MacDingbats       MacFarsi          MacGreek
  MacHebrew         MacIcelandic      MacJapanese       MacKorean
  MacRoman          MacRomanian       MacRumanian       MacSami
  MacSymbol         MacThai           MacTurkish        MacUkrainian
  nextstep          posix-bc          shiftjis          symbol
  UCS-2BE           UCS-2LE           UTF-16            UTF-16BE
  UTF-16LE          UTF-32            UTF-32BE          UTF-32LE
  utf8              viscii

(��114����)

�㤨�С�ʸ��������FOO�Υե������UTF-8���Ѵ�����ˤϡ��ʲ��Τ褦�ˤ��ޤ���

    perl -Mencoding=FOO,STDOUT,utf8 -pe1 < file.FOO > file.utf8

�ޤ���Perl�ˤϡ�������Perl�ǽ��줿ʸ���������Ѵ��桼�ƥ���ƥ���piconv����°���Ƥ���Τǡ��ʲ��Τ褦�ˤ��뤳�Ȥ�Ǥ��ޤ���

   piconv -f FOO -t utf8 < file.FOO > file.utf8
   piconv -f utf8 -t FOO < file.utf8 > file.FOO

=head2 About (jcode.pl|Jcode.pm|JPerl)

5.8�����Ρ�������ץȤ�EUC-JP�Ǥ���Х�ƥ������ϰ������Ȥ��Ǥ��ޤ������ޤ��������Ϥ����⥸�塼��Ȥ��Ƥ�Jcode.pm��( http://openlab.jp/Jcode/ )��perl4�ѤΥ桼�ƥ���ƥ��Ȥ��Ƥ�jcode.pl( http://srekcah.org/jcode/ )�����줾��¸�ߤ������ܸ�ΰ�����CGI�Ǥ褯���Ѥ���Ƥ��뤳�Ȥ��¸�������⾯�ʤ��ʤ����Ȼפ��ޤ��������������ܸ�ˤ������ɽ�����ޤ��������Ȥ��Բ�ǽ�Ǥ�����

5.005������Perl�ˤϡ����ܸ���ò����������饤���ǡ�Jperl��¸�ߤ��ޤ���( http://homepage2.nifty.com/kipp/perl/jperl/index.html )���ޤ���Mac OS 9.x/Classic�Ѥ�Perl��MacPerl�����ܸ��Ǥ�MacJPerl�Ȥ���¸�ߤ��Ƥޤ�����( http://world.std.com/~habilis/macjperl/ ).�����Ǥ�ʸ�������ɤȤ���EUC-JP�˲ä�Shift_JIS�⤽�Τޤް������Ȥ��Ǥ����ޤ����ܸ�ˤ������ɽ���������Ȥ��ǽ�Ǥ�����

Perl5.8�Ǥϡ������ε�ǽ�����٤�Perl���Τ����Ǽ¸��Ǥ����ˡ����ܸ�Τߤʤ餺�嵭114��ʸ�������ɤ��٤ơ�������Ʊ���˰������Ȥ��Ǥ��ޤ�������ˡ�CPAN�ʤɤ��鿷����ʸ���������ѤΥ⥸�塼������ꤹ�뤳�Ȥ��ñ�ˤǤ���褦�ˤʤäƤ��ޤ���

=over 4

=item *

������

�ʲ�����Ϥ��Ť��Shift_JIS�����Ϥ�EUC-JP���Ѵ����ƽ��Ϥ��ޤ���

  # jcode.pl
  require "jcode.pl";
  while(<>){
    jcode::convert(*_, 'euc', 'sjis');
    print;
  }
  # Jcode.pm
  use Jcode;
  while(<>){
  	print Jcode->new($_, 'sjis')->euc;
  }
  # Perl 5.8
  use Encode;
  while(<>){
    from_to($_, 'shiftjis', 'euc-jp');
    print;
  }
  # Perl 5.8 - encoding �����Ѥ���
  use encoding 'euc-jp', STDIN => 'shiftjis';
  while(<>){
  	print;
  }

=item *

Jperl �ߴ�������ץ�

 ������"shebang"���ѹ���������ǡ�Jperl�Ѥ�script�ΤۤȤ�ɤ��ѹ��ʤ������Ѳ�ǽ���Ȼפ��ޤ���

   #!/path/to/jperl
   ��
   #!/path/to/perl -Mencoding=euc-jp

 �ܤ����� perldoc encoding ���Ȥ��Ƥ���������

=back

=head2 ����˾ܤ���

Perl�ˤ�����ʻ�������°���Ƥ��ꡢPerl�ο���ǽ��Unicode���ݡ��ȡ�������Encode�⥸�塼��λ���ˡ�ʤɤ��٤������夵��Ƥ��ޤ��ʻ�ǰ�ʤ��顢�ۤȤ�ɱѸ�ǤϤ���ޤ����ˡ��ʲ��Υ��ޥ�ɤǤ����ΰ�����������뤳�Ȥ���ǽ�Ǥ���

  perldoc perlunicode # Perl��Unicode���ݡ�������
  perldoc Encode      # Encode�⥸�塼��˴ؤ���
  perldoc Encode::JP  # �������ܸ�ʸ�������ɤ˴ؤ���

=head2 Perl���̤˴ؤ��� URL

=over 4

=item L<http://www.perl.com/>

Perl �ۡ���ڡ��� (O'Reilly and Associates)

=item L<http://www.cpan.org/>

CPAN (Comprehensive Perl Archive Network)

=item L<http://lists.perl.org/>

Perl �᡼����ꥹ�Ƚ�

=back

=head2 Perl��������� URL

=over 4

=item L<http://www.oreilly.com.tw/chinese/>

O'Reilly �Ҥ�Perl��Ϣ����(���λ�����)

=item L<http://www.oreilly.com.cn/chinese/>

O'Reilly �Ҥ�Perl��Ϣ����(���λ�����)

=item L<http://www.oreilly.co.jp/catalog.htm>

���饤�꡼�Ҥ�Perl��Ϣ����(���ܸ�)

=back

=head2 Perl �桼�������롼��

=over 4

=item L<http://www.pm.org/groups/asia.shtml#China>

������ڿ�̱���¹��

=item L<http://www.pm.org/groups/asia.shtml#Japan>

����

=item L<http://www.pm.org/groups/asia.shtml#Korea%20(Republic%20of)>

�ڹ�����̱���

=item L<http://www.pm.org/groups/asia.shtml#Taiwan>

���ѡ����̱���

=back

=head2 Unicode��Ϣ��URL

=over 4

=item L<http://www.unicode.org/>

Unicode ������������ (Unicode���ʤ���������)

=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>

UTF-8 and Unicode FAQ for Unix/Linux

=item L<http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>

UTF-8 and Unicode FAQ for Unix/Linux (�ϥ�����)

=back

=head1 AUTHORS

Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
Dan Kogai (��������) E<lt>dankogai@dan.co.jpE<gt>

=cut

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

This file is in Korean encoded in EUC-KR.

�� ������ perldoc�� �Ἥ ���� �ʰ� ���� ���� ��쿡�� �� �κ���
������ ǥ���ϱ� ���� ���� =head, =item, 'L' ���� �����Ͻʽÿ�.
�� ������ ���� perldoc�� ���� �ʰ� ������ �дµ� �� ������
���� POD �������� ¥�� �ֽ��ϴ�.  �� �ڼ��� ���� perlpod
�Ŵ����� �����Ͻʽÿ�.


=head1 NAME

perlko - Perl�� �ѱ��� ���ڵ�

=head1 DESCRIPTION

Perl�� ���迡 ���� ���� ȯ���մϴ� !


Perl�� 5.8.0�Ǻ��� �����ڵ�/ISO 10646�� ���� �������� ������ �մϴ�.
�����ڵ� ������ ��ȯ���� �������� ����� ���� ��������
�����ڵ� ������ ���� �־��� ���ݵ� �θ� ���̰� �ִ� ������ ���ڵ���
�����մϴ�.  �����ڵ�� �� ���迡�� ���̴� ��� �� ���� ǥ�� ü�� -
������ ��ƾ ���ĺ�, Ű�� ���ĺ�, �׸��� ���ĺ�, �ε��� ���� �ƽþ���
���� �迭 ��ũ��Ʈ, �ƶ� ����, ���긮 ����, �������� ����, �ѱ����� �ѱ�,
�Ϻ����� ����, �Ϲ� �ε���� ǥ�� ü�� ��-�� �����ϴ� ���� ��ǥ�� �ϰ�
�ֱ� ������ ������ ���̴�  �� ��� �� ���� �׸��� � ü�迡 ������
���� ���հ� ���ڵ��� �� �� �ִ� ��� ���ڴ� �����̰�  ���� ���� ���տ���
�����ϰ� ���� �ʴ� ���� ���� ���ڸ�  �����ϰ� �ֽ��ϴ�.


Perl�� ���������� �����ڵ带 ���� ǥ���� ���� ����մϴ�. ���� ��ü������
���ϸ� Perl ��ũ��Ʈ �ȿ���  UTF-8 ���ڿ��� �� �� �ְ�,
���� �Լ��� ������(���� ���, ���Խ�, index, substr)�� ����Ʈ ����
��� �����ڵ� ���� ������ �����մϴ�. (�� �ڼ��� ����
perlunicode �Ŵ����� �����Ͻʽÿ�.) �����ڵ尡 �θ� ���޵DZ� ����
�θ� ���̰� �־���, ������ �θ� ���̰� �ִ� ����/�� �� ���ڵ�����
������� �ϰ� �̵� ���ڵ����� �� �����Ϳ� ������ �ٷ�� ���� ���� ����
'Encode'��  �������ϴ�. �������� 'Encode'��  �Ἥ ������ ���ڵ� ������
��ȯ�� ���� �� �� �ֽ��ϴ�.

'Encode'�� ������ ���� �ѱ��� ���ڵ��� �����մϴ�.

=over 4

=item euc-kr

  US-ASCII�� KS X 1001�� ���� ���� ��Ƽ����Ʈ ���ڵ� (���� �ϼ����̶��
  �Ҹ�.) KS X 2901�� RFC 1557 ����.

=item  cp949

	MS-Windows 9x/ME���� ���̴� Ȯ�� �ϼ���.  euc-kr�� 8,822����
	�ѱ� ������ ���� ����.  alias�� uhc, windows-949, x-windows-949,
	ks_c_5601-1987. �� ������ �̸��� �������� ���� �̸�������, Microsoft
	��ǰ���� CP949�� �ǹ̷� ���̰� ����.

=item  johab

	KS X 1001:1998 �η� 3���� ������ ������.  ���� �����丮�� cp949��
	���������� US-ASCII��  KS X 1001�� 8,822���� �ѱ� ������ ���� ����.
	���ڵ� ����� ���� �ٸ�.

=item iso-2022-kr

	RFC 1557���� ������ �ѱ��� ���ͳ� ���� ��ȯ�� ���ڵ����� US-ASCII��
	KS X 1001�� �����丮�� �ϴ� ������ euc-kr�� ������ ���ڵ� ����� �ٸ�.
	1997-8�� ����� �������� �� �̻� ���� ��ȯ�� ������ ����.

=item  ksc5601-raw

	KS X 1001(KS C 5601)�� GL(��, MSB�� 0���� �� ���) �� ������ ����
	���ڵ�. US-ASCII�� �������� �ʰ� �ܵ����� ���̴� ���� X11 ��� �۲�
	���ڵ� (ksc5601.1987-0. '0'�� GL�� �ǹ���.)���� ���̴� ���� �����ϰ��
	���� ����. KS C 5601�� 1997�� KS X 1001�� �̸��� �ٲپ���.  1998�⿡��  ��
	���� (����ȭ ��ȣ�� ��� ��ǥ ��ȣ)�� ��������.

=back

 �� ���� ��� ������ �Ʒ��� ���Դϴ�.

���� ���, euc-kr ���ڵ����� �� ������ UTF-8�� ��ȯ�Ϸ��� ������
���� �ϸ� �˴ϴ�.


    perl -Mencoding=euc-kr,STDOUT,utf8 -pe1  < file.euckr > file.utf8

����ȯ�� ������ ���� �� �� �ֽ��ϴ�.

    perl -Mencoding=utf8,STDOUT,euc-kr -pe1  < file.utf8  > file.euckr

  �̷� ��ȯ�� ���� ���ϰ� �� �� �ֵ��� Encode ����� �Ἥ
�����ϰ� Perl�θ� ���� piconv�� Perl�� ��� �ֽ��ϴ�.
�� �̸����� �� �� �ֵ��� piconv�� Unix�� �ִ� iconv��
���� �� ���Դϴ�. �� ������ �Ʒ��� �����ϴ�.

   piconv -f euc-kr -t utf8 < file.euckr > file.utf8
   piconv -f utf8 -t euc-kr < file.utf8 > file.euckr

  ��, 'PerlIO::encoding' ����� �Ἥ �ѱ��� ���ڵ��� ���鼭 ���� ����
(����Ʈ ������ �ƴ϶�) ó���� ���� �� �� �ֽ��ϴ�.

  #!/path/to/perl

  use encoding 'euc-kr', STDIN => 'euc-kr',
                         STDOUT-> 'euc-kr', STDERR=>'euc-kr';

  print length("����");        # 2  (ū ����ǥ�� ���� ���� ó���� ����)
  print length('����');        # 4  (���� ����ǥ�� ����Ʈ ���� ó���� ����)
  print index("�Ѱ�, �뵿��", "��");   # -1 ('��'�� ����)
  print index('�Ѱ�, �뵿��', '��');   # 7 (8��°�� 9��° ����Ʈ�� '��'��
                                            �ڵ尪�� ��ġ��.)


=head2 �� �ڼ��� �˰� ������...

  Perl�� ��ġ�ϸ�  ����� �ڼ��� ������ ���� ���� ����, �� ������ ����
Perl ���� �� �ƴ϶� �����ڵ� ����, Encode�� ���� � ���� ����
��� �� �ֽ��ϴ�.  ���� �� ������ ���� ��� ����� ���� �ֽ��ϴ�.


=head2 Perl ���� �ڷ�

������ �����  ���� �ܿ��� ������ ���� �ڷᰡ �ֽ��ϴ�. �� ����� ����
������ ���� �ƴϰ� �Ϻ� ��ǥ���� �͸� ���� ���Դϴ�.

=over 4

=item L<http://www.perl.com/>

   O'Reilly�� Perl �� ������

=item L<http://www.cpan.org/>

	Comprehensive Perl Archive Network

=item L<http://lists.perl.org/>

  Perl ���ϸ� ����Ʈ. ���� ����Ʈ ���
  perl-unicode���� 'Encode'�� ���� ������.

=back

=head2 Perl�� �� ��� �����ϴµ� ������ �� �� �ִ� �ѱ��� ���� ����Ʈ

=over 4

=item L<http://www.perl.or.kr/>

  Perl �ѱ� ����� ����

=item L<news:han.comp.lang.perl/>

  �ѱ��� Perl ���� �׷�

=item L<http://seoul.pm.org/>

  Perl ���Ž� (����)

=item L<http://www.perlmania.or.kr/>

  Home for Korean Perlmanias

=item L<http://www.oreilly.co.kr/perl/>

  O'Reilly���� ���� �ѱ��� Perl ���� ���

=item L<http://www.perlschool.net/>

  Perl ���� ���� �� �ҽ�, �ֱ� ����, ���� �ؿ� ����Ʈ ��ũ

=item L<http://www.perl.co.kr>

  Perl�� ���õ� CGI, DB, ���� � ����  ���� �� ���� ����

=back

=head2 �����ڵ� �� �ѱ��� ���ڵ� ���� �ڷ�

=over 4

=item L<http://www.unicode.org/>

  �����ڵ� ���ҽþ�.

=item L<http://std.dkuug.dk/JTC1/SC2/WG2>

�⺻������ Unicode�� ���� ISO ǥ����  ISO/IEC 10646 UCS(Universal
Character Set)�� �����  ISO/IEC JTC1/SC2/WG2�� �� ������.

=item L<http://jshin.net/faq/qa8.html>

  �ѱ��� ���� ���� �� ���ڵ��� ���� �ȳ�.

=item L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>

  ���н�/���������� �����ڵ�� UTF-8 ��뿡 ���� ������(FAQ)

=item L<http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>

  ���н�/���������� �����ڵ�� UTF-8 ��뿡 ���� ������(FAQ)��  �ѱ��� ����

=back

=head1 SEE ALSO

L<Encode>, L<Encode::KR>, L<encoding>, L<perluniintro>, L<perlunicode>


=head1 AUTHORS

Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
������ E<lt>jshin@mailaps.orgE<gt>

=cut

If you read this file _as_is_, just ignore the funny characters you
see.  It is written in the POD format (see pod/perlpod.pod) which is
specifically designed to be readable as is.

=head1 NAME

README.linux - Perl version 5 on Linux systems

=head1 DESCRIPTION

This document describes various features of Linux that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 Experimental Support for Sun Studio Compilers for Linux OS

Sun Microsystems has released a port of their Sun Studio compiliers for
Linux.  As of November 2005, only an alpha version has been released.
Until a release of these compilers is made, support for compiling Perl with
these compiler experimental.

Also, some special instructions for building Perl with Sun Studio on Linux.
Following the normal C<Configure>, you have to run make as follows:

    LDLOADLIBS=-lc make

C<LDLOADLIBS> is an environment variable used by the linker to link modules
C</ext> modules to glibc.  Currently, that environment variable is not getting
populated by a combination of C<Config> entries and C<ExtUtil::MakeMaker>.
While there may be a bug somewhere in Perl's configuration or
C<ExtUtil::MakeMaker> causing the problem, the most likely cause is an
incomplete understanding of Sun Studio by this author.  Further investigation
is needed to get this working better.

=head1 AUTHOR

Steve Peters <steve@fisharerojo.org>

Please report any errors, updates, or suggestions to F<perlbug@perl.org>.

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see pod/perlpod.pod) which is
specially designed to be readable as is.

=head1 NAME

README.machten - Perl version 5 on Power MachTen systems

=head1 DESCRIPTION

This document describes how to build Perl 5 on Power MachTen systems,
and discusses a few wrinkles in the implementation.

=head2 Perl version 5.8.x and greater not supported

B<Power MachTen is not supported by versions of Perl later than
5.6.x.>
If you wish to build a version from the 5.6 track, please
obtain a source distribution from the archive at
L<http://cpan.org/src/5.0/> and follow the instructions in its
README.machten file.

MachTen is no longer supported by its developers, Tenon Intersystems.
A UNIX environment hosted on Mac OS Classic, MachTen has been
superseded by Mac OS X and by BSD and Linux implementations for Macintosh
hardware.
The final version of Power MachTen, 4.1.4, lacks many features found in
modern implementations of UNIX, and has a number of bugs.
These shortcomings prevent recent versions of Perl from being able to use
extensions on MachTen, and cause numerous test suite failures in the
perl core.

In September 2003, a discussion on the MachTen mailing list determined
that there was no interest in making a later version of Perl build
successfully on MachTen.
Consequently, support for building Perl under MachTen has been suppressed
in Perl distributions published after February 2004.
The hints file, F<hints/machten.sh>, remains a part of the
distributions for reference purposes.

=head2 Compiling Perl 5.6.x on MachTen

To compile perl 5.6.x under MachTen 4.1.4 (and probably earlier versions):

  ./Configure -de
  make
  make test
  make install

This builds and installs a statically-linked perl; MachTen's dynamic
linking facilities are not adequate to support Perl's use of
dynamically linked libraries.  (See F<hints/machten.sh> for more
information.)

You should have at least 32 megabytes of free memory on your
system before running the C<make> command.

For much more information on building perl -- for example, on how to
change the default installation directory -- see F<INSTALL>.

=head2 Failures during C<make test> on MachTen

=over 4

=item op/lexassign.t

This test may fail when first run after building perl.  It does not
fail subsequently.  The cause is unknown.

=item pragma/warnings.t

Test 257 fails due to a failure to warn about attempts to read from a
filehandle which is a duplicate of stdout when stdout is attached to a
pipe.  The output of the test contains a block comment which discusses
a different failure, not applicable to MachTen.

The root of the problem is that Machten does not assign a file type to
either end of a pipe (see L<stat>), resulting, among other things
in Perl's C<-p> test failing on file descriptors belonging to pipes.
As a result, perl becomes confused, and the test for reading from a
write-only file fails.  I am reluctant to patch perl to get around
this, as it's clearly an OS bug (about which Tenon has been informed),
and limited in its effect on practical Perl programs.

=back

=head2 Building external modules on MachTen

To add an external module to perl, build in the normal way, which
is documented in L<ExtUtils::MakeMaker>, or which can be driven
automatically by the CPAN module (see L<CPAN>), which is part of the
standard distribution.  If you want to install a module which
contains XS code (C or C++ source which compiles to object code
for linking with perl), you will have to replace your perl binary with
a new version containing the new statically-linked object module.  The
build process tells you how to do this.

There is a gotcha, however, which users usually encounter immediately
they respond to CPAN's invitation to C<install Bundle::CPAN>. When
installing a I<bundle> -- a group of modules which together achieve
some particular purpose, the installation process for later modules in
the bundle tends to assume that earlier modules have been fully
installed and are available for use.  This is not true on a
statically-linked system for earlier modules which contain XS code.
As a result the installation of the bundle fails.  The work-around is
not to install the bundle as a one-shot operation, but instead to see
what modules it contains, and install these one-at-a-time by hand in
the order given.

=head1 AUTHOR

Dominic Dunlop <domo@computer.org>

=head1 DATE

Version 1.1.0 2004-02-13

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.macos - Perl under Mac OS (Classic)

=head1 SYNOPSIS

This document briefly describes perl under Mac OS (Classic).
If you are running perl under Mac OS X, you don't want to be
here (unless you are in the Classic environment under Mac OS X).

When we say "Mac OS" below, we mean Mac OS 7, 8, and 9, and I<not>
Mac OS X.


=head1 DESCRIPTION

The latest perl source itself builds on Mac OS, with some additional
pieces. Support for Mac OS is now in the perl core, and MacPerl is kept
in close sync with regular perl releases.

To build perl for Mac OS (as an MPW tool), you will need the addition
of the F<macos> subdirectory, distributed separately.  It includes extra
source files, config files, and make files.  It also includes extra
Mac-specific modules.

To build the MacPerl application, you will also need the F<macperl>
directory, which includes the source files for creating the
application itself.

All of this is available from the development site, via
HTTP (in the MacPerl Installer, which includes all the source
and binaries) and anonymous CVS.

	http://dev.macperl.org/

The source is also in the main perl repository in the macperl
branch (the 5.6 source is in the maint-5.6/macperl branch).

You will also need compilers and libraries, all of them freely
available.  These are linked to from the SourceForge site. Go that site
for all things having to do with MacPerl development.

MacPerl 5.6.1 and later are supported on Mac OS 8.1 and later, for 68040
and PowerPC architectures.  The MPW tool may be used on Mac OS 7.5.5
and 68030 computers.

MacPerl 5.2.0r4 is also available, on the CPAN and on SourceForge.  It
is based on perl 5.004, and works with Mac OS 7.5.5 and 68030 computers.


=head1 AUTHOR

perl was ported to Mac OS by Matthias Neeracher
E<lt>neeracher@mac.comE<gt>.  It is currently maintained by Chris
Nandor E<lt>pudge@pobox.comE<gt>.


=head1 DATE

Last modified 2002.05.02.

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.macosx - Perl under Mac OS X

=head1 SYNOPSIS

This document briefly describes perl under Mac OS X.


=head1 DESCRIPTION

The latest Perl release (5.8.8 as of this writing) builds without changes
under Mac OS X. Under 10.3 "Panther" and newer OS versions, all self-tests
pass, and all standard features are supported.

Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a
completely thread-safe libc, so threading is not fully supported. Also,
earlier releases included a buggy libdb, so some of the DB_File tests
are known to fail on those releases.


=head2 Installation Prefix

The default installation location for this release uses the traditional
UNIX directory layout under /usr/local. This is the recommended location
for most users, and will leave the Apple-supplied Perl and its modules
undisturbed.

Using an installation prefix of '/usr' will result in a directory layout
that mirrors that of Apple's default Perl, with core modules stored in
'/System/Library/Perl/${version}', CPAN modules stored in
'/Library/Perl/${version}', and the addition of
'/Network/Library/Perl/${version}' to @INC for modules that are stored
on a file server and used by many Macs.


=head2 SDK support

First, export the path to the SDK into the build environment:

    export SDK=/Developer/SDKs/MacOSX10.3.9.sdk

Use an SDK by exporting some additions to Perl's 'ccflags' and '..flags'
config variables:

    ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc \
                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
                           -F$SDK/System/Library/Frameworks" \
                -Aldflags="-Wl,-syslibroot,$SDK" \
                -de

=head2 Universal Binary support

To compile perl as a universal binary (built for both ppc and intel), export
the SDK variable as above, selecting the 10.4u SDK:

    export SDK=/Developer/SDKs/MacOSX10.4u.sdk

In addition to the compiler flags used to select the SDK, also add the flags
for creating a universal binary:

    ./Configure -Accflags="-arch i686 -arch ppc -nostdinc -B$SDK/usr/include/gcc \
                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
                           -F$SDK/System/Library/Frameworks" \
                -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK" \
                -de

Keep in mind that these compiler and linker settings will also be used when
building CPAN modules. For XS modules to be compiled as a universal binary, any
libraries it links to must also be universal binaries. The system libraries that
Apple includes with the 10.4u SDK are all universal, but user-installed libraries
may need to be re-installed as universal binaries.

=head2 libperl and Prebinding

Mac OS X ships with a dynamically-loaded libperl, but the default for
this release is to compile a static libperl. The reason for this is
pre-binding. Dynamic libraries can be pre-bound to a specific address in
memory in order to decrease load time. To do this, one needs to be aware
of the location and size of all previously-loaded libraries. Apple
collects this information as part of their overall OS build process, and
thus has easy access to it when building Perl, but ordinary users would
need to go to a great deal of effort to obtain the information needed
for pre-binding.

You can override the default and build a shared libperl if you wish
(S<Configure ... -Duseshrlib>), but the load time on pre-10.4 OS
releases will be greater than either the static library, or Apple's
pre-bound dynamic library.

With 10.4 "Tiger" and newer, Apple has all but eliminated the performance
penalty for non-prebound libraries.


=head2 Updating Apple's Perl

In a word - don't, at least without a *very* good reason. Your scripts
can just as easily begin with "#!/usr/local/bin/perl" as with
"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
part of installation packages and such have generally only been tested
with the /usr/bin/perl that's installed by Apple.

If you find that you do need to update the system Perl, one issue worth
keeping in mind is the question of static vs. dynamic libraries. If you
upgrade using the default static libperl, you will find that the dynamic
libperl supplied by Apple will not be deleted. If both libraries are
present when an application that links against libperl is built, ld will
link against the dynamic library by default. So, if you need to replace
Apple's dynamic libperl with a static libperl, you need to be sure to
delete the older dynamic library after you've installed the update.


=head2 Known problems

If you have installed extra libraries such as GDBM through Fink
(in other words, you have libraries under F</sw/lib>), or libdlcompat
to F</usr/local/lib>, you may need to be extra careful when running
Configure to not to confuse Configure and Perl about which libraries
to use.  Being confused will show up for example as "dyld" errors about
symbol problems, for example during "make test". The safest bet is to run
Configure as

    Configure ... -Uloclibpth -Dlibpth=/usr/lib

to make Configure look only into the system libraries.  If you have some
extra library directories that you really want to use (such as newer
Berkeley DB libraries in pre-Panther systems), add those to the libpth:

    Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'

The default of building Perl statically may cause problems with complex
applications like Tk: in that case consider building shared Perl

    Configure ... -Duseshrplib

but remember that there's a startup cost to pay in that case (see above
"libperl and Prebinding").

Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
failures in the C<lib/locale> test. These failures have been supressed
in the current release of Perl by making the test ignore the broken locale.
If you need to use the eu_ES locale, you should contact Apple support.

=head2 MacPerl

Quite a bit has been written about MacPerl, the Perl distribution for
"Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it
runs in environment that's very different from that of UNIX, many things
are done differently in MacPerl. Modules are installed using a different
procedure, Perl itself is built differently, path names are different,
etc.

From the perspective of a Perl programmer, Mac OS X is more like a
traditional UNIX than Classic MacOS. If you find documentation that
refers to a special procedure that's needed for MacOS that's drastically
different from the instructions provided for UNIX, the MacOS
instructions are quite often intended for MacPerl on Classic MacOS. In
that case, the correct procedure on Mac OS X is usually to follow the
UNIX instructions, rather than the MacPerl instructions.


=head2 Carbon

MacPerl ships with a number of modules that are used to access the
classic MacOS toolbox. Many of these modules have been updated to use
Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the
"Mac::Carbon" module.


=head2 Cocoa

There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
module, included with Mac OS X, can be used by standalone scripts to
access Foundation (i.e. non-GUI) classes and objects.

An alternative is CamelBones, a framework that allows access to both
Foundation and AppKit classes and objects, so that full GUI applications
can be built in Perl. CamelBones can be found on SourceForge, at
L<http://www.sourceforge.net/projects/camelbones/>.


=head1 Starting From Scratch

Unfortunately it is not that difficult somehow manage to break one's
Mac OS X Perl rather severely.  If all else fails and you want to
really, B<REALLY>, start from scratch and remove even your Apple Perl
installation (which has become corrupted somehow), the following
instructions should do it.  B<Please think twice before following
these instructions: they are much like conducting brain surgery to
yourself.  Without anesthesia.>  We will B<not> come to fix your system
if you do this.

First, get rid of the libperl.dylib:

    # cd /System/Library/Perl/darwin/CORE
    # rm libperl.dylib

Then delete every .bundle file found anywhere in the folders:

    /System/Library/Perl
    /Library/Perl

You can find them for example by

    # find /System/Library/Perl /Library/Perl -name '*.bundle' -print

After this you can either copy Perl from your operating system media
(you will need at least the /System/Library/Perl and /usr/bin/perl),
or rebuild Perl from the source code with C<Configure -Dprefix=/usr
-Dusershrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
settings were not quite right.

"Pacifist" from CharlesSoft (L<http://www.charlessoft.com/>) is a nice
way to extract the Perl binaries from the OS media, without having to
reinstall the entire OS.


=head1 AUTHOR

This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>.
The "Starting From Scratch" recipe was contributed by John Montbriand
E<lt>montbriand@apple.comE<gt>.

=head1 DATE

Last modified 2005-11-07.

microperl is supposed to be a really minimal perl, even more
minimal than miniperl.  No Configure is needed to build microperl,
on the other hand this means that interfaces between Perl and your
operating system are left very -- minimal.

All this is experimental.  If you don't know what to do with microperl
you probably shouldn't.  Do not report bugs in microperl; fix the bugs.

We assume ANSI C89 plus the following:
- <stdlib.h>
- rename()
- opendir(), readdir(), closedir() (via dirent.h)
- memchr (via string.h)
- (a safe) putenv() (via stdlib.h)
- strtoul() (via stdlib.h)
(grep for 'define' in uconfig.sh.)
Also, Perl times() is defined to always return zeroes.

If you are still reading this and you are itching to try out microperl:

	make -f Makefile.micro

If you make changes to uconfig.sh, run

	make -f Makefile.micro regen_uconfig

to regenerate uconfig.h.

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

README.mint - Perl version 5 on Atari MiNT

=head1 DESCRIPTION

There is a binary version of perl available from the FreeMiNT project
http://freemint.de/  You may wish to use this instead of trying to
compile yourself.

B<The following advice is from perl 5.004_02 and is probably rather
out of date.>

If you want to build perl yourself on MiNT (or maybe on an Atari without
MiNT) you may want to accept some advice from somebody who already did it...

There was a perl port for Atari ST done by ++jrb bammi@cadence.com.
This port tried very hard to build on non-MiNT-systems.  For the
sake of efficiency I've left this way.  Yet, I haven't removed bammi's
patches but left them intact.  Unfortunately some of the files that
bammi contributed to the perl distribution seem to have vanished?

So, how can you distinguish my patches from bammi's patches?  All of
bammi's stuff is embedded in "#ifdef atarist" preprocessor macros.
My MiNT port uses "#ifdef __MINT__" instead (and unconditionally
undefines "atarist".  If you want to continue on bammi's port, all
you have to do is to swap the "-D" and "-U" switches for "__MINT__"
and "atarist" in the variable ccflags.

However, I think that my version will still run on non-MiNT-systems
provided that the user has a Eunuchs-like environment (i.e. the
standard envariables like $PATH, $HOME, ... are set, there is a
POSIX compliant shell in /bin/sh, and...)

=head1 Known problems with Perl on MiNT

The problems you may encounter when building perl on your machine
are most probably due to deficiencies in MiNT resp. the Atari
platform in general.

First of all, if you have less than 8 MB of RAM you shouldn't
even try to build Perl yourself.  Better grab a binary pre-compiled
version somewhere.  Even if you have more memory you should take
some care.  Try to run in a fresh environment (without memory
fragmented too much) with as few daemons, accessories, xcontrol
modules etc. as possible.  If you run some AES you should
consider to start a console based environment instead.

A problem has been reported with sed.  Sed is used to create
some configuration files based on the answers you have given
to the Configure script.  Unfortunately the Perl Configure script
shows sed on MiNT its limits.  I have sed 2.05 with a stacksize
of 64k and I have encountered no problems.  If sed crashes
during your configuration process you should first try to
augment sed's stacksize:

	fixstk 64k /usr/bin/sed

(or similar).  If it still doesn't help you may have a look
which other versions of sed are installed on your system.
If you have a KGMD 1.0 installation you will find three
in /usr/bin.  Have a look there.

Perl has some "mammut" C files.  If gcc reports "internal
compiler error: program cc1 got fatal signal 10" this is very
likely due to a stack overflow in program cc1. Find cc1
and fix its stack.  I have made good experiences with

	fixstk 2 cc1

This doesn't establish a stack of 2 Bytes only as you might
think.  It really reserves one half of the available memory
for cc1's stack.  A setting of 1 would reserve the entire
memory for cc1, 3 would reserve three fourths.  You will have
to find out the value that suits to your system yourself.

To find out the location of the program "cc1" simply type
`gcc --print-prog-name cc1' at your shell prompt.

Now run make (maybe "make -k").  If you get a fatal signal 10
increase cc1's stacksize, if you run out of memory you should
either decrease the stacksize or follow some more hints:

Perl's building process is very handy on machines with a lot
of virtual memory but may result in a disaster if you are short
of memory.  If gcc fails to compile many source files you should
reduce the optimization.  Grep for "optimize" in the file
config.sh and change the flags.

If only several huge files cause problems (actually it is not a
matter of the file size resp. the amount of code but depends on
the size of the individual functions) it is useful to bypass
the make program and compile these files directly from the
command line.  For example if you got something like the
following from make:

	CCCMD = gcc -DPERL_CORE ....
	...
	...: virtual memory exhausted

you should hack into the shell:

	gcc -DPERL_CORE ... toke.c

Please note that you have to add the name of the source file
(here toke.c) at the end.

If none of this helps, you're helpless.  Wait for a binary
release.  If you have succeeded you may encounter another problem
at the linking process.  If gcc complains that it can't find
some libraries within the perl distribution you probably have
an old linker.  If it complains for example about "file not
found for xxx.olb" you should cd into the directory in
question and

	ln -s libxxx.a xxx.olb

This will fix the problem.

This version (5.00402) of perl has passed most of the tests on my system:

 Failed Test  Status Wstat Total Fail  Failed  List of failed
 ------------------------------------------------------------------------------
 io/pipe.t                    10    2  20.00%  7, 9
 io/tell.t                    13    1   7.69%  12
 lib/complex.t               762   13   1.71%  84-85, 248-251, 257, 272-273,
                                               371, 380, 419-420
 lib/io_pipe.t                10    1  10.00%  9
 lib/io_tell.t                13    1   7.69%  12
 op/magic.t                   30    2   6.67%  29-30
 Failed 6/152 test scripts, 96.05% okay. 20/4359 subtests failed, 99.54% okay.

Pipes always cause problems with MiNT, it's actually a surprise that
most of the tests did work.  I've got no idea why the "tell" test failed,
this shouldn't mean too big a problem however.

Most of the failures of lib/complex seem to be harmless, actually errors
far right to the decimal point...  Two failures seem to be serious:
The sign of the results is reversed.  I would say that this is due
to minor bugs in the portable math lib that I compiled perl with.

I haven't bothered very much to find the reason for the failures
with op/magic.t and op/stat.t.  Maybe you'll find it out.

##########################################################################

Another possible problem may arise from the implementation of the "pwd"
command.  It happened to add a carriage return and newline to its output
no matter what the setting of $UNIXMODE is.  This is quite annoying since many
library modules for perl take the output of pwd, chop off the
trailing newline character and then expect to see a valid path in
that.  But the carriage return (last but second character!) isn't
chopped off.  You can either try to patch all library modules (at
the price of performance for the extra transformation) or you can
use my version of pwd that doesn't suffer from this deficiency.

The fixed implementation is in the mint subdirectory.  Running
"Configure" will attempt to build and install it if necessary
(hints/mint.sh will do this work) but you can build and install it
explicitly by:

	cd mint
	make install

This is the fastest solution.

Just in case you want to go the hard way: perl won't even build with a
broken pwd!  You will have to fix the library modules
(ext/POSIX/POSIX.pm, lib/Cwd.pm, lib/pwd.pl) at last after building
miniperl.

A major nuisance of current MiNTLib versions is the implementation
of system() which is far from being POSIX compliant.  A real system()
should fork and then exec /bin/sh with its argument as a command
line to the shell.  The MiNTLib system() however doesn't expect
that every user has a POSIX shell in /bin/sh.  It tries to work
around the problem by forking and exec'ing the first token in its argument
string.  To get a little bit of compliance to POSIX system() it
tries to handle at least redirection ("<" or ">") on its own
behalf.

This isn't a good idea since many programs expect that they can
pass a command line to system() that exploits all features of a
POSIX shell.  If you use the MiNTLib version of system() with
perl the Perl function system() will suffer from the same deficiencies.

You will find a fixed version of system() in the mint subdirectory.
You can easily insert this version into your system libc:

	cd mint
	make system.o
	ar r /usr/lib/libc.a
	ranlib /usr/lib/libc.a

If you are suspicious you should either back up your libc before
or extract the original system.o from your libc with
"ar x /usr/lib/libc.a system.o".  You can then backup the system.o
module somewhere before you succeed.

Anything missing?  Yep, I've almost forgotten...
No file in this distribution without a fine saying.  Take this one:

	"From a thief you should learn: (1) to work at night;
	(2) if one cannot gain what one wants in one night to
	try again the next night; (3) to love one's coworkers
	just as thieves love each other; (4) to be willing to
	risk one's life even for a little thing; (5) not to
	attach too much value to things even though one has
	risked one's life for them - just as a thief will resell
	a stolen article for a fraction of its real value;
	(6) to withstand all kinds of beatings and tortures
	but to remain what you are; and (7) to believe your
	work is worthwhile and not be willing to change it."

			-- Rabbi Dov Baer, Maggid of Mezeritch

OK, this was my motto while working on Perl for MiNT, especially rule (1)...

Have fun with Perl!

=head1 AUTHOR

Guido Flohr

	mailto:guido@FreeMiNT.de