xref: /perl5/
NameDateSize

..16-Mar-201612 KiB

.dir-locals.el09-Dec-2015208

.gitignore20-Aug-20152.7 KiB

amigaos4/09-Dec-20154 KiB

Artistic29-Dec-20126.2 KiB

asan_ignore02-Jan-2015983

AUTHORS10-Dec-201546.2 KiB

autodoc.pl30-Nov-201514.8 KiB

av.c09-Nov-201524.1 KiB

av.h23-Mar-20152.9 KiB

caretx.c09-Dec-20154.2 KiB

cflags.SH09-Dec-201515.2 KiB

Changes29-Dec-20123.1 KiB

charclass_invlists.h09-Dec-2015951.7 KiB

config_h.SH15-Dec-2015160.9 KiB

configpm08-Sep-201431.7 KiB

Configure15-Dec-2015569.1 KiB

configure.com09-Nov-2015213.5 KiB

configure.gnu29-Dec-20122.5 KiB

cop.h17-Nov-201541.5 KiB

Copying29-Dec-201212.3 KiB

cpan/30-Nov-20154 KiB

Cross/30-Nov-20154 KiB

cv.h10-Sep-201511.8 KiB

cygwin/18-Feb-20144 KiB

deb.c29-Jun-20157.4 KiB

dist/30-Nov-20154 KiB

djgpp/19-Feb-20154 KiB

doio.c09-Nov-201567.6 KiB

doop.c12-Oct-201529.3 KiB

dosish.h23-Mar-20155.3 KiB

dquote.c30-Nov-20156.2 KiB

dquote_inline.h30-Nov-20154.7 KiB

dump.c10-Sep-201579.3 KiB

ebcdic_tables.h30-Nov-201543.6 KiB

embed.fnc10-Dec-2015118.3 KiB

embed.h10-Dec-201590 KiB

embedvar.h18-Aug-201517.8 KiB

ext/10-Sep-20154 KiB

EXTERN.h09-Nov-20151.7 KiB

fakesdio.h23-Mar-20153.1 KiB

feature.h07-Aug-20154.9 KiB

form.h29-Dec-20121.4 KiB

generate_uudmap.c16-Dec-20143.7 KiB

globals.c23-Mar-20151.2 KiB

globvar.sym10-Sep-20151.3 KiB

gv.c19-Oct-2015104.8 KiB

gv.h18-Aug-201510.3 KiB

h2pl/29-Dec-20124 KiB

haiku/29-Dec-20124 KiB

handy.h09-Nov-201598.9 KiB

hints/09-Dec-20154 KiB

hv.c09-Nov-2015105.3 KiB

hv.h10-Sep-201523.8 KiB

hv_func.h14-Oct-201521.5 KiB

inline.h10-Sep-201510.6 KiB

INSTALL30-Nov-2015104.5 KiB

install_lib.pl10-Sep-20154.8 KiB

installhtml09-Dec-201517 KiB

installman23-Mar-20155.5 KiB

installperl09-Nov-201527.2 KiB

INTERN.h09-Nov-20151.2 KiB

intrpvar.h30-Nov-201528.1 KiB

invlist_inline.h07-Aug-20152.7 KiB

iperlsys.h12-Oct-201547.7 KiB

keywords.c26-Jun-201488.8 KiB

keywords.h26-Jun-20146.4 KiB

l1_char_class_tab.h10-Sep-2015167 KiB

lib/15-Dec-20154 KiB

locale.c10-Sep-201569.5 KiB

make_ext.pl30-Nov-201525.1 KiB

make_patchnum.pl16-Dec-20146.7 KiB

makedef.pl28-Sep-201530.9 KiB

makedepend.SH23-Oct-20149 KiB

Makefile.micro07-Aug-20155.4 KiB

Makefile.SH30-Nov-201548.8 KiB

malloc.c11-Aug-201570 KiB

malloc_ctl.h29-Dec-20121.5 KiB

MANIFEST14-Dec-2015301 KiB

mathoms.c10-Sep-201536.1 KiB

META.json30-Nov-20153.5 KiB

META.yml30-Nov-20152.8 KiB

metaconfig.h24-Nov-2014969

metaconfig.SH19-Feb-20151.2 KiB

mg.c09-Dec-201590 KiB

mg.h23-Mar-20152.9 KiB

mg_names.inc07-Aug-20152.1 KiB

mg_raw.h03-Dec-20144.2 KiB

mg_vtable.h03-Dec-20149.1 KiB

miniperlmain.c02-Oct-20145.1 KiB

mkppport10-Sep-20154.4 KiB

mkppport.lst21-Sep-2015257

mro_core.c10-Sep-201542.5 KiB

myconfig.SH05-Nov-20142.5 KiB

mydtrace.h23-Mar-20152.7 KiB

NetWare/30-Nov-20154 KiB

nostdio.h23-Mar-20153.3 KiB

numeric.c09-Dec-201551.8 KiB

op.c09-Dec-2015423.5 KiB

op.h10-Sep-201534.6 KiB

op_reg_common.h24-Jun-20155.8 KiB

opcode.h16-Nov-201588.7 KiB

opnames.h07-Aug-20158.6 KiB

os2/12-Jun-20144 KiB

overload.h02-Feb-20153.2 KiB

overload.inc07-Aug-20153.6 KiB

packsizetables.inc07-Aug-20155.9 KiB

pad.c12-Oct-201581.6 KiB

pad.h10-Sep-201516.9 KiB

parser.h23-Mar-20156.1 KiB

patchlevel.h30-Nov-20155.2 KiB

perl.c20-Nov-2015133.1 KiB

perl.h15-Dec-2015229.3 KiB

perlapi.c29-Dec-20121.7 KiB

perlapi.h29-Dec-20125.5 KiB

perldtrace.d23-Mar-2015491

perlio.c30-Nov-2015120.5 KiB

perlio.h07-Aug-20159.2 KiB

perlio.sym12-Oct-2013446

perliol.h12-Jun-201513.4 KiB

perlsdio.h07-Aug-2015527

perlvars.h12-Oct-20159.2 KiB

perly.act12-Oct-201538.8 KiB

perly.c21-Sep-201515.3 KiB

perly.h12-Oct-20156.3 KiB

perly.tab12-Oct-201578.3 KiB

perly.y12-Oct-201529.9 KiB

plan9/30-Nov-20154 KiB

pod/15-Dec-20154 KiB

Policy_sh.SH29-Dec-20127.9 KiB

Porting/14-Dec-20154 KiB

pp.c15-Dec-2015165.5 KiB

pp.h30-Nov-201528.3 KiB

pp_ctl.c16-Nov-2015142 KiB

pp_hot.c16-Nov-2015112 KiB

pp_pack.c16-Nov-201584.1 KiB

pp_proto.h16-Nov-201511.5 KiB

pp_sort.c10-Sep-201564.8 KiB

pp_sys.c30-Nov-2015138 KiB

proto.h10-Dec-2015222 KiB

qnx/29-Dec-20124 KiB

README02-Feb-20155.5 KiB

README.aix10-Sep-201520 KiB

README.amiga21-Sep-20155.6 KiB

README.android10-Sep-20157.6 KiB

README.bs200012-May-20157.9 KiB

README.ce10-Sep-201514.3 KiB

README.cn14-Apr-20134.6 KiB

README.cygwin10-Sep-201526.2 KiB

README.dos29-Dec-201210.3 KiB

README.freebsd29-Dec-20121.6 KiB

README.haiku30-Nov-20151.5 KiB

README.hpux02-Feb-201529.6 KiB

README.hurd29-Dec-20121.9 KiB

README.irix29-Dec-20124.3 KiB

README.jp14-Apr-20137.3 KiB

README.ko09-Jul-201312 KiB

README.linux29-Dec-20121.5 KiB

README.macos29-Dec-20121,001

README.macosx30-Nov-201511.7 KiB

README.micro29-Dec-20121.8 KiB

README.netware26-May-20136.3 KiB

README.openbsd29-Dec-20121.2 KiB

README.os230-Nov-201590.5 KiB

README.os39012-May-201515.3 KiB

README.os40012-May-20154.7 KiB

README.plan929-Dec-20125 KiB

README.qnx03-Feb-20146.5 KiB

README.riscos29-Dec-20121.5 KiB

README.solaris31-Jan-201429.1 KiB

README.symbian29-Dec-201215.4 KiB

README.synology09-Mar-20157 KiB

README.tru6420-Nov-20158.3 KiB

README.tw12-Jun-20134.5 KiB

README.vms30-Nov-201523.4 KiB

README.vos25-Mar-20133.8 KiB

README.win3212-Oct-201538.4 KiB

reentr.c24-Jun-201515.7 KiB

reentr.h17-Sep-201376.4 KiB

regcharclass.h09-Dec-2015179.7 KiB

regcomp.c15-Dec-2015687.7 KiB

regcomp.h10-Sep-201541.5 KiB

regcomp.sym12-Oct-201512.3 KiB

regen/10-Dec-20154 KiB

regen.pl25-Jul-2013862

regen_perly.pl16-Jun-20149 KiB

regexec.c09-Dec-2015329.6 KiB

regexp.h10-Sep-201532.6 KiB

regnodes.h12-Oct-201534.8 KiB

run.c23-Mar-20151.4 KiB

runtests.SH16-Dec-20142.5 KiB

scope.c14-Dec-201538.2 KiB

scope.h10-Sep-201511.6 KiB

sv.c09-Dec-2015461.6 KiB

sv.h09-Dec-201579.5 KiB

symbian/16-Nov-20154 KiB

t/30-Nov-20154 KiB

taint.c23-Mar-20155.1 KiB

TestInit.pm03-Sep-20143.2 KiB

thread.h30-Nov-201511.7 KiB

time64.c07-Aug-201515.1 KiB

time64.h07-Aug-20151.5 KiB

time64_config.h29-Dec-20122 KiB

toke.c09-Dec-2015352.9 KiB

uconfig.h15-Dec-2015157.6 KiB

uconfig.sh09-Nov-201517.2 KiB

uconfig64.sh09-Nov-201517.3 KiB

unicode_constants.h10-Dec-20158.4 KiB

universal.c10-Sep-201526.8 KiB

unixish.h21-Sep-20154.9 KiB

utf8.c11-Dec-2015150 KiB

utf8.h10-Dec-201537.6 KiB

utfebcdic.h10-Dec-201512.4 KiB

util.c09-Dec-2015177.9 KiB

util.h10-Sep-20159.1 KiB

utils/16-Mar-20154 KiB

utils.lst10-Feb-2015564

vms/30-Nov-20154 KiB

vos/29-Dec-20124 KiB

vutil.c12-Aug-201425.5 KiB

vutil.h27-Jan-20147.1 KiB

vxs.inc05-Feb-201410.9 KiB

warnings.h12-Oct-20155.3 KiB

win32/15-Dec-20154 KiB

write_buildcustomize.pl09-Nov-20153.1 KiB

XSUB.h12-Oct-201524.2 KiB

README

1Perl is Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
22001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012,
32013, 2014, 2015 by Larry Wall and others.  All rights reserved.
4
5
6
7ABOUT PERL
8==========
9
10Perl is a general-purpose programming language originally developed for
11text manipulation and now used for a wide range of tasks including
12system administration, web development, network programming, GUI
13development, and more.
14
15The language is intended to be practical (easy to use, efficient,
16complete) rather than beautiful (tiny, elegant, minimal).  Its major
17features are that it's easy to use, supports both procedural and
18object-oriented (OO) programming, has powerful built-in support for text
19processing, and has one of the world's most impressive collections of
20third-party modules.
21
22For an introduction to the language's features, see pod/perlintro.pod.
23
24For a discussion of the important changes in this release, see
25pod/perldelta.pod.
26
27There are also many Perl books available, covering a wide variety of topics,
28from various publishers.  See pod/perlbook.pod for more information.
29
30
31INSTALLATION
32============
33
34If you're using a relatively modern operating system and want to
35install this version of Perl locally, run the following commands:
36
37  ./Configure -des -Dprefix=$HOME/localperl
38  make test
39  make install
40
41This will configure and compile perl for your platform, run the regression
42tests, and install perl in a subdirectory "localperl" of your home directory.
43
44If you run into any trouble whatsoever or you need to install a customized
45version of Perl, you should read the detailed instructions in the "INSTALL"
46file that came with this distribution.  Additionally, there are a number of
47"README" files with hints and tips about building and using Perl on a wide
48variety of platforms, some more common than others.
49
50Once you have Perl installed, a wealth of documentation is available to you
51through the 'perldoc' tool.  To get started, run this command:
52
53  perldoc perl
54
55
56IF YOU RUN INTO TROUBLE
57=======================
58
59Perl is a large and complex system that's used for everything from
60knitting to rocket science.  If you run into trouble, it's quite
61likely that someone else has already solved the problem you're
62facing. Once you've exhausted the documentation, please report bugs to us
63using the 'perlbug' tool. For more information about perlbug, either type
64'perldoc perlbug' or just 'perlbug' on a line by itself.
65
66While it was current when we made it available, Perl is constantly evolving
67and there may be a more recent version that fixes bugs you've run into or
68adds new features that you might find useful.
69
70You can always find the latest version of perl on a CPAN (Comprehensive Perl
71Archive Network) site near you at http://www.cpan.org/src/
72
73If you want to submit a simple patch to the perl source, see the "SUPER
74QUICK PATCH GUIDE" in pod/perlhack.pod.
75
76Just a personal note:  I want you to know that I create nice things like this
77because it pleases the Author of my story.  If this bothers you, then your
78notion of Authorship needs some revision.  But you can use perl anyway. :-)
79
80							The author.
81
82
83LICENSING
84=========
85
86This program is free software; you can redistribute it and/or modify
87it under the terms of either:
88
89	a) the GNU General Public License as published by the Free
90	Software Foundation; either version 1, or (at your option) any
91	later version, or
92
93	b) the "Artistic License" which comes with this Kit.
94
95This program is distributed in the hope that it will be useful,
96but WITHOUT ANY WARRANTY; without even the implied warranty of
97MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
98the GNU General Public License or the Artistic License for more details.
99
100You should have received a copy of the Artistic License with this
101Kit, in the file named "Artistic".  If not, I'll be glad to provide one.
102
103You should also have received a copy of the GNU General Public License
104along with this program in the file named "Copying". If not, write to the
105Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
106Boston, MA 02110-1301, USA or visit their web page on the internet at
107http://www.gnu.org/copyleft/gpl.html.
108
109For those of you that choose to use the GNU General Public License,
110my interpretation of the GNU General Public License is that no Perl
111script falls under the terms of the GPL unless you explicitly put
112said script under the terms of the GPL yourself.  Furthermore, any
113object code linked with perl does not automatically fall under the
114terms of the GPL, provided such object code only adds definitions
115of subroutines and variables, and does not otherwise impair the
116resulting interpreter from executing any standard Perl script.  I
117consider linking in C subroutines in this manner to be the moral
118equivalent of defining subroutines in the Perl language itself.  You
119may sell such an object file as proprietary provided that you provide
120or offer to provide the Perl source, as specified by the GNU General
121Public License.  (This is merely an alternate way of specifying input
122to the program.)  You may also sell a binary produced by the dumping of
123a running Perl script that belongs to you, provided that you provide or
124offer to provide the Perl source as specified by the GPL.  (The
125fact that a Perl interpreter and your code are in the same binary file
126is, in this case, a form of mere aggregation.)  This is my interpretation
127of the GPL.  If you still have concerns or difficulties understanding
128my intent, feel free to contact me.  Of course, the Artistic License
129spells all this out for your protection, so you may prefer to use that.
130
131
132

README.aix

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlaix - Perl version 5 on IBM AIX (UNIX) systems
8
9=head1 DESCRIPTION
10
11This document describes various features of IBM's UNIX operating
12system AIX that will affect how Perl version 5 (hereafter just Perl)
13is compiled and/or runs.
14
15=head2 Compiling Perl 5 on AIX
16
17For information on compilers on older versions of AIX, see L<Compiling
18Perl 5 on older AIX versions up to 4.3.3>.
19
20When compiling Perl, you must use an ANSI C compiler. AIX does not ship
21an ANSI compliant C compiler with AIX by default, but binary builds of
22gcc for AIX are widely available. A version of gcc is also included in
23the AIX Toolbox which is shipped with AIX.
24
25=head2 Supported Compilers
26
27Currently all versions of IBM's "xlc", "xlc_r", "cc", "cc_r" or
28"vac" ANSI/C compiler will work for building Perl if that compiler
29works on your system.
30
31If you plan to link Perl to any module that requires thread-support,
32like DBD::Oracle, it is better to use the _r version of the compiler.
33This will not build a threaded Perl, but a thread-enabled Perl. See
34also L<Threaded Perl> later on.
35
36As of writing (2010-09) only the I<IBM XL C for AIX> or I<IBM XL C/C++
37for AIX> compiler is supported by IBM on AIX 5L/6.1/7.1.
38
39The following compiler versions are currently supported by IBM:
40
41    IBM XL C and IBM XL C/C++ V8, V9, V10, V11
42
43The XL C for AIX is integrated in the XL C/C++ for AIX compiler and
44therefore also supported.
45
46If you choose XL C/C++ V9 you need APAR IZ35785 installed
47otherwise the integrated SDBM_File do not compile correctly due
48to an optimization bug. You can circumvent this problem by
49adding -qipa to the optimization flags (-Doptimize='-O -qipa').
50The PTF for APAR IZ35785 which solves this problem is available
51from IBM (April 2009 PTF for XL C/C++ Enterprise Edition for AIX, V9.0).
52
53If you choose XL C/C++ V11 you need the April 2010 PTF (or newer)
54installed otherwise you will not get a working Perl version.
55
56Perl can be compiled with either IBM's ANSI C compiler or with gcc.
57The former is recommended, as not only it can compile Perl with no
58difficulty, but also can take advantage of features listed later
59that require the use of IBM compiler-specific command-line flags.
60
61If you decide to use gcc, make sure your installation is recent and
62complete, and be sure to read the Perl INSTALL file for more gcc-specific
63details. Please report any hoops you had to jump through to the
64development team.
65
66=head2 Incompatibility with AIX Toolbox lib gdbm
67
68If the AIX Toolbox version of lib gdbm < 1.8.3-5 is installed on your
69system then Perl will not work. This library contains the header files
70/opt/freeware/include/gdbm/dbm.h|ndbm.h which conflict with the AIX
71system versions. The lib gdbm will be automatically removed from the
72wanted libraries if the presence of one of these two header files is
73detected. If you want to build Perl with GDBM support then please install
74at least gdbm-devel-1.8.3-5 (or higher).
75
76=head2 Perl 5 was successfully compiled and tested on:
77
78 Perl   | AIX Level           | Compiler Level          | w th | w/o th
79 -------+---------------------+-------------------------+------+-------
80 5.12.2 |5.1 TL9 32 bit       | XL C/C++ V7             | OK   | OK
81 5.12.2 |5.1 TL9 64 bit       | XL C/C++ V7             | OK   | OK
82 5.12.2 |5.2 TL10 SP8 32 bit  | XL C/C++ V8             | OK   | OK
83 5.12.2 |5.2 TL10 SP8 32 bit  | gcc 3.2.2               | OK   | OK
84 5.12.2 |5.2 TL10 SP8 64 bit  | XL C/C++ V8             | OK   | OK
85 5.12.2 |5.3 TL8 SP8 32 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
86 5.12.2 |5.3 TL8 SP8 32 bit   | gcc 4.2.4               | OK   | OK
87 5.12.2 |5.3 TL8 SP8 64 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
88 5.12.2 |5.3 TL10 SP3 32 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
89 5.12.2 |5.3 TL10 SP3 64 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
90 5.12.2 |6.1 TL1 SP7 32 bit   | XL C/C++ V10            | OK   | OK
91 5.12.2 |6.1 TL1 SP7 64 bit   | XL C/C++ V10            | OK   | OK
92 5.13   |7.1 TL0 SP1 32 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
93 5.13   |7.1 TL0 SP1 64 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
94
95 w th   = with thread support
96 w/o th = without thread support
97 OK     = tested
98
99Successfully tested means that all "make test" runs finish with a
100result of 100% OK. All tests were conducted with -Duseshrplib set.
101
102All tests were conducted on the oldest supported AIX technology level
103with the latest support package applied. If the tested AIX version is
104out of support (AIX 4.3.3, 5.1, 5.2) then the last available support
105level was used.
106
107=head2 Building Dynamic Extensions on AIX
108
109Starting from Perl 5.7.2 (and consequently 5.8.x / 5.10.x / 5.12.x)
110and AIX 4.3 or newer Perl uses the AIX native dynamic loading interface
111in the so called runtime linking mode instead of the emulated interface
112that was used in Perl releases 5.6.1 and earlier or, for AIX releases
1134.2 and earlier. This change does break backward compatibility with
114compiled modules from earlier Perl releases. The change was made to make
115Perl more compliant with other applications like Apache/mod_perl which are
116using the AIX native interface. This change also enables the use of
117C++ code with static constructors and destructors in Perl extensions,
118which was not possible using the emulated interface.
119
120It is highly recommended to use the new interface.
121
122=head2 Using Large Files with Perl
123
124Should yield no problems.
125
126=head2 Threaded Perl
127
128Should yield no problems with AIX 5.1 / 5.2 / 5.3 / 6.1 / 7.1.
129
130IBM uses the AIX system Perl (V5.6.0 on AIX 5.1 and V5.8.2 on
131AIX 5.2 / 5.3 and 6.1; V5.8.8 on AIX 5.3 TL11 and AIX 6.1 TL4; V5.10.1
132on AIX 7.1) for some AIX system scripts. If you switch the links in
133/usr/bin from the AIX system Perl (/usr/opt/perl5) to the newly build
134Perl then you get the same features as with the IBM AIX system Perl if
135the threaded options are used.
136
137The threaded Perl build works also on AIX 5.1 but the IBM Perl
138build (Perl v5.6.0) is not threaded on AIX 5.1.
139
140Perl 5.12 an newer is not compatible with the IBM fileset perl.libext.
141
142=head2 64-bit Perl
143
144If your AIX system is installed with 64-bit support, you can expect 64-bit
145configurations to work. If you want to use 64-bit Perl on AIX 6.1
146you need an APAR for a libc.a bug which affects (n)dbm_XXX functions.
147The APAR number for this problem is IZ39077.
148
149If you need more memory (larger data segment) for your Perl programs you
150can set:
151
152    /etc/security/limits
153    default:                    (or your user)
154        data = -1               (default is 262144 * 512 byte)
155
156With the default setting the size is limited to 128MB.
157The -1 removes this limit. If the "make test" fails please change
158your /etc/security/limits as stated above.
159
160=head2 Long doubles
161
162IBM calls its implementation of long doubles 128-bit, but it is not
163the IEEE 128-bit ("quadruple precision") which would give 116 bit of
164mantissa (nor it is implemented in hardware), instead it's a special
165software implementation called "double-double", which gives 106 bits
166of mantissa.
167
168There seem to be various problems in this long double implementation.
169If Configure detects this brokenness, it will disable the long double support.
170This can be overriden with explicit C<-Duselongdouble> (or C<-Dusemorebits>,
171which enables both long doubles and 64 bit integers).  If you decide to
172enable long doubles, for most of the broken things Perl has implemented
173workarounds, but the handling of the special values infinity and NaN
174remains badly broken: for example infinity plus zero results in NaN.
175
176=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)
177
178With the following options you get a threaded Perl version which
179passes all make tests in threaded 32-bit mode, which is the default
180configuration for the Perl builds that AIX ships with.
181
182    rm config.sh
183    ./Configure \
184    -d \
185    -Dcc=cc_r \
186    -Duseshrplib \
187    -Dusethreads \
188    -Dprefix=/usr/opt/perl5_32
189
190The -Dprefix option will install Perl in a directory parallel to the 
191IBM AIX system Perl installation.
192
193=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)
194
195With the following options you get a Perl version which passes 
196all make tests in 32-bit mode.
197
198    rm config.sh
199    ./Configure \
200    -d \
201    -Dcc=cc_r \
202    -Duseshrplib \
203    -Dprefix=/usr/opt/perl5_32
204
205The -Dprefix option will install Perl in a directory parallel to the
206IBM AIX system Perl installation.
207
208=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)
209
210With the following options you get a threaded Perl version which
211passes all make tests in 64-bit mode.
212
213 export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
214
215 rm config.sh
216 ./Configure \
217 -d \
218 -Dcc=cc_r \
219 -Duseshrplib \
220 -Dusethreads \
221 -Duse64bitall \
222 -Dprefix=/usr/opt/perl5_64
223
224=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)
225
226With the following options you get a Perl version which passes all
227make tests in 64-bit mode. 
228
229 export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
230
231 rm config.sh
232 ./Configure \
233 -d \
234 -Dcc=cc_r \
235 -Duseshrplib \
236 -Duse64bitall \
237 -Dprefix=/usr/opt/perl5_64
238
239The -Dprefix option will install Perl in a directory parallel to the
240IBM AIX system Perl installation.
241
242If you choose gcc to compile 64-bit Perl then you need to add the
243following option:
244
245    -Dcc='gcc -maix64'
246
247
248=head2 Compiling Perl 5 on AIX 7.1.0
249
250A regression in AIX 7 causes a failure in make test in Time::Piece during
251daylight savings time.  APAR IV16514 provides the fix for this.  A quick
252test to see if it's required, assuming it is currently daylight savings
253in Eastern Time, would be to run C< TZ=EST5 date +%Z >.  This will come
254back with C<EST> normally, but nothing if you have the problem.
255
256
257=head2 Compiling Perl 5 on older AIX versions up to 4.3.3
258
259Due to the fact that AIX 4.3.3 reached end-of-service in December 31,
2602003 this information is provided as is. The Perl versions prior to
261Perl 5.8.9 could be compiled on AIX up to 4.3.3 with the following
262settings (your mileage may vary):
263
264When compiling Perl, you must use an ANSI C compiler. AIX does not ship
265an ANSI compliant C-compiler with AIX by default, but binary builds of
266gcc for AIX are widely available.
267
268At the moment of writing, AIX supports two different native C compilers,
269for which you have to pay: B<xlC> and B<vac>. If you decide to use either
270of these two (which is quite a lot easier than using gcc), be sure to
271upgrade to the latest available patch level. Currently:
272
273    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
274    vac.C     4.4.0.3  or 5.0.2.6 or 6.0.0.1
275
276note that xlC has the OS version in the name as of version 4.0.2.0, so
277you will find xlC.C for AIX-5.0 as package
278
279    xlC.aix50.rte   5.0.2.0 or 6.0.0.3
280
281subversions are not the same "latest" on all OS versions. For example,
282the latest xlC-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.
283
284Perl can be compiled with either IBM's ANSI C compiler or with gcc.
285The former is recommended, as not only can it compile Perl with no
286difficulty, but also can take advantage of features listed later that
287require the use of IBM compiler-specific command-line flags.
288
289The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler
290optimization bugs that affect compiling perl.c and regcomp.c,
291respectively.  If Perl's configuration detects those compiler patch
292levels, optimization is turned off for the said source code files.
293Upgrading to at least 5.0.2.0 is recommended.
294
295If you decide to use gcc, make sure your installation is recent and
296complete, and be sure to read the Perl INSTALL file for more gcc-specific
297details. Please report any hoops you had to jump through to the development
298team.
299
300=head2 OS level
301
302Before installing the patches to the IBM C-compiler you need to know the
303level of patching for the Operating System. IBM's command 'oslevel' will
304show the base, but is not always complete (in this example oslevel shows
3054.3.NULL, whereas the system might run most of 4.3.THREE):
306
307    # oslevel
308    4.3.0.0
309    # lslpp -l | grep 'bos.rte '
310    bos.rte           4.3.3.75  COMMITTED  Base Operating System Runtime
311    bos.rte            4.3.2.0  COMMITTED  Base Operating System Runtime
312    #
313
314The same might happen to AIX 5.1 or other OS levels. As a side note, Perl
315cannot be built without bos.adt.syscalls and bos.adt.libm installed
316
317    # lslpp -l | egrep "syscalls|libm"
318    bos.adt.libm      5.1.0.25  COMMITTED  Base Application Development
319    bos.adt.syscalls  5.1.0.36  COMMITTED  System Calls Application
320    #
321
322=head2 Building Dynamic Extensions on AIX E<lt> 5L
323
324AIX supports dynamically loadable objects as well as shared libraries.
325Shared libraries by convention end with the suffix .a, which is a bit
326misleading, as an archive can contain static as well as dynamic members.
327For Perl dynamically loaded objects we use the .so suffix also used on
328many other platforms.
329
330Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3
331or newer Perl uses the AIX native dynamic loading interface in the so
332called runtime linking mode instead of the emulated interface that was
333used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and
334earlier.  This change does break backward compatibility with compiled
335modules from earlier Perl releases.  The change was made to make Perl
336more compliant with other applications like Apache/mod_perl which are
337using the AIX native interface. This change also enables the use of C++
338code with static constructors and destructors in Perl extensions, which
339was not possible using the emulated interface.
340
341=head2 The IBM ANSI C Compiler
342
343All defaults for Configure can be used.
344
345If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions
346will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0,
347but vac 5.0.2.6 or up is highly recommended. Note that since IBM has
348removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these
349versions should be considered obsolete.
350
351Here's a brief lead of how to upgrade the compiler to the latest
352level.  Of course this is subject to changes.  You can only upgrade
353versions from ftp-available updates if the first three digit groups
354are the same (in where you can skip intermediate unlike the patches
355in the developer snapshots of Perl), or to one version up where the
356"base" is available.  In other words, the AIX compiler patches are
357cumulative.
358
359 vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
360 xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not
361                                                              available)
362
363 # ftp ftp.software.ibm.com
364 Connected to service.boulder.ibm.com.
365 : welcome message ...
366 Name (ftp.software.ibm.com:merijn): anonymous
367 331 Guest login ok, send your complete e-mail address as password.
368 Password:
369 ... accepted login stuff
370 ftp> cd /aix/fixes/v4/
371 ftp> dir other other.ll
372 output to local-file: other.ll? y
373 200 PORT command successful.
374 150 Opening ASCII mode data connection for /bin/ls.
375 226 Transfer complete.
376 ftp> dir xlc xlc.ll
377 output to local-file: xlc.ll? y
378 200 PORT command successful.
379 150 Opening ASCII mode data connection for /bin/ls.
380 226 Transfer complete.
381 ftp> bye
382 ... goodbye messages
383 # ls -l *.ll
384 -rw-rw-rw-   1 merijn   system    1169432 Nov  2 17:29 other.ll
385 -rw-rw-rw-   1 merijn   system      29170 Nov  2 17:29 xlc.ll
386
387On AIX 4.2 using xlC, we continue:
388
389 # lslpp -l | fgrep 'xlC.C '
390   xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
391   xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
392 # grep 'xlC.C.3.1.4.*.bff' xlc.ll
393 -rw-r--r--   1 45776101 1       6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
394 -rw-rw-r--   1 45776101 1       6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
395 -rw-r--r--   1 45776101 1       6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
396 -rw-r--r--   1 45776101 1       6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
397 -rw-r--r--   1 45776101 1       6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
398 -rw-rw-r--   1 45776101 1       6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
399 -rw-rw-r--   1 45776101 1       6188032 May 22 1997  xlC.C.3.1.4.6.bff
400 -rw-rw-r--   1 45776101 1       6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
401 -rw-rw-r--   1 45776101 1       6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
402 -rw-rw-r--   1 45776101 1       6169600 May 27 1998  xlC.C.3.1.4.9.bff
403 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
404 #
405
406On AIX 4.3 using vac, we continue:
407
408 # lslpp -l | grep 'vac.C '
409  vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
410  vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
411 # grep 'vac.C.5.0.2.*.bff' other.ll
412 -rw-rw-r--   1 45776101 1       13592576 Apr 16 2001  vac.C.5.0.2.0.bff
413 -rw-rw-r--   1 45776101 1       14133248 Apr  9 2002  vac.C.5.0.2.3.bff
414 -rw-rw-r--   1 45776101 1       14173184 May 20 2002  vac.C.5.0.2.4.bff
415 -rw-rw-r--   1 45776101 1       14192640 Nov 22 2002  vac.C.5.0.2.6.bff
416 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
417 #
418
419Likewise on all other OS levels. Then execute the following command, and
420fill in its choices
421
422 # smit install_update
423  -> Install and Update from LATEST Available Software
424  * INPUT device / directory for software [ vac.C.5.0.2.6.bff    ]
425  [ OK ]
426  [ OK ]
427
428Follow the messages ... and you're done.
429
430If you like a more web-like approach, a good start point can be
431http://www14.software.ibm.com/webapp/download/downloadaz.jsp and click
432"C for AIX", and follow the instructions.
433
434=head2 The usenm option
435
436If linking miniperl
437
438 cc -o miniperl ... miniperlmain.o opmini.o perl.o ... -lm -lc ...
439
440causes error like this
441
442 ld: 0711-317 ERROR: Undefined symbol: .aintl
443 ld: 0711-317 ERROR: Undefined symbol: .copysignl
444 ld: 0711-317 ERROR: Undefined symbol: .syscall
445 ld: 0711-317 ERROR: Undefined symbol: .eaccess
446 ld: 0711-317 ERROR: Undefined symbol: .setresuid
447 ld: 0711-317 ERROR: Undefined symbol: .setresgid
448 ld: 0711-317 ERROR: Undefined symbol: .setproctitle
449 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more
450                                                            information.
451
452you could retry with
453
454 make realclean
455 rm config.sh
456 ./Configure -Dusenm ...
457
458which makes Configure to use the C<nm> tool when scanning for library
459symbols, which usually is not done in AIX.
460
461Related to this, you probably should not use the C<-r> option of
462Configure in AIX, because that affects of how the C<nm> tool is used.
463
464=head2 Using GNU's gcc for building Perl
465
466Using gcc-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box,
467as do recent gcc-2.9 builds available directly from IBM as part of their
468Linux compatibility packages, available here:
469
470  http://www.ibm.com/servers/aix/products/aixos/linux/
471
472=head2 Using Large Files with Perl E<lt> 5L
473
474Should yield no problems.
475
476=head2 Threaded Perl E<lt> 5L
477
478Threads seem to work OK, though at the moment not all tests pass when
479threads are used in combination with 64-bit configurations.
480
481You may get a warning when doing a threaded build:
482
483  "pp_sys.c", line 4640.39: 1506-280 (W) Function argument assignment 
484  between types "unsigned char*" and "const void*" is not allowed.
485
486The exact line number may vary, but if the warning (W) comes from a line
487line this
488
489  hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);
490
491in the "pp_ghostent" function, you may ignore it safely.  The warning
492is caused by the reentrant variant of gethostbyaddr() having a slightly
493different prototype than its non-reentrant variant, but the difference
494is not really significant here.
495
496=head2 64-bit Perl E<lt> 5L
497
498If your AIX is installed with 64-bit support, you can expect 64-bit
499configurations to work. In combination with threads some tests might
500still fail.
501
502=head2 AIX 4.2 and extensions using C++ with statics
503
504In AIX 4.2 Perl extensions that use C++ functions that use statics
505may have problems in that the statics are not getting initialized.
506In newer AIX releases this has been solved by linking Perl with
507the libC_r library, but unfortunately in AIX 4.2 the said library
508has an obscure bug where the various functions related to time
509(such as time() and gettimeofday()) return broken values, and
510therefore in AIX 4.2 Perl is not linked against the libC_r.
511
512=head1 AUTHORS
513
514Rainer Tammer <tammer@tammer.net>
515
516=cut
517

README.amiga

1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see perlpod manpage) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlamiga - Perl under AmigaOS 4.1
8
9=head1 NOTE
10
11This is a port of Perl 5.22.1, it is a fresh port and not in any way
12compatible with my previous ports of Perl 5.8 and 5.16.3. This means
13you will need to reinstall / rebuild any third party modules you have
14installed.
15
16newlib.library version 53.28 or greater is required.
17
18=head1 SYNOPSIS
19
20Once perl is installed you can read this document in the following way
21
22	sh -c "perldoc perlamiga"
23
24or you may read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
25
26=cut
27
28       NAME
29       SYNOPSIS
30       DESCRIPTION
31         -  Prerequisites
32         -  Starting Perl programs under AmigaOS
33         -  Shortcomings of Perl under AmigaOS
34       INSTALLATION
35       CHANGES
36
37=head1 DESCRIPTION
38
39=head2 Prerequisites for running Perl 5.22.1 under AmigaOS 4.1
40
41=over 6
42
43=item B<AmigaOS 4.1 update 6 with all updates applied as of 9th October 2013>
44
45The most important of which is:
46
47=item B<newlib.library version 53.28 or greater>
48
49=item B<AmigaOS SDK>
50
51Perl installs into the SDK directory structure and expects many of the
52build tools present in the SDK to be available. So for the best results
53install the SDK first.
54
55=item B<abc-shell>
56
57If you do not have the SDK installed you must at least have abc-shell
58installed or some other suitable sh port. This is required to run
59external commands and should be available as 'sh' in your path.
60
61=back
62
63=head2 Starting Perl programs under AmigaOS 4.1
64
65Perl may be run from the AmigaOS shell but for best results should be
66run under abc-shell.  (abc-shell handles file globbing, pattern
67expansion, and sets up environment variables in the UN*Xy way that
68Perl expects.)
69
70For example:
71
72	New Shell process 10
73	10.AmigaOS4:> sh
74	/AmigaOS4>perl path:to/myprog arg1 arrg2 arg3
75
76Abc-shell can also launch programs via the #! syntax at the start of
77the program file, it's best use the form #!SDK:Local/C/perl so that
78the AmigaOS shell may also find perl in the same way. AmigaOS requires
79the script bit to be set for this to work
80
81	10.AmigaOS4:> sh
82	/AmigaOS4>myprog arg1 arrg2 arg3
83
84=head2 Limitations of Perl under AmigaOS 4.1
85
86=over 6
87
88=item B<Nested Piped programs can crash when run from older abc-shells>
89
90abc-shell version 53.2 has a bug that can cause crashes in the
91subprocesses used to run piped programs, if a later version is
92available you should install it instead.
93
94=item B<Incorrect or unexpected command line unescaping>
95
96newlib.library 53.30 and earlier incorrectly unescape slashed escape
97sequences e.g. \" \n \t etc requiring unusual extra escaping.
98
99=item B<Starting subprocesses via open has limitations>
100
101	open FH, "command |"
102
103Subprocesses started with open use a minimal popen() routine and
104therefore they do not return pids usable with waitpid etc.
105
106=item If you find any other limitations or bugs then let me know.
107
108Please report bugs in this version of perl to andy@broad.ology.org.uk
109in the first instance.
110
111=back
112
113=head1 INSTALLATION
114
115This guide assumes you have obtained a prebuilt archive from os4depot.net.
116
117Unpack the main archive to a temporary location (RAM: is fine).
118
119Execute the provided install script from shell or via its icon.
120
121You B<must not> attempt to install by hand.
122
123Once installed you may delete the temporary archive.
124
125This approach will preserve links in the installation without creating
126duplicate binaries.
127
128If you have the earlier ports perl 5.16 or 5.8 installed you may like
129to rename your perl executable to perl516 or perl58 or something
130similar before the installation of 5.22.1, this will allow you to use
131both versions at the same time.
132
133=head1 Amiga Specific Modules
134
135=head2 Amiga::ARexx
136
137The Amiga::ARexx module allows you to easily create a perl based ARexx
138host or to send ARexx commands to other programs.
139
140Try C<perldoc Amiga::ARexx> for more info.
141
142=head2 Amiga::Exec
143
144The Amiga::Exec module introduces support for Wait().
145
146Try C<perldoc Amiga::Exec> for more info.
147
148=head1 BUILDING
149
150To build perl under AmigaOS from the patched sources you will need to
151have a recent version of the SDK. Version 53.29 is recommended,
152earlier versions will probably work too.
153
154With the help of Jarkko Hietaniemi the Configure system has been tweaked to
155run under abc-shell so the recommend build process is as follows.
156
157	stack 2000000
158	sh Configure -de
159	gmake
160
161This will build the default setup that installs under SDK:local/newlib/lib/
162
163=head1 CHANGES
164
165=over 6
166
167=item B<August 2015>
168
169=over 2
170
171=item Port to Perl 5.22
172
173=item Add handling of NIL: to afstat()
174
175=item Fix inheritance of environment variables by subprocesses.
176
177=item Fix exec, and exit in "forked" subprocesses.
178
179=item Fix issue with newlib's unlink, which could cause infinite loops.
180
181=item Add flock() emulation using IDOS->LockRecord thanks to Tony Cook
182for the suggestion.
183
184=item Fix issue where kill was using the wrong kind of process ID
185
186=back
187
188=item B<27th November 2013>
189
190=over 2
191
192=item Create new installation system based on installperl links
193and Amiga protection bits now set correctly.
194
195=item Pod now defaults to text.
196
197=item File::Spec should now recognise an Amiga style absolute path as well
198as an Unix style one. Relative paths must always be Unix style.
199
200=back
201
202=item B<20th November 2013>
203
204=over 2
205
206=item Configured to use SDK:Local/C/perl to start standard scripts
207
208=item Added Amiga::Exec module with support for Wait() and AmigaOS signal numbers.
209
210=back
211
212=item B<10th October 13>
213
214First release of port to 5.16.3.
215
216=back
217
218=head1 SEE ALSO
219
220You like this port?  See L<http://www.broad.ology.org.uk/amiga/>
221for how you can help.
222
223=cut
224

README.android

1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see pod/perlpod.pod) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlandroid - Perl under Android
8
9=head1 SYNOPSIS
10
11The first portions of this documents contains instructions
12to cross-compile Perl for Android 2.0 and later, using the
13binaries provided by Google.  The latter portion describes how to build
14perl native using one of the toolchains available on the Play Store.
15
16=head1 DESCRIPTION
17
18This document describes how to set up your host environment when
19attempting to build Perl for Android.
20
21=head1 Cross-compilation
22
23These instructions assume an Unixish build environment on your host system;
24they've been tested on Linux and OS X, and may work on Cygwin and MSYS.
25While Google also provides an NDK for Windows, these steps won't work
26native there, although it may be possible to cross-compile through different
27means.
28
29If your host system's architecture is 32 bits, remember to change the
30C<x86_64>'s below to C<x86>'s.  On a similar vein, the examples below
31use the 4.8 toolchain; if you want to use something older or newer (for
32example, the 4.4.3 toolchain included in the 8th revision of the NDK), just
33change those to the relevant version.
34
35=head2 Get the Android Native Development Kit (NDK)
36
37You can download the NDK from L<https://developer.android.com/tools/sdk/ndk/index.html>.
38You'll want the normal, non-legacy version.
39
40=head2 Determine the architecture you'll be cross-compiling for
41
42There's three possible options: arm-linux-androideabi for ARM,
43mipsel-linux-android for MIPS, and simply x86 for x86.
44As of 2014, most Android devices run on ARM, so that is generally a safe bet.
45
46With those two in hand, you should add
47
48$ANDROID_NDK/toolchains/$TARGETARCH-4.8/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin
49
50to your PATH, where $ANDROID_NDK is the location where you unpacked the
51NDK, and $TARGETARCH is your target's architecture.
52
53=head2 Set up a standalone toolchain
54
55This creates a working sysroot that we can feed to Configure later.
56
57    $ export ANDROID_TOOLCHAIN=/tmp/my-toolchain-$TARGETARCH
58    $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
59    $ $ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
60            --platform=android-9 \
61            --install-dir=$ANDROID_TOOLCHAIN \
62            --system=`uname | tr '[A-Z]' '[a-z]'`-x86_64 \
63            --toolchain=$TARGETARCH-4.8
64
65=head2 adb or ssh?
66
67adb is the Android Debug Bridge.  For our purposes, it's basically a way
68of establishing an ssh connection to an Android device without having to
69install anything on the device itself, as long as the device is either on
70the same local network as the host, or it is connected to the host through
71USB.
72Perl can be cross-compiled using either adb or a normal ssh connection;
73in general, if you can connect your device to the host using a USB port,
74or if you don't feel like installing an sshd app on your device,
75you may want to use adb, although you may be forced to switch to ssh if
76your device is not rooted and you're unlucky -- more on that later.
77Alternatively, if you're cross-compiling to an emulator, you'll have to
78use adb.
79
80=head3 adb
81
82To use adb, download the Android SDK from L<https://developer.android.com/sdk/index.html>.
83The "SDK Tools Only" version should suffice -- if you downloaded the ADT
84Bundle, you can find the sdk under $ADT_BUNDLE/sdk/.
85
86Add $ANDROID_SDK/platform-tools to your PATH, which should give you access
87to adb.  You'll now have to find your device's name using 'adb devices',
88and later pass that to Configure through '-Dtargethost=$DEVICE'.
89
90However, before calling Configure, you need to check if using adb is a
91viable choice in the first place.  Because Android doesn't have a /tmp,
92nor does it allow executables in the sdcard, we need to find somewhere in
93the device for Configure to put some files in, as well as for the tests
94to run in. If your device is rooted, then you're good.  Try running these:
95
96    $ export TARGETDIR=/mnt/asec/perl
97    $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
98
99Which will create the directory we need, and you can move on to the next
100step.  /mnt/asec is mounted as a tmpfs in Android, but it's only
101accessible to root.
102
103If your device is not rooted, you may still be in luck. Try running this:
104
105    $ export TARGETDIR=/data/local/tmp/perl
106    $ adb -s $DEVICE shell "mkdir $TARGETDIR"
107
108If the command works, you can move to the next step, but beware:
109B<You'll have to remove the directory from the device once you are done!
110Unlike /mnt/asec, /data/local/tmp may not get automatically garbage
111collected once you shut off the phone>.
112
113If neither of those work, then you can't use adb to cross-compile to your
114device.  Either try rooting it, or go for the ssh route.
115
116=head3 ssh
117
118To use ssh, you'll need to install and run a sshd app and set it up
119properly.  There are several paid and free apps that do this rather
120easily, so you should be able to spot one on the store.
121Remember that Perl requires a passwordless connection, so set up a 
122public key.
123
124Note that several apps spew crap to stderr every time you
125connect, which can throw off Configure.  You may need to monkeypatch
126the part of Configure that creates 'run-ssh' to have it discard stderr.
127
128Since you're using ssh, you'll have to pass some extra arguments to
129Configure: -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
130
131=head2 Configure and beyond
132
133With all of the previous done, you're now ready to call Configure.
134
135If using adb, a "basic" Configure line will look like this:
136
137$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
138    -Dcc=$TARGETARCH-gcc   \
139    -Dsysroot=$SYSROOT     \
140    -Dtargetdir=$TARGETDIR \
141    -Dtargethost=$DEVICE
142
143If using ssh, it's not too different -- we just change targetrun to ssh,
144and pass in targetuser and targetport.  It ends up looking like this:
145
146$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
147    -Dcc=$TARGETARCH-gcc        \
148    -Dsysroot=$SYSROOT          \
149    -Dtargetdir=$TARGETDIR      \
150    -Dtargethost="$TARGETHOST"  \
151    -Dtargetuser=$TARGETUSER    \
152    -Dtargetport=$TARGETPORT
153
154Now you're ready to run make and make test!
155
156As a final word of warning, if you're using adb, make test may appear to
157hang; this is because it doesn't output anything until it finishes
158running all tests.  You can check its progress by logging into the
159device, moving to $TARGETDIR, and looking at the file output.stdout.
160
161=head3 Notes
162
163=over
164
165=item *
166
167If you are targetting x86 Android, you will have to change $TARGETARCH-gcc
168to i686-linux-android-gcc.
169
170=item *
171
172On some older low-end devices -- think early 2.2 era -- some tests,
173particularly t/re/uniprops, may crash the phone, causing it to turn
174itself off once, and then back on again.
175
176=back
177
178=head1 Native Builds
179
180While Google doesn't provide a native toolchain for Android,
181you can still get one from the Play Store; for example, there's the CCTools
182app which you can get for free.
183Keep in mind that you want a full
184toolchain; some apps tend to default to installing only a barebones
185version without some important utilities, like ar or nm.
186
187Once you have the toolchain set up properly, the only
188remaining hurdle is actually locating where in the device it was installed
189in.  For example, CCTools installs its toolchain in 
190/data/data/com.pdaxrom.cctools/root/cctools.  With the path in hand,
191compiling perl is little more than:
192
193 export SYSROOT=<location of the native toolchain>
194 export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
195 sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"
196
197=head1 AUTHOR
198
199Brian Fraser <fraserbn@gmail.com>
200
201=cut
202

README.bs2000

1This document is written in pod format hence there are punctuation
2characters in odd places.  Do not worry, you've apparently got the
3ASCII->EBCDIC translation worked out correctly.  You can read more
4about pod in pod/perlpod.pod or the short summary in the INSTALL file.
5
6=head1 NAME
7
8perlbs2000 - building and installing Perl for BS2000.
9
10B<This document needs to be updated, but we don't know what it should say.
11Please email comments to L<perlbug@perl.org|mailto:perlbug@perl.org>.>
12
13=head1 SYNOPSIS
14
15This document will help you Configure, build, test and install Perl
16on BS2000 in the POSIX subsystem.
17
18=head1 DESCRIPTION
19
20This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
21V3.1A or later.  It may work on other versions, but we started porting
22and testing it with 3.1A and are currently using Version V4.0A.
23
24You may need the following GNU programs in order to install perl:
25
26=head2 gzip on BS2000
27
28We used version 1.2.4, which could be installed out of the box with
29one failure during 'make check'.
30
31=head2 bison on BS2000
32
33The yacc coming with BS2000 POSIX didn't work for us.  So we had to
34use bison.  We had to make a few changes to perl in order to use the
35pure (reentrant) parser of bison.  We used version 1.25, but we had to
36add a few changes due to EBCDIC.  See below for more details
37concerning yacc.
38
39=head2 Unpacking Perl Distribution on BS2000
40
41To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
42filesystem (we used the mountpoint /usr/local/ascii for this).  Now
43you extract the archive in the ASCII filesystem without
44I/O-conversion:
45
46cd /usr/local/ascii
47export IO_CONVERSION=NO
48gunzip < /usr/local/src/perl.tar.gz | pax -r
49
50You may ignore the error message for the first element of the archive
51(this doesn't look like a tar archive / skipping to next file...),
52it's only the directory which will be created automatically anyway.
53
54After extracting the archive you copy the whole directory tree to your
55EBCDIC filesystem.  B<This time you use I/O-conversion>:
56
57cd /usr/local/src
58IO_CONVERSION=YES
59cp -r /usr/local/ascii/perl5.005_02 ./
60
61=head2 Compiling Perl on BS2000
62
63There is a "hints" file for BS2000 called hints.posix-bc (because
64posix-bc is the OS name given by `uname`) that specifies the correct
65values for most things.  The major problem is (of course) the EBCDIC
66character set.  We have german EBCDIC version.
67
68Because of our problems with the native yacc we used GNU bison to
69generate a pure (=reentrant) parser for perly.y.  So our yacc is
70really the following script:
71
72-----8<-----/usr/local/bin/yacc-----8<-----
73#! /usr/bin/sh
74
75# Bison as a reentrant yacc:
76
77# save parameters:
78params=""
79while [[ $# -gt 1 ]]; do
80    params="$params $1"
81    shift
82done
83
84# add flag %pure_parser:
85
86tmpfile=/tmp/bison.$$.y
87echo %pure_parser > $tmpfile
88cat $1 >> $tmpfile
89
90# call bison:
91
92echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)"
93/usr/local/bin/bison --yacc $params $tmpfile
94
95# cleanup:
96
97rm -f $tmpfile
98-----8<----------8<-----
99
100We still use the normal yacc for a2p.y though!!!  We made a softlink
101called byacc to distinguish between the two versions:
102
103ln -s /usr/bin/yacc /usr/local/bin/byacc
104
105We build perl using GNU make.  We tried the native make once and it
106worked too.
107
108=head2 Testing Perl on BS2000
109
110We still got a few errors during C<make test>.  Some of them are the
111result of using bison.  Bison prints I<parser error> instead of I<syntax
112error>, so we may ignore them.  The following list shows
113our errors, your results may differ:
114
115op/numconvert.......FAILED tests 1409-1440
116op/regexp...........FAILED tests 483, 496
117op/regexp_noamp.....FAILED tests 483, 496
118pragma/overload.....FAILED tests 152-153, 170-171
119pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
120lib/bigfloat........FAILED tests 351-352, 355
121lib/bigfltpm........FAILED tests 354-355, 358
122lib/complex.........FAILED tests 267, 487
123lib/dumper..........FAILED tests 43, 45
124Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
125
126=head2 Installing Perl on BS2000
127
128We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
129installing the documentation.
130
131
132=head2 Using Perl in the Posix-Shell of BS2000
133
134BS2000 POSIX doesn't support the shebang notation
135(C<#!/usr/local/bin/perl>), so you have to use the following lines
136instead:
137
138: # use perl
139    eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
140        if $running_under_some_shell;
141
142=head2 Using Perl in "native" BS2000
143
144We don't have much experience with this yet, but try the following:
145
146Copy your Perl executable to a BS2000 LLM using bs2cp:
147
148C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>
149
150Now you can start it with the following (SDF) command:
151
152C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>
153
154First you get the BS2000 commandline prompt ('*').  Here you may enter
155your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
156double backslash!) or C<-w> and the name of your Perl script.
157Filenames starting with C</> are searched in the Posix filesystem,
158others are searched in the BS2000 filesystem.  You may even use
159wildcards if you put a C<%> in front of your filename (e.g. C<-w
160checkfiles.pl %*.c>).  Read your C/C++ manual for additional
161possibilities of the commandline prompt (look for
162PARAMETER-PROMPTING).
163
164=head2 Floating point anomalies on BS2000
165
166There appears to be a bug in the floating point implementation on BS2000 POSIX
167systems such that calling int() on the product of a number and a small
168magnitude number is not the same as calling int() on the quotient of
169that number and a large magnitude number.  For example, in the following
170Perl code:
171
172    my $x = 100000.0;
173    my $y = int($x * 1e-5) * 1e5; # '0'
174    my $z = int($x / 1e+5) * 1e5;  # '100000'
175    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
176
177Although one would expect the quantities $y and $z to be the same and equal
178to 100000 they will differ and instead will be 0 and 100000 respectively.
179
180=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions
181
182Since version 5.8 Perl uses the new PerlIO on BS2000.  This enables
183you using different encodings per IO channel.  For example you may use
184
185    use Encode;
186    open($f, ">:encoding(ascii)", "test.ascii");
187    print $f "Hello World!\n";
188    open($f, ">:encoding(posix-bc)", "test.ebcdic");
189    print $f "Hello World!\n";
190    open($f, ">:encoding(latin1)", "test.latin1");
191    print $f "Hello World!\n";
192    open($f, ">:encoding(utf8)", "test.utf8");
193    print $f "Hello World!\n";
194
195to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
196Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
197this example identical to normal EBCDIC).  See the documentation of
198Encode::PerlIO for details.
199
200As the PerlIO layer uses raw IO internally, all this totally ignores
201the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
202environment variable.  If you want to get the old behavior, that the
203BS2000 IO functions determine conversion depending on the filesystem
204PerlIO still is your friend.  You use IO_CONVERSION as usual and tell
205Perl, that it should use the native IO layer:
206
207    export IO_CONVERSION=YES
208    export PERLIO=stdio
209
210Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
211partitions.  See the documentation of PerlIO (without C<Encode::>!)
212for further possibilities.
213
214=head1 AUTHORS
215
216Thomas Dorner
217
218=head1 SEE ALSO
219
220L<INSTALL>, L<perlport>.
221
222=head2 Mailing list
223
224If you are interested in the z/OS (formerly known as OS/390)
225and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
226To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
227
228See also:
229
230    http://lists.perl.org/list/perl-mvs.html
231
232There are web archives of the mailing list at:
233
234    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
235    http://archive.develooper.com/perl-mvs@perl.org/
236
237=head1 HISTORY
238
239This document was originally written by Thomas Dorner for the 5.005
240release of Perl.
241
242This document was podified for the 5.6 release of perl 11 July 2000.
243
244=cut
245

README.ce

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlce - Perl for WinCE
8
9=head1 Building Perl for WinCE
10
11=head2 WARNING
12
13B<< Much of this document has become very out of date and needs updating,
14rewriting or deleting. The build process was overhauled during the 5.19
15development track and the current instructions as of that time are given
16in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which
17are largely superseded but may still contain some useful information, are
18left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything
19of use has been extracted from them. >>
20
21=head2 DESCRIPTION
22
23This file gives the instructions for building Perl5.8 and above for
24WinCE.  Please read and understand the terms under which this
25software is distributed.
26
27=head2 General explanations on cross-compiling WinCE
28
29=over
30
31=item *
32
33F<miniperl> is built. This is a single executable (without DLL), intended
34to run on Win32, and it will facilitate remaining build process; all binaries
35built after it are foreign and should not run locally.
36
37F<miniperl> is built using F<./win32/Makefile>; this is part of normal
38build process invoked as dependency from wince/Makefile.ce
39
40=item *
41
42After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm>
43in right place and its corresponding Cross.pm.
44
45Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach;
46it rather will use F<Config.pm> from within cross-compilation directories.
47
48File F<Cross.pm> is dead simple: for given cross-architecture places in @INC
49a path where perl modules are, and right F<Config.pm> in that place.
50
51That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
52it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm>
53is substituted, and resulting binaries will be a mess.
54
55C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
56F<Config.pm> for further compilations.
57
58=item *
59
60During extensions build phase, a script F<./win32/buldext.pl> is invoked,
61which in turn steps in F<./ext> subdirectories and performs a build of
62each extension in turn.
63
64All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross-
65compile.
66
67=back
68
69=head2 CURRENT BUILD INSTRUCTIONS
70
71(These instructions assume the host is 32-bit Windows. If you're on 64-bit
72Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.)
73
741. Install EVC4 from
75
76 http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe
77
78Use the key mentioned at 
79
80 http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc
81
82The installer is ancient and has a few bugs on the paths it uses. You 
83will have to fix them later. Basically, some things go into "C:/Program 
84Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless 
85of the path you gave to the installer (the default will be "C:/Windows 
86CE Tools"). Reboots will be required for the installer to proceed. Also 
87.c and .h associations with Visual Studio might get overridden when 
88installing EVC4. You have been warned.
89
902. Download celib from GitHub (using "Download ZIP") at
91
92    https://github.com/bulk88/celib 
93
94Extract it to a spaceless path but not into the perl build source.
95I call this directory "celib-palm-3.0" but in the GitHub 
96snapshot it will be called "celib-master". Make a copy of the 
97"wince-arm-pocket-wce300-release" folder and rename the copy to 
98"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 
99binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 
100Mobile/WinCE are backwards compatible with machine code like Desktop Windows.
101
1023. Download console-1.3-src.tar.gz from 
103
104 http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/
105
106Extract it to a spaceless path but not into the perl build source. 
107Don't extract it into the same directory as celib. Make a copy of the 
108"wince-arm-pocket-wce300" folder and rename the copy to 
109"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 
110binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 
111Mobile/WinCE are backwards compatible with machine code like Desktop Windows.
112
1134. Open a command prompt, run your regular batch file to set the environment
114for desktop Visual C building, goto the perl source directory, cd into win32/,
115fill out Makefile, and do a "nmake all" to build a Desktop Perl.
116
1175. Open win32/Makefile.ce in a text editor and do something similar to the 
118following patch.
119
120    -CELIBDLLDIR  = h:\src\wince\celib-palm-3.0
121    -CECONSOLEDIR = h:\src\wince\w32console
122    +CELIBDLLDIR  = C:\sources\celib-palm-3.0
123    +CECONSOLEDIR = C:\sources\w32console
124
125Also change
126
127    !if "$(MACHINE)" == ""
128    MACHINE=wince-arm-hpc-wce300
129    #MACHINE=wince-arm-hpc-wce211
130    #MACHINE=wince-sh3-hpc-wce211
131    #MACHINE=wince-mips-hpc-wce211
132    #MACHINE=wince-sh3-hpc-wce200
133    #MACHINE=wince-mips-hpc-wce200
134    #MACHINE=wince-arm-pocket-wce300
135    #MACHINE=wince-mips-pocket-wce300
136    #MACHINE=wince-sh3-pocket-wce300
137    #MACHINE=wince-x86em-pocket-wce300
138    #MACHINE=wince-mips-palm-wce211
139    #MACHINE=wince-sh3-palm-wce211
140    #MACHINE=wince-x86em-palm-wce211
141    #MACHINE=wince-x86-hpc-wce300
142    #MACHINE=wince-arm-pocket-wce400
143    !endif
144
145to
146
147    !if "$(MACHINE)" == ""
148    #MACHINE=wince-arm-hpc-wce300
149    #MACHINE=wince-arm-hpc-wce211
150    #MACHINE=wince-sh3-hpc-wce211
151    #MACHINE=wince-mips-hpc-wce211
152    #MACHINE=wince-sh3-hpc-wce200
153    #MACHINE=wince-mips-hpc-wce200
154    #MACHINE=wince-arm-pocket-wce300
155    #MACHINE=wince-mips-pocket-wce300
156    #MACHINE=wince-sh3-pocket-wce300
157    #MACHINE=wince-x86em-pocket-wce300
158    #MACHINE=wince-mips-palm-wce211
159    #MACHINE=wince-sh3-palm-wce211
160    #MACHINE=wince-x86em-palm-wce211
161    #MACHINE=wince-x86-hpc-wce300
162    MACHINE=wince-arm-pocket-wce400
163    !endif
164
165so wince-arm-pocket-wce400 is the MACHINE type.
166
1676. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++ 
1684.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for
169
170    if "%SDKROOT%"=="" set SDKROOT=...
171
172On a new install it is "C:\Windows CE Tools". Goto 
173"C:\Windows CE Tools" in a file manager and see if "C:\Windows CE 
174Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not
175the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools".
176
177Goto celib-palm-3.0\inc\cewin32.h, search for
178
179    typedef struct _ABC {
180
181and uncomment the struct.
182
1837. Open another command prompt, ensure PLATFORM is not set to anything
184already unless you know what you're doing (so that the correct default
185value is set by the next command), and run "C:\Program Files\Microsoft
186eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT"
187
1888. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl 
189source directory, cd into win32/ and run "nmake -f Makefile.ce".
190
1919. The ARM perl interpreter (perl519.dll and perl.exe) will be in something
192like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in
193"C:\perl519\src\xlib\wince-arm-hpc-wce400\auto".
194
195To prove success on the host machine, run
196"dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder
197and look for "machine (ARM)" in the FILE HEADER VALUES and
198"subsystem (Windows CE GUI)" in the OPTIONAL HEADER VALUES.
199
200=head2 OLD BUILD INSTRUCTIONS
201
202This section describes the steps to be performed to build PerlCE.
203You may find additional information about building perl for WinCE
204at L<http://perlce.sourceforge.net> and some pre-built binaries.
205
206=head3 Tools & SDK
207
208For compiling, you need following:
209
210=over 4
211
212=item * Microsoft Embedded Visual Tools
213
214=item * Microsoft Visual C++
215
216=item * Rainer Keuchel's celib-sources
217
218=item * Rainer Keuchel's console-sources
219
220=back
221
222Needed source files can be downloaded at
223L<http://perlce.sourceforge.net>
224
225=head3 Make
226
227Normally you only need to edit F<./win32/ce-helpers/compile.bat>
228to reflect your system and run it.
229
230File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call
231C<nmake -f makefile.ce> with appropriate parameters and it accepts extra
232parameters and forwards them to C<nmake> command as additional
233arguments. You should pass target this way.
234
235To prepare distribution you need to do following:
236
237=over 4
238
239=item * go to F<./win32> subdirectory
240
241=item * edit file F<./win32/ce-helpers/compile.bat>
242
243=item * run 
244  compile.bat
245
246=item * run 
247  compile.bat dist
248
249=back
250
251F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to
252your cross-compilation scheme. You could assign a name to it, but this
253is not necessary, because by default it is assigned after your machine
254configuration name, such as "wince-sh3-hpc-wce211", and this is enough
255to distinguish different builds at the same time. This option could be
256handy for several different builds on same platform to perform, say,
257threaded build. In a following example we assume that all required
258environment variables are set properly for C cross-compiler (a special
259*.bat file could fit perfectly to this purpose) and your F<compile.bat>
260has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>.
261
262  compile.bat
263  compile.bat dist
264  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
265    "USE_IMP_SYS=define" "USE_MULTI=define"
266  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
267    "USE_IMP_SYS=define" "USE_MULTI=define" dist
268
269If all goes okay and no errors during a build, you'll get two independent
270distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>.
271
272Target C<dist> prepares distribution file set. Target C<zipdist> performs
273same as C<dist> but additionally compresses distribution files into zip
274archive.
275
276NOTE: during a build there could be created a number (or one) of F<Config.pm>
277for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside
278F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to
279note, there should be B<no> F<Config.pm> for host miniperl.
280If you'll get an error that perl could not find Config.pm somewhere in building
281process this means something went wrong. Most probably you forgot to
282specify a cross-compilation when invoking miniperl.exe to Makefile.PL
283When building an extension for cross-compilation your command line should
284look like
285
286  ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
287
288or just
289
290  ..\miniperl.exe -I..\lib -MCross Makefile.PL
291
292to refer a cross-compilation that was created last time.
293
294All questions related to building for WinCE devices could be asked in
295F<perlce-user@lists.sourceforge.net> mailing list.
296
297=head1 Using Perl on WinCE
298
299=head2 DESCRIPTION
300
301PerlCE is currently linked with a simple console window, so it also
302works on non-hpc devices.
303
304The simple stdio implementation creates the files F<stdin.txt>,
305F<stdout.txt> and F<stderr.txt>, so you might examine them if your
306console has only a limited number of cols.
307
308When exitcode is non-zero, a message box appears, otherwise the
309console closes, so you might have to catch an exit with
310status 0 in your program to see any output.
311
312stdout/stderr now go into the files F</perl-stdout.txt> and
313F</perl-stderr.txt.>
314
315PerlIDE is handy to deal with perlce.
316
317=head2 LIMITATIONS
318
319No fork(), pipe(), popen() etc.
320
321=head2 ENVIRONMENT
322
323All environment vars must be stored in HKLM\Environment as
324strings. They are read at process startup.
325
326=over
327
328=item PERL5LIB
329
330Usual perl lib path (semi-list).
331
332=item PATH
333
334Semi-list for executables.
335
336=item TMP
337
338- Tempdir.
339
340=item UNIXROOTPATH
341
342- Root for accessing some special files, i.e. F</dev/null>, F</etc/services>.
343
344=item ROWS/COLS
345
346- Rows/cols for console.
347
348=item HOME
349
350- Home directory.
351
352=item CONSOLEFONTSIZE
353
354- Size for console font.
355
356=back
357
358You can set these with cereg.exe, a (remote) registry editor
359or via the PerlIDE.
360
361=head2 REGISTRY
362
363To start perl by clicking on a perl source file, you have
364to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>).
365cereg.exe (which must be executed on a desktop pc with
366ActiveSync) is reported not to work on some devices.
367You have to create the registry entries by hand using a 
368registry editor.
369
370=head2 XS
371
372The following Win32-Methods are built-in:
373
374	newXS("Win32::GetCwd", w32_GetCwd, file);
375	newXS("Win32::SetCwd", w32_SetCwd, file);
376	newXS("Win32::GetTickCount", w32_GetTickCount, file);
377	newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
378	newXS("Win32::IsWinNT", w32_IsWinNT, file);
379	newXS("Win32::IsWin95", w32_IsWin95, file);
380	newXS("Win32::IsWinCE", w32_IsWinCE, file);
381	newXS("Win32::CopyFile", w32_CopyFile, file);
382	newXS("Win32::Sleep", w32_Sleep, file);
383	newXS("Win32::MessageBox", w32_MessageBox, file);
384	newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
385	newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
386	newXS("Win32::ShellEx", w32_ShellEx, file);
387
388=head2 BUGS
389
390Opening files for read-write is currently not supported if
391they use stdio (normal perl file handles).
392
393If you find bugs or if it does not work at all on your
394device, send mail to the address below. Please report
395the details of your device (processor, ceversion, 
396devicetype (hpc/palm/pocket)) and the date of the downloaded
397files. 
398
399=head2 INSTALLATION
400
401Currently installation instructions are at L<http://perlce.sourceforge.net/>.
402
403After installation & testing processes will stabilize, information will
404be more precise.
405
406=head1 ACKNOWLEDGEMENTS
407
408The port for Win32 was used as a reference.
409
410=head1 History of WinCE port
411
412=over
413
414=item 5.6.0
415
416Initial port of perl to WinCE. It was performed in separate directory
417named F<wince>. This port was based on contents of F<./win32> directory.
418F<miniperl> was not built, user must have HOST perl and properly edit
419F<makefile.ce> to reflect this.
420
421=item 5.8.0
422
423wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce>
424was used to invoke native compiler to create HOST miniperl, which then
425facilitates cross-compiling process.
426Extension building support was added.
427
428=item 5.9.4
429
430Two directories F<./win32> and F<./wince> were merged, so perlce build
431process comes in F<./win32> directory.
432
433=back
434
435=head1 AUTHORS
436
437=over
438
439=item Rainer Keuchel <coyxc@rainer-keuchel.de>
440
441provided initial port of Perl, which appears to be most essential work, as
442it was a breakthrough on having Perl ported at all.
443Many thanks and obligations to Rainer!
444
445=item Vadim Konovalov
446
447made further support of WinCE port.
448
449=item Daniel Dragan
450
451updated the build process during the 5.19 development track.
452
453=back
454

README.cn

1=encoding utf8
2
3如果你用一般的文字编辑器阅览这份文件, 请忽略文中奇特的注记字符.
4这份文件是以 POD (简明文件格式) 写成; 这种格式是为了能让人直接阅读,
5而特别设计的. 关于此格式的进一步信息, 请参考 perlpod 线上文件.
6
7=head1 NAME
8
9perlcn - 简体中文 Perl 指南
10
11=head1 DESCRIPTION
12
13欢迎来到 Perl 的天地!
14
15从 5.8.0 版开始, Perl 具备了完善的 Unicode (统一码) 支援,
16也连带支援了许多拉丁语系以外的编码方式; CJK (中日韩) 便是其中的一部份.
17Unicode 是国际性的标准, 试图涵盖世界上所有的字符: 西方世界, 东方世界,
18以及两者间的一切 (希腊文, 叙利亚文, 亚拉伯文, 希伯来文, 印度文,
19印地安文, 等等). 它也容纳了多种作业系统与平台 (如 PC 及麦金塔).
20
21Perl 本身以 Unicode 进行操作. 这表示 Perl 内部的字符串数据可用 Unicode
22表示; Perl 的函式与算符 (例如正规表示式比对) 也能对 Unicode 进行操作.
23在输入及输出时, 为了处理以 Unicode 之前的编码方式存放的数据, Perl
24提供了 Encode 这个模块, 可以让你轻易地读取及写入旧有的编码数据.
25
26Encode 延伸模块支援下列简体中文的编码方式 ('gb2312' 表示 'euc-cn'):
27
28    euc-cn	Unix 延伸字符集, 也就是俗称的国标码
29    gb2312-raw	未经处理的 (低比特) GB2312 字符表
30    gb12345	未经处理的中国用繁体中文编码
31    iso-ir-165	GB2312 + GB6345 + GB8565 + 新增字符
32    cp936	字码页 936, 也可以用 'GBK' (扩充国标码) 指明
33    hz		7 比特逸出式 GB2312 编码
34
35举例来说, 将 EUC-CN 编码的档案转成 Unicode, 祗需键入下列指令:
36
37    perl -Mencoding=euc-cn,STDOUT,utf8 -pe1 < file.euc-cn > file.utf8
38
39Perl 也内附了 "piconv", 一支完全以 Perl 写成的字符转换工具程序, 用法如下:
40
41    piconv -f euc-cn -t utf8 < file.euc-cn > file.utf8
42    piconv -f utf8 -t euc-cn < file.utf8 > file.euc-cn
43
44另外, 利用 encoding 模块, 你可以轻易写出以字符为单位的程序码, 如下所示:
45
46    #!/usr/bin/env perl
47    # 启动 euc-cn 字串解析; 标准输出入及标准错误都设为 euc-cn 编码
48    use encoding 'euc-cn', STDIN => 'euc-cn', STDOUT => 'euc-cn';
49    print length("骆驼");	     #  2 (双引号表示字符)
50    print length('骆驼');	     #  4 (单引号表示字节)
51    print index("谆谆教诲", "蛔唤"); # -1 (不包含此子字符串)
52    print index('谆谆教诲', '蛔唤'); #  1 (从第二个字节开始)
53
54在最后一列例子里, "谆" 的第二个字节与 "谆" 的第一个字节结合成 EUC-CN
55码的 "蛔"; "谆" 的第二个字节则与 "教" 的第一个字节结合成 "唤".
56这解决了以前 EUC-CN 码比对处理上常见的问题.
57
58=head2 额外的中文编码
59
60如果需要更多的中文编码, 可以从 CPAN (L<http://www.cpan.org/>) 下载
61Encode::HanExtra 模块. 它目前提供下列编码方式:
62
63    gb18030	扩充过的国标码, 包含繁体中文
64
65另外, Encode::HanConvert 模块则提供了简繁转换用的两种编码:
66
67    big5-simp	Big5 繁体中文与 Unicode 简体中文互转
68    gbk-trad	GBK 简体中文与 Unicode 繁体中文互转
69
70若想在 GBK 与 Big5 之间互转, 请参考该模块内附的 b2g.plg2b.pl 两支程序,
71或在程序内使用下列写法:
72
73    use Encode::HanConvert;
74    $euc_cn = big5_to_gb($big5); # 从 Big5 转为 GBK
75    $big5 = gb_to_big5($euc_cn); # 从 GBK 转为 Big5
76
77=head2 进一步的信息
78
79请参考 Perl 内附的大量说明文件 (不幸全是用英文写的), 来学习更多关于
80Perl 的知识, 以及 Unicode 的使用方式. 不过, 外部的资源相当丰富:
81
82=head2 提供 Perl 资源的网址
83
84=over 4
85
86=item L<http://www.perl.com/>
87
88Perl 的首页 (由欧莱礼公司维护)
89
90=item L<http://www.cpan.org/>
91
92Perl 综合典藏网 (Comprehensive Perl Archive Network)
93
94=item L<http://lists.perl.org/>
95
96Perl 邮递论坛一览
97
98=back
99
100=head2 学习 Perl 的网址
101
102=over 4
103
104=item L<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>
105
106简体中文版的欧莱礼 Perl 书藉
107
108=back
109
110=head2 Perl 使用者集会
111
112=over 4
113
114=item L<http://www.pm.org/groups/asia.html>
115
116中国 Perl 推广组一览
117
118=back
119
120=head2 Unicode 相关网址
121
122=over 4
123
124=item L<http://www.unicode.org/>
125
126Unicode 学术学会 (Unicode 标准的制定者)
127
128=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
129
130Unix/Linux 上的 UTF-8 及 Unicode 答客问
131
132=back
133
134=head1 SEE ALSO
135
136L<Encode>, L<Encode::CN>, L<encoding>, L<perluniintro>, L<perlunicode>
137
138=head1 AUTHORS
139
140Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
141
142Audrey Tang (唐凤) E<lt>audreyt@audreyt.orgE<gt>
143
144=cut
145

README.cygwin

1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see F<pod/perlpod.pod>) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlcygwin - Perl for Cygwin
8
9=head1 SYNOPSIS
10
11This document will help you configure, make, test and install Perl
12on Cygwin.  This document also describes features of Cygwin that will
13affect how Perl behaves at runtime.
14
15B<NOTE:> There are pre-built Perl packages available for Cygwin and a
16version of Perl is provided in the normal Cygwin install.  If you do
17not need to customize the configuration, consider using one of those
18packages.
19
20
21=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN
22
23=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
24
25The Cygwin tools are ports of the popular GNU development tools for Win32
26platforms.  They run thanks to the Cygwin library which provides the UNIX
27system calls and environment these programs expect.  More information
28about this project can be found at:
29
30L<http://www.cygwin.com/>
31
32A recent net or commercial release of Cygwin is required.
33
34At the time this document was last updated, Cygwin 1.7.16 was current.
35
36
37=head2 Cygwin Configuration
38
39While building Perl some changes may be necessary to your Cygwin setup so
40that Perl builds cleanly.  These changes are B<not> required for normal
41Perl usage.
42
43B<NOTE:> The binaries that are built will run on all Win32 versions.
44They do not depend on your host system (WinXP/Win2K/Win7) or your
45Cygwin configuration (binary/text mounts, cvgserver).
46The only dependencies come from hard-coded pathnames like F</usr/local>.
47However, your host system and Cygwin configuration will affect Perl's
48runtime behavior (see L</"TEST">).
49
50=over 4
51
52=item * C<PATH>
53
54Set the C<PATH> environment variable so that Configure finds the Cygwin
55versions of programs. Any not-needed Windows directories should be removed or
56moved to the end of your C<PATH>.
57
58=item * I<nroff>
59
60If you do not have I<nroff> (which is part of the I<groff> package),
61Configure will B<not> prompt you to install I<man> pages.
62
63=back
64
65=head1 CONFIGURE PERL ON CYGWIN
66
67The default options gathered by Configure with the assistance of
68F<hints/cygwin.sh> will build a Perl that supports dynamic loading
69(which requires a shared F<cygperl5_16.dll>).
70
71This will run Configure and keep a record:
72
73  ./Configure 2>&1 | tee log.configure
74
75If you are willing to accept all the defaults run Configure with B<-de>.
76However, several useful customizations are available.
77
78=head2 Stripping Perl Binaries on Cygwin
79
80It is possible to strip the EXEs and DLLs created by the build process.
81The resulting binaries will be significantly smaller.  If you want the
82binaries to be stripped, you can either add a B<-s> option when Configure
83prompts you,
84
85  Any additional ld flags (NOT including libraries)? [none] -s
86  Any special flags to pass to g++ to create a dynamically loaded library?
87  [none] -s
88  Any special flags to pass to gcc to use dynamic linking? [none] -s
89
90or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
91near the end of the file.
92
93=head2 Optional Libraries for Perl on Cygwin
94
95Several Perl functions and modules depend on the existence of
96some optional libraries.  Configure will find them if they are
97installed in one of the directories listed as being used for library
98searches.  Pre-built packages for most of these are available from
99the Cygwin installer.
100
101=over 4
102
103=item * C<-lcrypt>
104
105The crypt package distributed with Cygwin is a Linux compatible 56-bit
106DES crypt port by Corinna Vinschen.
107
108Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
109
110=item * C<-lgdbm_compat> (C<use GDBM_File>)
111
112GDBM is available for Cygwin.
113
114NOTE: The GDBM library only works on NTFS partitions.
115
116=item * C<-ldb> (C<use DB_File>)
117
118BerkeleyDB is available for Cygwin.
119
120NOTE: The BerkeleyDB library only completely works on NTFS partitions.
121
122=item * C<cygserver> (C<use IPC::SysV>)
123
124A port of SysV IPC is available for Cygwin.
125
126NOTE: This has B<not> been extensively tested.  In particular,
127C<d_semctl_semun> is undefined because it fails a Configure test
128and on Win9x the I<shm*()> functions seem to hang.  It also creates
129a compile time dependency because F<perl.h> includes F<<sys/ipc.h>>
130and F<<sys/sem.h>> (which will be required in the future when compiling
131CPAN modules). CURRENTLY NOT SUPPORTED!
132
133=item * C<-lutil>
134
135Included with the standard Cygwin netrelease is the inetutils package
136which includes libutil.a.
137
138=back
139
140=head2 Configure-time Options for Perl on Cygwin
141
142The F<INSTALL> document describes several Configure-time options.  Some of
143these will work with Cygwin, others are not yet possible.  Also, some of
144these are experimental.  You can either select an option when Configure
145prompts you or you can define (undefine) symbols on the command line.
146
147=over 4
148
149=item * C<-Uusedl>
150
151Undefining this symbol forces Perl to be compiled statically.
152
153=item * C<-Dusemymalloc>
154
155By default Perl does not use the C<malloc()> included with the Perl source,
156because it was slower and not entirely thread-safe.  If you want to force
157Perl to build with the old -Dusemymalloc define this.
158
159=item * C<-Uuseperlio>
160
161Undefining this symbol disables the PerlIO abstraction.  PerlIO is now the
162default; it is not recommended to disable PerlIO.
163
164=item * C<-Dusemultiplicity>
165
166Multiplicity is required when embedding Perl in a C program and using
167more than one interpreter instance.  This is only required when you build
168a not-threaded perl with C<-Uuseithreads>.
169
170=item * C<-Uuse64bitint>
171
172By default Perl uses 64 bit integers.  If you want to use smaller 32 bit
173integers, define this symbol.
174
175=item * C<-Duselongdouble>
176
177I<gcc> supports long doubles (12 bytes).  However, several additional
178long double math functions are necessary to use them within Perl
179(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
180strtold>).
181These are B<not> yet available with newlib, the Cygwin libc.
182
183=item * C<-Uuseithreads>
184
185Define this symbol if you want not-threaded faster perl.
186
187=item * C<-Duselargefiles>
188
189Cygwin uses 64-bit integers for internal size and position calculations,
190this will be correctly detected and defined by Configure.
191
192=item * C<-Dmksymlinks>
193
194Use this to build perl outside of the source tree.  Details can be
195found in the F<INSTALL> document.  This is the recommended way to
196build perl from sources.
197
198=back
199
200=head2 Suspicious Warnings on Cygwin
201
202You may see some messages during Configure that seem suspicious.
203
204=over 4
205
206=item * Win9x and C<d_eofnblk>
207
208Win9x does not correctly report C<EOF> with a non-blocking read on a
209closed pipe.  You will see the following messages:
210
211  But it also returns -1 to signal EOF, so be careful!
212  WARNING: you can't distinguish between EOF and no data!
213
214  *** WHOA THERE!!! ***
215      The recommended value for $d_eofnblk on this machine was "define"!
216      Keep the recommended value? [y]
217
218At least for consistency with WinNT, you should keep the recommended
219value.
220
221=item * Compiler/Preprocessor defines
222
223The following error occurs because of the Cygwin C<#define> of
224C<_LONG_DOUBLE>:
225
226  Guessing which symbols your C compiler and preprocessor define...
227  try.c:<line#>: missing binary operator
228
229This failure does not seem to cause any problems.  With older gcc
230versions, "parse error" is reported instead of "missing binary
231operator".
232
233=back
234
235=head1 MAKE ON CYGWIN
236
237Simply run I<make> and wait:
238
239  make 2>&1 | tee log.make
240
241=head1 TEST ON CYGWIN
242
243There are two steps to running the test suite:
244
245  make test 2>&1 | tee log.make-test
246
247  cd t; ./perl harness 2>&1 | tee ../log.harness
248
249The same tests are run both times, but more information is provided when
250running as C<./perl harness>.
251
252Test results vary depending on your host system and your Cygwin
253configuration.  If a test can pass in some Cygwin setup, it is always
254attempted and explainable test failures are documented.  It is possible
255for Perl to pass all the tests, but it is more likely that some tests
256will fail for one of the reasons listed below.
257
258=head2 File Permissions on Cygwin
259
260UNIX file permissions are based on sets of mode bits for
261{read,write,execute} for each {user,group,other}.  By default Cygwin
262only tracks the Win32 read-only attribute represented as the UNIX file
263user write bit (files are always readable, files are executable if they
264have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are
265always readable and executable).  On WinNT with the I<ntea> C<CYGWIN>
266setting, the additional mode bits are stored as extended file attributes.
267On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the
268standard WinNT security descriptors and access control lists. Without one of
269these options, these tests will fail (listing not updated yet):
270
271  Failed Test           List of failed
272  ------------------------------------
273  io/fs.t               5, 7, 9-10
274  lib/anydbm.t          2
275  lib/db-btree.t        20
276  lib/db-hash.t         16
277  lib/db-recno.t        18
278  lib/gdbm.t            2
279  lib/ndbm.t            2
280  lib/odbm.t            2
281  lib/sdbm.t            2
282  op/stat.t             9, 20 (.tmp not an executable extension)
283
284=head2 NDBM_File and ODBM_File do not work on FAT filesystems
285
286Do not use NDBM_File or ODBM_File on FAT filesystem.  They can be
287built on a FAT filesystem, but many tests will fail:
288
289 ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1-2 4 16-71
290 ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
291 ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
292 ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7-11
293 ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1-4
294 run/fresh_perl.t                          97    1   1.03%  91
295
296If you intend to run only on FAT (or if using AnyDBM_File on FAT),
297run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
298NDBM_File and ODBM_File being built.
299
300With NTFS (and no CYGWIN=nontsec), there should be no problems even if
301perl was built on FAT.
302
303=head2 C<fork()> failures in io_* tests
304
305A C<fork()> failure may result in the following tests failing:
306
307  ext/IO/lib/IO/t/io_multihomed.t
308  ext/IO/lib/IO/t/io_sock.t
309  ext/IO/lib/IO/t/io_unix.t
310
311See comment on fork in L</Miscellaneous> below.
312
313=head1 Specific features of the Cygwin port
314
315=head2 Script Portability on Cygwin
316
317Cygwin does an outstanding job of providing UNIX-like semantics on top of
318Win32 systems.  However, in addition to the items noted above, there are
319some differences that you should know about.  This is a very brief guide
320to portability, more information can be found in the Cygwin documentation.
321
322=over 4
323
324=item * Pathnames
325
326Cygwin pathnames are separated by forward (F</>) slashes, Universal
327Naming Codes (F<//UNC>) are also supported Since cygwin-1.7 non-POSIX
328pathnames are discouraged.  Names may contain all printable
329characters.
330
331File names are case insensitive, but case preserving.  A pathname that
332contains a backslash or drive letter is a Win32 pathname, and not
333subject to the translations applied to POSIX style pathnames, but
334cygwin will warn you, so better convert them to POSIX.
335
336For conversion we have C<Cygwin::win_to_posix_path()> and
337C<Cygwin::posix_to_win_path()>.
338
339Since cygwin-1.7 pathnames are UTF-8 encoded.
340
341=item * Text/Binary
342
343Since cygwin-1.7 textmounts are deprecated and strongly discouraged.
344
345When a file is opened it is in either text or binary mode.  In text mode
346a file is subject to CR/LF/Ctrl-Z translations.  With Cygwin, the default
347mode for an C<open()> is determined by the mode of the mount that underlies
348the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function
349to set binary mode on files that otherwise would be treated as text.
350C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise
351would be treated as binary:
352
353    sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
354
355C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
356mode.
357
358The text/binary issue is covered at length in the Cygwin documentation.
359
360=item * PerlIO
361
362PerlIO overrides the default Cygwin Text/Binary behaviour.  A file will
363always be treated as binary, regardless of the mode of the mount it lives
364on, just like it is in UNIX.  So CR/LF translation needs to be requested in
365either the C<open()> call like this:
366
367  open(FH, ">:crlf", "out.txt");
368
369which will do conversion from LF to CR/LF on the output, or in the
370environment settings (add this to your .bashrc):
371
372  export PERLIO=crlf
373
374which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
375on every output generated by perl.
376
377=item * F<.exe>
378
379The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe>
380extension transparent by looking for F<foo.exe> when you ask for F<foo>
381(unless a F<foo> also exists).  Cygwin does not require a F<.exe>
382extension, but I<gcc> adds it automatically when building a program.
383However, when accessing an executable as a normal file (e.g., I<cp>
384in a makefile) the F<.exe> is not transparent.  The I<install> program
385included with Cygwin automatically appends a F<.exe> when necessary.
386
387=item * Cygwin vs. Windows process ids
388
389Cygwin processes have their own pid, which is different from the
390underlying windows pid.  Most posix compliant Proc functions expect
391the cygwin pid, but several Win32::Process functions expect the
392winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
393the winpid.  Use C<Cygwin::pid_to_winpid()> and C<Cygwin::winpid_to_pid()>
394to translate between them.
395
396=item * Cygwin vs. Windows errors
397
398Under Cygwin, $^E is the same as $!.  When using L<Win32 API Functions|Win32>,
399use C<Win32::GetLastError()> to get the last Windows error.
400
401=item * rebase errors on fork or system
402
403Using C<fork()> or C<system()> out to another perl after loading multiple dlls
404may result on a DLL baseaddress conflict. The internal cygwin error
405looks like like the following:
406
407  0 [main] perl 8916 child_info_fork::abort: data segment start: parent
408  (0xC1A000) != child(0xA6A000)
409
410or:
411
412  183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error - unable to remap
413  C:\cygwin\bin\cygsvn_subr-1-0.dll to same address as parent(0x6FB30000) != 0x6FE60000
414  46 [main] perl 3488 fork: child 3588 - died waiting for dll loading, errno11
415
416See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures>
417It helps if not too many DLLs are loaded in memory so the available address space is larger,
418e.g. stopping the MS Internet Explorer might help.
419
420Use the perlrebase or rebase utilities to resolve the conflicting dll addresses.
421The rebase package is included in the Cygwin setup. Use F<setup.exe>
422from L<http://www.cygwin.com/setup.exe> to install it.
423
4241. kill all perl processes and run C<perlrebase> or
425
4262. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>.
427
428=item * C<chown()>
429
430On WinNT C<chown()> can change a file's user and group IDs.  On Win9x C<chown()>
431is a no-op, although this is appropriate since there is no security model.
432
433=item * Miscellaneous
434
435File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
436returns C<ENOSYS>.
437
438Win9x can not C<rename()> an open file (although WinNT can).
439
440The Cygwin C<chroot()> implementation has holes (it can not restrict file
441access by native Win32 programs).
442
443Inplace editing C<perl -i> of files doesn't work without doing a backup
444of the file being edited C<perl -i.bak> because of windowish restrictions,
445therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
446without specifying a backup extension.
447
448=back
449
450=head2 Prebuilt methods:
451
452=over 4
453
454=item C<Cwd::cwd>
455
456Returns the current working directory.
457
458=item C<Cygwin::pid_to_winpid>
459
460Translates a cygwin pid to the corresponding Windows pid (which may or
461may not be the same).
462
463=item C<Cygwin::winpid_to_pid>
464
465Translates a Windows pid to the corresponding cygwin pid (if any).
466
467=item C<Cygwin::win_to_posix_path>
468
469Translates a Windows path to the corresponding cygwin path respecting
470the current mount points. With a second non-null argument returns an
471absolute path. Double-byte characters will not be translated.
472
473=item C<Cygwin::posix_to_win_path>
474
475Translates a cygwin path to the corresponding cygwin path respecting
476the current mount points. With a second non-null argument returns an
477absolute path. Double-byte characters will not be translated.
478
479=item C<Cygwin::mount_table()>
480
481Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
482
483  perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
484  /bin c:\cygwin\bin system binmode,cygexec
485  /usr/bin c:\cygwin\bin system binmode
486  /usr/lib c:\cygwin\lib system binmode
487  / c:\cygwin system binmode
488  /cygdrive/c c: system binmode,noumount
489  /cygdrive/d d: system binmode,noumount
490  /cygdrive/e e: system binmode,noumount
491
492=item C<Cygwin::mount_flags>
493
494Returns the mount type and flags for a specified mount point.
495A comma-separated string of mntent->mnt_type (always
496"system" or "user"), then the mntent->mnt_opts, where
497the first is always "binmode" or "textmode".
498
499  system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
500  notexec,managed,nosuid,devfs,proc,noumount
501
502If the argument is "/cygdrive", then just the volume mount settings,
503and the cygdrive mount prefix are returned.
504
505User mounts override system mounts.
506
507  $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
508  system,binmode,cygexec
509  $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
510  binmode,cygdrive,/cygdrive
511
512=item C<Cygwin::is_binmount>
513
514Returns true if the given cygwin path is binary mounted, false if the
515path is mounted in textmode.
516
517=item C<Cygwin::sync_winenv>
518
519Cygwin does not initialize all original Win32 environment variables.
520See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html>
521for "Restricted Win32 environment".
522
523Certain Win32 programs called from cygwin programs might need some environment
524variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
525Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
526process and note that cygwin will warn on every encounter of non-POSIX paths.
527
528=back
529
530=head1 INSTALL PERL ON CYGWIN
531
532This will install Perl, including I<man> pages.
533
534  make install 2>&1 | tee log.make-install
535
536NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
537you to install I<perl> into F</usr/bin>.
538
539You may need to be I<Administrator> to run C<make install>.  If you
540are not, you must have write access to the directories in question.
541
542Information on installing the Perl documentation in HTML format can be
543found in the F<INSTALL> document.
544
545=head1 MANIFEST ON CYGWIN
546
547These are the files in the Perl release that contain references to Cygwin.
548These very brief notes attempt to explain the reason for all conditional
549code.  Hopefully, keeping this up to date will allow the Cygwin port to
550be kept as clean as possible.
551
552=over 4
553
554=item Documentation
555
556 INSTALL README.cygwin README.win32 MANIFEST
557 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
558 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
559 pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
560 pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
561 pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
562 pod/perltoc.pod Porting/Glossary pod/perlgit.pod
563 Porting/checkAUTHORS.pl
564 dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
565 ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
566 ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
567 ext/Time-HiRes/Changes ext/Win32API-File/Changes
568 lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
569 lib/ExtUtils/PATCHING lib/ExtUtils/README
570 lib/Net/Ping/Changes lib/Test/Harness/Changes
571 lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
572 symbian/TODO
573
574=item Build, Configure, Make, Install
575
576 cygwin/Makefile.SHs
577 ext/IPC/SysV/hints/cygwin.pl
578 ext/NDBM_File/hints/cygwin.pl
579 ext/ODBM_File/hints/cygwin.pl
580 hints/cygwin.sh
581 Configure             - help finding hints from uname,
582                         shared libperl required for dynamic loading
583 Makefile.SH Cross/Makefile-cross-SH
584                       - linklibperl
585 Porting/patchls       - cygwin in port list
586 installman            - man pages with :: translated to .
587 installperl           - install dll, install to 'pods'
588 makedepend.SH         - uwinfix
589 regen_lib.pl          - file permissions
590
591 NetWare/Makefile
592 plan9/mkfile
593 symbian/sanity.pl symbian/sisify.pl
594 hints/uwin.sh
595 vms/descrip_mms.template
596 win32/Makefile win32/makefile.mk
597
598=item Tests
599
600 t/io/fs.t             - no file mode checks if not ntsec
601                         skip rename() check when not check_case:relaxed
602 t/io/tell.t           - binmode
603 t/lib/cygwin.t        - builtin cygwin function tests
604 t/op/groups.t         - basegroup has ID = 0
605 t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
606 t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
607                         (cache manager sometimes preserves ctime of file
608                         previously created and deleted), no -u (setuid)
609 t/op/taint.t          - can't use empty path under Cygwin Perl
610 t/op/time.t           - no tzset()
611
612=item Compiled Perl Source
613
614 EXTERN.h              - __declspec(dllimport)
615 XSUB.h                - __declspec(dllexport)
616 cygwin/cygwin.c       - os_extras (getcwd, spawn, and several Cygwin:: functions)
617 perl.c                - os_extras, -i.bak
618 perl.h                - binmode
619 doio.c                - win9x can not rename a file when it is open
620 pp_sys.c              - do not define h_errno, init _pwent_struct.pw_comment
621 util.c                - use setenv
622 util.h                - PERL_FILE_IS_ABSOLUTE macro
623 pp.c                  - Comment about Posix vs IEEE math under Cygwin
624 perlio.c              - CR/LF mode
625 perliol.c             - Comment about EXTCONST under Cygwin
626
627=item Compiled Module Source
628
629 ext/Compress-Raw-Zlib/Makefile.PL
630                       - Can't install via CPAN shell under Cygwin
631 ext/Compress-Raw-Zlib/zlib-src/zutil.h
632                       - Cygwin is Unix-like and has vsnprintf
633 ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
634 ext/POSIX/POSIX.xs    - tzname defined externally
635 ext/SDBM_File/sdbm/pair.c
636                       - EXTCONST needs to be redefined from EXTERN.h
637 ext/SDBM_File/sdbm/sdbm.c
638                       - binary open
639 ext/Sys/Syslog/Syslog.xs
640                       - Cygwin has syslog.h
641 ext/Sys/Syslog/win32/compile.pl
642                       - Convert paths to Windows paths
643 ext/Time-HiRes/HiRes.xs
644                       - Various timers not available
645 ext/Time-HiRes/Makefile.PL
646                       - Find w32api/windows.h
647 ext/Win32/Makefile.PL - Use various libraries under Cygwin
648 ext/Win32/Win32.xs    - Child dir and child env under Cygwin
649 ext/Win32API-File/File.xs
650                       - _open_osfhandle not implemented under Cygwin
651 ext/Win32CORE/Win32CORE.c
652                       - __declspec(dllexport)
653
654=item Perl Modules/Scripts
655
656 ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
657 ext/Digest-SHA/bin/shasum
658                       - Use binary mode under Cygwin
659 ext/Sys/Syslog/win32/Win32.pm
660                       - Convert paths to Windows paths
661 ext/Time-HiRes/HiRes.pm
662                       - Comment about various timers not available
663 ext/Win32API-File/File.pm
664                       - _open_osfhandle not implemented under Cygwin
665 ext/Win32CORE/Win32CORE.pm
666                       - History of Win32CORE under Cygwin
667 lib/Cwd.pm            - hook to internal Cwd::cwd
668 lib/ExtUtils/CBuilder/Platform/cygwin.pm
669                       - use gcc for ld, and link to libperl.dll.a
670 lib/ExtUtils/CBuilder.pm
671                       - Cygwin is Unix-like
672 lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
673 lib/ExtUtils/MM.pm    - OS classifications
674 lib/ExtUtils/MM_Any.pm - Example for Cygwin
675 lib/ExtUtils/MakeMaker.pm
676                       - require MM_Cygwin.pm
677 lib/ExtUtils/MM_Cygwin.pm
678                       - canonpath, cflags, manifypods, perl_archive
679 lib/File/Fetch.pm     - Comment about quotes using a Cygwin example
680 lib/File/Find.pm      - on remote drives stat() always sets st_nlink to 1
681 lib/File/Spec/Cygwin.pm - case_tolerant
682 lib/File/Spec/Unix.pm - preserve //unc
683 lib/File/Spec/Win32.pm - References a message on cygwin.com
684 lib/File/Spec.pm      - Pulls in lib/File/Spec/Cygwin.pm
685 lib/File/Temp.pm      - no directory sticky bit
686 lib/Module/CoreList.pm - List of all module files and versions
687 lib/Net/Domain.pm     - No domainname command under Cygwin
688 lib/Net/Netrc.pm      - Bypass using stat() under Cygwin
689 lib/Net/Ping.pm       - ECONREFUSED is EAGAIN under Cygwin
690 lib/Pod/Find.pm       - Set 'pods' dir
691 lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
692 lib/Pod/Perldoc.pm    - Use 'less' pager, and use .exe extension
693 lib/Term/ANSIColor.pm - Cygwin terminal info
694 lib/perl5db.pl        - use stdin not /dev/tty
695 utils/perlbug.PL      - Add CYGWIN environment variable to report
696
697=item Perl Module Tests
698
699 dist/Cwd/t/cwd.t
700 ext/Compress-Zlib/t/14gzopen.t
701 ext/DB_File/t/db-btree.t
702 ext/DB_File/t/db-hash.t
703 ext/DB_File/t/db-recno.t
704 ext/DynaLoader/t/DynaLoader.t
705 ext/File-Glob/t/basic.t
706 ext/GDBM_File/t/gdbm.t
707 ext/POSIX/t/sysconf.t
708 ext/POSIX/t/time.t
709 ext/SDBM_File/t/sdbm.t
710 ext/Sys/Syslog/t/syslog.t
711 ext/Time-HiRes/t/HiRes.t
712 ext/Win32/t/Unicode.t
713 ext/Win32API-File/t/file.t
714 ext/Win32CORE/t/win32core.t
715 lib/AnyDBM_File.t
716 lib/Archive/Extract/t/01_Archive-Extract.t
717 lib/Archive/Tar/t/02_methods.t
718 lib/ExtUtils/t/Embed.t
719 lib/ExtUtils/t/eu_command.t
720 lib/ExtUtils/t/MM_Cygwin.t
721 lib/ExtUtils/t/MM_Unix.t
722 lib/File/Compare.t
723 lib/File/Copy.t
724 lib/File/Find/t/find.t
725 lib/File/Path.t
726 lib/File/Spec/t/crossplatform.t
727 lib/File/Spec/t/Spec.t
728 lib/Net/hostent.t
729 lib/Net/Ping/t/110_icmp_inst.t
730 lib/Net/Ping/t/500_ping_icmp.t
731 lib/Net/t/netrc.t
732 lib/Pod/Simple/t/perlcyg.pod
733 lib/Pod/Simple/t/perlcygo.txt
734 lib/Pod/Simple/t/perlfaq.pod
735 lib/Pod/Simple/t/perlfaqo.txt
736 lib/User/grent.t
737 lib/User/pwent.t
738
739=back
740
741=head1 BUGS ON CYGWIN
742
743Support for swapping real and effective user and group IDs is incomplete.
744On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
745However, additional Cygwin calls for manipulating WinNT access tokens
746and security contexts are required.
747
748=head1 AUTHORS
749
750Charles Wilson <cwilson@ece.gatech.edu>,
751Eric Fifer <egf7@columbia.edu>,
752alexander smishlajev <als@turnhere.com>,
753Steven Morlock <newspost@morlock.net>,
754Sebastien Barre <Sebastien.Barre@utc.fr>,
755Teun Burgers <burgers@ecn.nl>,
756Gerrit P. Haase <gp@familiehaase.de>,
757Reini Urban <rurban@cpan.org>,
758Jan Dubois <jand@activestate.com>,
759Jerry D. Hedden <jdhedden@cpan.org>.
760
761=head1 HISTORY
762
763Last updated: 2012-02-08
764

README.dos

1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see perlpod manpage) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perldos - Perl under DOS, W31, W95.
8
9=head1 SYNOPSIS
10
11These are instructions for building Perl under DOS (or w??), using
12DJGPP v2.03 or later.  Under w95 long filenames are supported.
13
14=head1 DESCRIPTION
15
16Before you start, you should glance through the README file
17found in the top-level directory where the Perl distribution
18was extracted.  Make sure you read and understand the terms under
19which this software is being distributed.
20
21This port currently supports MakeMaker (the set of modules that
22is used to build extensions to perl).  Therefore, you should be
23able to build and install most extensions found in the CPAN sites.
24
25Detailed instructions on how to build and install perl extension
26modules, including XS-type modules, is included.  See 'BUILDING AND
27INSTALLING MODULES'.
28
29=head2 Prerequisites for Compiling Perl on DOS
30
31=over 4
32
33=item DJGPP
34
35DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit,
36protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible
37operating systems, by DJ Delorie <dj@delorie.com> and friends.
38
39For more details (FAQ), check out the home of DJGPP at:
40
41        http://www.delorie.com/djgpp/
42
43If you have questions about DJGPP, try posting to the DJGPP newsgroup:
44comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.
45
46You can find the full DJGPP distribution on any of the mirrors listed here:
47
48        http://www.delorie.com/djgpp/getting.html
49
50You need the following files to build perl (or add new modules):
51
52        v2/djdev203.zip
53        v2gnu/bnu2112b.zip
54        v2gnu/gcc2953b.zip
55        v2gnu/bsh204b.zip
56        v2gnu/mak3791b.zip
57        v2gnu/fil40b.zip
58        v2gnu/sed3028b.zip
59        v2gnu/txt20b.zip
60        v2gnu/dif272b.zip
61        v2gnu/grep24b.zip
62        v2gnu/shl20jb.zip
63        v2gnu/gwk306b.zip
64        v2misc/csdpmi5b.zip
65
66or possibly any newer version.
67
68=item Pthreads
69
70Thread support is not tested in this version of the djgpp perl.
71
72=back
73
74=head2 Shortcomings of Perl under DOS
75
76Perl under DOS lacks some features of perl under UNIX because of
77deficiencies in the UNIX-emulation, most notably:
78
79=over 4
80
81=item *
82
83fork() and pipe()
84
85=item *
86
87some features of the UNIX filesystem regarding link count and file dates
88
89=item *
90
91in-place operation is a little bit broken with short filenames
92
93=item *
94
95sockets
96
97=back
98
99=head2 Building Perl on DOS
100
101=over 4
102
103=item *
104
105Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want
106to use long file names under w95 and also to get Perl to pass all its
107tests, don't forget to use
108
109        set LFN=y
110        set FNCASE=y
111
112before unpacking the archive.
113
114=item *
115
116Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
117directory.
118
119        ln -s bash.exe sh.exe
120
121[If you have the recommended version of bash for DJGPP, this is already
122done for you.]
123
124And make the C<SHELL> environment variable point to this F<sh.exe>:
125
126        set SHELL=c:/djgpp/bin/sh.exe (use full path name!)
127
128You can do this in F<djgpp.env> too. Add this line BEFORE any section
129definition:
130
131        +SHELL=%DJDIR%/bin/sh.exe
132
133=item *
134
135If you have F<split.exe> and F<gsplit.exe> in your path, then rename 
136F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
137Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
138Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.
139
140[If you have the recommended versions of djdev, shell utilities and
141gawk, all these are already done for you, and you will not need to do
142anything.]
143
144=item *
145
146Chdir to the djgpp subdirectory of perl toplevel and type the following
147commands:
148
149        set FNCASE=y
150        configure.bat
151
152This will do some preprocessing then run the Configure script for you.
153The Configure script is interactive, but in most cases you just need to
154press ENTER.  The "set" command ensures that DJGPP preserves the letter
155case of file names when reading directories.  If you already issued this
156set command when unpacking the archive, and you are in the same DOS
157session as when you unpacked the archive, you don't have to issue the
158set command again.  This command is necessary *before* you start to 
159(re)configure or (re)build perl in order to ensure both that perl builds 
160correctly and that building XS-type modules can succeed.  See the DJGPP 
161info entry for "_preserve_fncase" for more information:
162
163        info libc alphabetical _preserve_fncase
164
165If the script says that your package is incomplete, and asks whether
166to continue, just answer with Y (this can only happen if you don't use
167long filenames or forget to issue "set FNCASE=y" first).
168
169When Configure asks about the extensions, I suggest IO and Fcntl,
170and if you want database handling then SDBM_File or GDBM_File
171(you need to install gdbm for this one). If you want to use the
172POSIX extension (this is the default), make sure that the stack
173size of your F<cc1.exe> is at least 512kbyte (you can check this
174with: C<stubedit cc1.exe>).
175
176You can use the Configure script in non-interactive mode too.
177When I built my F<perl.exe>, I used something like this:
178
179        configure.bat -des
180
181You can find more info about Configure's command line switches in
182the F<INSTALL> file.
183
184When the script ends, and you want to change some values in the
185generated F<config.sh> file, then run
186
187        sh Configure -S
188
189after you made your modifications.
190
191IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
192environment variable before running the script:
193
194        set CONFIG=
195
196=item *
197
198Now you can compile Perl. Type:
199
200        make
201
202=back
203
204=head2 Testing Perl on DOS
205
206Type:
207
208        make test
209
210If you're lucky you should see "All tests successful". But there can be
211a few failed subtests (less than 5 hopefully) depending on some external
212conditions (e.g. some subtests fail under linux/dosemu or plain dos
213with short filenames only).
214
215=head2 Installation of Perl on DOS
216
217Type:
218
219        make install
220
221This will copy the newly compiled perl and libraries into your DJGPP
222directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
223and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
224goes under C<($DJDIR)/lib/perl5/pod>.
225
226=head1 BUILDING AND INSTALLING MODULES ON DOS
227
228=head2 Building Prerequisites for Perl on DOS
229
230For building and installing non-XS modules, all you need is a working
231perl under DJGPP.  Non-XS modules do not require re-linking the perl
232binary, and so are simpler to build and install.
233
234XS-type modules do require re-linking the perl binary, because part of
235an XS module is written in "C", and has to be linked together with the
236perl binary to be executed.  This is required because perl under DJGPP
237is built with the "static link" option, due to the lack of "dynamic
238linking" in the DJGPP environment.
239
240Because XS modules require re-linking of the perl binary, you need both
241the perl binary distribution and the perl source distribution to build
242an XS extension module.  In addition, you will have to have built your
243perl binary from the source distribution so that all of the components
244of the perl binary are available for the required link step.
245
246=head2 Unpacking CPAN Modules on DOS
247
248First, download the module package from CPAN (e.g., the "Comma Separated
249Value" text package, Text-CSV-0.01.tar.gz).  Then expand the contents of
250the package into some location on your disk.  Most CPAN modules are
251built with an internal directory structure, so it is usually safe to
252expand it in the root of your DJGPP installation.  Some people prefer to
253locate source trees under /usr/src (i.e., C<($DJDIR)/usr/src>), but you may
254put it wherever seems most logical to you, *EXCEPT* under the same
255directory as your perl source code.  There are special rules that apply
256to modules which live in the perl source tree that do not apply to most
257of the modules in CPAN.
258
259Unlike other DJGPP packages, which are normal "zip" files, most CPAN
260module packages are "gzipped tarballs".  Recent versions of WinZip will
261safely unpack and expand them, *UNLESS* they have zero-length files.  It
262is a known WinZip bug (as of v7.0) that it will not extract zero-length
263files.
264
265From the command line, you can use the djtar utility provided with DJGPP
266to unpack and expand these files.  For example:
267
268        C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz
269
270This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling
271it with the source for this module.
272
273=head2 Building Non-XS Modules on DOS
274
275To build a non-XS module, you can use the standard module-building
276instructions distributed with perl modules.
277
278    perl Makefile.PL
279    make
280    make test
281    make install
282
283This is sufficient because non-XS modules install only ".pm" files and
284(sometimes) pod and/or man documentation.  No re-linking of the perl
285binary is needed to build, install or use non-XS modules.
286
287=head2 Building XS Modules on DOS
288
289To build an XS module, you must use the standard module-building
290instructions distributed with perl modules *PLUS* three extra
291instructions specific to the DJGPP "static link" build environment.
292
293    set FNCASE=y
294    perl Makefile.PL
295    make
296    make perl
297    make test
298    make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe
299    make install
300
301The first extra instruction sets DJGPP's FNCASE environment variable so
302that the new perl binary which you must build for an XS-type module will
303build correctly.  The second extra instruction re-builds the perl binary
304in your module directory before you run "make test", so that you are
305testing with the new module code you built with "make".  The third extra
306instruction installs the perl binary from your module directory into the
307standard DJGPP binary directory, C<($DJDIR)/bin>, replacing your
308previous perl binary.
309
310Note that the MAP_TARGET value *must* have the ".exe" extension or you
311will not create a "perl.exe" to replace the one in C<($DJDIR)/bin>.
312
313When you are done, the XS-module install process will have added information
314to your "perllocal" information telling that the perl binary has been replaced,
315and what module was installed.  You can view this information at any time
316by using the command:
317
318        perl -S perldoc perllocal
319
320=head1 AUTHOR
321
322Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se> [Installing/building perl]
323
324Peter J. Farley III F<pjfarley@banet.net> [Building/installing modules]
325
326=head1 SEE ALSO
327
328perl(1).
329
330=cut
331
332

README.freebsd

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlfreebsd - Perl version 5 on FreeBSD systems
8
9=head1 DESCRIPTION
10
11This document describes various features of FreeBSD that will affect how Perl
12version 5 (hereafter just Perl) is compiled and/or runs.
13
14=head2 FreeBSD core dumps from readdir_r with ithreads
15
16When perl is configured to use ithreads, it will use re-entrant library calls
17in preference to non-re-entrant versions.  There is a bug in FreeBSD's
18C<readdir_r> function in versions 4.5 and earlier that can cause a SEGV when
19reading large directories. A patch for FreeBSD libc is available
20(see http://www.freebsd.org/cgi/query-pr.cgi?pr=misc/30631 )
21which has been integrated into FreeBSD 4.6.
22
23=head2 $^X doesn't always contain a full path in FreeBSD
24
25perl sets C<$^X> where possible to a full path by asking the operating
26system. On FreeBSD the full path of the perl interpreter is found by using
27C<sysctl> with C<KERN_PROC_PATHNAME> if that is supported, else by reading
28the symlink F</proc/curproc/file>. FreeBSD 7 and earlier has a bug where
29either approach sometimes returns an incorrect value
30(see http://www.freebsd.org/cgi/query-pr.cgi?pr=35703 ).
31In these cases perl will fall back to the old behaviour of using C's
32argv[0] value for C<$^X>.
33
34=head1 AUTHOR
35
36Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic
37and Tim Bunce.
38
39Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
40
41

README.haiku

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlhaiku - Perl version 5.10+ on Haiku
8
9=head1 DESCRIPTION
10
11This file contains instructions how to build Perl for Haiku and lists
12known problems.
13
14=head1 BUILD AND INSTALL
15
16The build procedure is completely standard:
17
18  ./Configure -de
19  make
20  make install
21
22Make perl executable and create a symlink for libperl:
23
24  chmod a+x /boot/common/bin/perl
25  cd /boot/common/lib; ln -s perl5/5.23.6/BePC-haiku/CORE/libperl.so .
26
27Replace C<5.23.6> with your respective version of Perl.
28
29=head1 KNOWN PROBLEMS
30
31The following problems are encountered with Haiku revision 28311:
32
33=over 4
34
35=item *
36
37Perl cannot be compiled with threading support ATM.
38
39=item *
40
41The F<ext/Socket/t/socketpair.t> test fails. More precisely: the subtests
42using datagram sockets fail. Unix datagram sockets aren't implemented in
43Haiku yet.
44
45=item *
46
47A subtest of the F<ext/Sys/Syslog/t/syslog.t> test fails. This is due to Haiku
48not implementing F</dev/log> support yet.
49
50=item *
51
52The tests F<lib/Net/Ping/t/450_service.t> and F<lib/Net/Ping/t/510_ping_udp.t>
53fail. This is due to bugs in Haiku's network stack implementation.
54
55=back
56
57=head1 CONTACT
58
59For Haiku specific problems contact the HaikuPorts developers:
60L<http://ports.haiku-files.org/>
61
62The initial Haiku port was done by Ingo Weinhold <ingo_weinhold@gmx.de>.
63
64Last update: 2008-10-29
65

README.hpux

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
8
9=head1 DESCRIPTION
10
11This document describes various features of HP's Unix operating system
12(HP-UX) that will affect how Perl version 5 (hereafter just Perl) is
13compiled and/or runs.
14
15=head2 Using perl as shipped with HP-UX
16
17Application release September 2001, HP-UX 11.00 is the first to ship
18with Perl. By the time it was perl-5.6.1 in /opt/perl. The first
19occurrence is on CD 5012-7954 and can be installed using
20
21  swinstall -s /cdrom perl
22
23assuming you have mounted that CD on /cdrom.
24
25That build was a portable hppa-1.1 multithread build that supports large
26files compiled with gcc-2.9-hppa-991112.
27
28If you perform a new installation, then (a newer) Perl will be installed
29automatically.  Pre-installed HP-UX systems now have more recent versions
30of Perl and the updated modules.
31
32The official (threaded) builds from HP, as they are shipped on the
33Application DVD/CD's are available on
34L<http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL>
35for both PA-RISC and IPF (Itanium Processor Family). They are built
36with the HP ANSI-C compiler. Up till 5.8.8 that was done by ActiveState.
37
38To see what version is included on the DVD (assumed here to be mounted
39on /cdrom), issue this command:
40
41  # swlist -s /cdrom perl
42  # perl           D.5.8.8.B  5.8.8 Perl Programming Language
43    perl.Perl5-32  D.5.8.8.B  32-bit 5.8.8 Perl Programming Language with Extensions
44    perl.Perl5-64  D.5.8.8.B  64-bit 5.8.8 Perl Programming Language with Extensions
45
46To see what is installed on your system:
47
48  # swlist -R perl
49  # perl                    E.5.8.8.J  Perl Programming Language
50  # perl.Perl5-32           E.5.8.8.J  32-bit Perl Programming Language with Extensions
51    perl.Perl5-32.PERL-MAN  E.5.8.8.J  32-bit Perl Man Pages for IA
52    perl.Perl5-32.PERL-RUN  E.5.8.8.J  32-bit Perl Binaries for IA
53  # perl.Perl5-64           E.5.8.8.J  64-bit Perl Programming Language with Extensions
54    perl.Perl5-64.PERL-MAN  E.5.8.8.J  64-bit Perl Man Pages for IA
55    perl.Perl5-64.PERL-RUN  E.5.8.8.J  64-bit Perl Binaries for IA
56
57=head2 Using perl from HP's porting centre
58
59HP porting centre tries to keep up with customer demand and release
60updates from the Open Source community. Having precompiled Perl binaries
61available is obvious, though "up-to-date" is something relative. At the
62moment of writing only perl-5.10.1 was available (with 5.16.3 being the
63latest stable release from the porters point of view).
64
65The HP porting centres are limited in what systems they are allowed
66to port to and they usually choose the two most recent OS versions
67available.
68
69HP has asked the porting centre to move Open Source binaries
70from /opt to /usr/local, so binaries produced since the start
71of July 2002 are located in /usr/local.
72
73One of HP porting centres URL's is L<http://hpux.connect.org.uk/>
74The port currently available is built with GNU gcc.
75
76=head2 Other prebuilt perl binaries
77
78To get even more recent perl depots for the whole range of HP-UX, visit
79H.Merijn Brand's site at L<http://mirrors.develooper.com/hpux/#Perl>.
80Carefully read the notes to see if the available versions suit your needs.
81
82=head2 Compiling Perl 5 on HP-UX
83
84When compiling Perl, you must use an ANSI C compiler.  The C compiler
85that ships with all HP-UX systems is a K&R compiler that should only be
86used to build new kernels.
87
88Perl can be compiled with either HP's ANSI C compiler or with gcc.  The
89former is recommended, as not only can it compile Perl with no
90difficulty, but also can take advantage of features listed later that
91require the use of HP compiler-specific command-line flags.
92
93If you decide to use gcc, make sure your installation is recent and
94complete, and be sure to read the Perl INSTALL file for more gcc-specific
95details.
96
97=head2 PA-RISC
98
99HP's HP9000 Unix systems run on HP's own Precision Architecture
100(PA-RISC) chip.  HP-UX used to run on the Motorola MC68000 family of
101chips, but any machine with this chip in it is quite obsolete and this
102document will not attempt to address issues for compiling Perl on the
103Motorola chipset.
104
105The version of PA-RISC at the time of this document's last update is 2.0,
106which is also the last there will be. HP PA-RISC systems are usually
107referred to with model description "HP 9000". The last CPU in this series
108is the PA-8900.  Support for PA-RISC architectured machines officially
109ends as shown in the following table:
110
111   PA-RISC End-of-Life Roadmap
112 +--------+----------------+----------------+-----------------+
113 | HP9000 | Superdome      | PA-8700        | Spring 2011     |
114 | 4-128  |                | PA-8800/sx1000 | Summer 2012     |
115 | cores  |                | PA-8900/sx1000 | 2014            |
116 |        |                | PA-8900/sx2000 | 2015            |
117 +--------+----------------+----------------+-----------------+
118 | HP9000 | rp7410, rp8400 | PA-8700        | Spring 2011     |
119 | 2-32   | rp7420, rp8420 | PA-8800/sx1000 | 2012            |
120 | cores  | rp7440, rp8440 | PA-8900/sx1000 | Autumn 2013     |
121 |        |                | PA-8900/sx2000 | 2015            |
122 +--------+----------------+----------------+-----------------+
123 | HP9000 | rp44x0         | PA-8700        | Spring 2011     |
124 | 1-8    |                | PA-8800/rp44x0 | 2012            |
125 | cores  |                | PA-8900/rp44x0 | 2014            |
126 +--------+----------------+----------------+-----------------+
127 | HP9000 | rp34x0         | PA-8700        | Spring 2011     |
128 | 1-4    |                | PA-8800/rp34x0 | 2012            |
129 | cores  |                | PA-8900/rp34x0 | 2014            |
130 +--------+----------------+----------------+-----------------+
131
132From L<http://www.hp.com/products1/evolution/9000/faqs.html>
133
134 The last order date for HP 9000 systems was December 31, 2008.
135
136A complete list of models at the time the OS was built is in the file
137/usr/sam/lib/mo/sched.models. The first column corresponds to the last
138part of the output of the "model" command.  The second column is the
139PA-RISC version and the third column is the exact chip type used.
140(Start browsing at the bottom to prevent confusion ;-)
141
142  # model
143  9000/800/L1000-44
144  # grep L1000-44 /usr/sam/lib/mo/sched.models
145  L1000-44        2.0     PA8500
146
147=head2 Portability Between PA-RISC Versions
148
149An executable compiled on a PA-RISC 2.0 platform will not execute on a
150PA-RISC 1.1 platform, even if they are running the same version of
151HP-UX.  If you are building Perl on a PA-RISC 2.0 platform and want that
152Perl to also run on a PA-RISC 1.1, the compiler flags +DAportable and
153+DS32 should be used.
154
155It is no longer possible to compile PA-RISC 1.0 executables on either
156the PA-RISC 1.1 or 2.0 platforms.  The command-line flags are accepted,
157but the resulting executable will not run when transferred to a PA-RISC
1581.0 system.
159
160=head2 PA-RISC 1.0
161
162The original version of PA-RISC, HP no longer sells any system with this chip.
163
164The following systems contained PA-RISC 1.0 chips:
165
166  600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850,
167  852, 855, 860, 865, 870, 890
168
169=head2 PA-RISC 1.1
170
171An upgrade to the PA-RISC design, it shipped for many years in many different
172system.
173
174The following systems contain with PA-RISC 1.1 chips:
175
176  705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 744, 745,
177  747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
178  813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
179  851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
180  B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
181  C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
182  D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
183  G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
184  I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
185  K420, S700i, S715, S744, S760, T500, T520
186
187=head2 PA-RISC 2.0
188
189The most recent upgrade to the PA-RISC design, it added support for
19064-bit integer data.
191
192As of the date of this document's last update, the following systems
193contain PA-RISC 2.0 chips:
194
195  700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
196  893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
197  C180, C180+, C180-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
198  D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
199  J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260-EG, K270, K360,
200  K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000,
201  L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
202  T600, V2000, V2200, V2250, V2500, V2600
203
204Just before HP took over Compaq, some systems were renamed. the link
205that contained the explanation is dead, so here's a short summary:
206
207  HP 9000 A-Class servers, now renamed HP Server rp2400 series.
208  HP 9000 L-Class servers, now renamed HP Server rp5400 series.
209  HP 9000 N-Class servers, now renamed HP Server rp7400.
210
211  rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
212  rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
213  rp7410, rp7420, rp7440, rp8400, rp8420, rp8440, Superdome
214
215The current naming convention is:
216
217  aadddd
218  ||||`+- 00 - 99 relative capacity & newness (upgrades, etc.)
219  |||`--- unique number for each architecture to ensure different
220  |||     systems do not have the same numbering across
221  |||     architectures
222  ||`---- 1 - 9 identifies family and/or relative positioning
223  ||
224  |`----- c = ia32 (cisc)
225  |       p = pa-risc
226  |       x = ia-64 (Itanium & Itanium 2)
227  |       h = housing
228  `------ t = tower
229          r = rack optimized
230          s = super scalable
231          b = blade
232          sa = appliance
233
234=head2 Itanium Processor Family (IPF) and HP-UX
235
236HP-UX also runs on the new Itanium processor.  This requires the use
237of a different version of HP-UX (currently 11.23 or 11i v2), and with
238the exception of a few differences detailed below and in later sections,
239Perl should compile with no problems.
240
241Although PA-RISC binaries can run on Itanium systems, you should not
242attempt to use a PA-RISC version of Perl on an Itanium system.  This is
243because shared libraries created on an Itanium system cannot be loaded
244while running a PA-RISC executable.
245
246HP Itanium 2 systems are usually referred to with model description
247"HP Integrity".
248
249=head2 Itanium, Itanium 2 & Madison 6
250
251HP also ships servers with the 128-bit Itanium processor(s). The cx26x0
252is told to have Madison 6. As of the date of this document's last update,
253the following systems contain Itanium or Itanium 2 chips (this is likely
254to be out of date):
255
256  BL60p, BL860c, BL870c, BL890c, cx2600, cx2620, rx1600, rx1620, rx2600,
257  rx2600hptc, rx2620, rx2660, rx2800, rx3600, rx4610, rx4640, rx5670,
258  rx6600, rx7420, rx7620, rx7640, rx8420, rx8620, rx8640, rx9610,
259  sx1000, sx2000
260
261To see all about your machine, type
262
263  # model
264  ia64 hp server rx2600
265  # /usr/contrib/bin/machinfo
266
267=head2 HP-UX versions
268
269Not all architectures (PA = PA-RISC, IPF = Itanium Processor Family)
270support all versions of HP-UX, here is a short list
271
272  HP-UX version  Kernel  Architecture End-of-factory support
273  -------------  ------  ------------ ----------------------------------
274  10.20          32 bit  PA           30-Jun-2003
275  11.00          32/64   PA           31-Dec-2006
276  11.11  11i v1  32/64   PA           31-Dec-2015
277  11.22  11i v2     64        IPF     30-Apr-2004
278  11.23  11i v2     64   PA & IPF     31-Dec-2015
279  11.31  11i v3     64   PA & IPF     31-Dec-2020 (PA) 31-Dec-2022 (IPF)
280
281See for the full list of hardware/OS support and expected end-of-life
282L<http://www.hp.com/go/hpuxservermatrix>
283
284=head2 Building Dynamic Extensions on HP-UX
285
286HP-UX supports dynamically loadable libraries (shared libraries).
287Shared libraries end with the suffix .sl.  On Itanium systems,
288they end with the suffix .so.
289
290Shared libraries created on a platform using a particular PA-RISC
291version are not usable on platforms using an earlier PA-RISC version by
292default.  However, this backwards compatibility may be enabled using the
293same +DAportable compiler flag (with the same PA-RISC 1.0 caveat
294mentioned above).
295
296Shared libraries created on an Itanium platform cannot be loaded on
297a PA-RISC platform.  Shared libraries created on a PA-RISC platform
298can only be loaded on an Itanium platform if it is a PA-RISC executable
299that is attempting to load the PA-RISC library.  A PA-RISC shared
300library cannot be loaded into an Itanium executable nor vice-versa.
301
302To create a shared library, the following steps must be performed:
303
304  1. Compile source modules with +z or +Z flag to create a .o module
305     which contains Position-Independent Code (PIC).  The linker will
306     tell you in the next step if +Z was needed.
307     (For gcc, the appropriate flag is -fpic or -fPIC.)
308
309  2. Link the shared library using the -b flag.  If the code calls
310     any functions in other system libraries (e.g., libm), it must
311     be included on this line.
312
313(Note that these steps are usually handled automatically by the extension's
314Makefile).
315
316If these dependent libraries are not listed at shared library creation
317time, you will get fatal "Unresolved symbol" errors at run time when the
318library is loaded.
319
320You may create a shared library that refers to another library, which
321may be either an archive library or a shared library.  If this second
322library is a shared library, this is called a "dependent library".  The
323dependent library's name is recorded in the main shared library, but it
324is not linked into the shared library.  Instead, it is loaded when the
325main shared library is loaded.  This can cause problems if you build an
326extension on one system and move it to another system where the
327libraries may not be located in the same place as on the first system.
328
329If the referred library is an archive library, then it is treated as a
330simple collection of .o modules (all of which must contain PIC).  These
331modules are then linked into the shared library.
332
333Note that it is okay to create a library which contains a dependent
334library that is already linked into perl.
335
336Some extensions, like DB_File and Compress::Zlib use/require prebuilt
337libraries for the perl extensions/modules to work. If these libraries
338are built using the default configuration, it might happen that you
339run into an error like "invalid loader fixup" during load phase.
340HP is aware of this problem.  Search the HP-UX cxx-dev forums for
341discussions about the subject.  The short answer is that B<everything>
342(all libraries, everything) must be compiled with C<+z> or C<+Z> to be
343PIC (position independent code).  (For gcc, that would be
344C<-fpic> or C<-fPIC>).  In HP-UX 11.00 or newer the linker
345error message should tell the name of the offending object file.
346
347A more general approach is to intervene manually, as with an example for
348the DB_File module, which requires SleepyCat's libdb.sl:
349
350  # cd .../db-3.2.9/build_unix
351  # vi Makefile
352  ... add +Z to all cflags to create shared objects
353  CFLAGS=         -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
354                  -I/usr/local/include -I/usr/include/X11R6
355  CXXFLAGS=       -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
356                  -I/usr/local/include -I/usr/include/X11R6
357
358  # make clean
359  # make
360  # mkdir tmp
361  # cd tmp
362  # ar x ../libdb.a
363  # ld -b -o libdb-3.2.sl *.o
364  # mv libdb-3.2.sl /usr/local/lib
365  # rm *.o
366  # cd /usr/local/lib
367  # rm -f libdb.sl
368  # ln -s libdb-3.2.sl libdb.sl
369
370  # cd .../DB_File-1.76
371  # make distclean
372  # perl Makefile.PL
373  # make
374  # make test
375  # make install
376
377As of db-4.2.x it is no longer needed to do this by hand. Sleepycat
378has changed the configuration process to add +z on HP-UX automatically.
379
380  # cd .../db-4.2.25/build_unix
381  # env CFLAGS=+DD64 LDFLAGS=+DD64 ../dist/configure
382
383should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.
384
385It is no longer possible to link PA-RISC 1.0 shared libraries (even
386though the command-line flags are still present).
387
388PA-RISC and Itanium object files are not interchangeable.  Although
389you may be able to use ar to create an archive library of PA-RISC
390object files on an Itanium system, you cannot link against it using
391an Itanium link editor.
392
393=head2 The HP ANSI C Compiler
394
395When using this compiler to build Perl, you should make sure that the
396flag -Aa is added to the cpprun and cppstdin variables in the config.sh
397file (though see the section on 64-bit perl below). If you are using a
398recent version of the Perl distribution, these flags are set automatically.
399
400Even though HP-UX 10.20 and 11.00 are not actively maintained by HP
401anymore, updates for the HP ANSI C compiler are still available from
402time to time, and it might be advisable to see if updates are applicable.
403At the moment of writing, the latests available patches for 11.00 that
404should be applied are PHSS_35098, PHSS_35175, PHSS_35100, PHSS_33036,
405and PHSS_33902). If you have a SUM account, you can use it to search
406for updates/patches. Enter "ANSI" as keyword.
407
408=head2 The GNU C Compiler
409
410When you are going to use the GNU C compiler (gcc), and you don't have
411gcc yet, you can either build it yourself from the sources (available
412from e.g. L<http://gcc.gnu.org/mirrors.html>) or fetch
413a prebuilt binary from the HP porting center
414at L<http://hpux.connect.org.uk/hppd/cgi-bin/search?term=gcc&Search=Search>
415or from the DSPP (you need to be a member) at
416L<http://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=2a08725cc2f02110725cc2f02110275d6e10RCRD&jumpid=reg_r1002_usen_c-001_title_r0001>
417(Browse through the list, because there are often multiple versions of
418the same package available).
419
420Most mentioned distributions are depots. H.Merijn Brand has made prebuilt
421gcc binaries available on L<http://mirrors.develooper.com/hpux/> and/or
422L<http://www.cmve.net/~merijn/> for HP-UX 10.20 (only 32bit), HP-UX 11.00,
423HP-UX 11.11 (HP-UX 11i v1), and HP-UX 11.23 (HP-UX 11i v2 PA-RISC) in both
42432- and 64-bit versions. For HP-UX 11.23 IPF and HP-UX 11.31 IPF depots are
425available too. The IPF versions do not need two versions of GNU gcc.
426
427On PA-RISC you need a different compiler for 32-bit applications and for
42864-bit applications. On PA-RISC, 32-bit objects and 64-bit objects do
429not mix. Period. There is no different behaviour for HP C-ANSI-C or GNU
430gcc. So if you require your perl binary to use 64-bit libraries, like
431Oracle-64bit, you MUST build a 64-bit perl.
432
433Building a 64-bit capable gcc on PA-RISC from source is possible only when
434you have the HP C-ANSI C compiler or an already working 64-bit binary of
435gcc available. Best performance for perl is achieved with HP's native
436compiler.
437
438=head2 Using Large Files with Perl on HP-UX
439
440Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
441may be created and manipulated.  Three separate methods of doing this
442are available.  Of these methods, the best method for Perl is to compile
443using the -Duselargefiles flag to Configure.  This causes Perl to be
444compiled using structures and functions in which these are 64 bits wide,
445rather than 32 bits wide.  (Note that this will only work with HP's ANSI
446C compiler.  If you want to compile Perl using gcc, you will have to get
447a version of the compiler that supports 64-bit operations. See above for
448where to find it.)
449
450There are some drawbacks to this approach.  One is that any extension
451which calls any file-manipulating C function will need to be recompiled
452(just follow the usual "perl Makefile.PL; make; make test; make install"
453procedure).
454
455The list of functions that will need to recompiled is:
456  creat,          fgetpos,        fopen,
457  freopen,        fsetpos,        fstat,
458  fstatvfs,       fstatvfsdev,    ftruncate,
459  ftw,            lockf,          lseek,
460  lstat,          mmap,           nftw,
461  open,           prealloc,       stat,
462  statvfs,        statvfsdev,     tmpfile,
463  truncate,       getrlimit,      setrlimit
464
465Another drawback is only valid for Perl versions before 5.6.0.  This
466drawback is that the seek and tell functions (both the builtin version
467and POSIX module version) will not perform correctly.
468
469It is strongly recommended that you use this flag when you run
470Configure.  If you do not do this, but later answer the question about
471large files when Configure asks you, you may get a configuration that
472cannot be compiled, or that does not function as expected.
473
474=head2 Threaded Perl on HP-UX
475
476It is possible to compile a version of threaded Perl on any version of
477HP-UX before 10.30, but it is strongly suggested that you be running on
478HP-UX 11.00 at least.
479
480To compile Perl with threads, add -Dusethreads to the arguments of
481Configure.  Verify that the -D_POSIX_C_SOURCE=199506L compiler flag is
482automatically added to the list of flags.  Also make sure that -lpthread
483is listed before -lc in the list of libraries to link Perl with. The
484hints provided for HP-UX during Configure will try very hard to get
485this right for you.
486
487HP-UX versions before 10.30 require a separate installation of a POSIX
488threads library package. Two examples are the HP DCE package, available
489on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
490April 1999 (B3920-13941)" or the Freely available PTH package, available
491on H.Merijn's site (L<http://mirrors.develooper.com/hpux/>). The use of PTH
492will be unsupported in perl-5.12 and up and is rather buggy in 5.11.x.
493
494If you are going to use the HP DCE package, the library used for threading
495is /usr/lib/libcma.sl, but there have been multiple updates of that
496library over time. Perl will build with the first version, but it
497will not pass the test suite. Older Oracle versions might be a compelling
498reason not to update that library, otherwise please find a newer version
499in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672
500
501reformatted output:
502
503  d3:/usr/lib 106 > what libcma-*.1
504  libcma-00000.1:
505     HP DCE/9000 1.5               Module: libcma.sl (Export)
506                                   Date: Apr 29 1996 22:11:24
507  libcma-19739.1:
508     HP DCE/9000 1.5 PHSS_19739-40 Module: libcma.sl (Export)
509                                   Date: Sep  4 1999 01:59:07
510  libcma-20608.1:
511     HP DCE/9000 1.5 PHSS_20608    Module: libcma.1 (Export)
512                                   Date: Dec  8 1999 18:41:23
513  libcma-23672.1:
514     HP DCE/9000 1.5 PHSS_23672    Module: libcma.1 (Export)
515                                   Date: Apr  9 2001 10:01:06
516  d3:/usr/lib 107 >
517
518If you choose for the PTH package, use swinstall to install pth in
519the default location (/opt/pth), and then make symbolic links to the
520libraries from /usr/lib
521
522  # cd /usr/lib
523  # ln -s /opt/pth/lib/libpth* .
524
525For building perl to support Oracle, it needs to be linked with libcl
526and libpthread. So even if your perl is an unthreaded build, these
527libraries might be required. See "Oracle on HP-UX" below.
528
529=head2 64-bit Perl on HP-UX
530
531Beginning with HP-UX 11.00, programs compiled under HP-UX can take
532advantage of the LP64 programming environment (LP64 means Longs and
533Pointers are 64 bits wide), in which scalar variables will be able
534to hold numbers larger than 2^32 with complete precision.  Perl has
535proven to be consistent and reliable in 64bit mode since 5.8.1 on
536all HP-UX 11.xx.
537
538As of the date of this document, Perl is fully 64-bit compliant on
539HP-UX 11.00 and up for both cc- and gcc builds. If you are about to
540build a 64-bit perl with GNU gcc, please read the gcc section carefully.
541
542Should a user have the need for compiling Perl in the LP64 environment,
543use the -Duse64bitall flag to Configure.  This will force Perl to be
544compiled in a pure LP64 environment (with the +DD64 flag for HP C-ANSI-C,
545with no additional options for GNU gcc 64-bit on PA-RISC, and with
546-mlp64 for GNU gcc on Itanium).
547If you want to compile Perl using gcc, you will have to get a version of
548the compiler that supports 64-bit operations.)
549
550You can also use the -Duse64bitint flag to Configure.  Although there
551are some minor differences between compiling Perl with this flag versus
552the -Duse64bitall flag, they should not be noticeable from a Perl user's
553perspective. When configuring -Duse64bitint using a 64bit gcc on a
554pa-risc architecture, -Duse64bitint is silently promoted to -Duse64bitall.
555
556In both cases, it is strongly recommended that you use these flags when
557you run Configure.  If you do not use do this, but later answer the
558questions about 64-bit numbers when Configure asks you, you may get a
559configuration that cannot be compiled, or that does not function as
560expected.
561
562=head2 Oracle on HP-UX
563
564Using perl to connect to Oracle databases through DBI and DBD::Oracle
565has caused a lot of people many headaches. Read README.hpux in the
566DBD::Oracle for much more information. The reason to mention it here
567is that Oracle requires a perl built with libcl and libpthread, the
568latter even when perl is build without threads. Building perl using
569all defaults, but still enabling to build DBD::Oracle later on can be
570achieved using
571
572  Configure -A prepend:libswanted='cl pthread ' ...
573
574Do not forget the space before the trailing quote.
575
576Also note that this does not (yet) work with all configurations,
577it is known to fail with 64-bit versions of GCC.
578
579=head2 GDBM and Threads on HP-UX
580
581If you attempt to compile Perl with (POSIX) threads on an 11.X system
582and also link in the GDBM library, then Perl will immediately core dump
583when it starts up.  The only workaround at this point is to relink the
584GDBM library under 11.X, then relink it into Perl.
585
586the error might show something like:
587
588Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
589Return Pointer is 0xc082bf33
590sh: 5345 Quit(coredump)
591
592and Configure will give up.
593
594=head2 NFS filesystems and utime(2) on HP-UX
595
596If you are compiling Perl on a remotely-mounted NFS filesystem, the test
597io/fs.t may fail on test #18.  This appears to be a bug in HP-UX and no
598fix is currently available.
599
600=head2 HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
601
602By default, HP-UX comes configured with a maximum data segment size of
60364MB.  This is too small to correctly compile Perl with the maximum
604optimization levels.  You can increase the size of the maxdsiz kernel
605parameter through the use of SAM.
606
607When using the GUI version of SAM, click on the Kernel Configuration
608icon, then the Configurable Parameters icon.  Scroll down and select
609the maxdsiz line.  From the Actions menu, select the Modify Configurable
610Parameter item.  Insert the new formula into the Formula/Value box.
611Then follow the instructions to rebuild your kernel and reboot your
612system.
613
614In general, a value of 256MB (or "256*1024*1024") is sufficient for
615Perl to compile at maximum optimization.
616
617=head1 nss_delete core dump from op/pwent or op/grent
618
619You may get a bus error core dump from the op/pwent or op/grent
620tests. If compiled with -g you will see a stack trace much like
621the following:
622
623  #0  0xc004216c in  () from /usr/lib/libc.2
624  #1  0xc00d7550 in __nss_src_state_destr () from /usr/lib/libc.2
625  #2  0xc00d7768 in __nss_src_state_destr () from /usr/lib/libc.2
626  #3  0xc00d78a8 in nss_delete () from /usr/lib/libc.2
627  #4  0xc01126d8 in endpwent () from /usr/lib/libc.2
628  #5  0xd1950 in Perl_pp_epwent () from ./perl
629  #6  0x94d3c in Perl_runops_standard () from ./perl
630  #7  0x23728 in S_run_body () from ./perl
631  #8  0x23428 in perl_run () from ./perl
632  #9  0x2005c in main () from ./perl
633
634The key here is the C<nss_delete> call.  One workaround for this
635bug seems to be to create add to the file F</etc/nsswitch.conf>
636(at least) the following lines
637
638  group: files
639  passwd: files
640
641Whether you are using NIS does not matter.  Amazingly enough,
642the same bug also affects Solaris.
643
644=head1 error: pasting ")" and "l" does not give a valid preprocessing token
645
646There seems to be a broken system header file in HP-UX 11.00 that
647breaks perl building in 32bit mode with GNU gcc-4.x causing this
648error. The same file for HP-UX 11.11 (even though the file is older)
649does not show this failure, and has the correct definition, so the
650best fix is to patch the header to match:
651
652 --- /usr/include/inttypes.h  2001-04-20 18:42:14 +0200
653 +++ /usr/include/inttypes.h  2000-11-14 09:00:00 +0200
654 @@ -72,7 +72,7 @@
655  #define UINT32_C(__c)                   __CONCAT_U__(__c)
656  #else /* __LP64 */
657  #define INT32_C(__c)                    __CONCAT__(__c,l)
658 -#define UINT32_C(__c)                   __CONCAT__(__CONCAT_U__(__c),l)
659 +#define UINT32_C(__c)                   __CONCAT__(__c,ul)
660  #endif /* __LP64 */
661
662  #define INT64_C(__c)                    __CONCAT_L__(__c,l)
663
664=head1 Redeclaration of "sendpath" with a different storage class specifier
665
666The following compilation warnings may happen in HP-UX releases
667earlier than 11.31 but are harmless:
668
669  cc: "/usr/include/sys/socket.h", line 535: warning 562: Redeclaration of "sendfile" with a different storage class specifier: "sendfile" will have internal linkage.
670  cc: "/usr/include/sys/socket.h", line 536: warning 562: Redeclaration of "sendpath" with a different storage class specifier: "sendpath" will have internal linkage.
671
672They seem to be caused by broken system header files, and also other
673open source projects are seeing them.  The following HP-UX patches
674should make the warnings go away:
675
676  CR JAGae12001: PHNE_27063
677  Warning 562 on sys/socket.h due to redeclaration of prototypes
678
679  CR JAGae16787:
680  Warning 562 from socket.h sendpath/sendfile -D_FILEFFSET_BITS=64
681
682  CR JAGae73470 (11.23)
683  ER: Compiling socket.h with cc -D_FILEFFSET_BITS=64 warning 267/562
684
685=head1 Miscellaneous
686
687HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
688Patch Bundle" has been reported to break the io/fs test #18 which
689tests whether utime() can change timestamps.  The Y2K patch seems to
690break utime() so that over NFS the timestamps do not get changed
691(on local filesystems utime() still works). This has probably been
692fixed on your system by now.
693
694=head1 AUTHOR
695
696H.Merijn Brand <h.m.brand@xs4all.nl>
697Jeff Okamoto <okamoto@corp.hp.com>
698
699With much assistance regarding shared libraries from Marc Sabatella.
700
701=cut
702

README.hurd

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlhurd - Perl version 5 on Hurd
8
9=head1 DESCRIPTION
10
11If you want to use Perl on the Hurd, I recommend using the Debian
12GNU/Hurd distribution ( see http://www.debian.org/ ), even if an
13official, stable release has not yet been made.  The old "gnu-0.2"
14binary distribution will most certainly have additional problems.
15
16=head2 Known Problems with Perl on Hurd 
17
18The Perl test suite may still report some errors on the Hurd.  The
19"lib/anydbm" and "pragma/warnings" tests will almost certainly fail.
20Both failures are not really specific to the Hurd, as indicated by the
21test suite output.
22
23The socket tests may fail if the network is not configured.  You have
24to make "/hurd/pfinet" the translator for "/servers/socket/2", giving
25it the right arguments.  Try "/hurd/pfinet --help" for more
26information.
27
28Here are the statistics for Perl 5.005_62 on my system:
29
30 Failed Test  Status Wstat Total Fail  Failed  List of failed
31 -------------------------------------------------------------------------
32 lib/anydbm.t                 12    1   8.33%  12
33 pragma/warnings             333    1   0.30%  215
34
35 8 tests and 24 subtests skipped.
36 Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed, 99.98% okay.
37
38There are quite a few systems out there that do worse!
39
40However, since I am running a very recent Hurd snapshot, in which a lot of
41bugs that were exposed by the Perl test suite have been fixed, you may
42encounter more failures.  Likely candidates are: "op/stat", "lib/io_pipe",
43"lib/io_sock", "lib/io_udp" and "lib/time".
44
45In any way, if you're seeing failures beyond those mentioned in this
46document, please consider upgrading to the latest Hurd before reporting
47the failure as a bug. 
48
49=head1 AUTHOR
50
51Mark Kettenis <kettenis@gnu.org>
52
53Last Updated: Fri, 29 Oct 1999 22:50:30 +0200
54
55

README.irix

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlirix - Perl version 5 on Irix systems
8
9=head1 DESCRIPTION
10
11This document describes various features of Irix that will affect how Perl
12version 5 (hereafter just Perl) is compiled and/or runs.
13
14=head2 Building 32-bit Perl in Irix
15
16Use
17
18	sh Configure -Dcc='cc -n32'
19
20to compile Perl 32-bit.  Don't bother with -n32 unless you have 7.1
21or later compilers (use cc -version to check).
22
23(Building 'cc -n32' is the default.)
24
25=head2 Building 64-bit Perl in Irix
26
27Use
28
29	sh Configure -Dcc='cc -64' -Duse64bitint
30
31This requires require a 64-bit MIPS CPU (R8000, R10000, ...)
32
33You can also use
34
35	sh Configure -Dcc='cc -64' -Duse64bitall
36
37but that makes no difference compared with the -Duse64bitint because
38of the C<cc -64>.
39
40You can also do
41
42	sh Configure -Dcc='cc -n32' -Duse64bitint
43
44to use long longs for the 64-bit integer type, in case you don't
45have a 64-bit CPU.
46
47If you are using gcc, just
48
49	sh Configure -Dcc=gcc -Duse64bitint
50
51should be enough, the Configure should automatically probe for the
52correct 64-bit settings.
53
54=head2 About Compiler Versions of Irix
55
56Some Irix cc versions, e.g. 7.3.1.1m (try cc -version) have been known
57to have issues (coredumps) when compiling perl.c.  If you've used
58-OPT:fast_io=ON and this happens, try removing it.  If that fails, or
59you didn't use that, then try adjusting other optimization options
60(-LNO, -INLINE, -O3 to -O2, etcetera).  The compiler bug has been
61reported to SGI.  (Allen Smith <easmith@beatrice.rutgers.edu>)
62
63=head2 Linker Problems in Irix
64
65If you get complaints about so_locations then search in the file
66hints/irix_6.sh for "lddflags" and do the suggested adjustments.
67(David Billinghurst <David.Billinghurst@riotinto.com.au>)
68
69=head2 Malloc in Irix
70
71Do not try to use Perl's malloc, this will lead into very mysterious
72errors (especially with -Duse64bitall).
73
74=head2 Building with threads in Irix
75
76Run Configure with -Duseithreads which will configure Perl with
77the Perl 5.8.0 "interpreter threads", see L<threads>.
78
79For Irix 6.2 with perl threads, you have to have the following
80patches installed:
81
82        1404 Irix 6.2 Posix 1003.1b man pages
83        1645 Irix 6.2 & 6.3 POSIX header file updates
84        2000 Irix 6.2 Posix 1003.1b support modules
85        2254 Pthread library fixes
86        2401 6.2 all platform kernel rollup
87
88B<IMPORTANT>: Without patch 2401, a kernel bug in Irix 6.2 will cause
89your machine to panic and crash when running threaded perl.  Irix 6.3
90and later are okay.
91
92    Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
93    pthreads patches information.
94
95=head2 Irix 5.3
96
97While running Configure and when building, you are likely to get
98quite a few of these warnings:
99
100  ld:
101  The shared object /usr/lib/libm.so did not resolve any symbols.
102        You may want to remove it from your link line.
103
104Ignore them: in IRIX 5.3 there is no way to quieten ld about this.
105
106During compilation you will see this warning from toke.c:
107
108  uopt: Warning: Perl_yylex: this procedure not optimized because it
109        exceeds size threshold; to optimize this procedure, use -Olimit option
110        with value >= 4252.
111
112Ignore the warning.
113
114In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3)
115the following failures are known.
116
117 Failed Test                  Stat Wstat Total Fail  Failed  List of Failed
118 --------------------------------------------------------------------------
119 ../ext/List/Util/t/shuffle.t    0   139    ??   ??       %  ??
120 ../lib/Math/Trig.t            255 65280    29   12  41.38%  24-29
121 ../lib/sort.t                   0   138   119   72  60.50%  48-119
122 56 tests and 474 subtests skipped.
123 Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed, 99.90% okay.
124
125They are suspected to be compiler errors (at least the shuffle.t
126failure is known from some IRIX 6 setups) and math library errors
127(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
128further fixes for the IRIX are unlikely.  If you can get gcc for 5.3,
129you could try that, too, since gcc in IRIX 6 is a known workaround for
130at least the shuffle.t and sort.t failures.
131
132=head1 AUTHOR
133
134Jarkko Hietaniemi <jhi@iki.fi>
135
136Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
137
138

README.jp

1=encoding utf8
2
3=head1 NAME
4
5perljp - 日本語 Perl ガイド
6
7=head1 説明
8
9Perl の世界へようこそ!
10
11Perl 5.8.0 より、Unicodeサポートが大幅に強化され、その結果ラテン文字以外の文字コードのサポートが CJK (中国語、日本語、ハングル)を含めて加わりました。Unicodeは世界中の文字を一つの文字コードで扱うことを目指した標準規格であり、東から西、はたまたその間の文字(ギリシャ文字、キリール文字、アラビア文字、ヘブライ文字、ディーヴァナガーリ文字、などなど)や、これまではOSベンダーが独自に定めていた文字(PCおよびMacintosh)がすでに含まれています。
12
13Perl 自身は Unicode で動作します。Perl スクリプト内の文字列リテラルや正規表現は Unicode を前提としています。そして入出力のためには、これまで使われてきたさまざまな文字コードに対応するモジュール、「 Encode 」が標準装備されており、Unicode とこれらの文字コードの相互変換も簡単に行えるようになっています。
14
15現時点で Encode がサポートする文字コードは以下のとおりです。
16
17  7bit-jis      AdobeStandardEncoding AdobeSymbol       AdobeZdingbat
18  ascii             big5              big5-hkscs        cp1006
19  cp1026            cp1047            cp1250            cp1251
20  cp1252            cp1253            cp1254            cp1255
21  cp1256            cp1257            cp1258            cp37
22  cp424             cp437             cp500             cp737
23  cp775             cp850             cp852             cp855
24  cp856             cp857             cp860             cp861
25  cp862             cp863             cp864             cp865
26  cp866             cp869             cp874             cp875
27  cp932             cp936             cp949             cp950
28  dingbats          euc-cn            euc-jp            euc-kr
29  gb12345-raw       gb2312-raw        gsm0338           hp-roman8
30  hz                iso-2022-jp       iso-2022-jp-1     iso-8859-1
31  iso-8859-10       iso-8859-11       iso-8859-13       iso-8859-14
32  iso-8859-15       iso-8859-16       iso-8859-2        iso-8859-3
33  iso-8859-4        iso-8859-5        iso-8859-6        iso-8859-7
34  iso-8859-8        iso-8859-9        iso-ir-165        jis0201-raw
35  jis0208-raw       jis0212-raw       johab             koi8-f
36  koi8-r            koi8-u            ksc5601-raw       MacArabic
37  MacCentralEurRoman  MacChineseSimp    MacChineseTrad    MacCroatian
38  MacCyrillic       MacDingbats       MacFarsi          MacGreek
39  MacHebrew         MacIcelandic      MacJapanese       MacKorean
40  MacRoman          MacRomanian       MacRumanian       MacSami
41  MacSymbol         MacThai           MacTurkish        MacUkrainian
42  nextstep          posix-bc          shiftjis          symbol
43  UCS-2BE           UCS-2LE           UTF-16            UTF-16BE
44  UTF-16LE          UTF-32            UTF-32BE          UTF-32LE
45  utf8              viscii                              
46
47(全114種類)
48
49例えば、文字コードFOOのファイルをUTF-8に変換するには、以下のようにします。
50
51    perl -Mencoding=FOO,STDOUT,utf8 -pe1 < file.FOO > file.utf8
52
53また、Perlには、全部がPerlで書かれた文字コード変換ユーティリティ、piconvも付属しているので、以下のようにすることもできます。
54
55   piconv -f FOO -t utf8 < file.FOO > file.utf8
56   piconv -f utf8 -t FOO < file.utf8 > file.FOO
57
58=head2 About (jcode.pl|Jcode.pm|JPerl)
59
605.8以前の、スクリプトがEUC-JPであればリテラルだけは扱うことができました。また、入出力を扱うモジュールとしてはJcode.pmが( http://openlab.ring.gr.jp/Jcode/ )、perl4用のユーティリティとしてはjcode.plがそれぞれ存在し、日本語の扱えるCGIでよく利用されていることを御存じの方も少なくないかと思われます。ただし、日本語による正規表現をうまく扱うことは不可能でした。
61
625.005以前のPerlには、日本語に特化したローカライズ版、Jperlが存在しました( http://homepage2.nifty.com/kipp/perl/jperl/index.html )。また、Mac OS 9.x/Classic用のPerl、MacPerlの日本語版もMacJPerlとして存在してました。( http://habilis.net/macjperl/ ).これらでは文字コードとしてEUC-JPに加えShift_JISもそのまま扱うことができ、また日本語による正規表現を扱うことも可能でした。
63
64Perl5.8では、これらの機能がすべてPerl本体だけで実現できる上に、日本語のみならず上記114の文字コードをすべて、しかも同時に扱うことができます。さらに、CPANなどから新しい文字コード用のモジュールを入手することも簡単にできるようになっています。
65
66=over 4
67
68=item *
69
70入出力
71
72以下の例はいづれもShift_JISの入力をEUC-JPに変換して出力します。
73
74  # jcode.pl
75  require "jcode.pl";
76  while(<>){
77    jcode::convert(*_, 'euc', 'sjis');
78    print;
79  }
80  # Jcode.pm
81  use Jcode;
82  while(<>){
83  	print Jcode->new($_, 'sjis')->euc;
84  }
85  # Perl 5.8
86  use Encode;
87  while(<>){
88    from_to($_, 'shiftjis', 'euc-jp');
89    print;
90  }
91  # Perl 5.8 - encoding を利用して
92  use encoding 'euc-jp', STDIN => 'shiftjis';
93  while(<>){
94  	print;
95  }
96
97=item *
98
99Jperl 互換スクリプト
100
101いわゆる"shebang"を変更するだけで、Jperl用のscriptのほとんどは変更なしに利用可能だと思われます。
102
103   #!/path/to/jperl
104105   #!/path/to/perl -Mencoding=euc-jp
106
107詳しくは perldoc encoding を参照してください。
108
109=back
110
111=head2 さらに詳しく
112
113Perlには膨大な資料が付属しており、Perlの新機能やUnicodeサポート、そしてEncodeモジュールの使用法などが細かく網羅されています(残念ながら、ほとんど英語ではありますが)。以下のコマンドでそれらの一部を閲覧することが可能です。
114
115  perldoc perlunicode # PerlのUnicodeサポート全般
116  perldoc Encode      # Encodeモジュールに関して
117  perldoc Encode::JP  # うち日本語文字コードに関して
118
119=head2 Perl全般に関する URL
120
121=over 4
122
123=item L<http://www.perl.com/>
124
125Perl ホームページ (O'Reilly and Associates)
126
127=item L<http://www.cpan.org/>
128
129CPAN (Comprehensive Perl Archive Network)
130
131=item L<http://lists.perl.org/>
132
133Perl メーリングリスト集
134
135=back
136
137=head2 Perlの修得に役立つ URL
138
139=over 4
140
141=item L<http://www.oreilly.com.tw/>
142
143O'Reilly 社のPerl関連書籍(繁体字中国語)
144
145=item L<http://www.oreilly.com.cn/>
146
147O'Reilly 社のPerl関連書籍(簡体字中国語)
148
149=item L<http://www.oreilly.co.jp/catalog/>
150
151オライリー社のPerl関連書籍(日本語)
152
153=back
154
155=head2 Perl ユーザーグループ
156
157=over 4
158
159=item L<http://www.pm.org/groups/asia.html>
160
161=back
162
163=head2 Unicode関連のURL
164
165=over 4
166
167=item L<http://www.unicode.org/>
168
169Unicode コンソーシアム (Unicode規格の選定団体)
170
171=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
172
173UTF-8 and Unicode FAQ for Unix/Linux
174
175=item L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>
176
177UTF-8 and Unicode FAQ for Unix/Linux (ハングル訳)
178
179=back
180
181=head1 AUTHORS
182
183Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
184Dan Kogai (小飼 弾) E<lt>dankogai@dan.co.jpE<gt>
185
186=cut
187

README.ko

1=encoding utf8
2
3이 파일을 내용 그대로 읽고 있다면 우스꽝스러운 문자는 무시해주세요.
4이 문서는 POD로 읽을 수 있도록 POD 형식(F<pod/perlpod.pod> 문서를
5확인하세요)으로 작성되어 있습니다.
6
7
8=head1 NAME
9
10perlko - 한국어 Perl 안내서
11
12=head1 DESCRIPTION
13
14Perl의 세계에 오신 것을 환영합니다!
15
16Perl은 가끔 B<'Practical Extraction and Report Language'>라고 하기도 합니다만
17다른 널리 알려진 것들 중에서 B<'Pathologically Eclectic Rubbish Lister'>라고
18하기도 합니다. 사실 이것은 끼워 맞춘 것이며 Perl이 이것들의 첫 글자를
19가져와서 이름을 붙인 것은 아닙니다. Perl의 창시자 Larry가 첫 번째 이름을
20먼저 생각했고 널리 알려진 것을 나중에 지었기 때문입니다. 그렇기 때문에
21B<'Perl'>은 모두 대문자가 아닙니다. 널리 알려진 어떤 것을 가지고 논쟁하는
22것은 의미가 없습니다. Larry는 두 개 다 지지합니다.
23
24가끔 p가 소문자로 작성된 B<'perl'>을 볼 것입니다. P가 대문자로 되어 있는
25B<'Perl'>은 언어를 참조할 때 쓰이며 B<'perl'>처럼 p가 소문자인 경우는 여러분의
26프로그램을 컴파일하고 돌릴 때 사용되는 해석기를 지칭할 때 사용됩니다.
27
28
29=head1 Perl에 관하여
30
31Perl은 본래 문자열 생성을 위해 만들졌지만 지금은 시스템 관리와 웹 개발,
32네트워크 프로그래밍, GUI 개발 등을 포함한 여러 분야에서 널리 사용되는
33범용 프로그래밍 언어입니다.
34
35이 언어는 아름다움(아주 작고, 우아하고, 아주 적고)보다
36실용적(사용하기 쉽고, 효율적이며, 가능한 최대한)인 것을 지향하고 있습니다.
37사용하기 쉽고, 절차적 프로그래밍과 객체 지향 프로그래밍을 모두 지원하고,
38강력한 문자열 처리 기능을 내장하고, 세상에서 가장 인상적인 제 3자의 모듈
39모음처를 가지고 있다는 것은 Perl의 가장 중요한 특징입니다.
40
41Perl의 언어적 특징은 F<pod/perlintro.pod> 문서에서 소개합니다.
42
43이번 릴리스에서 가장 중요한 변화는 F<pod/perldelta.pod>에서 논의합니다.
44
45또한 다양한 출판사가 출판한 많은 Perl 책은 다양한 주제를 다루고 있습니다.
46자세한 정보는 F<pod/perlbook.pod> 문서를 확인하세요.
47
48
49=head1 설치
50
51여러분이 비교적 현대의 운영체제를 사용하고 있고 현재 버전의 Perl을
52지역적으로 설치하고 싶다면 다음 명령을 실행하세요.
53
54    ./Configure -des -Dprefix=$HOME/localperl
55    make test
56    make install
57
58앞의 명령은 여러분의 플랫폼에 맞게 환경을 설정하고 컴파일을 수행한 후,
59회기 테스트를 수행한뒤, 홈 디렉터리 하부의 F<localperl> 디렉터리에 perl을
60설치합니다.
61
62여러분이 어떠한 문제든 겪게 되거나 사용자 정의 버전 Perl을 설치할 필요가 있다면
63현재 배포판에 들어있는 F<INSTALL> 파일 안의 자세한 설명을 읽어야 합니다.
64추가적으로 일반적이지 않은 다양한 플랫폼에서 Perl을 빌드하고 사용하는
65방법에 대한 도움말과 귀띔이 적혀있는 많은 수의 F<README> 파일이 있습니다.
66
67일단 Perl을 설치하고 나면 C<perldoc> 도구를 이용해 풍부한 문서를 사용할
68수 있습니다. 시작하기 위해서 다음 명령을 실행하세요.
69
70    perldoc perl
71
72
73=head1 실행에 어려움을 겪는다면
74
75Perl은 뜨개질에서 부터 로켓 과학까지 모든 분야에서 사용할 수 있는 크고
76복잡한 시스템입니다. 여러분이 어려움에 부딪혔을때 그 문제는 이미 다른
77사람이 해결했을 가능성이 높습니다. 문서를 모두 확인했는데도 버그가
78확실하다면 C<perlbug> 도구를 이용해서 저희에게 버그를 보고해주세요.
79C<perlbug>에 대한 더 자세한 정보는 C<perldoc perlbug> 또는 C<perlbug>를
80명령줄에서 실행해서 확인할 수 있습니다.
81
82Perl을 사용 가능하게 만들었다 하더라도 Perl은 계속해서 진화하기 때문에
83여러분이 맞닥뜨린 버그를 수정했거나 여러분이 유용하다고 생각할법한
84새로운 기능이 추가된 좀 더 최신 버전이 있을 수 있습니다.
85
86여러분은 항상 최신 버전의 perl을 CPAN (Comprehensive Perl Archive Network)
87사이트 L<http://www.cpan.org/src/> 에서 찾을 수 있습니다.
88
89perl 소스에 간단한 패치를 등록하고 싶다면 F<pod/perlhack.pod> 문서의
90B<"SUPER QUICK PATCH GUIDE">를 살펴보세요.
91
92그냥 개인적으로 참고하세요.
93제가 이것처럼 멋진 물건을 만든다는 것을 여러분이 알기를 바랍니다.
94그것은 제 이야기의 B<"저자(Author)">를 기쁘게하기 때문입니다.
95이것이 여러분을 귀찮게 한다면 여러분의 B<"저작(Authorship)">에
96대한 생각을 정정해야 할 수도 있습니다. 하지만 어쨌거나 여러분은
97Perl을 사용하는데는 문제가 없답니다. :-)
98
99- B<"저자">로부터.
100
101
102=head1 인코딩
103
104Perl은 5.8.0판부터 유니코드/ISO 10646에 대해 광범위하게 지원합니다.
105유니코드 지원의 일환으로 한중일을 비롯한 세계 각국에서
106유니코드 이전에 쓰고 있었고 지금도 널리 쓰이고 있는 수많은 인코딩을
107지원합니다. 유니코드는 전 세계에서 쓰이는 모든 언어를 위한
108표기 체계(유럽의 라틴 알파벳, 키릴 알파벳, 그리스 알파벳, 인도와 동남 아시아의
109브라미 계열 스크립트, 아랍 문자, 히브리 문자, 한중일의 한자, 한국어의 한글,
110일본어의 가나, 북미 인디안의 표기 체계 등)를 수용하는 것을 목표로 하고
111있기 때문에 기존에 쓰이던  각 언어 및 국가 그리고 운영 체계에 고유한
112문자 집합과 인코딩에 쓸 수 있는 모든 글자는 물론이고  기존 문자 집합에서
113지원하고 있지 않던 아주 많은 글자를  포함하고 있습니다.
114
115Perl은 내부적으로 유니코드를 문자 표현을 위해 사용합니다.
116보다 구체적으로 말하면 Perl 스크립트 안에서  UTF-8 문자열을 쓸 수 있고,
117각종 함수와 연산자(예를 들어, 정규식, index, substr)가 바이트 단위
118대신 유니코드 글자 단위로 동작합니다.
119더 자세한 것은 F<pod/perlunicode.pod> 문서를 참고하세요.
120유니코드가 널리 보급되기 전에 널리 쓰이고 있었고, 여전히 널리 쓰이고 있는
121각국/각 언어별 인코딩으로 입출력을 하고 이들 인코딩으로 된 데이터와 문서를
122다루는 것을 돕기 위해 L<Encode> 모듈이 쓰이고 있습니다.
123무엇보다 L<Encode> 모듈을 사용하면 수많은 인코딩 사이의 변환을 쉽게 할 수 있습니다.
124
125
126=head2 Encode 모듈
127
128=head3 지원 인코딩
129
130L<Encode> 모듈은 다음과 같은 한국어 인코딩을 지원합니다.
131
132=over 4
133
134=item * C<euc-kr>
135
136US-ASCII와 KS X 1001을 같이 쓰는 멀티바이트 인코딩으로 흔히
137완성형이라고 불림. KS X 2901과 RFC 1557 참고.
138
139=item * C<cp949>
140
141MS-Windows 9x/ME에서 쓰이는 확장 완성형. euc-kr에 8,822자의
142한글 음절을 더한 것임. alias는 uhc, windows-949, x-windows-949,
143ks_c_5601-1987. 맨 마지막 이름은 적절하지 않은 이름이지만, Microsoft
144제품에서 CP949의 의미로 쓰이고 있음.
145
146=item * C<johab>
147
148KS X 1001:1998 부록 3에서 규정한 조합형. 문자 레퍼토리는 cp949와 마찬가지로
149US-ASCII와  KS X 1001에 8,822자의 한글 음절을 더한 것으로 인코딩 방식은 전혀 다름.
150
151=item * C<iso-2022-kr>
152
153RFC 1557에서 규정한 한국어 인터넷 메일 교환용 인코딩으로 US-ASCII와
154KS X 1001을 레퍼토리로 하는 점에서 euc-kr과 같지만 인코딩 방식이 다름.
1551997-8년 경까지 쓰였으나 더 이상 메일 교환에 쓰이지 않음.
156
157=item * C<ksc5601-raw>
158
159KS X 1001(KS C 5601)을 GL(즉, MSB를 0으로 한 경우)에 놓았을 때의 인코딩.
160US-ASCII와 결합하지 않고 단독으로 쓰이는 일은 X11 등에서 글꼴
161인코딩(ksc5601.1987-0. '0'은 GL을 의미함)으로 쓰이는 것을 제외하고는
162거의 없음. KS C 5601은 1997년 KS X 1001로 이름을 바꾸었음. 1998년에는 두
163글자(유로화 부호와 등록 상표 부호)가 더해졌음.
164
165=back
166
167=head3 변환 예제
168
169예를 들어, euc-kr 인코딩으로 된 파일을 UTF-8로 변환하려면
170명령줄에서 다음처럼 실행합니다.
171
172    perl -Mencoding=euc-kr,STDOUT,utf8 -pe1 < file.euc-kr > file.utf8
173
174반대로 변환할 경우 다음처럼 실행합니다.
175
176    perl -Mencoding=utf8,STDOUT,euc-kr -pe1 < file.utf8 > file.euc-kr
177
178이런 변환을 좀더 편리하게 할 수 있도록 도와주는 F<piconv>가 Perl에
179기본으로 들어있습니다. 이 유틸리티는 L<Encode> 모듈을 이용한 순수 Perl
180유틸리티로 이름에서 알 수 있듯이 Unix의 C<iconv>를 모델로 한 것입니다.
181사용법은 다음과 같습니다.
182
183   piconv -f euc-kr -t utf8 < file.euc-kr > file.utf8
184   piconv -f utf8 -t euc-kr < file.utf8 > file.euc-kr
185
186=head3 모범 사례
187
188Perl은 기본적으로 내부에서 UTF-8을 사용하며 Encode 모듈을 통해
189다양한 인코딩을 지원하지만 항상 다음 규칙을 지킴으로써 인코딩과
190관련한 다양하게 발생할 수 있는 문제의 가능성을 줄이는 것을 추천합니다.
191
192=over 4
193
194=item * 소스 코드는 항상 UTF-8 인코딩으로 저장
195
196=item * 소스 코드 상단에 C<use utf8;> 프라그마 사용
197
198=item * 소스 코드, 터미널, 운영체제, 데이터 인코딩을 분리해서 이해
199
200=item * 입출력 파일 핸들에 명시적인 인코딩을 사용
201
202=item * 중복(double) 인코딩을 주의
203
204=back
205
206
207=head3 유니코드 및 한국어 인코딩 관련 자료
208
209=over 4
210
211=item * L<perluniintro>
212
213=item * L<perlunicode>
214
215=item * L<Encode>
216
217=item * L<Encode::KR>
218
219=item * L<encoding>
220
221=item * L<http://www.unicode.org/>
222
223유니코드 컨소시엄
224
225=item * L<http://std.dkuug.dk/JTC1/SC2/WG2>
226
227기본적으로 Unicode와 같은 ISO 표준인  ISO/IEC 10646 UCS(Universal
228Character Set)을 만드는 ISO/IEC JTC1/SC2/WG2의 웹 페이지
229
230=item * L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
231
232유닉스/리눅스 사용자를 위한 UTF-8 및 유니코드 관련 FAQ
233
234=item * L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>
235
236유닉스/리눅스 사용자를 위한 UTF-8 및 유니코드 관련 FAQ의 한국어 번역
237
238=back
239
240
241=head1 Perl 관련 자료
242
243다음은 공식적인 Perl 관련 자료중 일부입니다.
244
245=over 4
246
247=item * L<http://www.perl.org/>
248
249Perl 공식 홈페이지
250
251=item * L<http://www.perl.com/>
252
253O'Reilly의 Perl 웹 페이지
254
255=item * L<http://www.cpan.org/>
256
257CPAN - Comprehensive Perl Archive Network, 통합적 Perl 파일 보관 네트워크
258
259=item * L<http://metacpan.org>
260
261메타 CPAN
262
263=item * L<http://lists.perl.org/>
264
265Perl 메일링 리스트
266
267=item * L<http://blogs.perl.org/>
268
269Perl 메타 블로그
270
271=item * L<http://www.perlmonks.org/>
272
273Perl 수도승들을 위한 수도원
274
275=item * L<http://www.pm.org/groups/asia.html>
276
277아시아 지역 Perl 몽거스 모임
278
279=item * L<http://www.perladvent.org/>
280
281Perl 크리스마스 달력
282
283=back
284
285
286다음은 Perl을 더 깊게 공부하는데 도움을 줄 수 있는 한국어 관련 사이트입니다.
287
288=over 4
289
290=item * L<http://perl.kr/>
291
292한국 Perl 커뮤니티 공식 포털
293
294=item * L<http://doc.perl.kr/>
295
296Perl 문서 한글화 프로젝트
297
298=item * L<http://cafe.naver.com/perlstudy.cafe>
299
300네이버 Perl 카페
301
302=item * L<http://www.perl.or.kr/>
303
304한국 Perl 사용자 모임
305
306=item * L<http://advent.perl.kr>
307
308Seoul.pm Perl 크리스마스 달력 (2010 ~ 2012)
309
310=item * L<http://gypark.pe.kr/wiki/Perl>
311
312GYPARK(Geunyoung Park)의 Perl 관련 한글 문서 저장소
313
314=item * L<http://seoul.pm.org>
315
316Seoul.pm - 서울 Perl 몽거스
317
318=back
319
320
321=head1 라이센스
322
323F<README> 파일의 B<'LICENSING'> 항목을 참고하세요.
324
325
326=head1 AUTHORS
327
328=over
329
330=item * Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
331
332=item * 신정식 E<lt>jshin@mailaps.orgE<gt>
333
334=item * 김도형 E<lt>keedi@cpan.orgE<gt>
335
336=back
337
338
339=cut
340

README.linux

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perllinux - Perl version 5 on Linux systems
8
9=head1 DESCRIPTION
10
11This document describes various features of Linux that will affect how Perl
12version 5 (hereafter just Perl) is compiled and/or runs.
13
14=head2 Experimental Support for Sun Studio Compilers for Linux OS
15
16Sun Microsystems has released a port of their Sun Studio compilers for
17Linux.  As of November 2005, only an alpha version has been released.  
18Until a release of these compilers is made, support for compiling Perl with
19these compiler experimental.
20
21Also, some special instructions for building Perl with Sun Studio on Linux.
22Following the normal C<Configure>, you have to run make as follows:
23
24    LDLOADLIBS=-lc make
25
26C<LDLOADLIBS> is an environment variable used by the linker to link modules
27C</ext> modules to glibc.  Currently, that environment variable is not getting
28populated by a combination of C<Config> entries and C<ExtUtil::MakeMaker>.
29While there may be a bug somewhere in Perl's configuration or
30C<ExtUtil::MakeMaker> causing the problem, the most likely cause is an
31incomplete understanding of Sun Studio by this author.  Further investigation
32is needed to get this working better.
33
34=head1 AUTHOR
35
36Steve Peters <steve@fisharerojo.org>
37
38Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
39
40

README.macos

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlmacos - Perl under Mac OS (Classic)
8
9=head1 SYNOPSIS
10
11For Mac OS X see README.macosx
12
13Perl under Mac OS Classic has not been supported since before Perl 5.10
14(April 2004).
15
16When we say "Mac OS" below, we mean Mac OS 7, 8, and 9, and I<not>
17Mac OS X.
18
19=head1 DESCRIPTION
20
21The port of Perl to to Mac OS was officially removed as of Perl 5.12,
22though the last official production release of MacPerl corresponded to 
23Perl 5.6. While Perl 5.10 included the port to Mac OS, ExtUtils::MakeMaker,
24a core part of Perl's module installation infrastructure officially dropped support for Mac OS in April 2004.
25
26=head1 AUTHOR
27
28Perl was ported to Mac OS by Matthias Neeracher
29E<lt>neeracher@mac.comE<gt>. Chris Nandor E<lt>pudge@pobox.comE<gt>
30continued development and maintenance for the duration of the port's life.
31

README.macosx

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlmacosx - Perl under Mac OS X
8
9=head1 SYNOPSIS
10
11This document briefly describes Perl under Mac OS X.
12
13  curl -O http://www.cpan.org/src/perl-5.23.6.tar.gz
14  tar -xzf perl-5.23.6.tar.gz
15  cd perl-5.23.6
16  ./Configure -des -Dprefix=/usr/local/
17  make
18  make test
19  sudo make install
20
21=head1 DESCRIPTION
22
23The latest Perl release (5.23.6 as of this writing) builds without changes
24under all versions of Mac OS X from 10.3 "Panther" onwards. 
25
26In order to build your own version of Perl you will need 'make',
27which is part of Apple's developer tools - also known as Xcode. From
28Mac OS X 10.7 "Lion" onwards, it can be downloaded separately as the
29'Command Line Tools' bundle directly from L<https://developer.apple.com/downloads/>
30(you will need a free account to log in), or as a part of the Xcode suite,
31freely available at the App Store. Xcode is a pretty big app, so
32unless you already have it or really want it, you are advised to get the
33'Command Line Tools' bundle separately from the link above. If you want
34to do it from within Xcode, go to Xcode -> Preferences -> Downloads and
35select the 'Command Line Tools' option.
36
37Between Mac OS X 10.3 "Panther" and 10.6 "Snow Leopard", the 'Command
38Line Tools' bundle was called 'unix tools', and was usually supplied
39with Mac OS install DVDs.
40
41Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a
42completely thread-safe libc, so threading is not fully supported. Also,
43earlier releases included a buggy libdb, so some of the DB_File tests
44are known to fail on those releases.
45
46
47=head2 Installation Prefix
48
49The default installation location for this release uses the traditional
50UNIX directory layout under /usr/local. This is the recommended location
51for most users, and will leave the Apple-supplied Perl and its modules
52undisturbed.
53
54Using an installation prefix of '/usr' will result in a directory layout
55that mirrors that of Apple's default Perl, with core modules stored in
56'/System/Library/Perl/${version}', CPAN modules stored in
57'/Library/Perl/${version}', and the addition of
58'/Network/Library/Perl/${version}' to @INC for modules that are stored
59on a file server and used by many Macs.
60
61
62=head2 SDK support
63
64First, export the path to the SDK into the build environment:
65
66    export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk
67
68Please make sure the SDK version (i.e. the numbers right before '.sdk')
69matches your system's (in this case, Mac OS X 10.8 "Mountain Lion"), as it is
70possible to have more than one SDK installed. Also make sure the path exists
71in your system, and if it doesn't please make sure the SDK is properly
72installed, as it should come with the 'Command Line Tools' bundle mentioned
73above. Finally, if you have an older Mac OS X (10.6 "Snow Leopard" and below)
74running Xcode 4.2 or lower, the SDK path might be something like
75C<'/Developer/SDKs/MacOSX10.3.9.sdk'>.
76
77You can use the SDK by exporting some additions to Perl's 'ccflags' and '..flags'
78config variables:
79
80    ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc \
81                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
82                           -F$SDK/System/Library/Frameworks" \
83                -Aldflags="-Wl,-syslibroot,$SDK" \
84                -de
85
86=head2 Universal Binary support
87
88Note: From Mac OS X 10.6 "Snow Leopard" onwards, Apple only supports
89Intel-based hardware. This means you can safely skip this section unless
90you have an older Apple computer running on ppc or wish to create a perl
91binary with backwards compatibility.
92
93You can compile perl as a universal binary (built for both ppc and intel).
94In Mac OS X 10.4 "Tiger", you must export the 'u' variant of the SDK:
95
96    export SDK=/Developer/SDKs/MacOSX10.4u.sdk
97
98Mac OS X 10.5 "Leopard" and above do not require the 'u' variant.
99
100In addition to the compiler flags used to select the SDK, also add the flags
101for creating a universal binary:
102
103    ./Configure -Accflags="-arch i686 -arch ppc -nostdinc -B$SDK/usr/include/gcc \
104                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
105                           -F$SDK/System/Library/Frameworks" \
106                -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK" \
107                -de
108
109Keep in mind that these compiler and linker settings will also be used when
110building CPAN modules. For XS modules to be compiled as a universal binary, any
111libraries it links to must also be universal binaries. The system libraries that
112Apple includes with the 10.4u SDK are all universal, but user-installed libraries
113may need to be re-installed as universal binaries.
114
115=head2 64-bit PPC support
116
117Follow the instructions in F<INSTALL> to build perl with support for 64-bit 
118integers (C<use64bitint>) or both 64-bit integers and 64-bit addressing
119(C<use64bitall>). In the latter case, the resulting binary will run only
120on G5-based hosts.
121
122Support for 64-bit addressing is experimental: some aspects of Perl may be
123omitted or buggy. Note the messages output by F<Configure> for further 
124information. Please use C<perlbug> to submit a problem report in the
125event that you encounter difficulties.
126
127When building 64-bit modules, it is your responsibility to ensure that linked
128external libraries and frameworks provide 64-bit support: if they do not,
129module building may appear to succeed, but attempts to use the module will
130result in run-time dynamic linking errors, and subsequent test failures.
131You can use C<file> to discover the architectures supported by a library:
132
133    $ file libgdbm.3.0.0.dylib 
134    libgdbm.3.0.0.dylib: Mach-O fat file with 2 architectures
135    libgdbm.3.0.0.dylib (for architecture ppc):      Mach-O dynamically linked shared library ppc
136    libgdbm.3.0.0.dylib (for architecture ppc64):    Mach-O 64-bit dynamically linked shared library ppc64
137
138Note that this issue precludes the building of many Macintosh-specific CPAN
139modules (C<Mac::*>), as the required Apple frameworks do not provide PPC64
140support. Similarly, downloads from Fink or Darwinports are unlikely to provide
14164-bit support; the libraries must be rebuilt from source with the appropriate
142compiler and linker flags. For further information, see Apple's
143I<64-Bit Transition Guide> at 
144L<http://developer.apple.com/documentation/Darwin/Conceptual/64bitPorting/index.html>.
145
146=head2 libperl and Prebinding
147
148Mac OS X ships with a dynamically-loaded libperl, but the default for
149this release is to compile a static libperl. The reason for this is
150pre-binding. Dynamic libraries can be pre-bound to a specific address in
151memory in order to decrease load time. To do this, one needs to be aware
152of the location and size of all previously-loaded libraries. Apple
153collects this information as part of their overall OS build process, and
154thus has easy access to it when building Perl, but ordinary users would
155need to go to a great deal of effort to obtain the information needed
156for pre-binding.
157
158You can override the default and build a shared libperl if you wish
159(S<Configure ... -Duseshrplib>).
160
161With Mac OS X 10.4 "Tiger" and newer, there is almost no performance
162penalty for non-prebound libraries. Earlier releases will suffer a greater
163load time than either the static library, or Apple's pre-bound dynamic library.
164
165=head2 Updating Apple's Perl
166
167In a word - don't, at least not without a *very* good reason. Your scripts
168can just as easily begin with "#!/usr/local/bin/perl" as with
169"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
170part of installation packages and such have generally only been tested
171with the /usr/bin/perl that's installed by Apple.
172
173If you find that you do need to update the system Perl, one issue worth
174keeping in mind is the question of static vs. dynamic libraries. If you
175upgrade using the default static libperl, you will find that the dynamic
176libperl supplied by Apple will not be deleted. If both libraries are
177present when an application that links against libperl is built, ld will
178link against the dynamic library by default. So, if you need to replace
179Apple's dynamic libperl with a static libperl, you need to be sure to
180delete the older dynamic library after you've installed the update.
181
182
183=head2 Known problems
184
185If you have installed extra libraries such as GDBM through Fink
186(in other words, you have libraries under F</sw/lib>), or libdlcompat
187to F</usr/local/lib>, you may need to be extra careful when running
188Configure to not to confuse Configure and Perl about which libraries
189to use.  Being confused will show up for example as "dyld" errors about
190symbol problems, for example during "make test". The safest bet is to run
191Configure as
192
193    Configure ... -Uloclibpth -Dlibpth=/usr/lib
194
195to make Configure look only into the system libraries.  If you have some
196extra library directories that you really want to use (such as newer
197Berkeley DB libraries in pre-Panther systems), add those to the libpth:
198
199    Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'
200
201The default of building Perl statically may cause problems with complex
202applications like Tk: in that case consider building shared Perl
203
204    Configure ... -Duseshrplib
205
206but remember that there's a startup cost to pay in that case (see above
207"libperl and Prebinding").
208
209Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
210the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
211failures in the F<lib/locale> test. These failures have been suppressed
212in the current release of Perl by making the test ignore the broken locale.
213If you need to use the eu_ES locale, you should contact Apple support.
214
215
216=head2 Cocoa
217
218There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
219module, included with Mac OS X, can be used by standalone scripts to
220access Foundation (i.e. non-GUI) classes and objects.
221
222An alternative is CamelBones, a framework that allows access to both
223Foundation and AppKit classes and objects, so that full GUI applications
224can be built in Perl. CamelBones can be found on SourceForge, at
225L<http://www.sourceforge.net/projects/camelbones/>.
226
227
228=head1 Starting From Scratch
229
230Unfortunately it is not that difficult somehow manage to break one's
231Mac OS X Perl rather severely.  If all else fails and you want to
232really, B<REALLY>, start from scratch and remove even your Apple Perl
233installation (which has become corrupted somehow), the following
234instructions should do it.  B<Please think twice before following
235these instructions: they are much like conducting brain surgery to
236yourself.  Without anesthesia.>  We will B<not> come to fix your system
237if you do this.
238
239First, get rid of the libperl.dylib:
240
241    # cd /System/Library/Perl/darwin/CORE
242    # rm libperl.dylib
243
244Then delete every .bundle file found anywhere in the folders:
245
246    /System/Library/Perl
247    /Library/Perl
248
249You can find them for example by
250
251    # find /System/Library/Perl /Library/Perl -name '*.bundle' -print
252
253After this you can either copy Perl from your operating system media
254(you will need at least the /System/Library/Perl and /usr/bin/perl),
255or rebuild Perl from the source code with C<Configure -Dprefix=/usr
256-Duseshrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
257works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
258settings were not quite right.
259
260"Pacifist" from CharlesSoft (L<http://www.charlessoft.com/>) is a nice
261way to extract the Perl binaries from the OS media, without having to
262reinstall the entire OS.
263
264
265=head1 AUTHOR
266
267This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
268and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>
269and Breno G. de Oliveira E<lt>garu@cpan.orgE<gt>. The "Starting From Scratch"
270recipe was contributed by John Montbriand E<lt>montbriand@apple.comE<gt>.
271
272=head1 DATE
273
274Last modified 2013-04-29.
275

README.micro

1microperl is supposed to be a really minimal perl, even more
2minimal than miniperl.  No Configure is needed to build microperl,
3on the other hand this means that interfaces between Perl and your
4operating system are left very -- minimal.
5
6All this is experimental.  If you don't know what to do with microperl
7you probably shouldn't.  Please don't report bugs in microperl; fix the
8bugs.  (Bugs reports about microperl without fixes/patches are equivalent
9to wishlist requests - they won't be discarded, but they likely won't get
10worked on either, unless they chance to coincide with someone's personal itch)
11
12We assume ANSI C89 plus the following:
13- <stddef.h>, <stdlib.h>
14- rename()
15- opendir(), readdir(), closedir() (via dirent.h)
16- memchr(), memcmp(), memcpy(), memset() (via string.h)
17- (a safe) putenv() (via stdlib.h)
18- strtoul() (via stdlib.h)
19(grep for 'define' in uconfig.sh.)
20Also, Perl times() is defined to always return zeroes.
21
22If you are still reading this and you are itching to try out microperl:
23
24	make -f Makefile.micro
25
26The defaults assume a little endian LP32 platform - ie long and pointers are
2732 bits, so sizeof(long) and sizeof(void *) are 4
28If your platform is little endian LP64 - ie long and pointers are 64 bits,
29sizeof(long) and sizeof(void *) are 8, then you first need to run
30
31	make -f Makefile.micro regen_uconfig64
32
33to generate a suitable uconfig.h
34
35If you make changes to uconfig.sh, run
36
37	make -f Makefile.micro regen_uconfig
38
39to regenerate uconfig.h.  (or regen_uconfig64 if you're editing uconfig64.sh)
40
41
42If neither of the above default configs work on your platform, you might want
43to try
44
45	make -f Makefile.micro patch_uconfig
46
47*before* the "make -f Makefile.micro".  This tries to minimally patch
48the uconfig.sh using your *current* Perl so that your microperl has
49the correct basic types and sizes and byteorder.
50

README.netware

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlnetware - Perl for NetWare
8
9=head1 DESCRIPTION
10
11This file gives instructions for building Perl 5.7 and above, and also 
12Perl modules for NetWare. Before you start, you may want to read the
13README file found in the top level directory into which the Perl source
14code distribution was extracted. Make sure you read and understand
15the terms under which the software is being distributed.
16
17=head1 BUILD
18
19This section describes the steps to be performed to build a Perl NLM
20and other associated NLMs.
21
22=head2 Tools & SDK
23
24The build requires CodeWarrior compiler and linker.  In addition,
25the "NetWare SDK", "NLM & NetWare Libraries for C" and
26"NetWare Server Protocol Libraries for C", all available at
27L<http://developer.novell.com/wiki/index.php/Category:Novell_Developer_Kit>,
28are required. Microsoft Visual C++ version 4.2 or later is also
29required.
30
31=head2 Setup
32
33The build process is dependent on the location of the NetWare SDK.
34Once the Tools & SDK are installed, the build environment has to
35be setup.  The following batch files setup the environment.
36
37=over 4
38
39=item SetNWBld.bat
40
41The Execution of this file takes 2 parameters as input. The first
42being the NetWare SDK path, second being the path for CodeWarrior
43Compiler & tools. Execution of this file sets these paths and also
44sets the build type to Release by default.
45
46=item Buildtype.bat
47
48This is used to set the build type to debug or release. Change the
49build type only after executing SetNWBld.bat
50
51Example:
52
53=over
54
55=item 1.
56
57Typing "buildtype d on" at the command prompt causes the buildtype
58to be set to Debug type with D2 flag set. 
59
60=item 2.
61
62Typing "buildtype d off" or "buildtype d" at the command prompt causes
63the buildtype to be set to Debug type with D1 flag set. 
64
65=item 3.
66
67Typing "buildtype r" at the command prompt sets it to Release Build type.
68
69=back
70
71=back
72
73=head2 Make
74
75The make process runs only under WinNT shell.  The NetWare makefile is
76located under the NetWare folder.  This makes use of miniperl.exe to
77run some of the Perl scripts. To create miniperl.exe, first set the
78required paths for Visual c++ compiler (specify vcvars32 location) at
79the command prompt.  Then run nmake from win32 folder through WinNT
80command prompt.  The build process can be stopped after miniperl.exe
81is created. Then run nmake from NetWare folder through WinNT command
82prompt.
83
84Currently the following two build types are tested on NetWare:
85
86=over 4
87
88=item *
89
90USE_MULTI, USE_ITHREADS & USE_IMP_SYS defined
91
92=item *
93
94USE_MULTI & USE_IMP_SYS defined and USE_ITHREADS not defined
95
96=back
97
98=head2 Interpreter
99
100Once miniperl.exe creation is over, run nmake from the NetWare folder.
101This will build the Perl interpreter for NetWare as I<perl.nlm>.
102This is copied under the I<Release> folder if you are doing
103a release build, else will be copied under I<Debug> folder for debug builds.
104
105=head2 Extensions
106
107The make process also creates the Perl extensions as I<<Extension>.nlm>
108
109=head1 INSTALL
110
111To install NetWare Perl onto a NetWare server, first map the Sys
112volume of a NetWare server to I<i:>. This is because the makefile by
113default sets the drive letter to I<i:>.  Type I<nmake nwinstall> from
114NetWare folder on a WinNT command prompt.  This will copy the binaries
115and module files onto the NetWare server under I<sys:\Perl>
116folder. The Perl interpreter, I<perl.nlm>, is copied under
117I<sys:\perl\system> folder.  Copy this to I<sys:\system> folder.
118
119Example: At the command prompt Type "nmake nwinstall".
120          This will install NetWare Perl on the NetWare Server.
121          Similarly, if you type "nmake install",
122          this will cause the binaries to be installed on the local machine.
123          (Typically under the c:\perl folder)
124
125=head1 BUILD NEW EXTENSIONS
126
127To build extensions other than standard extensions, NetWare Perl has
128to be installed on Windows along with Windows Perl. The Perl for
129Windows can be either downloaded from the CPAN site and built using
130the sources, or the binaries can be directly downloaded from the
131ActiveState site.  Installation can be done by invoking I<nmake
132install> from the NetWare folder on a WinNT command prompt after
133building NetWare Perl by following steps given above.  This will copy
134all the *.pm files and other required files.  Documentation files are
135not copied.  Thus one must first install Windows Perl, Then install
136NetWare Perl.
137
138Once this is done, do the following to build any extension:
139
140=over 4
141
142=item *
143
144Change to the extension directory where its source files are present.
145
146=item *
147
148Run the following command at the command prompt:
149
150    perl -II<path to NetWare lib dir> -II<path to lib> Makefile.pl
151
152Example:
153
154    perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl
155
156or
157
158    perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl
159
160=item *
161
162nmake
163
164=item *
165
166nmake install
167
168Install will copy the files into the Windows machine where NetWare
169Perl is installed and these files may have to be copied to the NetWare
170server manually. Alternatively, pass I<INSTALLSITELIB=i:\perl\lib> as
171an input to makefile.pl above. Here I<i:> is the mapped drive to the
172sys: volume of the server where Perl on NetWare is installed. Now
173typing I<nmake install>, will copy the files onto the NetWare server.
174
175Example: You can execute the following on the command prompt.
176
177  perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl
178  INSTALLSITELIB=i:\perl\lib
179
180or
181
182  perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl
183  INSTALLSITELIB=i:\perl\lib
184
185=item * 
186
187Note: Some modules downloaded from CPAN may require NetWare related
188API in order to build on NetWare.  Other modules may however build
189smoothly with or without minor changes depending on the type of
190module.
191
192=back
193
194=head1 ACKNOWLEDGEMENTS
195
196The makefile for Win32 is used as a reference to create the makefile
197for NetWare.  Also, the make process for NetWare port uses
198miniperl.exe to run scripts during the make and installation process.
199
200=head1 AUTHORS
201
202Anantha Kesari H Y (hyanantha@novell.com)
203Aditya C (caditya@novell.com)
204
205=head1 DATE
206
207=over 4
208
209=item *
210
211Created - 18 Jan 2001
212
213=item *
214
215Modified - 25 June 2001
216
217=item *
218
219Modified - 13 July 2001
220
221=item *
222
223Modified - 28 May 2002
224
225=back
226

README.openbsd

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlopenbsd - Perl version 5 on OpenBSD systems
8
9=head1 DESCRIPTION
10
11This document describes various features of OpenBSD that will affect how Perl
12version 5 (hereafter just Perl) is compiled and/or runs.
13
14=head2 OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads
15
16When Perl is configured to use ithreads, it will use re-entrant library calls
17in preference to non-re-entrant versions.  There is an incompatibility in
18OpenBSD's C<getprotobyname_r> and C<getservbyname_r> function in versions 3.7
19and later that will cause a SEGV when called without doing a C<bzero> on
20their return structs prior to calling these functions.  Current Perl's
21should handle this problem correctly.  Older threaded Perls (5.8.6 or earlier)
22will run into this problem.  If you want to run a threaded Perl on OpenBSD
233.7 or higher, you will need to upgrade to at least Perl 5.8.7.
24
25=head1 AUTHOR
26
27Steve Peters <steve@fisharerojo.org>
28
29Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
30
31

README.os2

1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see perlpod manpage) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
8
9=head1 SYNOPSIS
10
11One can read this document in the following formats:
12
13	man perlos2
14	view perl perlos2
15	explorer perlos2.html
16	info perlos2
17
18to list some (not all may be available simultaneously), or it may
19be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
20
21To read the F<.INF> version of documentation (B<very> recommended)
22outside of OS/2, one needs an IBM's reader (may be available on IBM
23ftp sites (?)  (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
24Visual Age C++ 3.5.
25
26A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
27
28  ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
29
30in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's 
31F<.INF> docs as well (text form is available in F</emx/doc> in 
32EMX's distribution).  There is also a different viewer named xview.
33
34Note that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links
35from this document in F<.INF> format. If you have EMX docs installed 
36correctly, you can follow library links (you need to have C<view emxbook>
37working by setting C<EMXBOOK> environment variable as it is described
38in EMX docs).
39
40=cut
41
42Contents (This may be a little bit obsolete)
43 
44 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 
45
46      NAME
47      SYNOPSIS
48      DESCRIPTION
49	 -  Target
50	 -  Other OSes
51	 -  Prerequisites
52	 -  Starting Perl programs under OS/2 (and DOS and...)
53	 -  Starting OS/2 (and DOS) programs under Perl
54      Frequently asked questions
55	 -  "It does not work"
56	 -  I cannot run external programs
57	 -  I cannot embed perl into my program, or use perl.dll from my
58	 -  `` and pipe-open do not work under DOS.
59	 -  Cannot start find.exe "pattern" file
60      INSTALLATION
61	 -  Automatic binary installation
62	 -  Manual binary installation
63	 -  Warning
64      Accessing documentation
65	 -  OS/2 .INF file
66	 -  Plain text
67	 -  Manpages
68	 -  HTML
69	 -  GNU info files
70	 -  PDF files
71	 -  LaTeX docs
72      BUILD
73	 -  The short story
74	 -  Prerequisites
75	 -  Getting perl source
76	 -  Application of the patches
77	 -  Hand-editing
78	 -  Making
79	 -  Testing
80	 -  Installing the built perl
81	 -  a.out-style build
82      Build FAQ
83	 -  Some / became \ in pdksh.
84	 -  'errno' - unresolved external
85	 -  Problems with tr or sed
86	 -  Some problem (forget which ;-)
87	 -  Library ... not found
88	 -  Segfault in make
89	 -  op/sprintf test failure
90      Specific (mis)features of OS/2 port
91	 -  setpriority, getpriority
92	 -  system()
93	 -  extproc on the first line
94	 -  Additional modules:
95	 -  Prebuilt methods:
96	 -  Prebuilt variables:
97	 -  Misfeatures
98	 -  Modifications
99	 -  Identifying DLLs
100	 -  Centralized management of resources
101      Perl flavors
102	 -  perl.exe
103	 -  perl_.exe
104	 -  perl__.exe
105	 -  perl___.exe
106	 -  Why strange names?
107	 -  Why dynamic linking?
108	 -  Why chimera build?
109      ENVIRONMENT
110	 -  PERLLIB_PREFIX
111	 -  PERL_BADLANG
112	 -  PERL_BADFREE
113	 -  PERL_SH_DIR
114	 -  USE_PERL_FLOCK
115	 -  TMP or TEMP
116      Evolution
117	 -  Text-mode filehandles
118	 -  Priorities
119	 -  DLL name mangling: pre 5.6.2
120	 -  DLL name mangling: 5.6.2 and beyond
121	 -  DLL forwarder generation
122	 -  Threading
123	 -  Calls to external programs
124	 -  Memory allocation
125	 -  Threads
126      BUGS
127      AUTHOR
128      SEE ALSO
129
130=head1 DESCRIPTION
131
132=head2 Target
133
134The target is to make OS/2 one of the best supported platform for
135using/building/developing Perl and I<Perl applications>, as well as
136make Perl the best language to use under OS/2. The secondary target is
137to try to make this work under DOS and Win* as well (but not B<too> hard).
138
139The current state is quite close to this target. Known limitations:
140
141=over 5
142
143=item *
144
145Some *nix programs use fork() a lot; with the mostly useful flavors of
146perl for OS/2 (there are several built simultaneously) this is
147supported; but some flavors do not support this (e.g., when Perl is
148called from inside REXX).  Using fork() after
149I<use>ing dynamically loading extensions would not work with I<very> old
150versions of EMX.
151
152=item *
153
154You need a separate perl executable F<perl__.exe> (see L</perl__.exe>)
155if you want to use PM code in your application (as Perl/Tk or OpenGL
156Perl modules do) without having a text-mode window present.
157
158While using the standard F<perl.exe> from a text-mode window is possible
159too, I have seen cases when this causes degradation of the system stability.
160Using F<perl__.exe> avoids such a degradation.
161
162=item *
163
164There is no simple way to access WPS objects. The only way I know
165is via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<SOM>).
166However, we do not have access to
167convenience methods of Object-REXX. (Is it possible at all? I know
168of no Object-REXX API.)  The C<SOM> extension (currently in alpha-text)
169may eventually remove this shortcoming; however, due to the fact that
170DII is not supported by the C<SOM> module, using C<SOM> is not as
171convenient as one would like it.
172
173=back
174
175Please keep this list up-to-date by informing me about other items.
176
177=head2 Other OSes
178
179Since OS/2 port of perl uses a remarkable EMX environment, it can
180run (and build extensions, and - possibly - be built itself) under any
181environment which can run EMX. The current list is DOS,
182DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
183only one works, see L<"perl_.exe">.
184
185Note that not all features of Perl are available under these
186environments. This depends on the features the I<extender> - most
187probably RSX - decided to implement.
188
189Cf. L</Prerequisites>.
190
191=head2 Prerequisites
192
193=over 6
194
195=item EMX
196
197EMX runtime is required (may be substituted by RSX). Note that
198it is possible to make F<perl_.exe> to run under DOS without any
199external support by binding F<emx.exe>/F<rsx.exe> to it, see C<emxbind>. Note
200that under DOS for best results one should use RSX runtime, which
201has much more functions working (like C<fork>, C<popen> and so on). In
202fact RSX is required if there is no VCPI present. Note the
203RSX requires DPMI.  Many implementations of DPMI are known to be very
204buggy, beware!
205
206Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
207under earlier versions of EMX, but this is not tested.
208
209One can get different parts of EMX from, say
210
211  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/
212  http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d/
213
214The runtime component should have the name F<emxrt.zip>.
215
216B<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One
217does not need to specify them explicitly (though this
218
219  emx perl_.exe -de 0
220
221will work as well.)
222
223=item RSX
224
225To run Perl on DPMI platforms one needs RSX runtime. This is
226needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 
227L<"Other OSes">). RSX would not work with VCPI
228only, as EMX would, it requires DMPI.
229
230Having RSX and the latest F<sh.exe> one gets a fully functional
231B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
232pipe-C<open> work. In fact, MakeMaker works (for static build), so one
233can have Perl development environment under DOS. 
234
235One can get RSX from, say
236
237  http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
238  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/
239
240Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
241
242The latest F<sh.exe> with DOS hooks is available in
243
244  http://www.ilyaz.org/software/os2/
245
246as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
247
248=item HPFS
249
250Perl does not care about file systems, but the perl library contains
251many files with long names, so to install it intact one needs a file
252system which supports long file names.
253
254Note that if you do not plan to build the perl itself, it may be
255possible to fool EMX to truncate file names. This is not supported,
256read EMX docs to see how to do it.
257
258=item pdksh
259
260To start external programs with complicated command lines (like with
261pipes in between, and/or quoting of arguments), Perl uses an external
262shell. With EMX port such shell should be named F<sh.exe>, and located
263either in the wired-in-during-compile locations (usually F<F:/bin>),
264or in configurable location (see L<"PERL_SH_DIR">).
265
266For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
267under DOS (with L</RSX>) as well, see
268
269  http://www.ilyaz.org/software/os2/
270
271=back
272
273=head2 Starting Perl programs under OS/2 (and DOS and...)
274
275Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
276same way as on any other platform, by
277
278	perl foo.pl arg1 arg2 arg3
279
280If you want to specify perl options C<-my_opts> to the perl itself (as
281opposed to your program), use
282
283	perl -my_opts foo.pl arg1 arg2 arg3
284
285Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
286the following at the start of your perl script:
287
288	extproc perl -S -my_opts
289
290rename your program to F<foo.cmd>, and start it by typing
291
292	foo arg1 arg2 arg3
293
294Note that because of stupid OS/2 limitations the full path of the perl
295script is not available when you use C<extproc>, thus you are forced to
296use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
297side, if you know a full path to your script, you may still start it
298with 
299
300	perl ../../blah/foo.cmd arg1 arg2 arg3
301
302(note that the argument C<-my_opts> is taken care of by the C<extproc> line
303in your script, see L<C<extproc> on the first line>).
304
305To understand what the above I<magic> does, read perl docs about C<-S>
306switch - see L<perlrun>, and cmdref about C<extproc>:
307
308	view perl perlrun
309	man perlrun
310	view cmdref extproc
311	help extproc
312
313or whatever method you prefer.
314
315There are also endless possibilities to use I<executable extensions> of
3164os2, I<associations> of WPS and so on... However, if you use
317*nixish shell (like F<sh.exe> supplied in the binary distribution),
318you need to follow the syntax specified in L<perlrun/"Command Switches">.
319
320Note that B<-S> switch supports scripts with additional extensions 
321F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
322
323=head2 Starting OS/2 (and DOS) programs under Perl
324
325This is what system() (see L<perlfunc/system>), C<``> (see
326L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
327are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
328do).
329
330Note however that to use some of these operators you need to have a
331sh-syntax shell installed (see L<"Pdksh">, 
332L<"Frequently asked questions">), and perl should be able to find it
333(see L<"PERL_SH_DIR">).
334
335The cases when the shell is used are:
336
337=over
338
339=item 1
340
341One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
342with redirection or shell meta-characters;
343
344=item 2
345
346Pipe-open (see L<perlfunc/open>) with the command which contains redirection 
347or shell meta-characters;
348
349=item 3
350
351Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
352redirection or shell meta-characters;
353
354=item 4
355
356If the executable called by system()/exec()/pipe-open()/C<``> is a script
357with the "magic" C<#!> line or C<extproc> line which specifies shell;
358
359=item 5
360
361If the executable called by system()/exec()/pipe-open()/C<``> is a script
362without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
363
364=item 6
365
366If the executable called by system()/exec()/pipe-open()/C<``> is not
367found (is not this remark obsolete?);
368
369=item 7
370
371For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">)
372(obsolete? Perl uses builtin globbing nowadays...).
373
374=back
375
376For the sake of speed for a common case, in the above algorithms 
377backslashes in the command name are not considered as shell metacharacters.
378
379Perl starts scripts which begin with cookies
380C<extproc> or C<#!> directly, without an intervention of shell.  Perl uses the
381same algorithm to find the executable as F<pdksh>: if the path
382on C<#!> line does not work, and contains C</>, then the directory
383part of the executable is ignored, and the executable
384is searched in F<.> and on C<PATH>.  To find arguments for these scripts
385Perl uses a different algorithm than F<pdksh>: up to 3 arguments are 
386recognized, and trailing whitespace is stripped.
387
388If a script
389does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
390the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
391script is given as the first argument to this command, if not set, then
392C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
393not set).
394
395When starting scripts directly, Perl uses exactly the same algorithm as for 
396the search of script given by B<-S> command-line option: it will look in
397the current directory, then on components of C<$ENV{PATH}> using the 
398following order of appended extensions: no extension, F<.cmd>, F<.btm>, 
399F<.bat>, F<.pl>.
400
401Note that Perl will start to look for scripts only if OS/2 cannot start the
402specified application, thus C<system 'blah'> will not look for a script if 
403there is an executable file F<blah.exe> I<anywhere> on C<PATH>.  In
404other words, C<PATH> is essentially searched twice: once by the OS for
405an executable, then by Perl for scripts.
406
407Note also that executable files on OS/2 can have an arbitrary extension, but
408F<.exe> will be automatically appended if no dot is present in the name.  The
409workaround is as simple as that:  since F<blah.> and F<blah> denote the same
410file (at list on FAT and HPFS file systems), to start an executable residing in
411file F<n:/bin/blah> (no extension) give an argument C<n:/bin/blah.> (dot
412appended) to system().
413
414Perl will start PM programs from VIO (=text-mode) Perl process in a
415separate PM session;
416the opposite is not true: when you start a non-PM program from a PM
417Perl process, Perl would not run it in a separate session.  If a separate
418session is desired, either ensure
419that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
420optional arguments to system() documented in C<OS2::Process> module.  This
421is considered to be a feature.
422
423=head1 Frequently asked questions
424
425=head2 "It does not work"
426
427Perl binary distributions come with a F<testperl.cmd> script which tries
428to detect common problems with misconfigured installations.  There is a
429pretty large chance it will discover which step of the installation you
430managed to goof.  C<;-)>
431
432=head2 I cannot run external programs
433
434=over 4
435
436=item *
437
438Did you run your programs with C<-w> switch? See 
439L<Starting OSE<sol>2 (and DOS) programs under Perl>.
440
441=item *
442
443Do you try to run I<internal> shell commands, like C<`copy a b`>
444(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
445need to specify your shell explicitly, like C<`cmd /c copy a b`>,
446since Perl cannot deduce which commands are internal to your shell.
447
448=back
449
450=head2 I cannot embed perl into my program, or use F<perl.dll> from my
451program. 
452
453=over 4
454
455=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
456
457Well, nowadays Perl DLL should be usable from a differently compiled
458program too...  If you can run Perl code from REXX scripts (see
459L<OS2::REXX>), then there are some other aspect of interaction which
460are overlooked by the current hackish code to support
461differently-compiled principal programs.
462
463If everything else fails, you need to build a stand-alone DLL for
464perl. Contact me, I did it once. Sockets would not work, as a lot of
465other stuff.
466
467=item Did you use L<ExtUtils::Embed>?
468
469Some time ago I had reports it does not work.  Nowadays it is checked
470in the Perl test suite, so grep F<./t> subdirectory of the build tree
471(as well as F<*.t> files in the F<./lib> subdirectory) to find how it
472should be done "correctly".
473
474=back
475
476=head2 C<``> and pipe-C<open> do not work under DOS.
477
478This may a variant of just L<"I cannot run external programs">, or a
479deeper problem. Basically: you I<need> RSX (see L</Prerequisites>)
480for these commands to work, and you may need a port of F<sh.exe> which
481understands command arguments. One of such ports is listed in
482L</Prerequisites> under RSX. Do not forget to set variable
483C<L<"PERL_SH_DIR">> as well.
484
485DPMI is required for RSX.
486
487=head2 Cannot start C<find.exe "pattern" file>
488
489The whole idea of the "standard C API to start applications" is that
490the forms C<foo> and C<"foo"> of program arguments are completely
491interchangeable.  F<find> breaks this paradigm;
492
493  find "pattern" file
494  find pattern file
495
496are not equivalent; F<find> cannot be started directly using the above
497API.  One needs a way to surround the doublequotes in some other
498quoting construction, necessarily having an extra non-Unixish shell in
499between.
500
501Use one of
502
503  system 'cmd', '/c', 'find "pattern" file';
504  `cmd /c 'find "pattern" file'`
505
506This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
507C<perl.exe>, but this is a price to pay if you want to use
508non-conforming program.
509
510=head1 INSTALLATION
511
512=head2 Automatic binary installation
513
514The most convenient way of installing a binary distribution of perl is via perl installer
515F<install.exe>. Just follow the instructions, and 99% of the
516installation blues would go away. 
517
518Note however, that you need to have F<unzip.exe> on your path, and
519EMX environment I<running>. The latter means that if you just
520installed EMX, and made all the needed changes to F<Config.sys>,
521you may need to reboot in between. Check EMX runtime by running
522
523	emxrev
524
525Binary installer also creates a folder on your desktop with some useful
526objects.  If you need to change some aspects of the work of the binary
527installer, feel free to edit the file F<Perl.pkg>.  This may be useful
528e.g., if you need to run the installer many times and do not want to
529make many interactive changes in the GUI.
530
531B<Things not taken care of by automatic binary installation:>
532
533=over 15
534
535=item C<PERL_BADLANG>
536
537may be needed if you change your codepage I<after> perl installation,
538and the new value is not supported by EMX. See L<"PERL_BADLANG">.
539
540=item C<PERL_BADFREE>
541
542see L<"PERL_BADFREE">.
543
544=item F<Config.pm>
545
546This file resides somewhere deep in the location you installed your
547perl library, find it out by 
548
549  perl -MConfig -le "print $INC{'Config.pm'}"
550
551While most important values in this file I<are> updated by the binary
552installer, some of them may need to be hand-edited. I know no such
553data, please keep me informed if you find one.  Moreover, manual
554changes to the installed version may need to be accompanied by an edit
555of this file.
556
557=back
558
559B<NOTE>. Because of a typo the binary installer of 5.00305
560would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
561remove this variable and put C<L</PERL_SH_DIR>> instead.
562
563=head2 Manual binary installation
564
565As of version 5.00305, OS/2 perl binary distribution comes split
566into 11 components. Unfortunately, to enable configurable binary
567installation, the file paths in the zip files are not absolute, but
568relative to some directory.
569
570Note that the extraction with the stored paths is still necessary
571(default with unzip, specify C<-d> to pkunzip). However, you
572need to know where to extract the files. You need also to manually
573change entries in F<Config.sys> to reflect where did you put the
574files. Note that if you have some primitive unzipper (like
575C<pkunzip>), you may get a lot of warnings/errors during
576unzipping. Upgrade to C<(w)unzip>.
577
578Below is the sample of what to do to reproduce the configuration on my
579machine.  In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and
580cut-and-paste from the resulting file - created in the directory you
581started F<VIEW.EXE> from.
582
583For each component, we mention environment variables related to each
584installation directory.  Either choose directories to match your
585values of the variables, or create/append-to variables to take into
586account the directories.
587
588=over 3
589
590=item Perl VIO and PM executables (dynamically linked)
591
592  unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
593  unzip perl_exc.zip *.dll -d f:/emx.add/dll
594
595(have the directories with C<*.exe> on PATH, and C<*.dll> on
596LIBPATH);
597
598=item Perl_ VIO executable (statically linked)
599
600  unzip perl_aou.zip -d f:/emx.add/bin
601
602(have the directory on PATH);
603
604=item Executables for Perl utilities
605
606  unzip perl_utl.zip -d f:/emx.add/bin
607
608(have the directory on PATH);
609
610=item Main Perl library
611
612  unzip perl_mlb.zip -d f:/perllib/lib
613
614If this directory is exactly the same as the prefix which was compiled
615into F<perl.exe>, you do not need to change
616anything. However, for perl to find the library if you use a different
617path, you need to
618C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
619
620=item Additional Perl modules
621
622  unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.23.6/
623
624Same remark as above applies.  Additionally, if this directory is not
625one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
626need to put this
627directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
628variable. Do not use C<PERL5LIB> unless you have it set already. See
629L<perl/"ENVIRONMENT">.
630
631B<[Check whether this extraction directory is still applicable with
632the new directory structure layout!]>
633
634=item Tools to compile Perl modules
635
636  unzip perl_blb.zip -d f:/perllib/lib
637
638Same remark as for F<perl_ste.zip>.
639
640=item Manpages for Perl and utilities
641
642  unzip perl_man.zip -d f:/perllib/man
643
644This directory should better be on C<MANPATH>. You need to have a
645working F<man> to access these files.
646
647=item Manpages for Perl modules
648
649  unzip perl_mam.zip -d f:/perllib/man
650
651This directory should better be on C<MANPATH>. You need to have a
652working man to access these files.
653
654=item Source for Perl documentation
655
656  unzip perl_pod.zip -d f:/perllib/lib
657
658This is used by the C<perldoc> program (see L<perldoc>), and may be used to
659generate HTML documentation usable by WWW browsers, and
660documentation in zillions of other formats: C<info>, C<LaTeX>,
661C<Acrobat>, C<FrameMaker> and so on.  [Use programs such as
662F<pod2latex> etc.]
663
664=item Perl manual in F<.INF> format
665
666  unzip perl_inf.zip -d d:/os2/book
667
668This directory should better be on C<BOOKSHELF>.
669
670=item Pdksh
671
672  unzip perl_sh.zip -d f:/bin
673
674This is used by perl to run external commands which explicitly
675require shell, like the commands using I<redirection> and I<shell
676metacharacters>. It is also used instead of explicit F</bin/sh>.
677
678Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
679the above location.
680
681B<Note.> It may be possible to use some other sh-compatible shell (untested).
682
683=back
684
685After you installed the components you needed and updated the
686F<Config.sys> correspondingly, you need to hand-edit
687F<Config.pm>. This file resides somewhere deep in the location you
688installed your perl library, find it out by
689
690  perl -MConfig -le "print $INC{'Config.pm'}"
691
692You need to correct all the entries which look like file paths (they
693currently start with C<f:/>).
694
695=head2 B<Warning>
696
697The automatic and manual perl installation leave precompiled paths
698inside perl executables. While these paths are overwriteable (see
699L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), some people may prefer
700binary editing of paths inside the executables/DLLs.
701
702=head1 Accessing documentation
703
704Depending on how you built/installed perl you may have (otherwise
705identical) Perl documentation in the following formats:
706
707=head2 OS/2 F<.INF> file
708
709Most probably the most convenient form. Under OS/2 view it as
710
711  view perl
712  view perl perlfunc
713  view perl less
714  view perl ExtUtils::MakeMaker
715
716(currently the last two may hit a wrong location, but this may improve
717soon). Under Win* see L<"SYNOPSIS">.
718
719If you want to build the docs yourself, and have I<OS/2 toolkit>, run
720
721	pod2ipf > perl.ipf
722
723in F</perllib/lib/pod> directory, then
724
725	ipfc /inf perl.ipf
726
727(Expect a lot of errors during the both steps.) Now move it on your
728BOOKSHELF path.
729
730=head2 Plain text
731
732If you have perl documentation in the source form, perl utilities
733installed, and GNU groff installed, you may use 
734
735	perldoc perlfunc
736	perldoc less
737	perldoc ExtUtils::MakeMaker
738
739to access the perl documentation in the text form (note that you may get
740better results using perl manpages).
741
742Alternately, try running pod2text on F<.pod> files.
743
744=head2 Manpages
745
746If you have F<man> installed on your system, and you installed perl
747manpages, use something like this:
748
749	man perlfunc
750	man 3 less
751	man ExtUtils.MakeMaker
752
753to access documentation for different components of Perl. Start with
754
755	man perl
756
757Note that dot (F<.>) is used as a package separator for documentation
758for packages, and as usual, sometimes you need to give the section - C<3>
759above - to avoid shadowing by the I<less(1) manpage>.
760
761Make sure that the directory B<above> the directory with manpages is
762on our C<MANPATH>, like this
763
764  set MANPATH=c:/man;f:/perllib/man
765
766for Perl manpages in C<f:/perllib/man/man1/> etc.
767
768=head2 HTML
769
770If you have some WWW browser available, installed the Perl
771documentation in the source form, and Perl utilities, you can build
772HTML docs. Cd to directory with F<.pod> files, and do like this
773
774	cd f:/perllib/lib/pod
775	pod2html
776
777After this you can direct your browser the file F<perl.html> in this
778directory, and go ahead with reading docs, like this:
779
780	explore file:///f:/perllib/lib/pod/perl.html
781
782Alternatively you may be able to get these docs prebuilt from CPAN.
783
784=head2 GNU C<info> files
785
786Users of Emacs would appreciate it very much, especially with
787C<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>,
788or, alternately, the prebuilt info pages.
789
790=head2 F<PDF> files
791
792for C<Acrobat> are available on CPAN (may be for slightly older version of
793perl).
794
795=head2 C<LaTeX> docs
796
797can be constructed using C<pod2latex>.
798
799=head1 BUILD
800
801Here we discuss how to build Perl under OS/2.
802
803=head2 The short story
804
805Assume that you are a seasoned porter, so are sure that all the necessary
806tools are already present on your system, and you know how to get the Perl
807source distribution.  Untar it, change to the extract directory, and
808
809  gnupatch -p0 < os2\diff.configure
810  sh Configure -des -D prefix=f:/perllib
811  make
812  make test
813  make install
814  make aout_test
815  make aout_install
816
817This puts the executables in f:/perllib/bin.  Manually move them to the
818C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for
819Perl DLL F<*> is a not-very-meaningful hex checksum), and run
820
821  make installcmd INSTALLCMDDIR=d:/ir/on/path
822
823Assuming that the C<man>-files were put on an appropriate location,
824this completes the installation of minimal Perl system.  (The binary
825distribution contains also a lot of additional modules, and the
826documentation in INF format.)
827
828What follows is a detailed guide through these steps.
829
830=head2 Prerequisites
831
832You need to have the latest EMX development environment, the full
833GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
834earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
835check use
836
837  find --version
838  sort --version
839
840). You need the latest version of F<pdksh> installed as F<sh.exe>.
841
842Check that you have B<BSD> libraries and headers installed, and - 
843optionally - Berkeley DB headers and libraries, and crypt.
844
845Possible locations to get the files:
846
847
848  ftp://ftp.uni-heidelberg.de/pub/os2/unix/
849  http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2
850  http://cd.textfiles.com/hobbesos29804/disk1/DEV32/
851  http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
852
853It is reported that the following archives contain enough utils to
854build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
855F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and
856F<ksh527rt.zip> (or a later version).  Note that all these utilities are
857known to be available from LEO:
858
859  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/
860
861Note also that the F<db.lib> and F<db.a> from the EMX distribution
862are not suitable for multi-threaded compile (even single-threaded
863flavor of Perl uses multi-threaded C RTL, for
864compatibility with XFree86-OS/2). Get a corrected one from
865
866  http://www.ilyaz.org/software/os2/db_mt.zip
867
868If you have I<exactly the same version of Perl> installed already,
869make sure that no copies or perl are currently running.  Later steps
870of the build may fail since an older version of F<perl.dll> loaded into
871memory may be found.  Running C<make test> becomes meaningless, since
872the test are checking a previous build of perl (this situation is detected
873and reported by F<lib/os2_base.t> test).  Do not forget to unset
874C<PERL_EMXLOAD_SEC> in environment.
875
876Also make sure that you have F</tmp> directory on the current drive,
877and F<.> directory in your C<LIBPATH>. One may try to correct the
878latter condition by
879
880  set BEGINLIBPATH .\.
881
882if you use something like F<CMD.EXE> or latest versions of
883F<4os2.exe>.  (Setting BEGINLIBPATH to just C<.> is ignored by the
884OS/2 kernel.)
885
886Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
887script in F</emx/lib> directory.
888
889Check that you have link386 installed. It comes standard with OS/2,
890but may be not installed due to customization. If typing
891
892  link386
893
894shows you do not have it, do I<Selective install>, and choose C<Link
895object modules> in I<Optional system utilities/More>. If you get into
896link386 prompts, press C<Ctrl-C> to exit.
897
898=head2 Getting perl source
899
900You need to fetch the latest perl source (including developers
901releases). With some probability it is located in 
902
903  http://www.cpan.org/src/
904  http://www.cpan.org/src/unsupported
905
906If not, you may need to dig in the indices to find it in the directory
907of the current maintainer.
908
909Quick cycle of developers release may break the OS/2 build time to
910time, looking into 
911
912  http://www.cpan.org/ports/os2/
913
914may indicate the latest release which was publicly released by the
915maintainer. Note that the release may include some additional patches
916to apply to the current source of perl.
917
918Extract it like this
919
920  tar vzxf perl5.00409.tar.gz
921
922You may see a message about errors while extracting F<Configure>. This is
923because there is a conflict with a similarly-named file F<configure>.
924
925Change to the directory of extraction.
926
927=head2 Application of the patches
928
929You need to apply the patches in F<./os2/diff.*> like this:
930
931  gnupatch -p0 < os2\diff.configure
932
933You may also need to apply the patches supplied with the binary
934distribution of perl.  It also makes sense to look on the
935perl5-porters mailing list for the latest OS/2-related patches (see
936L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>).  Such
937patches usually contain strings C</os2/> and C<patch>, so it makes
938sense looking for these strings.
939
940=head2 Hand-editing
941
942You may look into the file F<./hints/os2.sh> and correct anything
943wrong you find there. I do not expect it is needed anywhere.
944
945=head2 Making
946
947  sh Configure -des -D prefix=f:/perllib
948
949C<prefix> means: where to install the resulting perl library. Giving
950correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
951see L<"PERLLIB_PREFIX">.
952
953I<Ignore the message about missing C<ln>, and about C<-c> option to
954tr>. The latter is most probably already fixed, if you see it and can trace
955where the latter spurious warning comes from, please inform me.
956
957Now
958
959  make
960
961At some moment the built may die, reporting a I<version mismatch> or
962I<unable to run F<perl>>.  This means that you do not have F<.> in
963your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
964these hex digits as line noise).  After this is fixed the build
965should finish without a lot of fuss.
966
967=head2 Testing
968
969Now run
970
971  make test
972
973All tests should succeed (with some of them skipped).  If you have the
974same version of Perl installed, it is crucial that you have C<.> early
975in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
976probably test the wrong version of Perl.
977
978Some tests may generate extra messages similar to
979
980=over 4
981
982=item A lot of C<bad free>
983
984in database tests related to Berkeley DB. I<This should be fixed already.>
985If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
986
987=item Process terminated by SIGTERM/SIGINT
988
989This is a standard message issued by OS/2 applications. *nix
990applications die in silence. It is considered to be a feature. One can
991easily disable this by appropriate sighandlers. 
992
993However the test engine bleeds these message to screen in unexpected
994moments. Two messages of this kind I<should> be present during
995testing.
996
997=back
998
999To get finer test reports, call
1000
1001  perl t/harness
1002
1003The report with F<io/pipe.t> failing may look like this:
1004
1005  Failed Test  Status Wstat Total Fail  Failed  List of failed
1006  ------------------------------------------------------------
1007  io/pipe.t                    12    1   8.33%  9
1008  7 tests skipped, plus 56 subtests skipped.
1009  Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
1010
1011The reasons for most important skipped tests are:
1012
1013=over 8
1014
1015=item F<op/fs.t>
1016
1017=over 4
1018
1019=item Z<>18
1020
1021Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1022provides only 2sec time granularity (for compatibility with FAT?).
1023
1024=item Z<>25
1025
1026Checks C<truncate()> on a filehandle just opened for write - I do not
1027know why this should or should not work.
1028
1029=back
1030
1031=item F<op/stat.t>
1032
1033Checks C<stat()>. Tests:
1034
1035=over 4
1036
1037=item 4
1038
1039Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1040provides only 2sec time granularity (for compatibility with FAT?).
1041
1042=back
1043
1044=back
1045
1046=head2 Installing the built perl
1047
1048If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now.
1049
1050Run
1051
1052  make install
1053
1054It would put the generated files into needed locations. Manually put
1055F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
1056PATH, F<perl.dll> to a location on your LIBPATH.
1057
1058Run
1059
1060  make installcmd INSTALLCMDDIR=d:/ir/on/path
1061
1062to convert perl utilities to F<.cmd> files and put them on
1063PATH. You need to put F<.EXE>-utilities on path manually. They are
1064installed in C<$prefix/bin>, here C<$prefix> is what you gave to
1065F<Configure>, see L</Making>.
1066
1067If you use C<man>, either move the installed F<*/man/> directories to
1068your C<MANPATH>, or modify C<MANPATH> to match the location.  (One
1069could have avoided this by providing a correct C<manpath> option to
1070F<./Configure>, or editing F<./config.sh> between configuring and
1071making steps.)
1072
1073=head2 C<a.out>-style build
1074
1075Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
1076
1077  make perl_
1078
1079test and install by
1080
1081  make aout_test
1082  make aout_install
1083
1084Manually put F<perl_.exe> to a location on your PATH.
1085
1086B<Note.> The build process for C<perl_> I<does not know> about all the
1087dependencies, so you should make sure that anything is up-to-date,
1088say, by doing
1089
1090  make perl_dll
1091
1092first.
1093
1094=head1 Building a binary distribution
1095
1096[This section provides a short overview only...]
1097
1098Building should proceed differently depending on whether the version of perl
1099you install is already present and used on your system, or is a new version
1100not yet used.  The description below assumes that the version is new, so
1101installing its DLLs and F<.pm> files will not disrupt the operation of your
1102system even if some intermediate steps are not yet fully working.
1103
1104The other cases require a little bit more convoluted procedures.  Below I
1105suppose that the current version of Perl is C<5.8.2>, so the executables are
1106named accordingly.
1107
1108=over
1109
1110=item 1.
1111
1112Fully build and test the Perl distribution.  Make sure that no tests are
1113failing with C<test> and C<aout_test> targets; fix the bugs in Perl and
1114the Perl test suite detected by these tests.  Make sure that C<all_test>
1115make target runs as clean as possible.  Check that F<os2/perlrexx.cmd>
1116runs fine.
1117
1118=item 2.
1119
1120Fully install Perl, including C<installcmd> target.  Copy the generated DLLs
1121to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>)
1122to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>.  Think whether
1123you need backward-compatibility DLLs.  In most cases you do not need to install
1124them yet; but sometime this may simplify the following steps.
1125
1126=item 3.
1127
1128Make sure that C<CPAN.pm> can download files from CPAN.  If not, you may need
1129to manually install C<Net::FTP>.
1130
1131=item 4.
1132
1133Install the bundle C<Bundle::OS2_default>
1134
1135  perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
1136
1137This may take a couple of hours on 1GHz processor (when run the first time).
1138And this should not be necessarily a smooth procedure.  Some modules may not
1139specify required dependencies, so one may need to repeat this procedure several
1140times until the results stabilize.
1141
1142  perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
1143  perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
1144
1145Even after they stabilize, some tests may fail.
1146
1147Fix as many discovered bugs as possible.  Document all the bugs which are not
1148fixed, and all the failures with unknown reasons.  Inspect the produced logs
1149F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events.
1150
1151Keep in mind that I<installation> of some modules may fail too: for example,
1152the DLLs to update may be already loaded by F<CPAN.pm>.  Inspect the C<install>
1153logs (in the example above F<00cpan_i_1> etc) for errors, and install things
1154manually, as in
1155
1156  cd $CPANHOME/.cpan/build/Digest-MD5-2.31
1157  make install
1158
1159Some distributions may fail some tests, but you may want to install them
1160anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode).
1161
1162Since this procedure may take quite a long time to complete, it makes sense
1163to "freeze" your CPAN configuration by disabling periodic updates of the
1164local copy of CPAN index: set C<index_expire> to some big value (I use 365),
1165then save the settings
1166
1167  CPAN> o conf index_expire 365
1168  CPAN> o conf commit
1169
1170Reset back to the default value C<1> when you are finished.
1171
1172=item 5.
1173
1174When satisfied with the results, rerun the C<installcmd> target.  Now you
1175can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build
1176executables: C<perl__.exe> etc.  They are ready to be used.
1177
1178=item 6.
1179
1180Change to the C<./pod> directory of the build tree, download the Perl logo
1181F<CamelGrayBig.BMP>, and run
1182
1183  ( perl2ipf > perl.ipf ) |& tee 00ipf
1184  ipfc /INF perl.ipf |& tee 00inf
1185
1186This produces the Perl docs online book C<perl.INF>.  Install in on
1187C<BOOKSHELF> path.
1188
1189=item 7.
1190
1191Now is the time to build statically linked executable F<perl_.exe> which
1192includes newly-installed via C<Bundle::OS2_default> modules.  Doing testing
1193via C<CPAN.pm> is going to be painfully slow, since it statically links
1194a new executable per XS extension.
1195
1196Here is a possible workaround: create a toplevel F<Makefile.PL> in
1197F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
1198executables with a custom collection of statically loaded extensions>)
1199
1200  use ExtUtils::MakeMaker;
1201  WriteMakefile NAME => 'dummy';
1202
1203execute this as
1204
1205  perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
1206  make -k all test <nul |& 00aout_t1
1207
1208Again, this procedure should not be absolutely smooth.  Some C<Makefile.PL>'s
1209in subdirectories may be buggy, and would not run as "child" scripts.  The
1210interdependency of modules can strike you; however, since non-XS modules
1211are already installed, the prerequisites of most modules have a very good
1212chance to be present.
1213
1214If you discover some glitches, move directories of problematic modules to a
1215different location; if these modules are non-XS modules, you may just ignore
1216them - they are already installed; the remaining, XS, modules you need to
1217install manually one by one.
1218
1219After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
1220usually this procedure converges soon.  (But be sure to convert all the
1221necessary external C libraries from F<.lib> format to F<.a> format: run one of
1222
1223  emxaout foo.lib
1224  emximp -o foo.a foo.lib
1225
1226whichever is appropriate.)  Also, make sure that the DLLs for external
1227libraries are usable with with executables compiled without C<-Zmtd> options.
1228
1229When you are sure that only a few subdirectories
1230lead to failures, you may want to add C<-j4> option to C<make> to speed up
1231skipping subdirectories with already finished build.
1232
1233When you are satisfied with the results of tests, install the build C libraries
1234for extensions:
1235
1236  make install |& tee 00aout_i
1237
1238Now you can rename the file F<./perl.exe> generated during the last phase
1239to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency
1240between some XS modules, you may need to repeat the C<test>/C<install> loop
1241with this new executable and some excluded modules - until the procedure
1242converges.
1243
1244Now you have all the necessary F<.a> libraries for these Perl modules in the
1245places where Perl builder can find it.  Use the perl builder: change to an
1246empty directory, create a "dummy" F<Makefile.PL> again, and run
1247
1248  perl_5.8.2.exe Makefile.PL |& tee 00c
1249  make perl		     |& tee 00p
1250
1251This should create an executable F<./perl.exe> with all the statically loaded
1252extensions built in.  Compare the generated F<perlmain.c> files to make sure
1253that during the iterations the number of loaded extensions only increases.
1254Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>.
1255
1256When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it
1257to C<perl_.exe>.  You are done with generation of the local Perl installation.
1258
1259=item 8.
1260
1261Make sure that the installed modules are actually installed in the location
1262of the new Perl, and are not inherited from entries of @INC given for
1263inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
1264redirect the new version of Perl to a new location, and copy the installed
1265files to this new location.  Redo the tests to make sure that the versions of
1266modules inherited from older versions of Perl are not needed.
1267
1268Actually, the log output of L<pod2ipf(1)> during the step 6 gives a very detailed
1269info about which modules are loaded from which place; so you may use it as
1270an additional verification tool.
1271
1272Check that some temporary files did not make into the perl install tree.
1273Run something like this
1274
1275  pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less
1276
1277in the install tree (both top one and F<sitelib> one).
1278
1279Compress all the DLLs with F<lxlite>.  The tiny F<.exe> can be compressed with
1280C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a
1281page (?); since the tiny executables are much smaller than a page, the bug
1282will not hit).  Do not compress C<perl_.exe> - it would not work under DOS.
1283
1284=item 9.
1285
1286Now you can generate the binary distribution.  This is done by running the
1287test of the CPAN distribution C<OS2::SoftInstaller>.  Tune up the file
1288F<test.pl> to suit the layout of current version of Perl first.  Do not
1289forget to pack the necessary external DLLs accordingly.  Include the
1290description of the bugs and test suite failures you could not fix.  Include
1291the small-stack versions of Perl executables from Perl build directory.
1292
1293Include F<perl5.def> so that people can relink the perl DLL preserving
1294the binary compatibility, or can create compatibility DLLs.  Include the diff
1295files (C<diff -pu old new>) of fixes you did so that people can rebuild your
1296version.  Include F<perl5.map> so that one can use remote debugging.
1297
1298=item 10.
1299
1300Share what you did with the other people.  Relax.  Enjoy fruits of your work.
1301
1302=item 11.
1303
1304Brace yourself for thanks, bug reports, hate mail and spam coming as result
1305of the previous step.  No good deed should remain unpunished!
1306
1307=back
1308
1309=head1 Building custom F<.EXE> files
1310
1311The Perl executables can be easily rebuilt at any moment.  Moreover, one can
1312use the I<embedding> interface (see L<perlembed>) to make very customized
1313executables.
1314
1315=head2 Making executables with a custom collection of statically loaded extensions
1316
1317It is a little bit easier to do so while I<decreasing> the list of statically
1318loaded extensions.  We discuss this case only here.
1319
1320=over
1321
1322=item 1.
1323
1324Change to an empty directory, and create a placeholder <Makefile.PL>:
1325
1326  use ExtUtils::MakeMaker;
1327  WriteMakefile NAME => 'dummy';
1328
1329=item 2.
1330
1331Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to
1332rebuild.
1333
1334  perl_ Makefile.PL
1335
1336=item 3.
1337
1338Ask it to create new Perl executable:
1339
1340  make perl
1341
1342(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on
1343some versions of Perl; the symptom is that the command-line globbing does not
1344work from OS/2 shells with the newly-compiled executable; check with
1345
1346  .\perl.exe -wle "print for @ARGV" *
1347
1348).
1349
1350=item 4.
1351
1352The previous step created F<perlmain.c> which contains a list of newXS() calls
1353near the end.  Removing unnecessary calls, and rerunning
1354
1355  make perl
1356
1357will produce a customized executable.
1358
1359=back
1360
1361=head2 Making executables with a custom search-paths
1362
1363The default perl executable is flexible enough to support most usages.
1364However, one may want something yet more flexible; for example, one may want
1365to find Perl DLL relatively to the location of the EXE file; or one may want
1366to ignore the environment when setting the Perl-library search patch, etc.
1367
1368If you fill comfortable with I<embedding> interface (see L<perlembed>), such
1369things are easy to do repeating the steps outlined in L<Making
1370executables with a custom collection of statically loaded extensions>, and
1371doing more comprehensive edits to main() of F<perlmain.c>.  The people with
1372little desire to understand Perl can just rename main(), and do necessary
1373modification in a custom main() which calls the renamed function in appropriate
1374time.
1375
1376However, there is a third way: perl DLL exports the main() function and several
1377callbacks to customize the search path.  Below is a complete example of a
1378"Perl loader" which
1379
1380=over
1381
1382=item 1.
1383
1384Looks for Perl DLL in the directory C<$exedir/../dll>;
1385
1386=item 2.
1387
1388Prepends the above directory to C<BEGINLIBPATH>;
1389
1390=item 3.
1391
1392Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was
1393loaded on step 1; e.g., another process could have loaded it from C<LIBPATH>
1394or from a different value of C<BEGINLIBPATH>.  In these cases one needs to
1395modify the setting of the system so that this other process either does not
1396run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available
1397with kernels after September 2000).
1398
1399=item 4.
1400
1401Loads Perl library from C<$exedir/../dll/lib/>.
1402
1403=item 5.
1404
1405Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>.
1406
1407=back
1408
1409For best results compile the C file below with the same options as the Perl
1410DLL.  However, a lot of functionality will work even if the executable is not
1411an EMX applications, e.g., if compiled with
1412
1413  gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c \
1414    -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1415
1416Here is the sample C file:
1417
1418  #define INCL_DOS
1419  #define INCL_NOPM
1420  /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
1421  #define INCL_DOSPROCESS
1422  #include <os2.h>
1423
1424  #include "EXTERN.h"
1425  #define PERL_IN_MINIPERLMAIN_C
1426  #include "perl.h"
1427
1428  static char *me;
1429  HMODULE handle;
1430
1431  static void
1432  die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1433  {
1434     ULONG c;
1435     char *s = " error: ";
1436
1437     DosWrite(2, me, strlen(me), &c);
1438     DosWrite(2, s, strlen(s), &c);
1439     DosWrite(2, msg1, strlen(msg1), &c);
1440     DosWrite(2, msg2, strlen(msg2), &c);
1441     DosWrite(2, msg3, strlen(msg3), &c);
1442     DosWrite(2, msg4, strlen(msg4), &c);
1443     DosWrite(2, "\r\n", 2, &c);
1444     exit(255);
1445  }
1446
1447  typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
1448  typedef int (*main_t)(int type, char *argv[], char *env[]);
1449  typedef int (*handler_t)(void* data, int which);
1450
1451  #ifndef PERL_DLL_BASENAME
1452  #  define PERL_DLL_BASENAME "perl"
1453  #endif
1454
1455  static HMODULE
1456  load_perl_dll(char *basename)
1457  {
1458      char buf[300], fail[260];
1459      STRLEN l, dirl;
1460      fill_extLibpath_t f;
1461      ULONG rc_fullname;
1462      HMODULE handle, handle1;
1463
1464      if (_execname(buf, sizeof(buf) - 13) != 0)
1465          die_with("Can't find full path: ", strerror(errno), "", "");
1466      /* XXXX Fill 'me' with new value */
1467      l = strlen(buf);
1468      while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1469          l--;
1470      dirl = l - 1;
1471      strcpy(buf + l, basename);
1472      l += strlen(basename);
1473      strcpy(buf + l, ".dll");
1474      if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
1475           && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1476          die_with("Can't load DLL ", buf, "", "");
1477      if (rc_fullname)
1478          return handle;		/* was loaded with short name; all is fine */
1479      if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1480          die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
1481      buf[dirl] = 0;
1482      if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1483            0 /* keep old value */, me))
1484          die_with(me, ": prepending BEGINLIBPATH", "", "");
1485      if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1486          die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
1487      buf[dirl] = '\\';     
1488      if (handle1 != handle) {
1489          if (DosQueryModuleName(handle1, sizeof(fail), fail))
1490              strcpy(fail, "???");
1491          die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1492                   fail,
1493                   "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
1494                   "\n\tso that the other copy is loaded via BEGINLIBPATH.");
1495      }
1496      return handle;
1497  }
1498
1499  int
1500  main(int argc, char **argv, char **env)
1501  {
1502      main_t f;
1503      handler_t h;
1504
1505      me = argv[0];
1506      /**/
1507      handle = load_perl_dll(PERL_DLL_BASENAME);
1508
1509      if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
1510          die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
1511      if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1512           || !h((void *)"~dll", Perlos2_handler_perllib_to)
1513           || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1514          die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
1515
1516      if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1517          die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
1518      return f(argc, argv, env);
1519  }
1520
1521
1522=head1 Build FAQ
1523
1524=head2 Some C</> became C<\> in pdksh.
1525
1526You have a very old pdksh. See L</Prerequisites>.
1527
1528=head2 C<'errno'> - unresolved external
1529
1530You do not have MT-safe F<db.lib>. See L</Prerequisites>.
1531
1532=head2 Problems with tr or sed
1533
1534reported with very old version of tr and sed.
1535
1536=head2 Some problem (forget which ;-)
1537
1538You have an older version of F<perl.dll> on your LIBPATH, which
1539broke the build of extensions.
1540
1541=head2 Library ... not found
1542
1543You did not run C<omflibs>. See L</Prerequisites>.
1544
1545=head2 Segfault in make
1546
1547You use an old version of GNU make. See L</Prerequisites>.
1548
1549=head2 op/sprintf test failure
1550
1551This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
1552
1553=head1 Specific (mis)features of OS/2 port
1554
1555=head2 C<setpriority>, C<getpriority>
1556
1557Note that these functions are compatible with *nix, not with the older
1558ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1559lower is quicker. 0 is the default priority.
1560
1561B<WARNING>.  Calling C<getpriority> on a non-existing process could lock
1562the system before Warp3 fixpak22.  Starting with Warp3, Perl will use
1563a workaround: it aborts getpriority() if the process is not present.
1564This is not possible on older versions C<2.*>, and has a race
1565condition anyway.
1566
1567=head2 C<system()>
1568
1569Multi-argument form of C<system()> allows an additional numeric
1570argument. The meaning of this argument is described in
1571L<OS2::Process>.
1572
1573When finding a program to run, Perl first asks the OS to look for executables
1574on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
1575If not found, it looks for a script with possible extensions 
1576added in this order: no extension, F<.cmd>, F<.btm>, 
1577F<.bat>, F<.pl>.  If found, Perl checks the start of the file for magic
1578strings C<"#!"> and C<"extproc ">.  If found, Perl uses the rest of the
1579first line as the beginning of the command line to run this script.  The
1580only mangling done to the first line is extraction of arguments (currently
1581up to 3), and ignoring of the path-part of the "interpreter" name if it can't
1582be found using the full path.
1583
1584E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
1585F<C:/emx/bin/foo.cmd> with the first line being
1586
1587 extproc /bin/bash    -x   -c
1588
1589If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
1590C<PATH>.  If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
1591translated to
1592
1593  system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1594
1595One additional translation is performed: instead of F</bin/sh> Perl uses
1596the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
1597
1598The above search for "interpreter" is recursive: if F<bash> executable is not
1599found, but F<bash.btm> is found, Perl will investigate its first line etc.
1600The only hardwired limit on the recursion depth is implicit: there is a limit
16014 on the number of additional arguments inserted before the actual arguments
1602given to system().  In particular, if no additional arguments are specified
1603on the "magic" first lines, then the limit on the depth is 4.
1604
1605If Perl finds that the found executable is of PM type when the
1606current session is not, it will start the new process in a separate session of
1607necessary type.  Call via C<OS2::Process> to disable this magic.
1608
1609B<WARNING>.  Due to the described logic, you need to explicitly
1610specify F<.com> extension if needed.  Moreover, if the executable
1611F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
1612[This may change in the future.]
1613
1614=head2 C<extproc> on the first line
1615
1616If the first chars of a Perl script are C<"extproc ">, this line is treated
1617as C<#!>-line, thus all the switches on this line are processed (twice
1618if script was started via cmd.exe).  See L<perlrun/DESCRIPTION>.
1619
1620=head2 Additional modules:
1621
1622L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
1623modules provide access to additional numeric argument for C<system>
1624and to the information about the running process,
1625to DLLs having functions with REXX signature and to the REXX runtime, to
1626OS/2 databases in the F<.INI> format, and to Extended Attributes.
1627
1628Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
1629C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
1630Other OS/2-related extensions are available too.
1631
1632=head2 Prebuilt methods:
1633
1634=over 4
1635
1636=item C<File::Copy::syscopy>
1637
1638used by C<File::Copy::copy>, see L<File::Copy>.
1639
1640=item C<DynaLoader::mod2fname>
1641
1642used by C<DynaLoader> for DLL name mangling.
1643
1644=item  C<Cwd::current_drive()>
1645
1646Self explanatory.
1647
1648=item  C<Cwd::sys_chdir(name)>
1649
1650leaves drive as it is.
1651
1652=item  C<Cwd::change_drive(name)>
1653
1654changes the "current" drive.
1655
1656=item  C<Cwd::sys_is_absolute(name)>
1657
1658means has drive letter and is_rooted.
1659
1660=item  C<Cwd::sys_is_rooted(name)>
1661
1662means has leading C<[/\\]> (maybe after a drive-letter:).
1663
1664=item  C<Cwd::sys_is_relative(name)>
1665
1666means changes with current dir.
1667
1668=item  C<Cwd::sys_cwd(name)>
1669
1670Interface to cwd from EMX. Used by C<Cwd::cwd>.
1671
1672=item  C<Cwd::sys_abspath(name, dir)>
1673
1674Really really odious function to implement. Returns absolute name of
1675file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
1676current dir.
1677
1678=item  C<Cwd::extLibpath([type])>
1679
1680Get current value of extended library search path. If C<type> is
1681present and positive, works with C<END_LIBPATH>, if negative, works
1682with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 
1683
1684=item  C<Cwd::extLibpath_set( path [, type ] )>
1685
1686Set current value of extended library search path. If C<type> is
1687present and positive, works with <END_LIBPATH>, if negative, works
1688with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
1689
1690=item C<OS2::Error(do_harderror,do_exception)>
1691
1692Returns	C<undef> if it was not called yet, otherwise bit 1 is
1693set if on the previous call do_harderror was enabled, bit
16942 is set if on previous call do_exception was enabled.
1695
1696This function enables/disables error popups associated with 
1697hardware errors (Disk not ready etc.) and software exceptions.
1698
1699I know of no way to find out the state of popups I<before> the first call
1700to this function.
1701
1702=item C<OS2::Errors2Drive(drive)>
1703
1704Returns C<undef> if it was not called yet, otherwise return false if errors
1705were not requested to be written to a hard drive, or the drive letter if
1706this was requested.
1707
1708This function may redirect error popups associated with hardware errors
1709(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
1710the root directory of the specified drive.  Overrides OS2::Error() specified
1711by individual programs.  Given argument undef will disable redirection.
1712
1713Has global effect, persists after the application exits.
1714
1715I know of no way to find out the state of redirection of popups to the disk
1716I<before> the first call to this function.
1717
1718=item OS2::SysInfo()
1719
1720Returns a hash with system information. The keys of the hash are
1721
1722	MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1723	MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1724	MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1725	VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1726	MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1727	TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1728	MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1729	FOREGROUND_PROCESS
1730
1731=item OS2::BootDrive()
1732
1733Returns a letter without colon.
1734
1735=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
1736
1737Transforms the current application into a PM application and back.
1738The argument true means that a real message loop is going to be served.
1739OS2::MorphPM() returns the PM message queue handle as an integer.
1740
1741See L<"Centralized management of resources"> for additional details.
1742
1743=item C<OS2::Serve_Messages(force)>
1744
1745Fake on-demand retrieval of outstanding PM messages.  If C<force> is false,
1746will not dispatch messages if a real message loop is known to
1747be present.  Returns number of messages retrieved.
1748
1749Dies with "QUITing..." if WM_QUIT message is obtained.
1750
1751=item C<OS2::Process_Messages(force [, cnt])>
1752
1753Retrieval of PM messages until window creation/destruction.  
1754If C<force> is false, will not dispatch messages if a real message loop
1755is known to be present.
1756
1757Returns change in number of windows.  If C<cnt> is given,
1758it is incremented by the number of messages retrieved.
1759
1760Dies with "QUITing..." if WM_QUIT message is obtained.
1761
1762=item C<OS2::_control87(new,mask)>
1763
1764the same as L<_control87(3)> of EMX.  Takes integers as arguments, returns
1765the previous coprocessor control word as an integer.  Only bits in C<new> which
1766are present in C<mask> are changed in the control word.
1767
1768=item OS2::get_control87()
1769
1770gets the coprocessor control word as an integer.
1771
1772=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
1773
1774The variant of OS2::_control87() with default values good for
1775handling exception mask: if no C<mask>, uses exception mask part of C<new>
1776only.  If no C<new>, disables all the floating point exceptions.
1777
1778See L<"Misfeatures"> for details.
1779
1780=item C<OS2::DLLname([how [, \&xsub]])>
1781
1782Gives the information about the Perl DLL or the DLL containing the C
1783function bound to by C<&xsub>.  The meaning of C<how> is: default (2):
1784full name; 0: handle; 1: module name.
1785
1786=back
1787
1788(Note that some of these may be moved to different libraries -
1789eventually).
1790
1791
1792=head2 Prebuilt variables:
1793
1794=over 4
1795
1796=item $OS2::emx_rev
1797
1798numeric value is the same as _emx_rev of EMX, a string value the same
1799as _emx_vprt (similar to C<0.9c>).
1800
1801=item $OS2::emx_env
1802
1803same as _emx_env of EMX, a number similar to 0x8001.
1804
1805=item $OS2::os_ver
1806
1807a number C<OS_MAJOR + 0.001 * OS_MINOR>.
1808
1809=item $OS2::is_aout
1810
1811true if the Perl library was compiled in AOUT format.
1812
1813=item $OS2::can_fork
1814
1815true if the current executable is an AOUT EMX executable, so Perl can
1816fork.  Do not use this, use the portable check for
1817$Config::Config{dfork}.
1818
1819=item $OS2::nsyserror
1820
1821This variable (default is 1) controls whether to enforce the contents
1822of $^E to start with C<SYS0003>-like id.  If set to 0, then the string
1823value of $^E is what is available from the OS/2 message file.  (Some
1824messages in this file have an C<SYS0003>-like id prepended, some not.)
1825
1826=back
1827
1828=head2 Misfeatures
1829
1830=over 4
1831
1832=item *
1833
1834Since L<flock(3)> is present in EMX, but is not functional, it is 
1835emulated by perl.  To disable the emulations, set environment variable
1836C<USE_PERL_FLOCK=0>.
1837
1838=item *
1839
1840Here is the list of things which may be "broken" on
1841EMX (from EMX docs):
1842
1843=over 4
1844
1845=item *
1846
1847The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
1848implemented.
1849
1850=item *
1851
1852L<sock_init(3)> is not required and not implemented.
1853
1854=item *
1855
1856L<flock(3)> is not yet implemented (dummy function).  (Perl has a workaround.)
1857
1858=item *
1859
1860L<kill(3)>:  Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1861
1862=item *
1863
1864L<waitpid(3)>:
1865
1866      WUNTRACED
1867	      Not implemented.
1868      waitpid() is not implemented for negative values of PID.
1869
1870=back
1871
1872Note that C<kill -9> does not work with the current version of EMX.
1873
1874=item *
1875
1876See L<"Text-mode filehandles">.
1877
1878=item *
1879
1880Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
1881To avoid a failure to create a socket with a name of a different form,
1882C<"/socket/"> is prepended to the socket name (unless it starts with this
1883already).
1884
1885This may lead to problems later in case the socket is accessed via the
1886"usual" file-system calls using the "initial" name.
1887
1888=item *
1889
1890Apparently, IBM used a compiler (for some period of time around '95?) which
1891changes FP mask right and left.  This is not I<that> bad for IBM's
1892programs, but the same compiler was used for DLLs which are used with
1893general-purpose applications.  When these DLLs are used, the state of
1894floating-point flags in the application is not predictable.
1895
1896What is much worse, some DLLs change the floating point flags when in
1897_DLLInitTerm() (e.g., F<TCP32IP>).  This means that even if you do not I<call>
1898any function in the DLL, just the act of loading this DLL will reset your
1899flags.  What is worse, the same compiler was used to compile some HOOK DLLs.
1900Given that HOOK dlls are executed in the context of I<all> the applications
1901in the system, this means a complete unpredictability of floating point
1902flags on systems using such HOOK DLLs.  E.g., F<GAMESRVR.DLL> of B<DIVE>
1903origin changes the floating point flags on each write to the TTY of a VIO
1904(windowed text-mode) applications.
1905
1906Some other (not completely debugged) situations when FP flags change include
1907some video drivers (?), and some operations related to creation of the windows.
1908People who code B<OpenGL> may have more experience on this.
1909
1910Perl is generally used in the situation when all the floating-point
1911exceptions are ignored, as is the default under EMX.  If they are not ignored,
1912some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
1913
1914To circumvent this, Perl uses two hacks.  They help against I<one> type of
1915damage only: FP flags changed when loading a DLL.
1916
1917One of the hacks is to disable floating point exceptions on Perl startup (as
1918is the default with EMX).  This helps only with compile-time-linked DLLs
1919changing the flags before main() had a chance to be called.
1920
1921The other hack is to restore FP flags after a call to dlopen().  This helps
1922against similar damage done by DLLs _DLLInitTerm() at runtime.  Currently
1923no way to switch these hacks off is provided.
1924
1925=back
1926
1927=head2 Modifications
1928
1929Perl modifies some standard C library calls in the following ways:
1930
1931=over 9
1932
1933=item C<popen>
1934
1935C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
1936
1937=item C<tmpnam>
1938
1939is created using C<TMP> or C<TEMP> environment variable, via
1940C<tempnam>.
1941
1942=item C<tmpfile>
1943
1944If the current directory is not writable, file is created using modified
1945C<tmpnam>, so there may be a race condition.
1946
1947=item C<ctermid>
1948
1949a dummy implementation.
1950
1951=item C<stat>
1952
1953C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1954
1955=item C<mkdir>, C<rmdir>
1956
1957these EMX functions do not work if the path contains a trailing C</>.
1958Perl contains a workaround for this.
1959
1960=item C<flock>
1961
1962Since L<flock(3)> is present in EMX, but is not functional, it is 
1963emulated by perl.  To disable the emulations, set environment variable
1964C<USE_PERL_FLOCK=0>.
1965
1966=back
1967
1968=head2 Identifying DLLs
1969
1970All the DLLs built with the current versions of Perl have ID strings
1971identifying the name of the extension, its version, and the version
1972of Perl required for this DLL.  Run C<bldlevel DLL-name> to find this
1973info.
1974
1975=head2 Centralized management of resources
1976
1977Since to call certain OS/2 API one needs to have a correctly initialized
1978C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
1979C<HMQ>s.  If an extension would do it on its own, another extension could
1980fail to initialize.
1981
1982Perl provides a centralized management of these resources:
1983
1984=over
1985
1986=item C<HAB>
1987
1988To get the HAB, the extension should call C<hab = perl_hab_GET()> in C.  After
1989this call is performed, C<hab> may be accessed as C<Perl_hab>.  There is
1990no need to release the HAB after it is used.
1991
1992If by some reasons F<perl.h> cannot be included, use
1993
1994  extern int Perl_hab_GET(void);
1995
1996instead.
1997
1998=item C<HMQ>
1999
2000There are two cases:
2001
2002=over
2003
2004=item *
2005
2006the extension needs an C<HMQ> only because some API will not work otherwise.
2007Use C<serve = 0> below.
2008
2009=item *
2010
2011the extension needs an C<HMQ> since it wants to engage in a PM event loop.
2012Use C<serve = 1> below.
2013
2014=back
2015
2016To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
2017After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
2018
2019To signal to Perl that HMQ is not needed any more, call
2020C<perl_hmq_UNSET(serve)>.  Perl process will automatically morph/unmorph itself
2021into/from a PM process if HMQ is needed/not-needed.  Perl will automatically
2022enable/disable C<WM_QUIT> message during shutdown if the message queue is
2023served/not-served.
2024
2025B<NOTE>.  If during a shutdown there is a message queue which did not disable
2026WM_QUIT, and which did not process the received WM_QUIT message, the
2027shutdown will be automatically cancelled.  Do not call C<perl_hmq_GET(1)>
2028unless you are going to process messages on an orderly basis.
2029
2030=item Treating errors reported by OS/2 API
2031
2032There are two principal conventions (it is useful to call them C<Dos*>
2033and C<Win*> - though this part of the function signature is not always
2034determined by the name of the API) of reporting the error conditions
2035of OS/2 API.  Most of C<Dos*> APIs report the error code as the result
2036of the call (so 0 means success, and there are many types of errors).
2037Most of C<Win*> API report success/fail via the result being
2038C<TRUE>/C<FALSE>; to find the reason for the failure one should call
2039WinGetLastError() API.
2040
2041Some C<Win*> entry points also overload a "meaningful" return value
2042with the error indicator; having a 0 return value indicates an error.
2043Yet some other C<Win*> entry points overload things even more, and 0
2044return value may mean a successful call returning a valid value 0, as
2045well as an error condition; in the case of a 0 return value one should
2046call WinGetLastError() API to distinguish a successful call from a
2047failing one.
2048
2049By convention, all the calls to OS/2 API should indicate their
2050failures by resetting $^E.  All the Perl-accessible functions which
2051call OS/2 API may be broken into two classes: some die()s when an API
2052error is encountered, the other report the error via a false return
2053value (of course, this does not concern Perl-accessible functions
2054which I<expect> a failure of the OS/2 API call, having some workarounds
2055coded).
2056
2057Obviously, in the situation of the last type of the signature of an OS/2
2058API, it is must more convenient for the users if the failure is
2059indicated by die()ing: one does not need to check $^E to know that
2060something went wrong.  If, however, this solution is not desirable by
2061some reason, the code in question should reset $^E to 0 before making
2062this OS/2 API call, so that the caller of this Perl-accessible
2063function has a chance to distinguish a success-but-0-return value from
2064a failure.  (One may return undef as an alternative way of reporting
2065an error.)
2066
2067The macros to simplify this type of error propagation are
2068
2069=over
2070
2071=item C<CheckOSError(expr)>
2072
2073Returns true on error, sets $^E.  Expects expr() be a call of
2074C<Dos*>-style API.
2075
2076=item C<CheckWinError(expr)>
2077
2078Returns true on error, sets $^E.  Expects expr() be a call of
2079C<Win*>-style API.
2080
2081=item C<SaveWinError(expr)>
2082
2083Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false.
2084
2085=item C<SaveCroakWinError(expr,die,name1,name2)>
2086
2087Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false,
2088and die()s if C<die> and $^E are true.  The message to die is the
2089concatenated strings C<name1> and C<name2>, separated by C<": "> from
2090the contents of $^E.
2091
2092=item C<WinError_2_Perl_rc>
2093
2094Sets C<Perl_rc> to the return value of WinGetLastError().
2095
2096=item C<FillWinError>
2097
2098Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E
2099to the corresponding value.
2100
2101=item C<FillOSError(rc)>
2102
2103Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value.
2104
2105=back
2106
2107=item Loading DLLs and ordinals in DLLs
2108
2109Some DLLs are only present in some versions of OS/2, or in some
2110configurations of OS/2.  Some exported entry points are present only
2111in DLLs shipped with some versions of OS/2.  If these DLLs and entry
2112points were linked directly for a Perl executable/DLL or from a Perl
2113extensions, this binary would work only with the specified
2114versions/setups.  Even if these entry points were not needed, the
2115I<load> of the executable (or DLL) would fail.
2116
2117For example, many newer useful APIs are not present in OS/2 v2; many
2118PM-related APIs require DLLs not available on floppy-boot setup.
2119
2120To make these calls fail I<only when the calls are executed>, one
2121should call these API via a dynamic linking API.  There is a subsystem
2122in Perl to simplify such type of calls.  A large number of entry
2123points available for such linking is provided (see C<entries_ordinals>
2124- and also C<PMWIN_entries> - in F<os2ish.h>).  These ordinals can be
2125accessed via the APIs:
2126
2127  CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
2128  DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
2129  DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
2130  DeclWinFuncByORD_CACHE_resetError_survive(),
2131  DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
2132  DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
2133
2134See the header files and the C code in the supplied OS/2-related
2135modules for the details on usage of these functions.
2136
2137Some of these functions also combine dynaloading semantic with the
2138error-propagation semantic discussed above.
2139
2140=back
2141
2142=head1 Perl flavors
2143
2144Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
2145same basket (though EMX environment tries hard to overcome this
2146limitations, so the situation may somehow improve). There are 4
2147executables for Perl provided by the distribution:
2148
2149=head2 F<perl.exe>
2150
2151The main workhorse. This is a chimera executable: it is compiled as an
2152C<a.out>-style executable, but is linked with C<omf>-style dynamic
2153library F<perl.dll>, and with dynamic CRT DLL. This executable is a
2154VIO application.
2155
2156It can load perl dynamic extensions, and it can fork().
2157
2158B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
2159
2160=head2 F<perl_.exe>
2161
2162This is a statically linked C<a.out>-style executable. It cannot
2163load dynamic Perl extensions. The executable supplied in binary
2164distributions has a lot of extensions prebuilt, thus the above restriction is 
2165important only if you use custom-built extensions. This executable is a VIO
2166application.
2167
2168I<This is the only executable with does not require OS/2.> The
2169friends locked into C<M$> world would appreciate the fact that this
2170executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
2171appropriate extender. See L<"Other OSes">.
2172
2173=head2 F<perl__.exe>
2174
2175This is the same executable as F<perl___.exe>, but it is a PM
2176application. 
2177
2178B<Note.> Usually (unless explicitly redirected during the startup)
2179STDIN, STDERR, and STDOUT of a PM
2180application are redirected to F<nul>. However, it is possible to I<see>
2181them if you start C<perl__.exe> from a PM program which emulates a
2182console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
2183possible> to use Perl debugger (see L<perldebug>) to debug your PM
2184application (but beware of the message loop lockups - this will not
2185work if you have a message queue to serve, unless you hook the serving
2186into the getc() function of the debugger).
2187
2188Another way to see the output of a PM program is to run it as
2189
2190  pm_prog args 2>&1 | cat -
2191
2192with a shell I<different> from F<cmd.exe>, so that it does not create
2193a link between a VIO session and the session of C<pm_porg>.  (Such a link
2194closes the VIO window.)  E.g., this works with F<sh.exe> - or with Perl!
2195
2196  open P, 'pm_prog args 2>&1 |' or die;
2197  print while <P>;
2198
2199The flavor F<perl__.exe> is required if you want to start your program without
2200a VIO window present, but not C<detach>ed (run C<help detach> for more info).
2201Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
2202
2203Note also that the differences between PM and VIO executables are only
2204in the I<default> behaviour.  One can start I<any> executable in
2205I<any> kind of session by using the arguments C</fs>, C</pm> or
2206C</win> switches of the command C<start> (of F<CMD.EXE> or a similar
2207shell).  Alternatively, one can use the numeric first argument of the
2208C<system> Perl function (see L<OS2::Process>).
2209
2210=head2 F<perl___.exe>
2211
2212This is an C<omf>-style executable which is dynamically linked to
2213F<perl.dll> and CRT DLL. I know no advantages of this executable
2214over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
2215that the build process is not so convoluted as with C<perl.exe>.
2216
2217It is a VIO application.
2218
2219=head2 Why strange names?
2220
2221Since Perl processes the C<#!>-line (cf. 
2222L<perlrun/DESCRIPTION>, L<perlrun/Command Switches>,
2223L<perldiag/"No Perl script found in input">), it should know when a
2224program I<is a Perl>. There is some naming convention which allows
2225Perl to distinguish correct lines from wrong ones. The above names are
2226almost the only names allowed by this convention which do not contain
2227digits (which have absolutely different semantics).
2228
2229=head2 Why dynamic linking?
2230
2231Well, having several executables dynamically linked to the same huge
2232library has its advantages, but this would not substantiate the
2233additional work to make it compile. The reason is the complicated-to-developers
2234but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
2235
2236There are two distinctive features of the dyna-linking model of OS/2:
2237first, all the references to external functions are resolved at the compile time;
2238second, there is no runtime fixup of the DLLs after they are loaded into memory.
2239The first feature is an enormous advantage over other models: it avoids
2240conflicts when several DLLs used by an application export entries with
2241the same name.  In such cases "other" models of dyna-linking just choose
2242between these two entry points using some random criterion - with predictable
2243disasters as results.  But it is the second feature which requires the build
2244of F<perl.dll>.
2245
2246The address tables of DLLs are patched only once, when they are
2247loaded. The addresses of the entry points into DLLs are guaranteed to be
2248the same for all the programs which use the same DLL.  This removes the
2249runtime fixup - once DLL is loaded, its code is read-only.
2250
2251While this allows some (significant?) performance advantages, this makes life
2252much harder for developers, since the above scheme makes it impossible
2253for a DLL to be "linked" to a symbol in the F<.EXE> file.  Indeed, this
2254would need a DLL to have different relocations tables for the
2255(different) executables which use this DLL.
2256
2257However, a dynamically loaded Perl extension is forced to use some symbols
2258from the perl
2259executable, e.g., to know how to find the arguments to the functions:
2260the arguments live on the perl
2261internal evaluation stack. The solution is to put the main code of
2262the interpreter into a DLL, and make the F<.EXE> file which just loads
2263this DLL into memory and supplies command-arguments.  The extension DLL
2264cannot link to symbols in F<.EXE>, but it has no problem linking
2265to symbols in the F<.DLL>.
2266
2267This I<greatly> increases the load time for the application (as well as
2268complexity of the compilation). Since interpreter is in a DLL,
2269the C RTL is basically forced to reside in a DLL as well (otherwise
2270extensions would not be able to use CRT).  There are some advantages if
2271you use different flavors of perl, such as running F<perl.exe> and
2272F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
2273
2274B<NOTE>.  There is one additional effect which makes DLLs more wasteful:
2275DLLs are loaded in the shared memory region, which is a scarse resource
2276given the 512M barrier of the "standard" OS/2 virtual memory.  The code of
2277F<.EXE> files is also shared by all the processes which use the particular
2278F<.EXE>, but they are "shared in the private address space of the process";
2279this is possible because the address at which different sections
2280of the F<.EXE> file are loaded is decided at compile-time, thus all the
2281processes have these sections loaded at same addresses, and no fixup
2282of internal links inside the F<.EXE> is needed.
2283
2284Since DLLs may be loaded at run time, to have the same mechanism for DLLs
2285one needs to have the address range of I<any of the loaded> DLLs in the
2286system to be available I<in all the processes> which did not load a particular
2287DLL yet.  This is why the DLLs are mapped to the shared memory region.
2288
2289=head2 Why chimera build?
2290
2291Current EMX environment does not allow DLLs compiled using Unixish
2292C<a.out> format to export symbols for data (or at least some types of
2293data). This forces C<omf>-style compile of F<perl.dll>.
2294
2295Current EMX environment does not allow F<.EXE> files compiled in
2296C<omf> format to fork(). fork() is needed for exactly three Perl
2297operations:
2298
2299=over 4
2300
2301=item *
2302
2303explicit fork() in the script, 
2304
2305=item *
2306
2307C<open FH, "|-">
2308
2309=item *
2310
2311C<open FH, "-|">, in other words, opening pipes to itself.
2312
2313=back
2314
2315While these operations are not questions of life and death, they are
2316needed for a lot of
2317useful scripts. This forces C<a.out>-style compile of
2318F<perl.exe>.
2319
2320
2321=head1 ENVIRONMENT
2322
2323Here we list environment variables with are either OS/2- and DOS- and
2324Win*-specific, or are more important under OS/2 than under other OSes.
2325
2326=head2 C<PERLLIB_PREFIX>
2327
2328Specific for EMX port. Should have the form
2329
2330  path1;path2
2331
2332or
2333
2334  path1 path2
2335
2336If the beginning of some prebuilt path matches F<path1>, it is
2337substituted with F<path2>.
2338
2339Should be used if the perl library is moved from the default
2340location in preference to C<PERL(5)LIB>, since this would not leave wrong
2341entries in @INC.  For example, if the compiled version of perl looks for @INC
2342in F<f:/perllib/lib>, and you want to install the library in
2343F<h:/opt/gnu>, do
2344
2345  set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
2346
2347This will cause Perl with the prebuilt @INC of
2348
2349  f:/perllib/lib/5.00553/os2
2350  f:/perllib/lib/5.00553
2351  f:/perllib/lib/site_perl/5.00553/os2
2352  f:/perllib/lib/site_perl/5.00553
2353  .
2354
2355to use the following @INC:
2356
2357  h:/opt/gnu/5.00553/os2
2358  h:/opt/gnu/5.00553
2359  h:/opt/gnu/site_perl/5.00553/os2
2360  h:/opt/gnu/site_perl/5.00553
2361  .
2362
2363=head2 C<PERL_BADLANG>
2364
2365If 0, perl ignores setlocale() failing. May be useful with some
2366strange I<locale>s.
2367
2368=head2 C<PERL_BADFREE>
2369
2370If 0, perl would not warn of in case of unwarranted free(). With older
2371perls this might be
2372useful in conjunction with the module DB_File, which was buggy when
2373dynamically linked and OMF-built.
2374
2375Should not be set with newer Perls, since this may hide some I<real> problems.
2376
2377=head2 C<PERL_SH_DIR>
2378
2379Specific for EMX port. Gives the directory part of the location for
2380F<sh.exe>.
2381
2382=head2 C<USE_PERL_FLOCK>
2383
2384Specific for EMX port. Since L<flock(3)> is present in EMX, but is not 
2385functional, it is emulated by perl.  To disable the emulations, set 
2386environment variable C<USE_PERL_FLOCK=0>.
2387
2388=head2 C<TMP> or C<TEMP>
2389
2390Specific for EMX port. Used as storage place for temporary files.
2391
2392=head1 Evolution
2393
2394Here we list major changes which could make you by surprise.
2395
2396=head2 Text-mode filehandles
2397
2398Starting from version 5.8, Perl uses a builtin translation layer for
2399text-mode files.  This replaces the efficient well-tested EMX layer by
2400some code which should be best characterized as a "quick hack".
2401
2402In addition to possible bugs and an inability to follow changes to the
2403translation policy with off/on switches of TERMIO translation, this
2404introduces a serious incompatible change: before sysread() on
2405text-mode filehandles would go through the translation layer, now it
2406would not.
2407
2408=head2 Priorities
2409
2410C<setpriority> and C<getpriority> are not compatible with earlier
2411ports by Andreas Kaiser. See C<"setpriority, getpriority">.
2412
2413=head2 DLL name mangling: pre 5.6.2
2414
2415With the release 5.003_01 the dynamically loadable libraries
2416should be rebuilt when a different version of Perl is compiled. In particular,
2417DLLs (including F<perl.dll>) are now created with the names
2418which contain a checksum, thus allowing workaround for OS/2 scheme of
2419caching DLLs.
2420
2421It may be possible to code a simple workaround which would 
2422
2423=over
2424
2425=item *
2426
2427find the old DLLs looking through the old @INC;
2428
2429=item *
2430
2431mangle the names according to the scheme of new perl and copy the DLLs to
2432these names;
2433
2434=item *
2435
2436edit the internal C<LX> tables of DLL to reflect the change of the name
2437(probably not needed for Perl extension DLLs, since the internally coded names
2438are not used for "specific" DLLs, they used only for "global" DLLs).
2439
2440=item *
2441
2442edit the internal C<IMPORT> tables and change the name of the "old"
2443F<perl????.dll> to the "new" F<perl????.dll>.
2444
2445=back
2446
2447=head2 DLL name mangling: 5.6.2 and beyond
2448
2449In fact mangling of I<extension> DLLs was done due to misunderstanding
2450of the OS/2 dynaloading model.  OS/2 (effectively) maintains two
2451different tables of loaded DLL:
2452
2453=over
2454
2455=item Global DLLs
2456
2457those loaded by the base name from C<LIBPATH>; including those
2458associated at link time;
2459
2460=item specific DLLs
2461
2462loaded by the full name.
2463
2464=back
2465
2466When resolving a request for a global DLL, the table of already-loaded
2467specific DLLs is (effectively) ignored; moreover, specific DLLs are
2468I<always> loaded from the prescribed path.
2469
2470There is/was a minor twist which makes this scheme fragile: what to do
2471with DLLs loaded from
2472
2473=over
2474
2475=item C<BEGINLIBPATH> and C<ENDLIBPATH>
2476
2477(which depend on the process)
2478
2479=item F<.> from C<LIBPATH>
2480
2481which I<effectively> depends on the process (although C<LIBPATH> is the
2482same for all the processes).
2483
2484=back
2485
2486Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
24872000/09/01), such DLLs are considered to be global.  When loading a
2488global DLL it is first looked in the table of already-loaded global
2489DLLs.  Because of this the fact that one executable loaded a DLL from
2490C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
2491I<which> DLL is loaded when I<another> executable requests a DLL with
2492the same name.  I<This> is the reason for version-specific mangling of
2493the DLL name for perl DLL.
2494
2495Since the Perl extension DLLs are always loaded with the full path,
2496there is no need to mangle their names in a version-specific ways:
2497their directory already reflects the corresponding version of perl,
2498and @INC takes into account binary compatibility with older version.
2499Starting from C<5.6.2> the name mangling scheme is fixed to be the
2500same as for Perl 5.005_53 (same as in a popular binary release).  Thus
2501new Perls will be able to I<resolve the names> of old extension DLLs
2502if @INC allows finding their directories.
2503
2504However, this still does not guarantee that these DLL may be loaded.
2505The reason is the mangling of the name of the I<Perl DLL>.  And since
2506the extension DLLs link with the Perl DLL, extension DLLs for older
2507versions would load an older Perl DLL, and would most probably
2508segfault (since the data in this DLL is not properly initialized).
2509
2510There is a partial workaround (which can be made complete with newer
2511OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2512the older version of Perl, which forwards the entry points to the
2513newer Perl's DLL.  Make this DLL accessible on (say) the C<BEGINLIBPATH> of
2514the new Perl executable.  When the new executable accesses old Perl's
2515extension DLLs, they would request the old Perl's DLL by name, get the
2516forwarder instead, so effectively will link with the currently running
2517(new) Perl DLL.
2518
2519This may break in two ways:
2520
2521=over
2522
2523=item *
2524
2525Old perl executable is started when a new executable is running has
2526loaded an extension compiled for the old executable (ouph!).  In this
2527case the old executable will get a forwarder DLL instead of the old
2528perl DLL, so would link with the new perl DLL.  While not directly
2529fatal, it will behave the same as new executable.  This beats the whole
2530purpose of explicitly starting an old executable.
2531
2532=item *
2533
2534A new executable loads an extension compiled for the old executable
2535when an old perl executable is running.  In this case the extension
2536will not pick up the forwarder - with fatal results.
2537
2538=back
2539
2540With support for C<LIBPATHSTRICT> this may be circumvented - unless
2541one of DLLs is started from F<.> from C<LIBPATH> (I do not know
2542whether C<LIBPATHSTRICT> affects this case).
2543
2544B<REMARK>.  Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
2545do not), this mess cannot be completely cleaned.  (It turns out that
2546as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and
2547it has the same effect.)
2548
2549
2550B<REMARK>.  C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
2551not environment variables, although F<cmd.exe> emulates them on C<SET
2552...> lines.  From Perl they may be accessed by
2553L<Cwd::extLibpath|/Cwd::extLibpath([type])> and
2554L<Cwd::extLibpath_set|/Cwd::extLibpath_set( path [, type ] )>.
2555
2556=head2 DLL forwarder generation
2557
2558Assume that the old DLL is named F<perlE0AC.dll> (as is one for
25595.005_53), and the new version is 5.6.1.  Create a file
2560F<perl5shim.def-leader> with
2561
2562  LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2563  DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2564  CODE LOADONCALL
2565  DATA LOADONCALL NONSHARED MULTIPLE
2566  EXPORTS
2567
2568modifying the versions/names as needed.  Run
2569
2570 perl -wnle "next if 0../EXPORTS/; print qq(  \"$1\") if /\"(\w+)\"/" perl5.def >lst
2571
2572in the Perl build directory (to make the DLL smaller replace perl5.def
2573with the definition file for the older version of Perl if present).
2574
2575 cat perl5shim.def-leader lst >perl5shim.def
2576 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2577
2578(ignore multiple C<warning L4085>).
2579
2580=head2 Threading
2581
2582As of release 5.003_01 perl is linked to multithreaded C RTL
2583DLL.  If perl itself is not compiled multithread-enabled, so will not be perl's
2584malloc(). However, extensions may use multiple thread on their own
2585risk. 
2586
2587This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
2588link with DLLs for other useful libraries, which typically are compiled
2589with C<-Zmt -Zcrtdll>.
2590
2591=head2 Calls to external programs
2592
2593Due to a popular demand the perl external program calling has been
2594changed wrt Andreas Kaiser's port.  I<If> perl needs to call an
2595external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
2596whatever is the override, see L<"PERL_SH_DIR">.
2597
2598Thus means that you need to get some copy of a F<sh.exe> as well (I
2599use one from pdksh). The path F<F:/bin> above is set up automatically during
2600the build to a correct value on the builder machine, but is
2601overridable at runtime,
2602
2603B<Reasons:> a consensus on C<perl5-porters> was that perl should use
2604one non-overridable shell per platform. The obvious choices for OS/2
2605are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
2606with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
2607100% compatibility with the scripts coming from *nix. As an added benefit 
2608this works as well under DOS if you use DOS-enabled port of pdksh 
2609(see L</Prerequisites>).
2610
2611B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
2612via fork()/exec(), and there is I<no> functioning exec() on
2613OS/2. exec() is emulated by EMX by an asynchronous call while the caller
2614waits for child completion (to pretend that the C<pid> did not change). This
2615means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
2616which may lead to some resources taken from the system (even if we do
2617not count extra work needed for fork()ing).
2618
2619Note that this a lesser issue now when we do not spawn F<sh.exe>
2620unless needed (metachars found).
2621
2622One can always start F<cmd.exe> explicitly via
2623
2624  system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2625
2626If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
2627scripts, the long-term solution proposed on p5-p is to have a directive
2628
2629  use OS2::Cmd;
2630
2631which will override system(), exec(), C<``>, and
2632C<open(,'...|')>. With current perl you may override only system(),
2633readpipe() - the explicit version of C<``>, and maybe exec(). The code
2634will substitute the one-argument call to system() by
2635C<CORE::system('cmd.exe', '/c', shift)>.
2636
2637If you have some working code for C<OS2::Cmd>, please send it to me,
2638I will include it into distribution. I have no need for such a module, so
2639cannot test it.
2640
2641For the details of the current situation with calling external programs,
2642see L<Starting OSE<sol>2 (and DOS) programs under Perl>.  Set us mention a couple
2643of features:
2644
2645=over 4
2646
2647=item *
2648
2649External scripts may be called by their basename.  Perl will try the same
2650extensions as when processing B<-S> command-line switch.
2651
2652=item *
2653
2654External scripts starting with C<#!> or C<extproc > will be executed directly,
2655without calling the shell, by calling the program specified on the rest of
2656the first line.
2657
2658=back
2659
2660=head2 Memory allocation
2661
2662Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
2663for speed, but perl is not, since its malloc is lightning-fast.
2664Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
2665than EMX one.  I do not have convincing data about memory footprint, but
2666a (pretty random) benchmark showed that Perl's one is 5% better.
2667
2668Combination of perl's malloc() and rigid DLL name resolution creates
2669a special problem with library functions which expect their return value to
2670be free()d by system's free(). To facilitate extensions which need to call 
2671such functions, system memory-allocation functions are still available with
2672the prefix C<emx_> added. (Currently only DLL perl has this, it should 
2673propagate to F<perl_.exe> shortly.)
2674
2675=head2 Threads
2676
2677One can build perl with thread support enabled by providing C<-D usethreads>
2678option to F<Configure>.  Currently OS/2 support of threads is very 
2679preliminary.
2680
2681Most notable problems: 
2682
2683=over 4
2684
2685=item C<COND_WAIT> 
2686
2687may have a race condition (but probably does not due to edge-triggered
2688nature of OS/2 Event semaphores).  (Needs a reimplementation (in terms of chaining
2689waiting threads, with the linked list stored in per-thread structure?)?)
2690
2691=item F<os2.c>
2692
2693has a couple of static variables used in OS/2-specific functions.  (Need to be
2694moved to per-thread structure, or serialized?)
2695
2696=back
2697
2698Note that these problems should not discourage experimenting, since they
2699have a low probability of affecting small programs.
2700
2701=head1 BUGS
2702
2703This description is not updated often (since 5.6.1?), see F<./os2/Changes>
2704for more info.
2705
2706=cut
2707
2708OS/2 extensions
2709~~~~~~~~~~~~~~~
2710I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 
2711into my ftp directory, mirrored on CPAN. I made
2712some minor changes needed to compile them by standard tools. I cannot 
2713test UPM and FTP, so I will appreciate your feedback. Other extensions
2714there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
2715files - and maybe some other extensions at the time you read it.
2716
2717Note that OS2 perl defines 2 pseudo-extension functions
2718OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
2719L<Prebuilt methods>).
2720
2721The -R switch of older perl is deprecated. If you need to call a REXX code
2722which needs access to variables, include the call into a REXX compartment
2723created by 
2724	REXX_call {...block...};
2725
2726Two new functions are supported by REXX code, 
2727	REXX_eval 'string';
2728	REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
2729
2730If you have some other extensions you want to share, send the code to
2731me.  At least two are available: tied access to EA's, and tied access
2732to system databases.
2733
2734=head1 AUTHOR
2735
2736Ilya Zakharevich, cpan@ilyaz.org
2737
2738=head1 SEE ALSO
2739
2740perl(1).
2741
2742=cut
2743
2744

README.os390

1This document is written in pod format hence there are punctuation
2characters in odd places.  Do not worry, you've apparently got the
3ASCII->EBCDIC translation worked out correctly.  You can read more
4about pod in pod/perlpod.pod or the short summary in the INSTALL file.
5
6=head1 NAME
7
8perlos390 - building and installing Perl for OS/390 and z/OS
9
10=head1 SYNOPSIS
11
12This document will help you Configure, build, test and install Perl
13on OS/390 (aka z/OS) Unix System Services.
14
15B<This document needs to be updated, but we don't know what it should say.
16Please email comments to L<perlbug@perl.org|mailto:perlbug@perl.org>.>
17
18=head1 DESCRIPTION
19
20This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7,
218, and 9.  It may work on other versions or releases, but those are
22the ones we've tested it on.
23
24You may need to carry out some system configuration tasks before
25running the Configure script for Perl.
26
27
28=head2 Tools
29
30The z/OS Unix Tools and Toys list may prove helpful and contains links
31to ports of much of the software helpful for building Perl.
32http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
33
34
35=head2 Unpacking Perl distribution on OS/390
36
37If using ftp remember to transfer the distribution in binary format.
38
39Gunzip/gzip for OS/390 is discussed at:
40
41  http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html
42
43to extract an ASCII tar archive on OS/390, try this:
44
45   pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
46
47or
48
49   zcat latest.tar.Z | pax -o to=IBM-1047,from=ISO8859-1 -r
50
51If you get lots of errors of the form
52
53  tar: FSUM7171 ...: cannot set uid/gid: EDC5139I Operation not permitted.
54
55you didn't read the above and tried to use tar instead of pax, you'll
56first have to remove the (now corrupt) perl directory
57
58   rm -rf perl-...
59
60and then use pax.
61
62=head2 Setup and utilities for Perl on OS/390
63
64Be sure that your yacc installation is in place including any necessary
65parser template files. If you have not already done so then be sure to:
66
67  cp /samples/yyparse.c /etc
68
69This may also be a good time to ensure that your /etc/protocol file
70and either your /etc/resolv.conf or /etc/hosts files are in place.
71The IBM document that described such USS system setup issues was
72SC28-1890-07 "OS/390 UNIX System Services Planning", in particular
73Chapter 6 on customizing the OE shell.
74
75GNU make for OS/390, which is recommended for the build of perl (as
76well as building CPAN modules and extensions), is available from the
77L</Tools>.
78
79Some people have reported encountering "Out of memory!" errors while
80trying to build Perl using GNU make binaries.  If you encounter such
81trouble then try to download the source code kit and build GNU make
82from source to eliminate any such trouble.  You might also find GNU make
83(as well as Perl and Apache) in the red-piece/book "Open Source Software
84for OS/390 UNIX", SG24-5944-00 from IBM.
85
86If instead of the recommended GNU make you would like to use the system
87supplied make program then be sure to install the default rules file
88properly via the shell command:
89
90    cp /samples/startup.mk /etc
91
92and be sure to also set the environment variable _C89_CCMODE=1 (exporting
93_C89_CCMODE=1 is also a good idea for users of GNU make).
94
95You might also want to have GNU groff for OS/390 installed before
96running the "make install" step for Perl.
97
98There is a syntax error in the /usr/include/sys/socket.h header file
99that IBM supplies with USS V2R7, V2R8, and possibly V2R9.  The problem with
100the header file is that near the definition of the SO_REUSEPORT constant
101there is a spurious extra '/' character outside of a comment like so:
102
103 #define SO_REUSEPORT    0x0200    /* allow local address & port
104                                      reuse */                    /
105
106You could edit that header yourself to remove that last '/', or you might
107note that Language Environment (LE) APAR PQ39997 describes the problem
108and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and apply them.
109If left unattended that syntax error will turn up as an inability for Perl
110to build its "Socket" extension.
111
112For successful testing you may need to turn on the sticky bit for your
113world readable /tmp directory if you have not already done so (see man chmod).
114
115=head2 Configure Perl on OS/390
116
117Once you've unpacked the distribution, run "sh Configure" (see INSTALL
118for a full discussion of the Configure options).  There is a "hints" file
119for os390 that specifies the correct values for most things.  Some things
120to watch out for include:
121
122=over 4
123
124=item *
125
126A message of the form:
127
128 (I see you are using the Korn shell.  Some ksh's blow up on Configure,
129 mainly on older exotic systems.  If yours does, try the Bourne shell instead.)
130
131is nothing to worry about at all.
132
133=item *
134
135Some of the parser default template files in /samples are needed in /etc.
136In particular be sure that you at least copy /samples/yyparse.c to /etc
137before running Perl's Configure.  This step ensures successful extraction
138of EBCDIC versions of parser files such as perly.c and perly.h.
139This has to be done before running Configure the first time.  If you failed
140to do so then the easiest way to re-Configure Perl is to delete your
141misconfigured build root and re-extract the source from the tar ball.
142Then you must ensure that /etc/yyparse.c is properly in place before
143attempting to re-run Configure.
144
145=item *
146
147This port will support dynamic loading, but it is not selected by
148default.  If you would like to experiment with dynamic loading then
149be sure to specify -Dusedl in the arguments to the Configure script.
150See the comments in hints/os390.sh for more information on dynamic loading.
151If you build with dynamic loading then you will need to add the
152$archlibexp/CORE directory to your LIBPATH environment variable in order
153for perl to work.  See the config.sh file for the value of $archlibexp.
154If in trying to use Perl you see an error message similar to:
155
156 CEE3501S The module libperl.dll was not found.
157         From entry point __dllstaticinit at compile unit offset +00000194 at
158
159then your LIBPATH does not have the location of libperl.x and either
160libperl.dll or libperl.so in it.  Add that directory to your LIBPATH and
161proceed.
162
163=item *
164
165Do not turn on the compiler optimization flag "-O".  There is
166a bug in either the optimizer or perl that causes perl to
167not work correctly when the optimizer is on.
168
169=item *
170
171Some of the configuration files in /etc used by the
172networking APIs are either missing or have the wrong
173names.  In particular, make sure that there's either
174an /etc/resolv.conf or an /etc/hosts, so that
175gethostbyname() works, and make sure that the file
176/etc/proto has been renamed to /etc/protocol (NOT
177/etc/protocols, as used by other Unix systems).
178You may have to look for things like HOSTNAME and DOMAINORIGIN
179in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to
180properly set up your /etc networking files.
181
182=back
183
184=head2 Build, Test, Install Perl on OS/390
185
186Simply put:
187
188    sh Configure
189    make
190    make test
191
192if everything looks ok (see the next section for test/IVP diagnosis) then:
193
194    make install
195
196this last step may or may not require UID=0 privileges depending
197on how you answered the questions that Configure asked and whether
198or not you have write access to the directories you specified.
199
200=head2 Build Anomalies with Perl on OS/390
201
202"Out of memory!" messages during the build of Perl are most often fixed
203by re building the GNU make utility for OS/390 from a source code kit.
204
205Another memory limiting item to check is your MAXASSIZE parameter in your
206'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space
207limits can be set on a per user ID basis in the USS segment of a RACF
208profile).  People have reported successful builds of Perl with MAXASSIZE
209parameters as small as 503316480 (and it may be possible to build Perl
210with a MAXASSIZE smaller than that).
211
212Within USS your /etc/profile or $HOME/.profile may limit your ulimit
213settings.  Check that the following command returns reasonable values:
214
215    ulimit -a
216
217To conserve memory you should have your compiler modules loaded into the
218Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
219
220If the c89 compiler complains of syntax errors during the build of the
221Socket extension then be sure to fix the syntax error in the system
222header /usr/include/sys/socket.h.
223
224=head2 Testing Anomalies with Perl on OS/390
225
226The "make test" step runs a Perl Verification Procedure, usually before
227installation.  You might encounter STDERR messages even during a successful
228run of "make test".  Here is a guide to some of the more commonly seen
229anomalies:
230
231=over 4
232
233=item *
234
235A message of the form:
236
237 io/openpid...........CEE5210S The signal SIGHUP was received.
238 CEE5210S The signal SIGHUP was received.
239 CEE5210S The signal SIGHUP was received.
240 ok
241
242indicates that the t/io/openpid.t test of Perl has passed but done so
243with extraneous messages on stderr from CEE.
244
245=item *
246
247A message of the form:
248
249 lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/) is not safe
250 (sticky bit not set when world writable?) at lib/ftmp-security.t line 100
251 File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky bit not
252 set when world writable?) at lib/ftmp-security.t line 100
253 ok
254
255indicates a problem with the permissions on your /tmp directory within the HFS.
256To correct that problem issue the command:
257
258     chmod a+t /tmp
259
260from an account with write access to the directory entry for /tmp.
261
262=item *
263
264Out of Memory!
265
266Recent perl test suite is quite memory hungry. In addition to the comments
267above on memory limitations it is also worth checking for _CEE_RUNOPTS
268in your environment. Perl now has (in miniperlmain.c) a C #pragma
269to set CEE run options, but the environment variable wins.
270
271The C code asks for:
272
273 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
274
275The important parts of that are the second argument (the increment) to HEAP,
276and allowing the stack to be "Above the (16M) line". If the heap
277increment is too small then when perl (for example loading unicode/Name.pl) tries
278to create a "big" (400K+) string it cannot fit in a single segment
279and you get "Out of Memory!" - even if there is still plenty of memory
280available.
281
282A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
283to get memory, and C<sbrk()> is limited to the first allocation so in this
284case something like:
285
286  HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
287
288is needed to get through the test suite.
289
290
291=back
292
293=head2 Installation Anomalies with Perl on OS/390
294
295The installman script will try to run on OS/390.  There will be fewer errors
296if you have a roff utility installed.  You can obtain GNU groff from the
297Redbook SG24-5944-00 ftp site.
298
299=head2 Usage Hints for Perl on OS/390
300
301When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
302character sets are different.  See perlebcdic.pod for more on such character
303set issues.  Perl builtin functions that may behave differently under
304EBCDIC are also mentioned in the perlport.pod document.
305
306Open Edition (UNIX System Services) from V2R8 onward does support
307#!/path/to/perl script invocation.  There is a PTF available from
308IBM for V2R7 that will allow shell/kernel support for #!.  USS
309releases prior to V2R7 did not support the #! means of script invocation.
310If you are running V2R6 or earlier then see:
311
312    head `whence perldoc`
313
314for an example of how to use the "eval exec" trick to ask the shell to
315have Perl run your scripts on those older releases of Unix System Services.
316
317If you are having trouble with square brackets then consider switching your
318rlogin or telnet client.  Try to avoid older 3270 emulators and ISHELL for
319working with Perl on USS.
320
321=head2 Floating Point Anomalies with Perl on OS/390
322
323There appears to be a bug in the floating point implementation on S/390
324systems such that calling int() on the product of a number and a small
325magnitude number is not the same as calling int() on the quotient of
326that number and a large magnitude number.  For example, in the following
327Perl code:
328
329    my $x = 100000.0;
330    my $y = int($x * 1e-5) * 1e5; # '0'
331    my $z = int($x / 1e+5) * 1e5;  # '100000'
332    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
333
334Although one would expect the quantities $y and $z to be the same and equal
335to 100000 they will differ and instead will be 0 and 100000 respectively.
336
337The problem can be further examined in a roughly equivalent C program:
338
339    #include <stdio.h>
340    #include <math.h>
341    main()
342    {
343    double r1,r2;
344    double x = 100000.0;
345    double y = 0.0;
346    double z = 0.0;
347    x = 100000.0 * 1e-5;
348    r1 = modf (x,&y);
349    x = 100000.0 / 1e+5;
350    r2 = modf (x,&z);
351    printf("y is %e and z is %e\n",y*1e5,z*1e5);
352    /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
353    }
354
355=head2 Modules and Extensions for Perl on OS/390
356
357Pure pure (that is non xs) modules may be installed via the usual:
358
359    perl Makefile.PL
360    make
361    make test
362    make install
363
364If you built perl with dynamic loading capability then that would also
365be the way to build xs based extensions.  However, if you built perl with
366the default static linking you can still build xs based extensions for OS/390
367but you will need to follow the instructions in ExtUtils::MakeMaker for
368building statically linked perl binaries.  In the simplest configurations
369building a static perl + xs extension boils down to:
370
371    perl Makefile.PL
372    make
373    make perl
374    make test
375    make install
376    make -f Makefile.aperl inst_perl MAP_TARGET=perl
377
378In most cases people have reported better results with GNU make rather
379than the system's /bin/make program, whether for plain modules or for
380xs based extensions.
381
382If the make process encounters trouble with either compilation or
383linking then try setting the _C89_CCMODE to 1.  Assuming sh is your
384login shell then run:
385
386    export _C89_CCMODE=1
387
388If tcsh is your login shell then use the setenv command.
389
390=head1 AUTHORS
391
392David Fiander and Peter Prymmer with thanks to Dennis Longnecker
393and William Raffloer for valuable reports, LPAR and PTF feedback.
394Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
395Thanks to Ignasi Roca for pointing out the floating point problems.
396Thanks to John Goodyear for dynamic loading help.
397
398=head1 SEE ALSO
399
400L<INSTALL>, L<perlport>, L<perlebcdic>, L<ExtUtils::MakeMaker>.
401
402    http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
403
404    http://www.redbooks.ibm.com/redbooks/SG245944.html
405
406    http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
407
408    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
409
410    http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
411
412    http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/
413
414=head2 Mailing list for Perl on OS/390
415
416If you are interested in the z/OS (formerly known as OS/390)
417and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
418To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
419
420See also:
421
422    http://lists.perl.org/list/perl-mvs.html
423
424There are web archives of the mailing list at:
425
426    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
427    http://archive.develooper.com/perl-mvs@perl.org/
428
429=head1 HISTORY
430
431This document was originally written by David Fiander for the 5.005
432release of Perl.
433
434This document was podified for the 5.005_03 release of Perl 11 March 1999.
435
436Updated 28 November 2001 for broken URLs.
437
438Updated 12 November 2000 for the 5.7.1 release of Perl.
439
440Updated 15 January 2001 for the 5.7.1 release of Perl.
441
442Updated 24 January 2001 to mention dynamic loading.
443
444Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
445
446=cut
447
448

README.os400

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlos400 - Perl version 5 on OS/400
8
9B<This document needs to be updated, but we don't know what it should say.
10Please email comments to L<perlbug@perl.org|mailto:perlbug@perl.org>.>
11
12=head1 DESCRIPTION
13
14This document describes various features of IBM's OS/400 operating
15system that will affect how Perl version 5 (hereafter just Perl) is
16compiled and/or runs.
17
18By far the easiest way to build Perl for OS/400 is to use the PASE
19(Portable Application Solutions Environment), for more information see
20L<http://www.iseries.ibm.com/developer/factory/pase/index.html>
21This environment allows one to use AIX APIs while programming, and it
22provides a runtime that allows AIX binaries to execute directly on the
23PowerPC iSeries.
24
25=head2 Compiling Perl for OS/400 PASE
26
27The recommended way to build Perl for the OS/400 PASE is to build the
28Perl 5 source code (release 5.8.1 or later) under AIX.
29
30The trick is to give a special parameter to the Configure shell script
31when running it on AIX:
32
33  sh Configure -DPASE ...
34
35The default installation directory of Perl under PASE is /QOpenSys/perl.
36This can be modified if needed with Configure parameter -Dprefix=/some/dir.
37
38Starting from OS/400 V5R2 the IBM Visual Age compiler is supported
39on OS/400 PASE, so it is possible to build Perl natively on OS/400.  
40The easier way, however, is to compile in AIX, as just described.
41
42If you don't want to install the compiled Perl in AIX into /QOpenSys
43(for packaging it before copying it to PASE), you can use a Configure
44parameter: -Dinstallprefix=/tmp/QOpenSys/perl.  This will cause the
45"make install" to install everything into that directory, while the
46installed files still think they are (will be) in /QOpenSys/perl.
47
48If building natively on PASE, please do the build under the /QOpenSys
49directory, since Perl is happier when built on a case sensitive filesystem.
50
51=head2 Installing Perl in OS/400 PASE
52
53If you are compiling on AIX, simply do a "make install" on the AIX box.
54Once the install finishes, tar up the /QOpenSys/perl directory.  Transfer
55the tarball to the OS/400 using FTP with the following commands:
56
57  > binary
58  > site namefmt 1
59  > put perl.tar /QOpenSys
60
61Once you have it on, simply bring up a PASE shell and extract the tarball.
62
63If you are compiling in PASE, then "make install" is the only thing you
64will need to do.
65
66The default path for perl binary is /QOpenSys/perl/bin/perl.  You'll
67want to symlink /QOpenSys/usr/bin/perl to this file so you don't have
68to modify your path.
69
70=head2 Using Perl in OS/400 PASE
71
72Perl in PASE may be used in the same manner as you would use Perl on AIX.
73
74Scripts starting with #!/usr/bin/perl should work if you have
75/QOpenSys/usr/bin/perl symlinked to your perl binary.  This will not
76work if you've done a setuid/setgid or have environment variable
77PASE_EXEC_QOPENSYS="N".  If you have V5R1, you'll need to get the
78latest PTFs to have this feature.  Scripts starting with
79#!/QOpenSys/perl/bin/perl should always work.
80
81=head2 Known Problems
82
83When compiling in PASE, there is no "oslevel" command.  Therefore,
84you may want to create a script called "oslevel" that echoes the
85level of AIX that your version of PASE runtime supports.  If you're
86unsure, consult your documentation or use "4.3.3.0".
87
88If you have test cases that fail, check for the existence of spool files.
89The test case may be trying to use a syscall that is not implemented
90in PASE.  To avoid the SIGILL, try setting the PASE_SYSCALL_NOSIGILL
91environment variable or have a handler for the SIGILL.  If you can
92compile programs for PASE, run the config script and edit config.sh
93when it gives you the option.  If you want to remove fchdir(), which
94isn't implement in V5R1, simply change the line that says:
95
96d_fchdir='define'
97
98to
99
100d_fchdir='undef'
101
102and then compile Perl.  The places where fchdir() is used have
103alternatives for systems that do not have fchdir() available.
104
105=head2 Perl on ILE
106
107There exists a port of Perl to the ILE environment.  This port, however,
108is based quite an old release of Perl, Perl 5.00502 (August 1998).
109(As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1
110has been out since April 2001.)  If you need to run Perl on ILE, though,
111you may need this older port: L<http://www.cpan.org/ports/#os400>
112Note that any Perl release later than 5.00502 has not been ported to ILE.
113
114If you need to use Perl in the ILE environment, you may want to consider
115using Qp2RunPase() to call the PASE version of Perl.
116
117=head1 AUTHORS
118
119Jarkko Hietaniemi <jhi@iki.fi>
120Bryan Logan <bryanlog@us.ibm.com>
121David Larson <larson1@us.ibm.com>
122
123=cut
124

README.plan9

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlplan9 - Plan 9-specific documentation for Perl
8
9=head1 DESCRIPTION
10
11These are a few notes describing features peculiar to
12Plan 9 Perl. As such, it is not intended to be a replacement
13for the rest of the Perl 5 documentation (which is both 
14copious and excellent). If you have any questions to 
15which you can't find answers in these man pages, contact 
16Luther Huffman at lutherh@stratcom.com and we'll try to 
17answer them.
18
19=head2 Invoking Perl
20
21Perl is invoked from the command line as described in 
22L<perl>. Most perl scripts, however, do have a first line 
23such as "#!/usr/local/bin/perl". This is known as a shebang 
24(shell-bang) statement and tells the OS shell where to find 
25the perl interpreter. In Plan 9 Perl this statement should be 
26"#!/bin/perl" if you wish to be able to directly invoke the 
27script by its name.
28     Alternatively, you may invoke perl with the command "Perl"
29instead of "perl". This will produce Acme-friendly error
30messages of the form "filename:18".
31
32Some scripts, usually identified with a *.PL extension, are 
33self-configuring and are able to correctly create their own 
34shebang path from config information located in Plan 9 
35Perl. These you won't need to be worried about.
36
37=head2 What's in Plan 9 Perl
38
39Although Plan 9 Perl currently only  provides static 
40loading, it is built with a number of useful extensions. 
41These include Opcode, FileHandle, Fcntl, and POSIX. Expect 
42to see others (and DynaLoading!) in the future.
43
44=head2 What's not in Plan 9 Perl
45
46As mentioned previously, dynamic loading isn't currently 
47available nor is MakeMaker. Both are high-priority items.
48
49=head2 Perl5 Functions not currently supported in Plan 9 Perl
50
51Some, such as C<chown> and C<umask> aren't provided 
52because the concept does not exist within Plan 9. Others,
53such as some of the socket-related functions, simply
54haven't been written yet. Many in the latter category 
55may be supported in the future.
56
57The functions not currently implemented include:
58
59    chown, chroot, dbmclose, dbmopen, getsockopt, 
60    setsockopt, recvmsg, sendmsg, getnetbyname, 
61    getnetbyaddr, getnetent, getprotoent, getservent, 
62    sethostent, setnetent, setprotoent, setservent, 
63    endservent, endnetent, endprotoent, umask
64
65There may be several other functions that have undefined 
66behavior so this list shouldn't be considered complete.
67
68=head2 Signals in Plan 9 Perl
69
70For compatibility with perl scripts written for the Unix 
71environment, Plan 9 Perl uses the POSIX signal emulation
72provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
73isn't supported. The signals provided are:
74
75    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
76    SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM, 
77    SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
78    SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU
79
80=head1 COMPILING AND INSTALLING PERL ON PLAN 9
81
82WELCOME to Plan 9 Perl, brave soul!
83
84   This is a preliminary alpha version of Plan 9 Perl. Still to be
85implemented are MakeMaker and DynaLoader. Many perl commands are
86missing or currently behave in an inscrutable manner. These gaps will,
87with perseverance and a modicum of luck, be remedied in the near
88future.To install this software:
89
901. Create the source directories and libraries for perl by running the
91plan9/setup.rc command (i.e., located in the plan9 subdirectory).
92Note: the setup routine assumes that you haven't dearchived these
93files into /sys/src/cmd/perl. After running setup.rc you may delete
94the copy of the source you originally detarred, as source code has now
95been installed in /sys/src/cmd/perl. If you plan on installing perl
96binaries for all architectures, run "setup.rc -a".
97
982. After making sure that you have adequate privileges to build system
99software, from /sys/src/cmd/perl/5.00301 (adjust version
100appropriately) run:
101
102	mk install
103
104If you wish to install perl versions for all architectures (68020,
105mips, sparc and 386) run:
106
107	mk installall
108
1093. Wait. The build process will take a *long* time because perl
110bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30
111minutes to build the distribution from scratch.
112
113=head2 Installing Perl Documentation on Plan 9
114
115This perl distribution comes with a tremendous amount of
116documentation. To add these to the built-in manuals that come with
117Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately)
118run:
119
120	mk man
121
122To begin your reading, start with:
123
124	man perl
125
126This is a good introduction and will direct you towards other man
127pages that may interest you.
128
129(Note: "mk man" may produce some extraneous noise. Fear not.)
130
131=head1 BUGS
132
133"As many as there are grains of sand on all the beaches of the 
134world . . ." - Carl Sagan
135
136=head1 Revision date
137
138This document was revised 09-October-1996 for Perl 5.003_7.
139
140=head1 AUTHOR
141
142Direct questions, comments, and the unlikely bug report (ahem) direct
143comments toward:
144
145Luther Huffman, lutherh@stratcom.com, 
146Strategic Computer Solutions, Inc.		
147

README.qnx

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlqnx - Perl version 5 on QNX
8
9=head1 DESCRIPTION
10
11As of perl5.7.2 all tests pass under:
12
13  QNX 4.24G
14  Watcom 10.6 with Beta/970211.wcc.update.tar.F
15  socket3r.lib Nov21 1996.
16
17As of perl5.8.1 there is at least one test still failing.
18
19Some tests may complain under known circumstances.
20
21See below and hints/qnx.sh for more information.
22
23Under QNX 6.2.0 there are still a few tests which fail.
24See below and hints/qnx.sh for more information.
25
26=head2 Required Software for Compiling Perl on QNX4
27
28As with many unix ports, this one depends on a few "standard"
29unix utilities which are not necessarily standard for QNX4.
30
31=over 4
32
33=item /bin/sh
34
35This is used heavily by Configure and then by
36perl itself. QNX4's version is fine, but Configure
37will choke on the 16-bit version, so if you are
38running QNX 4.22, link /bin/sh to /bin32/ksh
39
40=item ar
41
42This is the standard unix library builder.
43We use wlib. With Watcom 10.6, when wlib is
44linked as "ar", it behaves like ar and all is
45fine. Under 9.5, a cover is required. One is
46included in ../qnx
47
48=item nm
49
50This is used (optionally) by configure to list
51the contents of libraries. I will generate
52a cover function on the fly in the UU directory.
53
54=item cpp
55
56Configure and perl need a way to invoke a C
57preprocessor. I have created a simple cover
58for cc which does the right thing. Without this,
59Configure will create its own wrapper which works,
60but it doesn't handle some of the command line arguments
61that perl will throw at it.
62
63=item make
64
65You really need GNU make to compile this. GNU make
66ships by default with QNX 4.23, but you can get it
67from quics for earlier versions.
68
69=back
70
71=head2 Outstanding Issues with Perl on QNX4
72
73There is no support for dynamically linked libraries in QNX4.
74
75If you wish to compile with the Socket extension, you need
76to have the TCP/IP toolkit, and you need to make sure that
77-lsocket locates the correct copy of socket3r.lib. Beware
78that the Watcom compiler ships with a stub version of
79socket3r.lib which has very little functionality. Also
80beware the order in which wlink searches directories for
81libraries. You may have /usr/lib/socket3r.lib pointing to
82the correct library, but wlink may pick up
83/usr/watcom/10.6/usr/lib/socket3r.lib instead. Make sure
84they both point to the correct library, that is,
85/usr/tcptk/current/usr/lib/socket3r.lib.
86
87The following tests may report errors under QNX4:
88
89dist/Cwd/Cwd.t will complain if `pwd` and cwd don't give
90the same results. cwd calls `fullpath -t`, so if you
91cd `fullpath -t` before running the test, it will
92pass.
93
94lib/File/Find/taint.t will complain if '.' is in your
95PATH. The PATH test is triggered because cwd calls
96`fullpath -t`.
97
98ext/IO/lib/IO/t/io_sock.t: Subtests 14 and 22 are skipped due to
99the fact that the functionality to read back the non-blocking
100status of a socket is not implemented in QNX's TCP/IP. This has
101been reported to QNX and it may work with later versions of
102TCP/IP.
103
104t/io/tell.t: Subtest 27 is failing. We are still investigating.
105
106=head2 QNX auxiliary files
107
108The files in the "qnx" directory are:
109
110=over 4
111
112=item qnx/ar
113
114A script that emulates the standard unix archive (aka library)
115utility.  Under Watcom 10.6, ar is linked to wlib and provides the
116expected interface. With Watcom 9.5, a cover function is
117required. This one is fairly crude but has proved adequate for
118compiling perl.
119
120=item qnx/cpp
121
122A script that provides C preprocessing functionality.  Configure can
123generate a similar cover, but it doesn't handle all the command-line
124options that perl throws at it. This might be reasonably placed in
125/usr/local/bin.
126
127=back
128
129=head2 Outstanding issues with perl under QNX6
130
131The following tests are still failing for Perl 5.8.1 under QNX 6.2.0:
132
133  op/sprintf.........................FAILED at test 91
134  lib/Benchmark......................FAILED at test 26
135
136This is due to a bug in the C library's printf routine.
137printf("'%e'", 0. ) produces '0.000000e+0', but ANSI requires
138'0.000000e+00'. QNX has acknowledged the bug.
139
140=head2 Cross-compilation
141
142Perl supports cross-compiling to QNX NTO through the
143Native Development Kit (NDK) for the Blackberry 10.  This means that you
144can cross-compile for both ARM and x86 versions of the platform.
145
146=head3 Setting up a cross-compilation environment
147
148You can download the NDK from
149L<http://developer.blackberry.com/native/downloads/>.
150
151See
152L<http://developer.blackberry.com/native/documentation/cascades/getting_started/setting_up.html>
153for instructions to set up your device prior to attempting anything else.
154
155Once you've installed the NDK and set up your device, all that's
156left to do is setting up the device and the cross-compilation
157environment.  Blackberry provides a script, C<bbndk-env.sh> (occasionally
158named something like C<bbndk-env_10_1_0_4828.sh>) which can be used
159to do this.  However, there's a bit of a snag that we have to work through:
160The script modifies PATH so that 'gcc' or 'ar' point to their
161cross-compilation equivalents, which screws over the build process.
162
163So instead you'll want to do something like this:
164
165    $ orig_path=$PATH
166    $ source $location_of_bbndk/bbndk-env*.sh
167    $ export PATH="$orig_path:$PATH"
168
169Besides putting the cross-compiler and the rest of the toolchain in your
170PATH, this will also provide the QNX_TARGET variable, which
171we will pass to Configure through -Dsysroot.
172
173=head3 Preparing the target system
174
175It's quite possible that the target system doesn't have a readily
176available /tmp, so it's generall safer to do something like this:
177
178 $ ssh $TARGETUSER@$TARGETHOST 'rm -rf perl; mkdir perl; mkdir perl/tmp'
179 $ export TARGETDIR=`ssh $TARGETUSER@$TARGETHOST pwd`/perl
180 $ export TARGETENV="export TMPDIR=$TARGETDIR/tmp; "
181
182Later on, we'll pass this to Configure through -Dtargetenv
183
184=head3 Calling Configure
185
186If you are targetting an ARM device -- which currently includes the vast 
187majority of phones and tablets -- you'll want to pass
188-Dcc=arm-unknown-nto-qnx8.0.0eabi-gcc to Configure.  Alternatively, if you 
189are targetting an x86 device, or using the simulator provided with the NDK,
190you should specify -Dcc=ntox86-gcc instead.
191
192A sample Configure invocation looks something like this:
193
194    ./Configure -des -Dusecrosscompile \
195        -Dsysroot=$QNX_TARGET          \
196        -Dtargetdir=$TARGETDIR         \
197        -Dtargetenv="$TARGETENV"       \
198        -Dcc=ntox86-gcc                \
199        -Dtarghost=... # Usual cross-compilation options
200
201=head1 AUTHOR
202
203Norton T. Allen (allen@huarp.harvard.edu)
204
205

README.riscos

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlriscos - Perl version 5 for RISC OS
8
9=head1 DESCRIPTION
10
11This document gives instructions for building Perl for RISC OS. It is
12complicated by the need to cross compile. There is a binary version of
13perl available from L<http://www.cp15.org/perl/> which you may wish to
14use instead of trying to compile it yourself.
15
16=head1 BUILD
17
18You need an installed and working gccsdk cross compiler
19L<http://gccsdk.riscos.info/> and REXEN
20L<http://www.cp15.org/programming/>
21
22Firstly, copy the source and build a native copy of perl for your host
23system.
24Then, in the source to be cross compiled:
25
26=over 4
27
28=item 1.
29
30    $ ./Configure
31
32=item 2.
33
34Select the riscos hint file. The default answers for the rest of the
35questions are usually sufficient.
36
37Note that, if you wish to run Configure non-interactively (see the INSTALL
38document for details), to have it select the correct hint file, you'll
39need to provide the argument -Dhintfile=riscos on the Configure
40command-line.
41
42=item 3.
43
44    $ make miniperl
45
46=item 4.
47
48This should build miniperl and then fail when it tries to run it.
49
50=item 5.
51
52Copy the miniperl executable from the native build done earlier to
53replace the cross compiled miniperl.
54
55=item 6.
56
57    $ make
58
59=item 7.
60
61This will use miniperl to complete the rest of the build.
62
63=back
64
65=head1 AUTHOR
66
67Alex Waugh <alex@alexwaugh.com>
68

README.solaris

1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlsolaris - Perl version 5 on Solaris systems
8
9=head1 DESCRIPTION
10
11This document describes various features of Sun's Solaris operating system
12that will affect how Perl version 5 (hereafter just perl) is
13compiled and/or runs.  Some issues relating to the older SunOS 4.x are
14also discussed, though they may be out of date.
15
16For the most part, everything should just work.
17
18Starting with Solaris 8, perl5.00503 (or higher) is supplied with the
19operating system, so you might not even need to build a newer version
20of perl at all.  The Sun-supplied version is installed in /usr/perl5
21with F</usr/bin/perl> pointing to F</usr/perl5/bin/perl>.  Do not disturb
22that installation unless you really know what you are doing.  If you
23remove the perl supplied with the OS, you will render some bits of
24your system inoperable.  If you wish to install a newer version of perl,
25install it under a different prefix from /usr/perl5.  Common prefixes
26to use are /usr/local and /opt/perl.
27
28You may wish to put your version of perl in the PATH of all users by
29changing the link F</usr/bin/perl>.  This is probably OK, as most perl
30scripts shipped with Solaris use an explicit path.  (There are a few
31exceptions, such as F</usr/bin/rpm2cpio> and F</etc/rcm/scripts/README>, but
32these are also sufficiently generic that the actual version of perl
33probably doesn't matter too much.)
34
35Solaris ships with a range of Solaris-specific modules.  If you choose
36to install your own version of perl you will find the source of many of
37these modules is available on CPAN under the Sun::Solaris:: namespace.
38
39Solaris may include two versions of perl, e.g. Solaris 9 includes
40both 5.005_03 and 5.6.1.  This is to provide stability across Solaris
41releases, in cases where a later perl version has incompatibilities
42with the version included in the preceding Solaris release.  The
43default perl version will always be the most recent, and in general
44the old version will only be retained for one Solaris release.  Note
45also that the default perl will NOT be configured to search for modules
46in the older version, again due to compatibility/stability concerns.
47As a consequence if you upgrade Solaris, you will have to
48rebuild/reinstall any additional CPAN modules that you installed for
49the previous Solaris version.  See the CPAN manpage under 'autobundle'
50for a quick way of doing this.
51
52As an interim measure, you may either change the #! line of your
53scripts to specifically refer to the old perl version, e.g. on
54Solaris 9 use #!/usr/perl5/5.00503/bin/perl to use the perl version
55that was the default for Solaris 8, or if you have a large number of
56scripts it may be more convenient to make the old version of perl the
57default on your system.  You can do this by changing the appropriate
58symlinks under /usr/perl5 as follows (example for Solaris 9):
59
60 # cd /usr/perl5
61 # rm bin man pod
62 # ln -s ./5.00503/bin
63 # ln -s ./5.00503/man
64 # ln -s ./5.00503/lib/pod
65 # rm /usr/bin/perl
66 # ln -s ../perl5/5.00503/bin/perl /usr/bin/perl
67
68In both cases this should only be considered to be a temporary
69measure - you should upgrade to the later version of perl as soon as
70is practicable.
71
72Note also that the perl command-line utilities (e.g. perldoc) and any
73that are added by modules that you install will be under
74/usr/perl5/bin, so that directory should be added to your PATH.
75
76=head2 Solaris Version Numbers.
77
78For consistency with common usage, perl's Configure script performs
79some minor manipulations on the operating system name and version
80number as reported by uname.  Here's a partial translation table:
81
82          Sun:                      perl's Configure:
83 uname    uname -r   Name           osname     osvers
84 SunOS    4.1.3     Solaris 1.1     sunos      4.1.3
85 SunOS    5.6       Solaris 2.6     solaris    2.6
86 SunOS    5.8       Solaris 8       solaris    2.8
87 SunOS    5.9       Solaris 9       solaris    2.9
88 SunOS    5.10      Solaris 10      solaris    2.10
89
90The complete table can be found in the Sun Managers' FAQ
91L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq> under
92"9.1) Which Sun models run which versions of SunOS?".
93
94=head1 RESOURCES
95
96There are many, many sources for Solaris information.  A few of the
97important ones for perl:
98
99=over 4
100
101=item Solaris FAQ
102
103The Solaris FAQ is available at
104L<http://www.science.uva.nl/pub/solaris/solaris2.html>.
105
106The Sun Managers' FAQ is available at
107L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq>
108
109=item Precompiled Binaries
110
111Precompiled binaries, links to many sites, and much, much more are
112available at L<http://www.sunfreeware.com/> and
113L<http://www.blastwave.org/>.
114
115=item Solaris Documentation
116
117All Solaris documentation is available on-line at L<http://docs.sun.com/>.
118
119=back
120
121=head1 SETTING UP
122
123=head2 File Extraction Problems on Solaris.
124
125Be sure to use a tar program compiled under Solaris (not SunOS 4.x)
126to extract the perl-5.x.x.tar.gz file.  Do not use GNU tar compiled
127for SunOS4 on Solaris.  (GNU tar compiled for Solaris should be fine.)
128When you run SunOS4 binaries on Solaris, the run-time system magically
129alters pathnames matching m#lib/locale# so that when tar tries to create
130lib/locale.pm, a file named lib/oldlocale.pm gets created instead.
131If you found this advice too late and used a SunOS4-compiled tar
132anyway, you must find the incorrectly renamed file and move it back
133to lib/locale.pm.
134
135=head2 Compiler and Related Tools on Solaris.
136
137You must use an ANSI C compiler to build perl.  Perl can be compiled
138with either Sun's add-on C compiler or with gcc.  The C compiler that
139shipped with SunOS4 will not do.
140
141=head3 Include /usr/ccs/bin/ in your PATH.
142
143Several tools needed to build perl are located in /usr/ccs/bin/:  ar,
144as, ld, and make.  Make sure that /usr/ccs/bin/ is in your PATH.
145
146
147On all the released versions of Solaris (8, 9 and 10) you need to make sure the following packages are installed (this info is extracted from the Solaris FAQ):
148
149for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool,
150SUNWsprot, SUNWtoo
151
152for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh,
153SUNWcg6h, SUNWxwinc
154
155Additionaly, on Solaris 8 and 9 you also need:
156
157for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux,
158SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
159
160And only on Solaris 8 you also need:
161
162for libraries & headers: SUNWolinc
163
164
165If you are in doubt which package contains a file you are missing,
166try to find an installation that has that file. Then do a
167
168 $ grep /my/missing/file /var/sadm/install/contents
169
170This will display a line like this:
171
172/usr/include/sys/errno.h f none 0644 root bin 7471 37605 956241356 SUNWhea
173
174The last item listed (SUNWhea in this example) is the package you need.
175
176=head3 Avoid /usr/ucb/cc.
177
178You don't need to have /usr/ucb/ in your PATH to build perl.  If you
179want /usr/ucb/ in your PATH anyway, make sure that /usr/ucb/ is NOT
180in your PATH before the directory containing the right C compiler.
181
182=head3 Sun's C Compiler
183
184If you use Sun's C compiler, make sure the correct directory
185(usually /opt/SUNWspro/bin/) is in your PATH (before /usr/ucb/).
186
187=head3 GCC
188
189If you use gcc, make sure your installation is recent and complete.
190perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >=
1912.6.
192
193You must Configure perl with
194
195 $ sh Configure -Dcc=gcc
196
197If you don't, you may experience strange build errors.
198
199If you have updated your Solaris version, you may also have to update
200your gcc.  For example, if you are running Solaris 2.6 and your gcc is
201installed under /usr/local, check in /usr/local/lib/gcc-lib and make
202sure you have the appropriate directory, sparc-sun-solaris2.6/ or
203i386-pc-solaris2.6/.  If gcc's directory is for a different version of
204Solaris than you are running, then you will need to rebuild gcc for
205your new version of Solaris.
206
207You can get a precompiled version of gcc from
208L<http://www.sunfreeware.com/> or L<http://www.blastwave.org/>. Make
209sure you pick up the package for your Solaris release.
210
211If you wish to use gcc to build add-on modules for use with the perl
212shipped with Solaris, you should use the Solaris::PerlGcc module
213which is available from CPAN.  The perl shipped with Solaris
214is configured and built with the Sun compilers, and the compiler
215configuration information stored in Config.pm is therefore only
216relevant to the Sun compilers.  The Solaris:PerlGcc module contains a
217replacement Config.pm that is correct for gcc - see the module for
218details.
219
220=head3 GNU as and GNU ld
221
222The following information applies to gcc version 2.  Volunteers to
223update it as appropriately for gcc version 3 would be appreciated.
224
225The versions of as and ld supplied with Solaris work fine for building
226perl.  There is normally no need to install the GNU versions to
227compile perl.
228
229If you decide to ignore this advice and use the GNU versions anyway,
230then be sure that they are relatively recent.  Versions newer than 2.7
231are apparently new enough.  Older versions may have trouble with
232dynamic loading.
233
234If you wish to use GNU ld, then you need to pass it the -Wl,-E flag.
235The hints/solaris_2.sh file tries to do this automatically by setting
236the following Configure variables:
237
238 ccdlflags="$ccdlflags -Wl,-E"
239 lddlflags="$lddlflags -Wl,-E -G"
240
241However, over the years, changes in gcc, GNU ld, and Solaris ld have made
242it difficult to automatically detect which ld ultimately gets called.
243You may have to manually edit config.sh and add the -Wl,-E flags
244yourself, or else run Configure interactively and add the flags at the
245appropriate prompts.
246
247If your gcc is configured to use GNU as and ld but you want to use the
248Solaris ones instead to build perl, then you'll need to add
249-B/usr/ccs/bin/ to the gcc command line.  One convenient way to do
250that is with
251
252 $ sh Configure -Dcc='gcc -B/usr/ccs/bin/'
253
254Note that the trailing slash is required.  This will result in some
255harmless warnings as Configure is run:
256
257 gcc: file path prefix `/usr/ccs/bin/' never used
258
259These messages may safely be ignored.
260(Note that for a SunOS4 system, you must use -B/bin/ instead.)
261
262Alternatively, you can use the GCC_EXEC_PREFIX environment variable to
263ensure that Sun's as and ld are used.  Consult your gcc documentation
264for further information on the -B option and the GCC_EXEC_PREFIX variable.
265
266=head3 Sun and GNU make
267
268The make under /usr/ccs/bin works fine for building perl.  If you
269have the Sun C compilers, you will also have a parallel version of
270make (dmake).  This works fine to build perl, but can sometimes cause
271problems when running 'make test' due to underspecified dependencies
272between the different test harness files.  The same problem can also
273affect the building of some add-on modules, so in those cases either
274specify '-m serial' on the dmake command line, or use
275/usr/ccs/bin/make instead.  If you wish to use GNU make, be sure that
276the set-group-id bit is not set.  If it is, then arrange your PATH so
277that /usr/ccs/bin/make is before GNU make or else have the system
278administrator disable the set-group-id bit on GNU make.
279
280=head3 Avoid libucb.
281
282Solaris provides some BSD-compatibility functions in /usr/ucblib/libucb.a.
283Perl will not build and run correctly if linked against -lucb since it
284contains routines that are incompatible with the standard Solaris libc.
285Normally this is not a problem since the solaris hints file prevents
286Configure from even looking in /usr/ucblib for libraries, and also
287explicitly omits -lucb.
288
289=head2 Environment for Compiling perl on Solaris
290
291=head3 PATH
292
293Make sure your PATH includes the compiler (/opt/SUNWspro/bin/ if you're
294using Sun's compiler) as well as /usr/ccs/bin/ to pick up the other
295development tools (such as make, ar, as, and ld).  Make sure your path
296either doesn't include /usr/ucb or that it includes it after the
297compiler and compiler tools and other standard Solaris directories.
298You definitely don't want /usr/ucb/cc.
299
300=head3 LD_LIBRARY_PATH
301
302If you have the LD_LIBRARY_PATH environment variable set, be sure that
303it does NOT include /lib or /usr/lib.  If you will be building
304extensions that call third-party shared libraries (e.g. Berkeley DB)
305then make sure that your LD_LIBRARY_PATH environment variable includes
306the directory with that library (e.g. /usr/local/lib).
307
308If you get an error message
309
310 dlopen: stub interception failed
311
312it is probably because your LD_LIBRARY_PATH environment variable
313includes a directory which is a symlink to /usr/lib (such as /lib).
314The reason this causes a problem is quite subtle.  The file
315libdl.so.1.0 actually *only* contains functions which generate 'stub
316interception failed' errors!  The runtime linker intercepts links to
317"/usr/lib/libdl.so.1.0" and links in internal implementations of those
318functions instead.  [Thanks to Tim Bunce for this explanation.]
319
320=head1 RUN CONFIGURE.
321
322See the INSTALL file for general information regarding Configure.
323Only Solaris-specific issues are discussed here.  Usually, the
324defaults should be fine.
325
326=head2 64-bit perl on Solaris.
327
328See the INSTALL file for general information regarding 64-bit compiles.
329In general, the defaults should be fine for most people.
330
331By default, perl-5.6.0 (or later) is compiled as a 32-bit application
332with largefile and long-long support.
333
334=head3 General 32-bit vs. 64-bit issues.
335
336Solaris 7 and above will run in either 32 bit or 64 bit mode on SPARC
337CPUs, via a reboot. You can build 64 bit apps whilst running 32 bit
338mode and vice-versa. 32 bit apps will run under Solaris running in
339either 32 or 64 bit mode.  64 bit apps require Solaris to be running
34064 bit mode.
341
342Existing 32 bit apps are properly known as LP32, i.e. Longs and
343Pointers are 32 bit.  64-bit apps are more properly known as LP64.
344The discriminating feature of a LP64 bit app is its ability to utilise a
34564-bit address space.  It is perfectly possible to have a LP32 bit app
346that supports both 64-bit integers (long long) and largefiles (> 2GB),
347and this is the default for perl-5.6.0.
348
349For a more complete explanation of 64-bit issues, see the
350"Solaris 64-bit Developer's Guide" at L<http://docs.sun.com/>
351
352You can detect the OS mode using "isainfo -v", e.g.
353
354 $ isainfo -v   # Ultra 30 in 64 bit mode
355 64-bit sparcv9 applications
356 32-bit sparc applications
357
358By default, perl will be compiled as a 32-bit application.  Unless
359you want to allocate more than ~ 4GB of memory inside perl, or unless
360you need more than 255 open file descriptors, you probably don't need
361perl to be a 64-bit app.
362
363=head3 Large File Support
364
365For Solaris 2.6 and onwards, there are two different ways for 32-bit
366applications to manipulate large files (files whose size is > 2GByte).
367(A 64-bit application automatically has largefile support built in
368by default.)
369
370First is the "transitional compilation environment", described in
371lfcompile64(5).  According to the man page,
372
373 The transitional compilation  environment  exports  all  the
374 explicit 64-bit functions (xxx64()) and types in addition to
375 all the regular functions (xxx()) and types. Both xxx()  and
376 xxx64()  functions  are  available to the program source.  A
377 32-bit application must use the xxx64() functions in  order
378 to  access  large  files.  See the lf64(5) manual page for a
379 complete listing of the 64-bit transitional interfaces.
380
381The transitional compilation environment is obtained with the
382following compiler and linker flags:
383
384 getconf LFS64_CFLAGS        -D_LARGEFILE64_SOURCE
385 getconf LFS64_LDFLAG        # nothing special needed
386 getconf LFS64_LIBS          # nothing special needed
387
388Second is the "large file compilation environment", described in
389lfcompile(5).  According to the man page,
390
391 Each interface named xxx() that needs to access 64-bit entities
392 to  access  large  files maps to a xxx64() call in the
393 resulting binary. All relevant data types are defined to  be
394 of correct size (for example, off_t has a typedef definition
395 for a 64-bit entity).
396
397 An application compiled in this environment is able  to  use
398 the  xxx()  source interfaces to access both large and small
399 files, rather than having to explicitly utilize the  transitional
400 xxx64()  interface  calls to access large files.
401
402Two exceptions are fseek() and ftell().  32-bit applications should
403use fseeko(3C) and ftello(3C).  These will get automatically mapped
404to fseeko64() and ftello64().
405
406The large file compilation environment is obtained with
407
408 getconf LFS_CFLAGS      -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
409 getconf LFS_LDFLAGS     # nothing special needed
410 getconf LFS_LIBS        # nothing special needed
411
412By default, perl uses the large file compilation environment and
413relies on Solaris to do the underlying mapping of interfaces.
414
415=head3 Building an LP64 perl
416
417To compile a 64-bit application on an UltraSparc with a recent Sun Compiler,
418you need to use the flag "-xarch=v9".  getconf(1) will tell you this, e.g.
419
420 $ getconf -a | grep v9
421 XBS5_LP64_OFF64_CFLAGS:         -xarch=v9
422 XBS5_LP64_OFF64_LDFLAGS:        -xarch=v9
423 XBS5_LP64_OFF64_LINTFLAGS:      -xarch=v9
424 XBS5_LPBIG_OFFBIG_CFLAGS:       -xarch=v9
425 XBS5_LPBIG_OFFBIG_LDFLAGS:      -xarch=v9
426 XBS5_LPBIG_OFFBIG_LINTFLAGS:    -xarch=v9
427 _XBS5_LP64_OFF64_CFLAGS:        -xarch=v9
428 _XBS5_LP64_OFF64_LDFLAGS:       -xarch=v9
429 _XBS5_LP64_OFF64_LINTFLAGS:     -xarch=v9
430 _XBS5_LPBIG_OFFBIG_CFLAGS:      -xarch=v9
431 _XBS5_LPBIG_OFFBIG_LDFLAGS:     -xarch=v9
432 _XBS5_LPBIG_OFFBIG_LINTFLAGS:   -xarch=v9
433
434This flag is supported in Sun WorkShop Compilers 5.0 and onwards
435(now marketed under the name Forte) when used on Solaris 7 or later on
436UltraSparc systems.
437
438If you are using gcc, you would need to use -mcpu=v9 -m64 instead.  This
439option is not yet supported as of gcc 2.95.2; from install/SPECIFIC
440in that release:
441
442 GCC version 2.95 is not able to compile code correctly for sparc64
443 targets. Users of the Linux kernel, at least, can use the sparc32
444 program to start up a new shell invocation with an environment that
445 causes configure to recognize (via uname -a) the system as sparc-*-*
446 instead.
447
448All this should be handled automatically by the hints file, if
449requested.
450
451=head3 Long Doubles.
452
453As of 5.8.1, long doubles are working if you use the Sun compilers
454(needed for additional math routines not included in libm).
455
456=head2 Threads in perl on Solaris.
457
458It is possible to build a threaded version of perl on Solaris.  The entire
459perl thread implementation is still experimental, however, so beware.
460
461=head2 Malloc Issues with perl on Solaris.
462
463Starting from perl 5.7.1 perl uses the Solaris malloc, since the perl
464malloc breaks when dealing with more than 2GB of memory, and the Solaris
465malloc also seems to be faster.
466
467If you for some reason (such as binary backward compatibility) really
468need to use perl's malloc, you can rebuild perl from the sources
469and Configure the build with 
470
471 $ sh Configure -Dusemymalloc
472
473You should not use perl's malloc if you are building with gcc.  There
474are reports of core dumps, especially in the PDL module.  The problem
475appears to go away under -DDEBUGGING, so it has been difficult to
476track down.  Sun's compiler appears to be okay with or without perl's
477malloc. [XXX further investigation is needed here.]
478
479=head1 MAKE PROBLEMS.
480
481=over 4
482
483=item Dynamic Loading Problems With GNU as and GNU ld
484
485If you have problems with dynamic loading using gcc on SunOS or
486Solaris, and you are using GNU as and GNU ld, see the section
487L<"GNU as and GNU ld"> above.
488
489=item ld.so.1: ./perl: fatal: relocation error:
490
491If you get this message on SunOS or Solaris, and you're using gcc,
492it's probably the GNU as or GNU ld problem in the previous item
493L<"GNU as and GNU ld">.
494
495=item dlopen: stub interception failed
496
497The primary cause of the 'dlopen: stub interception failed' message is
498that the LD_LIBRARY_PATH environment variable includes a directory
499which is a symlink to /usr/lib (such as /lib).  See
500L<"LD_LIBRARY_PATH"> above.
501
502=item #error "No DATAMODEL_NATIVE specified"
503
504This is a common error when trying to build perl on Solaris 2.6 with a
505gcc installation from Solaris 2.5 or 2.5.1.  The Solaris header files
506changed, so you need to update your gcc installation.  You can either
507rerun the fixincludes script from gcc or take the opportunity to
508update your gcc installation.
509
510=item sh: ar: not found
511
512This is a message from your shell telling you that the command 'ar'
513was not found.  You need to check your PATH environment variable to
514make sure that it includes the directory with the 'ar' command.  This
515is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin/
516directory.
517
518=back
519
520=head1 MAKE TEST
521
522=head2 op/stat.t test 4 in Solaris
523
524F<op/stat.t> test 4 may fail if you are on a tmpfs of some sort.
525Building in /tmp sometimes shows this behavior.  The
526test suite detects if you are building in /tmp, but it may not be able
527to catch all tmpfs situations.
528
529=head2 nss_delete core dump from op/pwent or op/grent
530
531See L<perlhpux/"nss_delete core dump from op/pwent or op/grent">.
532
533=head1 CROSS-COMPILATION
534
535Nothing too unusual here.  You can easily do this if you have a 
536cross-compiler available;  A usual Configure invocation when targetting a
537Solaris x86 looks something like this:
538
539    sh ./Configure -des -Dusecrosscompile \
540        -Dcc=i386-pc-solaris2.11-gcc      \
541        -Dsysroot=$SYSROOT                \
542        -Alddlflags=" -Wl,-z,notext"      \
543        -Dtargethost=... # The usual cross-compilation options
544
545The lddlflags addition is the only abnormal bit.
546
547=head1 PREBUILT BINARIES OF PERL FOR SOLARIS.
548
549You can pick up prebuilt binaries for Solaris from
550L<http://www.sunfreeware.com/>, L<http://www.blastwave.org>,
551ActiveState L<http://www.activestate.com/>, and
552L<http://www.perl.com/> under the Binaries list at the top of the
553page.  There are probably other sources as well.  Please note that
554these sites are under the control of their respective owners, not the
555perl developers.
556
557=head1 RUNTIME ISSUES FOR PERL ON SOLARIS.
558
559=head2 Limits on Numbers of Open Files on Solaris.
560
561The stdio(3C) manpage notes that for LP32 applications, only 255
562files may be opened using fopen(), and only file descriptors 0
563through 255 can be used in a stream.  Since perl calls open() and
564then fdopen(3C) with the resulting file descriptor, perl is limited
565to 255 simultaneous open files, even if sysopen() is used.  If this
566proves to be an insurmountable problem, you can compile perl as a
567LP64 application, see L<Building an LP64 perl> for details.  Note
568also that the default resource limit for open file descriptors on
569Solaris is 255, so you will have to modify your ulimit or rctl
570(Solaris 9 onwards) appropriately.
571
572=head1 SOLARIS-SPECIFIC MODULES.
573
574See the modules under the Solaris:: and Sun::Solaris namespaces on CPAN,
575see L<http://www.cpan.org/modules/by-module/Solaris/> and
576L<http://www.cpan.org/modules/by-module/Sun/>.
577
578=head1 SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
579
580=head2 Proc::ProcessTable on Solaris
581
582Proc::ProcessTable does not compile on Solaris with perl5.6.0 and higher
583if you have LARGEFILES defined.  Since largefile support is the
584default in 5.6.0 and later, you have to take special steps to use this
585module.
586
587The problem is that various structures visible via procfs use off_t,
588and if you compile with largefile support these change from 32 bits to
58964 bits.  Thus what you get back from procfs doesn't match up with
590the structures in perl, resulting in garbage.  See proc(4) for further
591discussion.
592
593A fix for Proc::ProcessTable is to edit Makefile to
594explicitly remove the largefile flags from the ones MakeMaker picks up
595from Config.pm.  This will result in Proc::ProcessTable being built
596under the correct environment.  Everything should then be OK as long as
597Proc::ProcessTable doesn't try to share off_t's with the rest of perl,
598or if it does they should be explicitly specified as off64_t.
599
600=head2 BSD::Resource on Solaris
601
602BSD::Resource versions earlier than 1.09 do not compile on Solaris
603with perl 5.6.0 and higher, for the same reasons as Proc::ProcessTable.
604BSD::Resource versions starting from 1.09 have a workaround for the problem.
605
606=head2 Net::SSLeay on Solaris
607
608Net::SSLeay requires a /dev/urandom to be present. This device is
609available from Solaris 9 onwards.  For earlier Solaris versions you
610can either get the package SUNWski (packaged with several Sun
611software products, for example the Sun WebServer, which is part of
612the Solaris Server Intranet Extension, or the Sun Directory Services,
613part of Solaris for ISPs) or download the ANDIrand package from
614L<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a
615symbolic link /dev/urandom pointing to /dev/random.  For more details,
616see Document ID27606 entitled "Differing /dev/random support requirements
617within Solaris[TM] Operating Environments", available at
618L<http://sunsolve.sun.com> .
619
620It may be possible to use the Entropy Gathering Daemon (written in
621Perl!), available from L<http://www.lothar.com/tech/crypto/>.
622
623=head1 SunOS 4.x
624
625In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld,
626since the more recent versions of GNU ld (like 2.13) do not seem to
627work for building Perl anymore.  When linking the extensions, the
628GNU ld gets very unhappy and spews a lot of errors like this
629
630  ... relocation truncated to fit: BASE13 ...
631
632and dies.  Therefore the SunOS 4.1 hints file explicitly sets the
633ld to be F</usr/bin/ld>.
634
635As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader)
636also seems to have become broken in in SunOS 4.x.  Therefore the default
637is to build Perl statically.
638
639Running the test suite in SunOS 4.1 is a bit tricky since the
640F<lib/Tie/File/t/09_gen_rs> test hangs (subtest #51, FWIW) for some
641unknown reason.  Just stop the test and kill that particular Perl
642process.
643
644There are various other failures, that as of SunOS 4.1.4 and gcc 3.2.2
645look a lot like gcc bugs.  Many of the failures happen in the Encode
646tests, where for example when the test expects "0" you get "&#48;"
647which should after a little squinting look very odd indeed.
648Another example is earlier in F<t/run/fresh_perl> where chr(0xff) is
649expected but the test fails because the result is chr(0xff).  Exactly.
650
651This is the "make test" result from the said combination:
652
653  Failed 27 test scripts out of 745, 96.38% okay.
654
655Running the C<harness> is painful because of the many failing
656Unicode-related tests will output megabytes of failure messages,
657but if one patiently waits, one gets these results:
658
659 Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
660 -----------------------------------------------------------------------------
661 ...
662 ../ext/Encode/t/at-cn.t            4  1024    29    4  13.79%  14-17
663 ../ext/Encode/t/at-tw.t           10  2560    17   10  58.82%  2 4 6 8 10 12
664                                                                14-17
665 ../ext/Encode/t/enc_data.t        29  7424    ??   ??       %  ??
666 ../ext/Encode/t/enc_eucjp.t       29  7424    ??   ??       %  ??
667 ../ext/Encode/t/enc_module.t      29  7424    ??   ??       %  ??
668 ../ext/Encode/t/encoding.t        29  7424    ??   ??       %  ??
669 ../ext/Encode/t/grow.t            12  3072    24   12  50.00%  2 4 6 8 10 12 14
670                                                                16 18 20 22 24
671  Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
672 ------------------------------------------------------------------------------
673 ../ext/Encode/t/guess.t          255 65280    29   40 137.93%  10-29
674 ../ext/Encode/t/jperl.t           29  7424    15   30 200.00%  1-15
675 ../ext/Encode/t/mime-header.t      2   512    10    2  20.00%  2-3
676 ../ext/Encode/t/perlio.t          22  5632    38   22  57.89%  1-4 9-16 19-20
677                                                                23-24 27-32
678 ../ext/List/Util/t/shuffle.t       0   139    ??   ??       %  ??
679 ../ext/PerlIO/t/encoding.t                    14    1   7.14%  11
680 ../ext/PerlIO/t/fallback.t                     9    2  22.22%  3 5
681 ../ext/Socket/t/socketpair.t       0     2    45   70 155.56%  11-45
682 ../lib/CPAN/t/vcmp.t                          30    1   3.33%  25
683 ../lib/Tie/File/t/09_gen_rs.t      0    15    ??   ??       %  ??
684 ../lib/Unicode/Collate/t/test.t              199   30  15.08%  7 26-27 71-75
685                                                                81-88 95 101
686                                                                103-104 106 108-
687                                                                109 122 124 161
688                                                                169-172
689 ../lib/sort.t                      0   139   119   26  21.85%  107-119
690 op/alarm.t                                     4    1  25.00%  4
691 op/utfhash.t                                  97    1   1.03%  31
692 run/fresh_perl.t                              91    1   1.10%  32
693 uni/tr_7jis.t                                 ??   ??       %  ??
694 uni/tr_eucjp.t                    29  7424     6   12 200.00%  1-6
695 uni/tr_sjis.t                     29  7424     6   12 200.00%  1-6
696 56 tests and 467 subtests skipped.
697 Failed 27/811 test scripts, 96.67% okay. 1383/75399 subtests failed, 98.17% okay.
698
699The alarm() test failure is caused by system() apparently blocking
700alarm().  That is probably a libc bug, and given that SunOS 4.x
701has been end-of-lifed years ago, don't hold your breath for a fix.
702In addition to that, don't try anything too Unicode-y, especially
703with Encode, and you should be fine in SunOS 4.x.
704
705=head1 AUTHOR
706
707The original was written by Andy Dougherty F<doughera@lafayette.edu>
708drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce,
709and many other Solaris users over the years.
710
711Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
712

README.symbian

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perlsymbian - Perl version 5 on Symbian OS
8
9=head1 DESCRIPTION
10
11This document describes various features of the Symbian operating
12system that will affect how Perl version 5 (hereafter just Perl)
13is compiled and/or runs.
14
15B<NOTE: this port (as of 0.4.1) does not compile into a Symbian
16OS GUI application, but instead it results in a Symbian DLL.>
17The DLL includes a C++ class called CPerlBase, which one can then
18(derive from and) use to embed Perl into applications, see F<symbian/README>.
19
20The base port of Perl to Symbian only implements the basic POSIX-like
21functionality; it does not implement any further Symbian or Series 60,
22Series 80, or UIQ bindings for Perl.
23
24It is also possible to generate Symbian executables for "miniperl"
25and "perl", but since there is no standard command line interface
26for Symbian (nor full keyboards in the devices), these are useful
27mainly as demonstrations.
28
29=head2 Compiling Perl on Symbian
30
31(0) You need to have the appropriate Symbian SDK installed.
32
33    These instructions have been tested under various Nokia Series 60
34    Symbian SDKs (1.2 to 2.6, 2.8 should also work, 1.2 compiles but
35    does not work), Series 80 2.0, and Nokia 7710 (Series 90) SDK.
36    You can get the SDKs from Forum Nokia (L<http://www.forum.nokia.com/>).
37    A very rough port ("it compiles") to UIQ 2.1 has also been made.
38
39    A prerequisite for any of the SDKs is to install ActivePerl
40    from ActiveState, L<http://www.activestate.com/Products/ActivePerl/>
41
42    Having the SDK installed also means that you need to have either
43    the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing)
44    or the Microsoft Visual C++ 6.0 installed (SP3 minimum, SP5 recommended).
45
46    Note that for example the Series 60 2.0 VC SDK installation talks
47    about ActivePerl build 518, which does no more (as of mid-2005) exist
48    at the ActiveState website.  The ActivePerl 5.8.4 build 810 was
49    used successfully for compiling Perl on Symbian.  The 5.6.x ActivePerls
50    do not work.
51
52    Other SDKs or compilers like Visual.NET, command-line-only
53    Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried.
54
55    These instructions almost certainly won't work with older Symbian
56    releases or other SDKs.  Patches to get this port running in other
57    releases, SDKs, compilers, platforms, or devices are naturally welcome.
58
59(1) Get a Perl source code distribution (for example the file
60    perl-5.9.2.tar.gz is fine) from L<http://www.cpan.org/src/>
61    and unpack it in your the C:/Symbian directory of your Windows
62    system.
63
64(2) Change to the perl source directory.
65
66	cd c:\Symbian\perl-5.x.x
67
68(3) Run the following script using the perl coming with the SDK
69
70	perl symbian\config.pl
71
72    You must use the cmd.exe, the Cygwin shell will not work.
73    The PATH must include the SDK tools, including a Perl,
74    which should be the case under cmd.exe.  If you do not
75    have that, see the end of symbian\sdk.pl for notes of
76    how your environment should be set up for Symbian compiles.
77
78(4) Build the project, either by
79
80	make all
81
82    in cmd.exe or by using either the Metrowerks CodeWarrior
83    or the Visual C++ 6.0, or the Visual Studio 8 (the Visual C++
84    2005 Express Edition works fine).
85
86    If you use the VC IDE, you will have to run F<symbian\config.pl>
87    first using the cmd.exe, and then run 'make win.mf vc6.mf' to generate
88    the VC6 makefiles and workspaces.  "make vc6" will compile for the VC6,
89    and "make cw" for the CodeWarrior.
90
91    The following SDK and compiler configurations and Nokia phones were
92    tested at some point in time (+ = compiled and PerlApp run, - = not),
93    both for Perl 5.8.x and 5.9.x:
94
95        SDK     | VC | CW |
96        --------+----+----+---
97        S60 1.2 | +  | +  | 3650 (*)
98        S60 2.0 | +  | +  | 6600
99        S60 2.1 | -  | +  | 6670
100        S60 2.6 | +  | +  | 6630    
101        S60 2.8 | +  | +  | (not tested in a device)
102        S80 2.6 | -  | +  | 9300
103        S90 1.1 | +  | -  | 7710
104        UIQ 2.1 | -  | +  | (not tested in a device)
105
106    (*) Compiles but does not work, unfortunately, a problem with Symbian.
107
108    If you are using the 'make' directly, it is the GNU make from the SDKs,
109    and it will invoke the right make commands for the Windows emulator
110    build and the Arm target builds ('thumb' by default) as necessary.
111
112    The build scripts assume the 'absolute style' SDK installs under C:,
113    the 'subst style' will not work.
114
115    If using the VC IDE, to build use for example the File->Open Workspace->
116    C:\Symbian\8.0a\S60_2nd_FP2\epoc32\build\symbian\perl\perl\wins\perl.dsw
117    The emulator binaries will appear in the same directory.
118
119    If using the VC IDE, you will a lot of warnings in the beginning of
120    the build because a lot of headers mentioned by the source cannot
121    be found, but this is not serious since those headers are not used.
122
123    The Metrowerks will give a lot of warnings about unused variables and
124    empty declarations, you can ignore those.
125
126    When the Windows and Arm DLLs are built do not be scared by a very long
127    messages whizzing by: it is the "export freeze" phase where the whole
128    (rather large) API of Perl is listed.
129
130    Once the build is completed you need to create the DLL SIS file by
131
132	make perldll.sis
133
134    which will create the file perlXYZ.sis (the XYZ being the Perl version)
135    which you can then install into your Symbian device: an easy way
136    to do this is to send them via Bluetooth or infrared and just open
137    the messages.
138
139    Since the total size of all Perl SIS files once installed is
140    over 2 MB, it is recommended to do the installation into a
141    memory card (drive E:) instead of the C: drive.
142
143    The size of the perlXYZ.SIS is about 370 kB but once it is in the
144    device it is about one 750 kB (according to the application manager).
145
146    The perlXYZ.sis includes only the Perl DLL: to create an additional
147    SIS file which includes some of the standard (pure) Perl libraries,
148    issue the command
149
150        make perllib.sis
151
152    Some of the standard Perl libraries are included, but not all:
153    see L</HISTORY> or F<symbian\install.cfg> for more details
154    (250 kB -> 700 kB).
155
156    Some of the standard Perl XS extensions (see L</HISTORY> are
157    also available:
158
159        make perlext.sis
160
161    which will create perlXYZext.sis (290 kB -> 770 kB).
162
163    To compile the demonstration application PerlApp you need first to
164    install the Perl headers under the SDK.
165
166    To install the Perl headers and the class CPerlBase documentation
167    so that you no more need the Perl sources around to compile Perl
168    applications using the SDK:
169
170        make sdkinstall
171
172    The destination directory is C:\Symbian\perl\X.Y.Z.  For more
173    details, see F<symbian\PerlBase.pod>.
174
175    Once the headers have been installed, you can create a SIS for
176    the PerlApp:
177
178        make perlapp.sis
179
180    The perlapp.sis (11 kB -> 16 kB) will be built in the symbian
181    subdirectory, but a copy will also be made to the main directory.
182
183    If you want to package the Perl DLLs (one for WINS, one for ARMI),
184    the headers, and the documentation:
185
186        make perlsdk.zip
187
188    which will create perlXYZsdk.zip that can be used in another
189    Windows system with the SDK, without having to compile Perl in
190    that system.
191
192    If you want to package the PerlApp sources:
193
194        make perlapp.zip
195
196    If you want to package the perl.exe and miniperl.exe, you
197    can use the perlexe.sis and miniperlexe.sis make targets.
198    You also probably want the perllib.sis for the libraries
199    and maybe even the perlapp.sis for the recognizer.
200
201    The make target 'allsis' combines all the above SIS targets.
202
203    To clean up after compilation you can use either of
204
205        make clean
206        make distclean
207
208    depending on how clean you want to be.
209
210=head2 Compilation problems
211
212If you see right after "make" this
213
214    cat makefile.sh >makefile
215    'cat' is not recognized as an internal or external command,
216    operable program or batch file.
217
218it means you need to (re)run the F<symbian\config.pl>.
219
220If you get the error
221
222        'perl' is not recognized as an internal or external command,
223        operable program or batch file.
224
225you may need to reinstall the ActivePerl.
226
227If you see this
228
229    ren makedef.pl nomakedef.pl
230    The system cannot find the file specified.
231    C:\Symbian\...\make.exe: [rename_makedef] Error 1 (ignored)
232
233please ignore it since it is nothing serious (the build process of
234renames the Perl makedef.pl as nomakedef.pl to avoid confusing it
235with a makedef.pl of the SDK).
236
237=head2 PerlApp
238
239The PerlApp application demonstrates how to embed Perl interpreters
240to a Symbian application.  The "Time" menu item runs the following
241Perl code: C<print "Running in ", $^O, "\n", scalar localtime>,
242the "Oneliner" allows one to type in Perl code, and the "Run"
243opens a file chooser for selecting a Perl file to run.
244
245The PerlApp also is started when the "Perl recognizer" (also included
246and installed) detects a Perl file being activated through the GUI,
247and offers either to install it under \Perl (if the Perl file is in
248the inbox of the messaging application) or to run it (if the Perl file
249is under \Perl).
250
251=head2 sisify.pl
252
253In the symbian subdirectory there is F<sisify.pl> utility which can be used
254to package Perl scripts and/or Perl library directories into SIS files,
255which can be installed to the device.  To run the sisify.pl utility,
256you will need to have the 'makesis' and 'uidcrc' utilities already
257installed.  If you don't have the Win32 SDKs, you may try for example
258L<http://gnupoc.sourceforge.net/> or L<http://symbianos.org/~andreh/>.
259
260=head2 Using Perl in Symbian
261
262First of all note that you have full access to the Symbian device
263when using Perl: you can do a lot of damage to your device (like
264removing system files) unless you are careful.  Please do take
265backups before doing anything.
266
267The Perl port has been done for the most part using the Symbian
268standard POSIX-ish STDLIB library. It is a reasonably complete
269library, but certain corners of such emulation libraries that tend
270to be left unimplemented on non-UNIX platforms have been left
271unimplemented also this time: fork(), signals(), user/group ids,
272select() working for sockets, non-blocking sockets, and so forth.
273See the file F<symbian/config.sh> and look for 'undef' to find the
274unsupported APIs (or from Perl use Config).
275
276The filesystem of Symbian devices uses DOSish syntax, "drives"
277separated from paths by a colon, and backslashes for the path.  The
278exact assignment of the drives probably varies between platforms, but
279for example in Series 60 you might see C: as the (flash) main memory,
280D: as the RAM drive, E: as the memory card (MMC), Z: as the ROM.  In
281Series 80 D: is the memory card.  As far the devices go the NUL: is
282the bit bucket, the COMx: are the serial lines, IRCOMx: are the IR
283ports, TMP: might be C:\System\Temp.  Remember to double those
284backslashes in doublequoted strings.
285
286The Perl DLL is installed in \System\Libs\.  The Perl libraries and
287extension DLLs are installed in \System\Libs\Perl\X.Y.Z\.  The PerlApp
288is installed in \System\Apps\, and the SIS also installs a couple of
289demo scripts in \Perl\ (C:\Mydocs\Perl\ on Nokia 7710).
290
291Note that the Symbian filesystem is very picky: it strongly prefers
292the \ instead of the /.
293
294When doing XS / Symbian C++ programming include first the Symbian
295headers, then any standard C/POSIX headers, then Perl headers, and finally
296any application headers.
297
298New() and Copy() are unfortunately used by both Symbian and Perl code
299so you'll have to play cpp games if you need them.  PerlBase.h undefines
300the Perl definitions and redefines them as PerlNew() and PerlCopy().
301
302=head1 TO DO
303
304Lots.  See F<symbian/TODO>.
305
306=head1 WARNING
307
308As of Perl Symbian port version 0.4.1 any part of Perl's standard
309regression test suite has not been run on a real Symbian device using
310the ported Perl, so innumerable bugs may lie in wait.  Therefore there
311is absolutely no warranty.
312
313=head1 NOTE
314
315When creating and extending application programming interfaces (APIs)
316for Symbian or Series 60 or Series 80 or Series 90 it is suggested
317that trademarks, registered trademarks, or trade names are not used in
318the API names.  Instead, developers should consider basing the API
319naming in the existing (C++, or maybe Java) public component and API
320naming, modified as appropriate by the rules of the programming
321language the new APIs are for.
322
323Nokia is a registered trademark of Nokia Corporation. Nokia's product
324names are trademarks or registered trademarks of Nokia.  Other product
325and company names mentioned herein may be trademarks or trade names of
326their respective owners.
327
328=head1 AUTHOR
329
330Jarkko Hietaniemi
331
332=head1 COPYRIGHT
333
334Copyright (c) 2004-2005 Nokia.  All rights reserved.
335
336Copyright (c) 2006-2007 Jarkko Hietaniemi.
337
338=head1 LICENSE
339
340The Symbian port is licensed under the same terms as Perl itself.
341
342=head1 HISTORY
343
344=over 4
345
346=item *
347
3480.1.0: April 2005
349
350(This will show as "0.01" in the Symbian Installer.)
351
352  - The console window is a very simple console indeed: one can
353    get the newline with "000" and the "C" button is a backspace.
354    Do not expect a terminal capable of vt100 or ANSI sequences.
355    The console is also "ASCII", you cannot input e.g. any accented
356    letters.  Because of obvious physical constraints the console is
357    also very small: (in Nokia 6600) 22 columns, 17 rows.
358  - The following libraries are available:
359    AnyDBM_File AutoLoader base Carp Config Cwd constant
360    DynaLoader Exporter File::Spec integer lib strict Symbol
361    vars warnings XSLoader
362  - The following extensions are available:
363    attributes Compress::Zlib Cwd Data::Dumper Devel::Peek Digest::MD5 DynaLoader
364    Fcntl File::Glob Filter::Util::Call IO List::Util MIME::Base64
365    PerlIO::scalar PerlIO::via SDBM_File Socket Storable Time::HiRes
366  - The following extensions are missing for various technical reasons:
367    B ByteLoader Devel::DProf Devel::PPPort Encode GDBM_File
368    I18N::Langinfo IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX
369    re Safe Sys::Hostname Sys::Syslog
370    threads threads::shared Unicode::Normalize
371  - Using MakeMaker or the Module::* to build and install modules
372    is not supported.
373  - Building XS other than the ones in the core is not supported.
374
375Since this is 0.something release, any future releases are almost
376guaranteed to be binary incompatible.  As a sign of this the Symbian
377symbol exports are kept unfrozen and the .def files fully rebuilt
378every time.
379
380=item *
381
3820.2.0: October 2005
383
384  - Perl 5.9.3 (patch level 25741)
385  - Compress::Zlib and IO::Zlib supported
386  - sisify.pl added
387
388We maintain the binary incompatibility.
389
390=item *
391
3920.3.0: October 2005
393
394  - Perl 5.9.3 (patch level 25911)
395  - Series 80 2.0 and UIQ 2.1 support
396
397We maintain the binary incompatibility.
398
399=item *
400
4010.4.0: November 2005
402
403  - Perl 5.9.3 (patch level 26052)
404  - adding a sample Symbian extension
405
406We maintain the binary incompatibility.
407
408=item *
409
4100.4.1: December 2006
411
412  - Perl 5.9.5-to-be (patch level 30002)
413  - added extensions: Compress/Raw/Zlib, Digest/SHA,
414    Hash/Util, Math/BigInt/FastCalc, Text/Soundex, Time/Piece
415  - port to S90 1.1 by alexander smishlajev
416
417We maintain the binary incompatibility.
418
419=item *
420
4210.4.2: March 2007
422
423  - catchup with Perl 5.9.5-to-be (patch level 30812)
424  - tested to build with Microsoft Visual C++ 2005 Express Edition
425    (which uses Microsoft Visual C 8, instead of the old VC6),
426    SDK used for testing S60_2nd_FP3 aka 8.1a
427
428We maintain the binary incompatibility.
429
430=back
431
432=cut
433

README.synology

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is. But if you have been into Perl you
4probably already know this.
5
6=head1 NAME
7
8perlsynology - Perl 5 on Synology DSM systems
9
10=head1 DESCRIPTION
11
12Synology manufactures a vast number of Network Attached Storage (NAS)
13devices that are very popular in large organisations as well as small
14businesses and homes.
15
16The NAS systems are equipped with Synology Disk Storage Manager (DSM),
17which is a trimmed-down Linux system enhanced with several tools for
18managing the NAS. There are several flavours of hardware: Marvell
19Armada (ARMv5tel, ARMv7l), Intel Atom (i686, x86_64), Freescale QorIQ
20(PPC), and more. For a full list see the
21L<Synology FAQ|http://forum.synology.com/wiki/index.php/What_kind_of_CPU_does_my_NAS_have>.
22
23Since it is based on Linux, the NAS can run many popular Linux
24software packages, including Perl. In fact, Synology provides a
25ready-to-install package for Perl, depending on the version of DSM
26the installed perl ranges from 5.8.6 on DSM-4.3 to 5.18.4 on DSM-5.1.
27
28There is an active user community that provides many software packages
29for the Synology DSM systems; at the time of writing this document
30they provide Perl version 5.18.4.
31
32This document describes various features of Synology DSM operating
33system that will affect how Perl 5 (hereafter just Perl) is
34configured, compiled and/or runs. It has been compiled and verified by
35Johan Vromans for the Synology DS413 (QorIQ), with feedback from
36H.Merijn Brand (DS213, ARMv5tel).
37
38=head2 Setting up the build environment
39
40As DSM is a trimmed-down Linux system, it lacks many of the tools and
41libraries commonly found on Linux. The basic tools like sh, cp, rm,
42etc. are implemented using
43L<BusyBox|http://en.wikipedia.org/wiki/BusyBox>.
44
45=over 4
46
47=item *
48
49Using your favourite browser open the DSM management page and start
50the Package Center.
51
52=item *
53
54If you want to smoke test Perl, install C<Perl>.
55
56=item *
57
58In Settings, add the following Package Sources:
59
60  http://www.cphub.net
61  http://packages.quadrat4.de
62
63=item *
64
65Still in Settings, in Channel Update, select Beta Channel.
66
67=item *
68
69Press Refresh. In the left panel the item "Community" will appear.
70Click it. Select "Bootstrap Installer Beta" and install it.
71
72=item *
73
74Likewise, install "iPKGui Beta".
75
76The application window should now show an icon for iPKGui.
77
78=item *
79
80Start iPKGui. Install the packages C<make>, C<gcc> and C<coreutils>.
81
82If you want to smoke test Perl, install C<patch>.
83
84=back
85
86The next step is to add some symlinks to system libraries. For
87example, the development software expect a library C<libm.so> that
88normally is a symlink to C<libm.so.6>. Synology only provides the
89latter and not the symlink.
90
91Here the actual architecture of the Synology system matters. You have
92to find out where the gcc libraries have been installed. Look in /opt
93for a directory similar to arm-none-linux-gnueab or
94powerpc-linux-gnuspe. In the instructions below I'll use
95powerpc-linux-gnuspe as an example.
96
97=over 4
98
99=item *
100
101On the DSM management page start the Control Panel.
102
103=item *
104
105Click Terminal, and enable SSH service.
106
107=item *
108
109Close Terminal and the Control Panel.
110
111=item *
112
113Open a shell on the Synology using ssh and become root.
114
115=item *
116
117Execute the following commands:
118
119  cd /lib
120  ln -s libm.so.6 libm.so
121  ln -s libcrypt.so.1 libcrypt.so
122  ln -s libdl.so.2 libdl.so
123  cd /opt/powerpc-linux-gnuspe/lib  (or
124                                    /opt/arm-none-linux-gnueabi/lib)
125  ln -s /lib/libdl.so.2 libdl.so
126
127=back
128
129B<WARNING:> When you perform a system software upgrade, these links
130will disappear and need to be re-established.
131
132=head2 Compiling Perl 5
133
134When the build environment has been set up, building and testing Perl
135is straightforward. The only thing you need to do is download the
136sources as usual, and add a file Policy.sh as follows:
137
138  # Administrivia.
139  perladmin="your.email@goes.here"
140
141  # Install Perl in a tree in /opt/perl instead of /opt/bin.
142  prefix=/opt/perl
143
144  # Select the compiler. Note that there is no 'cc' alias or link.
145  cc=gcc
146
147  # Build flags.
148  ccflags="-DDEBUGGING"
149
150  # Library and include paths.
151  libpth="/lib"
152  locincpth="/opt/include"
153  loclibpth="/lib"
154
155You may want to create the destination directory and give it the right
156permissions before installing, thus eliminating the need to build Perl
157as a super user.
158
159In the directory where you unpacked the sources, issue the familiar
160commands:
161
162  ./Configure -des
163  make
164  make test
165  make install
166
167=head2 Known problems
168
169=head3 Configure
170
171No known problems yet
172
173=head3 Build
174
175=over 4
176
177=item Error message "No error definitions found".
178
179This error is generated when it is not possible to find the local
180definitions for error codes, due to the uncommon structure of the
181Synology file system.
182
183This error was fixed in the Perl development git for version 5.19,
184commit 7a8f1212e5482613c8a5b0402528e3105b26ff24.
185
186=back
187
188=head3 Failing tests
189
190=over 4
191
192=item C<ext/DynaLoader/t/DynaLoader.t>
193
194One subtest fails due to the uncommon structure of the Synology file
195system. The file C</lib/glibc.so> is missing.
196
197B<WARNING:> Do not symlink C</lib/glibc.so.6> to C</lib/glibc.so> or
198some system components will start to fail.
199
200=back
201
202=head2 Smoke testing Perl 5
203
204If building completes successfully, you can set up smoke testing as
205described in the Test::Smoke documentation.
206
207For smoke testing you need a running Perl. You can either install the
208Synology supplied package for Perl 5.8.6, or build and install your
209own, much more recent version.
210
211Note that I could not run successful smokes when initiated by the
212Synology Task Scheduler. I resorted to initiating the smokes via a
213cron job run on another system, using ssh:
214
215  ssh nas1 wrk/Test-Smoke/smoke/smokecurrent.sh
216
217=head3 Local patches
218
219When local patches are applied with smoke testing, the test driver
220will automatically request regeneration of certain tables after the
221patches are applied. The Synology supplied Perl 5.8.6 (at least on the
222DS413) B<is NOT capable> of generating these tables. It will generate
223opcodes with bogus values, causing the build to fail.
224
225You can prevent regeneration by adding the setting
226
227  'flags' => 0,
228
229to the smoke config, or by adding another patch that inserts
230
231  exit 0 if $] == 5.008006;
232
233in the beginning of the C<regen.pl> program.
234
235=head2 Adding libraries
236
237The above procedure describes a basic environment and hence results in
238a basic Perl. If you want to add additional libraries to Perl, you may
239need some extra settings.
240
241For example, the basic Perl does not have any of the DB libraries (db,
242dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to
243set environment variable LD_LIBRARY_PATH to the appropriate value:
244
245  LD_LIBRARY_PATH=/lib:/opt/lib
246  export LD_LIBRARY_PATH
247
248This setting needs to be in effect while Perl is built, but also when
249the programs are run.
250
251=head1 REVISION
252
253March 2015, for Synology DSM 5.1.5022.
254
255=head1 AUTHOR
256
257Johan Vromans <jvromans@squirrel.nl>
258H. Merijn Brand <h.m.brand@xs4all.nl>
259
260=cut
261

README.tru64

1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
5=head1 NAME
6
7perltru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems
8
9=head1 DESCRIPTION
10
11This document describes various features of HP's (formerly Compaq's,
12formerly Digital's) Unix operating system (Tru64) that will affect
13how Perl version 5 (hereafter just Perl) is configured, compiled
14and/or runs.
15
16=head2 Compiling Perl 5 on Tru64
17
18The recommended compiler to use in Tru64 is the native C compiler.
19The native compiler produces much faster code (the speed difference is
20noticeable: several dozen percentages) and also more correct code: if
21you are considering using the GNU C compiler you should use at the
22very least the release of 2.95.3 since all older gcc releases are
23known to produce broken code when compiling Perl.  One manifestation
24of this brokenness is the lib/sdbm test dumping core; another is many
25of the op/regexp and op/pat, or ext/Storable tests dumping core
26(the exact pattern of failures depending on the GCC release and
27optimization flags).
28
29Both the native cc and gcc seem to consume lots of memory when
30building Perl.  toke.c is a known trouble spot when optimizing:
31256 megabytes of data section seems to be enough.  Another known
32trouble spot is the mktables script which builds the Unicode support
33tables.  The default setting of the process data section in Tru64
34should be one gigabyte, but some sites/setups might have lowered that.
35The configuration process of Perl checks for too low process limits,
36and lowers the optimization for the toke.c if necessary, and also
37gives advice on how to raise the process limits
38(for example: C<ulimit -d 262144>)
39
40Also, Configure might abort with
41
42    Build a threading Perl? [n]
43    Configure[2437]: Syntax error at line 1 : 'config.sh' is not expected.
44
45This indicates that Configure is being run with a broken Korn shell
46(even though you think you are using a Bourne shell by using
47"sh Configure" or "./Configure").  The Korn shell bug has been reported
48to Compaq as of February 1999 but in the meanwhile, the reason ksh is
49being used is that you have the environment variable BIN_SH set to
50'xpg4'.  This causes /bin/sh to delegate its duties to /bin/posix/sh
51(a ksh).  Unset the environment variable and rerun Configure.
52
53=head2 Using Large Files with Perl on Tru64
54
55In Tru64 Perl is automatically able to use large files, that is,
56files larger than 2 gigabytes, there is no need to use the Configure
57-Duselargefiles option as described in INSTALL (though using the option
58is harmless).
59
60=head2 Threaded Perl on Tru64
61
62If you want to use threads, you should primarily use the Perl
635.8.0 threads model by running Configure with -Duseithreads.
64
65Perl threading is going to work only in Tru64 4.0 and newer releases,
66older operating releases like 3.2 aren't probably going to work
67properly with threads.
68
69In Tru64 V5 (at least V5.1A, V5.1B) you cannot build threaded Perl with gcc
70because the system header <pthread.h> explicitly checks for supported
71C compilers, gcc (at least 3.2.2) not being one of them.  But the
72system C compiler should work just fine.
73
74=head2 Long Doubles on Tru64
75
76You cannot Configure Perl to use long doubles unless you have at least
77Tru64 V5.0, the long double support simply wasn't functional enough
78before that.  Perl's Configure will override attempts to use the long
79doubles (you can notice this by Configure finding out that the modfl()
80function does not work as it should).
81
82At the time of this writing (June 2002), there is a known bug in the
83Tru64 libc printing of long doubles when not using "e" notation.
84The values are correct and usable, but you only get a limited number
85of digits displayed unless you force the issue by using C<printf
86"%.33e",$num> or the like.  For Tru64 versions V5.0A through V5.1A, a
87patch is expected sometime after perl 5.8.0 is released.  If your libc
88has not yet been patched, you'll get a warning from Configure when
89selecting long doubles.
90
91=head2 DB_File tests failing on Tru64
92
93The DB_File tests (db-btree.t, db-hash.t, db-recno.t) may fail you
94have installed a newer version of Berkeley DB into the system and the
95-I and -L compiler and linker flags introduce version conflicts with
96the DB 1.85 headers and libraries that came with the Tru64.  For example, 
97mixing a DB v2 library with the DB v1 headers is a bad idea.  Watch
98out for Configure options -Dlocincpth and -Dloclibpth, and check your
99/usr/local/include and /usr/local/lib since they are included by default.
100
101The second option is to explicitly instruct Configure to detect the
102newer Berkeley DB installation, by supplying the right directories with
103C<-Dlocincpth=/some/include> and C<-Dloclibpth=/some/lib> B<and> before
104running "make test" setting your LD_LIBRARY_PATH to F</some/lib>.
105
106The third option is to work around the problem by disabling the
107DB_File completely when build Perl by specifying -Ui_db to Configure,
108and then using the BerkeleyDB module from CPAN instead of DB_File.
109The BerkeleyDB works with Berkeley DB versions 2.* or greater.
110
111The Berkeley DB 4.1.25 has been tested with Tru64 V5.1A and found
112to work.  The latest Berkeley DB can be found from L<http://www.sleepycat.com>.
113
114=head2 64-bit Perl on Tru64
115
116In Tru64 Perl's integers are automatically 64-bit wide, there is
117no need to use the Configure -Duse64bitint option as described
118in INSTALL.  Similarly, there is no need for -Duse64bitall
119since pointers are automatically 64-bit wide.
120
121=head2 Warnings about floating-point overflow when compiling Perl on Tru64
122
123When compiling Perl in Tru64 you may (depending on the compiler
124release) see two warnings like this
125
126    cc: Warning: numeric.c, line 104: In this statement, floating-point
127    overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
128        return HUGE_VAL;
129    -----------^
130
131and when compiling the POSIX extension
132
133    cc: Warning: const-c.inc, line 2007: In this statement, floating-point
134    overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
135                return HUGE_VAL;
136    -------------------^
137
138The exact line numbers may vary between Perl releases.  The warnings
139are benign and can be ignored: in later C compiler releases the warnings
140should be gone.
141
142When the file F<pp_sys.c> is being compiled you may (depending on the
143operating system release) see an additional compiler flag being used:
144C<-DNO_EFF_ONLY_OK>.  This is normal and refers to a feature that is
145relevant only if you use the C<filetest> pragma.  In older releases of
146the operating system the feature was broken and the NO_EFF_ONLY_OK
147instructs Perl not to use the feature.
148
149=head1 Testing Perl on Tru64
150
151During "make test" the C<comp>/C<cpp> will be skipped because on Tru64 it
152cannot be tested before Perl has been installed.  The test refers to
153the use of the C<-P> option of Perl.
154
155=head1 ext/ODBM_File/odbm Test Failing With Static Builds
156
157The ext/ODBM_File/odbm is known to fail with static builds
158(Configure -Uusedl) due to a known bug in Tru64's static libdbm
159library.  The good news is that you very probably don't need to ever
160use the ODBM_File extension since more advanced NDBM_File works fine,
161not to mention the even more advanced DB_File.
162
163=head1 Perl Fails Because Of Unresolved Symbol sockatmark
164
165If you get an error like
166
167    Can't load '.../OSF1/lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so' for module IO: Unresolved symbol in .../lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so: sockatmark at .../lib/perl5/5.8.0/alpha-dec_osf/XSLoader.pm line 75.
168
169you need to either recompile your Perl in Tru64 4.0D or upgrade your
170Tru64 4.0D to at least 4.0F: the sockatmark() system call was
171added in Tru64 4.0F, and the IO extension refers that symbol.
172
173=head1 read_cur_obj_info: bad file magic number
174
175You may be mixing the Tru64 cc/ar/ld with the GNU gcc/ar/ld.
176That may work, but sometimes it doesn't (your gcc or GNU utils
177may have been compiled for an incompatible OS release).
178
179Try 'which ld' and 'which ld' (or try 'ar --version' and 'ld --version',
180which work only for the GNU tools, and will announce themselves to be such),
181and adjust your PATH so that you are consistently using either
182the native tools or the GNU tools.  After fixing your PATH, you should
183do 'make distclean' and start all the way from running the Configure
184since you may have quite a confused situation.
185
186=head1 AUTHOR
187
188Jarkko Hietaniemi <jhi@iki.fi>
189
190=cut
191

README.tw

1=encoding utf8
2
3如果你用一般的文字編輯器閱覽這份文件, 請忽略文中奇特的註記字符.
4這份文件是以 POD (簡明文件格式) 寫成; 這種格式是為了能讓人直接讀取,
5而特別設計的. 關於此格式的進一步資訊, 請參考 perlpod 線上文件.
6
7=head1 NAME
8
9perltw - 正體中文 Perl 指南
10
11=head1 DESCRIPTION
12
13歡迎來到 Perl 的天地!
14
15從 5.8.0 版開始, Perl 具備了完善的 Unicode (萬國碼) 支援,
16也連帶支援了許多拉丁語系以外的編碼方式; CJK (中日韓) 便是其中的一部份.
17Unicode 是國際性的標準, 試圖涵蓋世界上所有的字符: 西方世界, 東方世界,
18以及兩者間的一切 (希臘文, 敘利亞文, 阿拉伯文, 希伯來文, 印度文,
19印地安文, 等等). 它也容納了多種作業系統與平臺 (如 PC 及麥金塔).
20
21Perl 本身以 Unicode 進行操作. 這表示 Perl 內部的字串資料可用 Unicode
22表示; Perl 的函式與算符 (例如正規表示式比對) 也能對 Unicode 進行操作.
23在輸入及輸出時, 為了處理以 Unicode 之前的編碼方式儲存的資料, Perl
24提供了 Encode 這個模組, 可以讓你輕易地讀取及寫入舊有的編碼資料.
25
26Encode 延伸模組支援下列正體中文的編碼方式 ('big5' 表示 'big5-eten'):
27
28    big5-eten	Big5 編碼 (含倚天延伸字形)
29    big5-hkscs	Big5 + 香港外字集, 2001 年版
30    cp950	字碼頁 950 (Big5 + 微軟添加的字符)
31
32舉例來說, 將 Big5 編碼的檔案轉成 Unicode, 祗需鍵入下列指令:
33
34    perl -MEncode -pe '$_= encode( utf8 => decode( big5 => $_ ) )' \
35      < file.big5 > file.utf8
36
37Perl 也內附了 "piconv", 一支完全以 Perl 寫成的字符轉換工具程式, 用法如下:
38
39    piconv -f big5 -t utf8 < file.big5 > file.utf8
40    piconv -f utf8 -t big5 < file.utf8 > file.big5
41
42另外,若程式碼本身以 utf8 編碼儲存,配合使用 utf8 模組,可讓程式碼中字串以及其運
43算皆以字符為單位,而不以位元為單位,如下所示:
44
45    #!/usr/bin/env perl
46    use utf8;
47    print length("駱駝");	     #  2 (不是 6)
48    print index("諄諄教誨", "教誨"); #  2 (從 0 起算第 2 個字符)
49
50
51=head2 額外的中文編碼
52
53如果需要更多的中文編碼, 可以從 CPAN (L<http://www.cpan.org/>) 下載
54Encode::HanExtra 模組. 它目前提供下列編碼方式:
55
56    cccii	1980 年文建會的中文資訊交換碼
57    euc-tw	Unix 延伸字符集, 包含 CNS11643 平面 1-7
58    big5plus	中文數位化技術推廣基金會的 Big5+
59    big5ext	中文數位化技術推廣基金會的 Big5e
60
61另外, Encode::HanConvert 模組則提供了簡繁轉換用的兩種編碼:
62
63    big5-simp	Big5 正體中文與 Unicode 簡體中文互轉
64    gbk-trad	GBK 簡體中文與 Unicode 正體中文互轉
65
66若想在 GBK 與 Big5 之間互轉, 請參考該模組內附的 b2g.plg2b.pl 兩支程式,
67或在程式內使用下列寫法:
68
69    use Encode::HanConvert;
70    $euc_cn = big5_to_gb($big5); # 從 Big5 轉為 GBK
71    $big5 = gb_to_big5($euc_cn); # 從 GBK 轉為 Big5
72
73=head2 進一步的資訊
74
75請參考 Perl 內附的大量說明文件 (不幸全是用英文寫的), 來學習更多關於
76Perl 的知識, 以及 Unicode 的使用方式. 不過, 外部的資源相當豐富:
77
78=head2 提供 Perl 資源的網址
79
80=over 4
81
82=item L<http://www.perl.com/>
83
84Perl 的首頁 (由歐萊禮公司維護)
85
86=item L<http://www.cpan.org/>
87
88Perl 綜合典藏網 (Comprehensive Perl Archive Network)
89
90=item L<http://lists.perl.org/>
91
92Perl 郵遞論壇一覽
93
94=back
95
96=head2 學習 Perl 的網址
97
98=over 4
99
100=item L<http://www.oreilly.com.tw/product_perl.php?id=index_perl>
101
102正體中文版的歐萊禮 Perl 書藉
103
104=item L<http://groups.google.com/groups?q=tw.bbs.comp.lang.perl>
105
106臺灣 Perl 連線討論區 (也就是各大 BBS 的 Perl 連線版)
107
108=back
109
110=head2 Perl 使用者集會
111
112=over 4
113
114=item L<http://www.pm.org/groups/taiwan.html>
115
116臺灣 Perl 推廣組一覽
117
118=item L<irc://irc.freenode.org/#perl.tw>
119
120Perl.tw 線上聊天室
121
122=back
123
124=head2 Unicode 相關網址
125
126=over 4
127
128=item L<http://www.unicode.org/>
129
130Unicode 學術學會 (Unicode 標準的制定者)
131
132=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
133
134Unix/Linux 上的 UTF-8 及 Unicode 答客問
135
136=back
137
138=head2 中文化資訊
139
140=over 4
141
142=item 中文化軟體聯盟
143
144L<http://www.cpatch.org/>
145
146=item Linux 軟體中文化計劃
147
148L<http://www.linux.org.tw/CLDP/>
149
150=back
151
152=head1 SEE ALSO
153
154L<Encode>, L<Encode::TW>, L<perluniintro>, L<perlunicode>
155
156=head1 AUTHORS
157
158Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
159
160Audrey Tang (唐鳳) E<lt>audreyt@audreyt.orgE<gt>
161
162=cut
163

README.vms

1If you read this file _as_is_, just ignore the equal signs on the left.
2This file is written in the POD format (see [.POD]PERLPOD.POD;1) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlvms - Configuring, building, testing, and installing perl on VMS
8
9=head1 SYNOPSIS
10
11To configure, build, test, and install perl on VMS:
12
13    @configure
14    mmk
15    mmk test
16    mmk install
17
18=head1 DESCRIPTION
19
20=head2 Important safety tip
21
22For best results, make sure you read the "Configuring the Perl Build",
23"Building  Perl", and "Installing Perl" sections of this document before
24you build or install.  Also please note other changes in the current
25release by having a look at L<perldelta/VMS>.
26
27=head2 Introduction to Perl on VMS
28
29The VMS port of Perl is as functionally complete as any other Perl port
30(and as complete as the ports on some Unix systems). The Perl binaries
31provide all the Perl system calls that are either available under VMS or
32reasonably emulated. There are some incompatibilities in process handling
33(e.g. the fork/exec model for creating subprocesses doesn't do what you
34might expect under Unix), mainly because VMS and Unix handle processes and
35sub-processes very differently.
36
37There are still some unimplemented system functions, and of course we
38could use modules implementing useful VMS system services, so if you'd like
39to lend a hand we'd love to have you.  Join the Perl Porting Team Now!
40
41=head2 Other required software for Compiling Perl on VMS
42
43In addition to VMS and DCL you will need three things:
44
45=over 4
46
47=item 1  A C compiler. 
48
49HP (formerly Compaq, more formerly DEC) C for VMS (VAX, Alpha, or Itanium).
50Various ancient versions of DEC C had some caveats, so if you're using a 
51version older than 7.x on Alpha or Itanium or 6.x on VAX, you may need to 
52upgrade to get a successful build.
53
54There have been no recent reports of builds using Gnu C, but latent
55(and most likely outdated) support for it is still present in various
56parts of the sources.
57
58There is rudimentary but not quite complete support for HP C++; to try it out,
59configure with C<-"Dusecxx" -"Duser_c_flags=/WARN=INFORMATIONAL=NOCTOBUTCONREFM">.
60
61=item 2  A make tool. 
62
63You will need the free MMS analog MMK (available from
64L<http://ftp.endlesssoftware.com.au/mmk/kits/> or 
65L<https://github.com/endlesssoftware/mmk>). HP's MMS has not been known to work for
66some time as Perl's automatically-generated description files are too complex for it,
67but MMS support may return in the future.  Gnu Make might work, but it's been so long
68since anyone's tested it that we're not sure.
69
70=item 3  ODS-5 and Extended Parse
71
72All development and testing of Perl on VMS takes place on ODS-5 volumes with
73extended parse enabled in the environment via the command C<SET PROCESS/PARSE=EXTENDED>.
74Latent support for ODS-2 volumes (including on VAX) is still present, but the number
75of components that require ODS-5 features is steadily growing and ODS-2 support may be
76completely removed in a future release.
77
78
79=back
80
81=head2 Additional software that is optional for Perl on VMS
82
83You may also want to have on hand:
84
85=over 4
86
87=item 1  gunzip/gzip for VMS 
88
89A de-compressor for *.gz and *.tgz files available from a number 
90of web/ftp sites such as:
91
92    L<http://www.antinode.info/dec/sw/gzip.html>
93    L<http://vms.process.com/scripts/fileserv/fileserv.com?GZIP>
94
95=item 2  VMS tar 
96
97For reading and writing Unix tape archives (*.tar files).  Vmstar is also 
98available from a number of sites such as:
99
100    L<http://www.antinode.info/dec/sw/vmstar.html>
101    L<http://vms.process.com/scripts/fileserv/fileserv.com?VMSTAR>
102
103A port of GNU tar is also available as part of the GNV package:
104
105    L<http://h71000.www7.hp.com/opensource/gnv.html>
106
107=item 3  unzip for VMS
108
109A combination decompressor and archive reader/writer for *.zip files.  
110Unzip is available from a number of web/ftp sites.
111
112    L<http://www.info-zip.org/UnZip.html>
113    L<http://www.hp.com/go/openvms/freeware/>
114    L<http://vms.process.com/fileserv-software.html>
115
116=item 5 GNU patch and diffutils for VMS
117
118Patches to Perl are usually distributed as GNU unified or contextual diffs. 
119Such patches are created by the GNU diff program (part of the diffutils
120distribution) and applied with GNU patch.  VMS ports of these utilities are
121available here:
122
123    L<http://www.antinode.info/dec/sw/diffutils.html>
124    L<http://vms.pdv-systeme.de/users/martinv/gnupatch.zip>
125
126=back
127
128Please note that unzip and gunzip are not the same thing (they work with
129different formats).  Many of the useful files from CPAN (the Comprehensive
130Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies 
131of the source code for perl as well as modules and scripts that you may 
132wish to add later) hence you probably want to have GUNZIP.EXE and 
133VMSTAR.EXE on your VMS machine.
134
135If you want to include socket support, you'll need a TCP/IP stack and either
136DEC C, or socket libraries.  See the "Socket Support (optional)" topic 
137for more details.
138
139=head1 Unpacking the Perl source code
140
141You may need to set up a foreign symbol for the unpacking utility of
142choice.  Once you have done so, use a command like the following to
143unpack the archive:
144
145    vmstar -xvf perl-5^.23^.6.tar
146
147Then set default to the top-level source directory like so:
148
149    set default [.perl-5^.23^.6]
150
151and proceed with configuration as described in the next section.
152
153
154=head1 Configuring the Perl build
155
156To configure perl (a necessary first step), issue the command
157
158   @configure.com
159
160from the top of an unpacked perl source directory.  You will be asked a 
161series of questions, and the answers to them (along with the capabilities 
162of your C compiler and network stack) will determine how perl is custom-
163built for your machine.
164
165If you have any symbols or logical names in your environment that may 
166interfere with the build or regression testing of perl then F<configure.com> 
167will try to warn you about them.  If a logical name is causing
168you trouble but is in an LNM table that you do not have write access to
169then try defining your own to a harmless equivalence string in a table 
170such that it is resolved before the other (e.g. if TMP is defined in the
171SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table) 
172otherwise simply deassign the dangerous logical names.  The potentially 
173troublesome logicals and symbols include:
174
175    COMP    "LOGICAL"
176    EXT     "LOGICAL"
177    FOO     "LOGICAL"
178    LIB     "LOGICAL"
179    LIST    "LOGICAL"
180    MIME    "LOGICAL"
181    POSIX   "LOGICAL"
182    SYS     "LOGICAL"
183    T       "LOGICAL"
184    THREAD  "LOGICAL"
185    THREADS "LOGICAL"
186    TIME    "LOGICAL"
187    TMP     "LOGICAL"
188    UNICODE "LOGICAL"
189    UTIL    "LOGICAL"
190    TEST    "SYMBOL"
191
192As a handy shortcut, the command:
193
194    @configure "-des"
195
196(note the quotation marks and case) will choose reasonable defaults 
197automatically.  Some options can be given explicitly on the command line;
198the following example specifies a non-default location for where Perl
199will be installed:
200
201    @configure "-d" "-Dprefix=dka100:[utils.perl5.]"
202
203Note that the installation location would be by default where you unpacked 
204the source with a "_ROOT." appended.  For example if you unpacked the perl 
205source into:
206
207   F<DKA200:[PERL-5^.18^.0...]>
208
209Then the F<PERL_SETUP.COM> that gets written out by F<configure.com> will
210try to DEFINE your installation PERL_ROOT to be:
211
212   F<DKA200:[PERL-5^.18^.0_ROOT.]>
213
214More help with configure.com is available from:
215
216    @configure "-h"
217
218If you find yourself reconfiguring and rebuilding  then be sure to also follow
219the advice in the "Cleaning up and starting  fresh (optional)" and the checklist
220of items in the "CAVEATS" sections below.
221
222=head2 Changing compile-time options (optional) for Perl on VMS
223
224Most of the user-definable features of Perl are enabled or disabled in
225configure.com, which processes the hints file config_h.SH.  There is
226code in there to Do The Right Thing, but that  may end up being the
227wrong thing for you.  Make sure you understand what you are doing since
228inappropriate changes to configure.com or config_h.SH can render perl 
229unbuildable; odds are that there's nothing in there you'll need to
230change. Note also that non-default options are tested less than default
231options, so you may end up being more of a pioneer than you intend to be.
232
233=head2 Socket Support (optional) for Perl on VMS
234
235Perl includes a number of functions for IP sockets, which are available if
236you choose to compile Perl with socket support.  It does this via the socket
237routines built into the CRTL regarless of which TCP/IP stack your system
238has.
239
240=head1 Building Perl
241
242The configuration script will print out, at the very end, the MMS or MMK
243command you need to compile perl.  Issue it (exactly as printed) to start
244the build.  
245
246Once you issue your MMS or MMK command, sit back and wait.  Perl should 
247compile and link without a problem.  If a problem does occur check the 
248"CAVEATS" section of this document.  If that does not help send some 
249mail to the VMSPERL mailing list.  Instructions are in the L<"Mailing Lists"> 
250section of this document.
251
252=head1 Testing Perl
253
254Once Perl has built cleanly you need to test it to make sure things work.
255This step is very important since there are always things that can go wrong
256somehow and yield a dysfunctional Perl for you.
257
258Testing is very easy, though, as there's a full test suite in the perl
259distribution.  To run the tests, enter the I<exact> MMS line you used to
260compile Perl and add the word "test" to the end, like this:
261
262If the compile command was:
263
264    MMK
265
266then the test command ought to be:
267
268    MMK test
269
270MMK (or MMS) will run all the tests.  This may take some time, as there are 
271a lot of tests.  If any tests fail, there will be a note made on-screen. 
272At the end of all the tests, a summary of the tests, the number passed and 
273failed, and the time taken will be displayed.
274
275The test driver invoked via MMK TEST has a DCL wrapper ([.VMS]TEST.COM) that
276downgrades privileges to NETMBX, TMPMBX for the duration of the test run,
277and then restores them to their prior state upon completion of testing. 
278This is done to ensure that the tests run in a private sandbox and can do no
279harm to your system even in the unlikely event something goes badly wrong in
280one of the test scripts while running the tests from a privileged account. 
281A side effect of this safety precaution is that the account used to run the
282test suite must be the owner of the directory tree in which Perl has been
283built; otherwise the manipulations of temporary files and directories
284attempted by some of the tests will fail.
285
286If any tests fail, it means something is wrong with Perl, or at least
287with the particular module or feature that reported failure. If the test suite
288hangs (some tests can take upwards of two or three minutes, or more if
289you're on an especially slow machine, depending on your machine speed, so
290don't be hasty), then the test I<after> the last one displayed failed. Don't
291install Perl unless you're confident that you're OK. Regardless of how
292confident you are, make a bug report to the VMSPerl mailing list.
293
294If one or more tests fail, you can get more information on the failure by 
295issuing this command sequence:
296
297    @[.vms]test .typ "" "-v" [.subdir]test.t
298
299where ".typ" is the file type of the Perl images you just built (if you
300didn't do anything special, use .EXE), and "[.subdir]test.t" is the test
301that failed. For example, with a normal Perl build, if the test indicated
302that t/op/time failed, then you'd do this:
303
304    @ .vms]test .EXE "" "-v" [.OP]TIME.t
305
306Note that test names are reported in UNIX syntax and relative to the
307top-level build directory.  When supplying them individually to the test
308driver, you can use either UNIX or VMS syntax, but you must give the path
309relative to the [.t] directory and you must also add the .t extension to the
310filename.  So, for example if the test lib/Math/Trig fails, you would run:
311
312    @[.vms]test .EXE "" -"v" [-.lib.math]trig.t
313
314When you send in a bug report for failed tests, please include the output
315from this command, which is run from the main source directory:
316
317    MCR []MINIPERL "-Ilib" "-V"
318
319Note that -"V" really is a capital V in double quotes. This will dump out a
320couple of screens worth of configuration information, and can help us 
321diagnose the problem.  If (and only if) that did not work then try enclosing 
322the output of:
323
324    MMK printconfig
325
326If (and only if) that did not work then try enclosing the output of:
327
328    @[.vms]myconfig
329
330You may also be asked to provide your C compiler version ("CC/VERSION NL:" 
331with DEC C, "gcc --version" with GNU CC).  To obtain the version of MMS or 
332MMK you are running try "MMS/ident" or "MMK /ident".  The GNU make version 
333can be identified with "make --version".
334
335=head2 Cleaning up and starting fresh (optional) installing Perl on VMS
336
337If you need to recompile from scratch, you have to make sure you clean up
338first.  There is a procedure to do it--enter the I<exact> MMK line you used 
339to compile and add "realclean" at the end, like this:
340
341if the compile command was:
342
343    MMK
344
345then the cleanup command ought to be:
346
347    MMK realclean
348
349If you do not do this things may behave erratically during the subsequent 
350rebuild attempt.  They might not, too, so it is best to be sure and do it.
351
352=head1 Installing Perl
353
354There are several steps you need to take to get Perl installed and
355running.
356
357=over 4
358
359=item 1
360
361Check your default file protections with
362
363     SHOW PROTECTION /DEFAULT
364
365and adjust if necessary with C<SET PROTECTION=(code)/DEFAULT>.
366
367=item 2
368
369Decide where you want Perl to be installed (unless you have already done so
370by using the "prefix" configuration parameter -- see the example in the
371"Configuring the Perl build" section).
372
373The DCL script PERL_SETUP.COM that is written by configure.com will help you
374with the definition of the PERL_ROOT and PERLSHR logical names and the PERL
375foreign command  symbol.  Take a look at PERL_SETUP.COM and modify it if you
376want to.  The installation process will execute PERL_SETUP.COM and copy
377files to the directory tree pointed to by the PERL_ROOT logical name defined
378there, so make sure that you have write access to the parent directory of
379what will become the root of your Perl installation.
380
381=item 3
382
383Run the install script via:
384
385    MMK install
386
387If for some reason it complains about target INSTALL being up to date,
388throw a /FORCE switch on the MMS or MMK command.
389
390=back
391
392Installation will copy F<PERL_SETUP.COM> to the root of your installation
393tree.  If you want to give everyone on the system  access to Perl (and you
394have, for example, installed to F<dsa0:[utils.perl_root]>) then add a line
395that reads:
396
397    $ @dsa0:[utils.perl_root]perl_setup
398
399to F<SYS$MANAGER:SYLOGIN.COM>.  Or for your own use only, simply place
400that line in F<SYS$LOGIN:LOGIN.COM>.
401
402Two alternatives to the foreign symbol would be to install PERL into 
403DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES 
404(optional)" for more information), or put the image in a 
405directory that's in your DCL$PATH.
406
407See also the "INSTALLing images (optional)" section.
408
409=head2 Installing Perl into DCLTABLES (optional) on VMS
410
411Execute the following command file to define PERL as a DCL command.
412You'll need CMKRNL privilege to install the new dcltables.exe.
413
414    $ create perl.cld
415    !
416    ! modify to reflect location of your perl.exe
417    !
418    define verb perl
419      image perl_root:[000000]perl.exe
420      cliflags (foreign)
421    $!
422    $ set command perl /table=sys$common:[syslib]dcltables.exe -
423     /output=sys$common:[syslib]dcltables.exe
424    $ install replace sys$common:[syslib]dcltables.exe
425    $ exit
426
427=head2 INSTALLing Perl images (optional) on VMS
428
429On systems that are using perl quite a bit, and particularly those with 
430minimal RAM, you can boost the performance of perl by INSTALLing it as
431a known image.  PERLSHR.EXE is typically larger than 3000 blocks
432and that is a reasonably large amount of IO to load each time perl is 
433invoked. 
434
435   INSTALL ADD PERLSHR/SHARE
436   INSTALL ADD PERL/HEADER
437
438should be enough for F<PERLSHR.EXE> (/share implies /header and /open), 
439while /HEADER should do for FPERL.EXE> (perl.exe is not a shared image).
440
441If your code 'use's modules, check to see if there is a shareable image for
442them, too.  In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File,
443DCLsym, and Stdio, and other extensions all have shared images that can be
444installed /SHARE.
445
446How much of a win depends on your memory situation, but if you are firing
447off perl with any regularity (like more than once every 20 seconds or so)
448it is probably beneficial to INSTALL at least portions of perl.
449
450While there is code in perl to remove privileges as it runs you are advised
451to NOT INSTALL F<PERL.EXE> with PRIVs!
452
453=head2 Running h2ph to create perl header files (optional) on VMS
454
455If using HP C, ensure that you have extracted loose versions of your 
456compiler's header or *.H files.  Be sure to check the contents of:
457
458    SYS$LIBRARY:DECC$RTLDEF.TLB
459    SYS$LIBRARY:SYS$LIB_C.TLB
460    SYS$LIBRARY:SYS$STARLET_C.TLB
461
462etcetera.
463
464If using GNU cc then also check your GNU_CC:[000000...] tree for the locations
465of the GNU cc headers.
466
467=head1 Reporting Bugs
468
469If you come across what you think might be a bug in Perl, please report
470it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
471the process of creating a bug report. This script includes details of your
472installation, and is very handy. Completed bug reports should go to
473perlbug@perl.com.
474