• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

.github/H11-Oct-2021-817733

Cross/H11-Oct-2021-4,5893,874

Porting/H03-May-2022-44,47332,671

amigaos4/H11-Oct-2021-2,1071,657

cpan/H11-Oct-2021-847,557633,495

cygwin/H11-Oct-2021-606486

dist/H11-Oct-2021-191,874138,840

djgpp/H11-Oct-2021-724599

ext/H11-Oct-2021-97,97867,373

h2pl/H11-Oct-2021-578491

haiku/H11-Oct-2021-222137

hints/H03-May-2022-12,2707,170

lib/H11-Oct-2021-105,03966,703

os2/H07-May-2022-17,74012,408

plan9/H11-Oct-2021-10,5279,292

pod/H11-Oct-2021-171,067119,290

qnx/H11-Oct-2021-7030

regen/H11-Oct-2021-17,60211,226

t/H11-Oct-2021-146,143114,734

utils/H11-Oct-2021-7,5545,804

vms/H11-Oct-2021-17,02212,613

vos/H11-Oct-2021-243191

win32/H03-May-2022-33,99527,687

.dir-locals.elH A D11-Oct-2021208 64

.editorconfigH A D11-Oct-2021169 119

.git_patchH A D11-Oct-202181 21

.gitattributesH A D11-Oct-2021109 54

.gitignoreH A D11-Oct-20212.9 KiB209177

.lgtm.ymlH A D11-Oct-2021347 1615

.mailmapH A D11-Oct-20215.9 KiB9796

.travis.ymlH A D11-Oct-20212.1 KiB7061

AUTHORSH A D11-Oct-202168.6 KiB1,3771,376

ArtisticH A D11-Oct-20216.2 KiB13299

CODE_OF_CONDUCT.mdH A D11-Oct-2021973 2116

ChangesH A D11-Oct-20213 KiB7055

ConfigureH A D03-May-2022586.1 KiB25,75023,854

CopyingH A D11-Oct-202112.3 KiB252200

EXTERN.hH A D11-Oct-20211.5 KiB5837

INSTALLH A D11-Oct-2021106.2 KiB2,7442,037

INTERN.hH A D11-Oct-20211.2 KiB5232

MANIFESTH A D11-Oct-2021333.6 KiB6,3106,309

META.jsonH A D11-Oct-20214.7 KiB171170

META.ymlH A D11-Oct-20213.7 KiB157156

Makefile.SHH A D03-May-202251.1 KiB1,7521,226

Makefile.microH A D11-Oct-20215.2 KiB199133

PACKAGINGH A D11-Oct-20211.7 KiB5134

Policy_sh.SHH A D11-Oct-20217.9 KiB259124

READMEH A D11-Oct-20215.5 KiB13296

README.aixH A D11-Oct-202120 KiB517389

README.amigaH A D11-Oct-20215.6 KiB224134

README.androidH A D11-Oct-20218 KiB219152

README.bs2000H A D11-Oct-20217.8 KiB244169

README.cnH A D11-Oct-20214.7 KiB15592

README.cygwinH A D11-Oct-202126.5 KiB779570

README.dosH A D11-Oct-202110.3 KiB332223

README.freebsdH A D11-Oct-20211.6 KiB4229

README.haikuH A D11-Oct-20211.5 KiB6538

README.hpuxH A D11-Oct-202129.9 KiB710551

README.hurdH A D11-Oct-20211.9 KiB5638

README.irixH A D11-Oct-20214.3 KiB14091

README.jpH A D11-Oct-20218.1 KiB210132

README.koH A D11-Oct-202111.9 KiB336200

README.linuxH A D11-Oct-20212 KiB5235

README.macosH A D11-Oct-2021998 3120

README.macosxH A D11-Oct-202111.8 KiB276203

README.microH A D11-Oct-20211.8 KiB5035

README.openbsdH A D11-Oct-20211.2 KiB3221

README.os2H A D11-Oct-202191.2 KiB2,7711,920

README.os390H A D11-Oct-202116.1 KiB459315

README.os400H A D11-Oct-20214.7 KiB12487

README.plan9H A D11-Oct-20215 KiB147104

README.qnxH A D11-Oct-20216.5 KiB205141

README.riscosH A D11-Oct-20211.5 KiB6841

README.solarisH A D11-Oct-202129.1 KiB714532

README.synologyH A D11-Oct-20217.8 KiB278180

README.tru64H A D11-Oct-20218.3 KiB191143

README.twH A D11-Oct-20214.4 KiB15992

README.vmsH A D11-Oct-202122.5 KiB596427

README.vosH A D11-Oct-20213.8 KiB12281

README.win32H A D11-Oct-202138.1 KiB948684

SECURITY.mdH A D11-Oct-20212 KiB4333

TestInit.pmH A D11-Oct-20214 KiB14980

XSUB.hH A D11-Oct-202123.7 KiB679385

asan_ignoreH A D11-Oct-2021868 2923

autodoc.plH A D11-Oct-202172.4 KiB1,8601,270

av.cH A D11-Oct-202130.1 KiB1,138695

av.hH A D11-Oct-20216.5 KiB18735

caretx.cH A D11-Oct-20214.3 KiB14581

cflags.SHH A D11-Oct-202115.6 KiB538365

charclass_invlists.hH A D11-Oct-20214.3 MiB430,837424,786

config_h.SHH A D11-Oct-2021166.8 KiB5,3784,315

configpmH A D11-Oct-202132.5 KiB1,264939

configure.comH A D11-Oct-2021219.6 KiB7,7297,700

configure.gnuH A D11-Oct-20212.5 KiB137107

cop.hH A D11-Oct-202147.2 KiB1,355647

cv.hH A D11-Oct-202112.1 KiB319176

deb.cH A D11-Oct-20218.9 KiB333241

doio.cH A D11-Oct-2021103.5 KiB3,3562,793

doop.cH A D11-Oct-202136.2 KiB1,221898

dosish.hH A D11-Oct-20215.2 KiB17987

dquote.cH A D11-Oct-202118.3 KiB567361

dump.cH A D11-Oct-2021105.3 KiB3,1422,485

ebcdic_tables.hH A D11-Oct-202152 KiB849653

embed.fncH A D11-Oct-2021159.3 KiB3,7223,632

embed.hH A D11-Oct-2021100.3 KiB2,1342,079

embedvar.hH A D11-Oct-202114.7 KiB358336

fakesdio.hH A D11-Oct-20213.1 KiB128102

feature.hH A D11-Oct-202113 KiB402341

form.hH A D11-Oct-20211.4 KiB2818

generate_uudmap.cH A D11-Oct-20215.5 KiB200129

globals.cH A D11-Oct-20211.4 KiB457

globvar.symH A D11-Oct-20211.7 KiB10199

gv.cH A D11-Oct-2021130.1 KiB3,9812,822

gv.hH A D11-Oct-202111.3 KiB299192

handy.hH A D11-Oct-2021133.8 KiB2,9261,160

hv.cH A D11-Oct-2021121.6 KiB3,8452,565

hv.hH A D11-Oct-202125.7 KiB660355

hv_func.hH A D11-Oct-20217 KiB175118

hv_macro.hH A D11-Oct-20213 KiB8656

inline.hH A D11-Oct-2021102.1 KiB3,4351,611

install_lib.plH A D11-Oct-20214.8 KiB205162

installhtmlH A D11-Oct-202117.4 KiB588390

installmanH A D11-Oct-20215.9 KiB189142

installperlH A D03-May-202225.2 KiB780610

intrpvar.hH A D11-Oct-202135.1 KiB1,040412

invlist_inline.hH A D11-Oct-20217.3 KiB249136

iperlsys.hH A D11-Oct-202150.5 KiB1,4161,237

keywords.cH A D11-Oct-202190.2 KiB3,4912,854

keywords.hH A D11-Oct-20216.5 KiB279259

l1_char_class_tab.hH A D11-Oct-2021118.1 KiB797780

libperl.soH A D01-Jan-19700

libperl.so.5.35H A D01-Jan-19700

locale.cH A D11-Oct-2021204.1 KiB5,6283,238

make_ext.plH A D11-Oct-202126.3 KiB779532

make_patchnum.plH A D11-Oct-20217.5 KiB235166

makedef.plH A D11-Oct-202128.4 KiB1,184991

makedepend.SHH A D11-Oct-20214.5 KiB173139

makedepend_file.SHH A D11-Oct-20216.4 KiB178127

malloc.cH A D11-Oct-202180.2 KiB2,3811,645

malloc_ctl.hH A D11-Oct-20211.5 KiB6346

mathoms.cH A D11-Oct-202130 KiB1,419731

metaconfig.SHH A D11-Oct-20211.2 KiB331

metaconfig.hH A D11-Oct-2021766 230

mg.cH A D03-May-2022107.4 KiB3,8702,920

mg.hH A D11-Oct-20213.6 KiB9061

mg_names.incH A D11-Oct-20212.1 KiB5552

mg_raw.hH A D11-Oct-20214.3 KiB9382

mg_vtable.hH A D11-Oct-20219.5 KiB244203

miniperlmain.cH A D11-Oct-20214.6 KiB16073

mkppportH A D11-Oct-20214.4 KiB187147

mkppport.lstH A D11-Oct-2021211 1210

mro_core.cH A D11-Oct-202149.2 KiB1,436876

myconfig.SHH A D11-Oct-20212.6 KiB10090

mydtrace.hH A D11-Oct-20211.7 KiB5528

nostdio.hH A D11-Oct-20213.3 KiB135106

numeric.cH A D11-Oct-202162.6 KiB1,9901,169

op.cH A D11-Oct-2021626 KiB18,78312,342

op.hH A D11-Oct-202139.6 KiB1,156613

op_reg_common.hH A D11-Oct-20215.8 KiB14666

opcode.hH A D11-Oct-202191.8 KiB3,3943,304

opnames.hH A D11-Oct-20218.8 KiB452422

overload.hH A D11-Oct-20213.2 KiB9979

overload.incH A D11-Oct-20213.6 KiB181176

packsizetables.incH A D11-Oct-20215.9 KiB223219

pad.cH A D11-Oct-202192.1 KiB2,8491,753

pad.hH A D11-Oct-202117.2 KiB519210

parser.hH A D11-Oct-20216.9 KiB166117

patchlevel.hH A D11-Oct-20216.4 KiB17833

perl.cH A D03-May-2022163.2 KiB5,3413,840

perl.hH A D11-Oct-2021293.1 KiB8,4455,261

perl_inc_macro.hH A D11-Oct-20216.2 KiB192123

perl_langinfo.hH A D11-Oct-20212.8 KiB191178

perl_siphash.hH A D11-Oct-20215.1 KiB128105

perlapi.hH A D11-Oct-2021634 233

perldtrace.dH A D11-Oct-2021491 218

perlio.cH A D11-Oct-2021141.8 KiB5,2434,265

perlio.hH A D11-Oct-20219.2 KiB340245

perlio.symH A D11-Oct-2021446 2927

perliol.hH A D11-Oct-202113.3 KiB284225

perlsdio.hH A D11-Oct-2021527 223

perlvars.hH A D11-Oct-202112 KiB308103

perly.actH A D11-Oct-202151.7 KiB2,1601,599

perly.cH A D11-Oct-202118.7 KiB615382

perly.hH A D11-Oct-20218.8 KiB230167

perly.tabH A D11-Oct-202191.6 KiB1,4281,395

perly.yH A D11-Oct-202146.3 KiB1,4491,205

pp.cH A D11-Oct-2021212.9 KiB7,2185,732

pp.hH A D11-Oct-202129 KiB704342

pp_ctl.cH A D11-Oct-2021188.6 KiB5,9844,550

pp_hot.cH A D11-Oct-2021191.6 KiB5,6813,831

pp_pack.cH A D11-Oct-2021107.5 KiB3,1812,726

pp_proto.hH A D11-Oct-202112 KiB309300

pp_sort.cH A D11-Oct-202142.6 KiB1,330857

pp_sys.cH A D11-Oct-2021157 KiB5,9134,859

proto.hH A D11-Oct-2021275.9 KiB7,0406,386

reentr.cH A D11-Oct-202119.9 KiB681503

reentr.hH A D11-Oct-202185.2 KiB1,7011,416

regcharclass.hH A D11-Oct-2021264.1 KiB3,7713,027

regcomp.cH A D11-Oct-20211 MiB25,72216,403

regcomp.hH A D11-Oct-202151.9 KiB1,217622

regcomp.symH A D11-Oct-202117.1 KiB329270

regen.plH A D11-Oct-2021869 3318

regen_perly.plH A D11-Oct-20219.7 KiB359216

regexec.cH A D11-Oct-2021443.1 KiB11,5767,766

regexp.hH A D11-Oct-202137.9 KiB936528

regnodes.hH A D11-Oct-2021108.4 KiB2,1181,717

run.cH A D11-Oct-20211.4 KiB5315

runtests.SHH A D11-Oct-20212.5 KiB10467

sbox32_hash.hH A D11-Oct-202156 KiB1,7841,743

scope.cH A D11-Oct-202147.3 KiB1,6261,275

scope.hH A D11-Oct-202112.3 KiB344223

sv.cH A D11-Oct-2021557.8 KiB17,24811,205

sv.hH A D11-Oct-202196.8 KiB2,5951,187

taint.cH A D11-Oct-20215.8 KiB194140

thread.hH A D11-Oct-202117.4 KiB529414

time64.cH A D11-Oct-202117.3 KiB591366

time64.hH A D11-Oct-2021900 4932

time64_config.hH A D11-Oct-20212 KiB8814

toke.cH A D11-Oct-2021445.8 KiB13,3679,551

uconfig.hH A D11-Oct-2021163 KiB5,345378

uconfig.shH A D11-Oct-202118.3 KiB931929

uconfig64.shH A D11-Oct-202118.4 KiB931929

uni_keywords.hH A D11-Oct-2021553.1 KiB7,7077,623

unicode_constants.hH A D11-Oct-20218.3 KiB204117

universal.cH A D11-Oct-202136.7 KiB1,385964

unixish.hH A D11-Oct-20215.2 KiB17457

utf8.cH A D11-Oct-2021163.6 KiB4,3692,220

utf8.hH A D11-Oct-202157.3 KiB1,238397

utfebcdic.hH A D11-Oct-202111.5 KiB20913

util.cH A D11-Oct-2021198.3 KiB6,8494,578

util.hH A D11-Oct-202110.3 KiB284126

utils.lstH A D11-Oct-2021503 2928

vutil.cH A D11-Oct-202127.4 KiB1,141808

vutil.hH A D11-Oct-20214 KiB11588

vxs.incH A D11-Oct-202110.5 KiB450404

warnings.hH A D11-Oct-202110.7 KiB331132

write_buildcustomize.plH A D11-Oct-20213.3 KiB12175

zaphod32_hash.hH A D11-Oct-20219.4 KiB288238

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, 2016, 2017, 2018, 2019, 2020, 2021 by Larry Wall and others.
4All rights reserved.
5
6
7
8ABOUT PERL
9==========
10
11Perl is a general-purpose programming language originally developed for
12text manipulation and now used for a wide range of tasks including
13system administration, web development, network programming, GUI
14development, and more.
15
16The language is intended to be practical (easy to use, efficient,
17complete) rather than beautiful (tiny, elegant, minimal).  Its major
18features are that it's easy to use, supports both procedural and
19object-oriented (OO) programming, has powerful built-in support for text
20processing, and has one of the world's most impressive collections of
21third-party modules.
22
23For an introduction to the language's features, see pod/perlintro.pod.
24
25For a discussion of the important changes in this release, see
26pod/perldelta.pod.
27
28There are also many Perl books available, covering a wide variety of topics,
29from various publishers.  See pod/perlbook.pod for more information.
30
31
32INSTALLATION
33============
34
35If you're using a relatively modern operating system and want to
36install this version of Perl locally, run the following commands:
37
38  ./Configure -des -Dprefix=$HOME/localperl
39  make test
40  make install
41
42This will configure and compile perl for your platform, run the regression
43tests, and install perl in a subdirectory "localperl" of your home directory.
44
45If you run into any trouble whatsoever or you need to install a customized
46version of Perl, you should read the detailed instructions in the "INSTALL"
47file that came with this distribution.  Additionally, there are a number of
48"README" files with hints and tips about building and using Perl on a wide
49variety of platforms, some more common than others.
50
51Once you have Perl installed, a wealth of documentation is available to you
52through the 'perldoc' tool.  To get started, run this command:
53
54  perldoc perl
55
56
57IF YOU RUN INTO TROUBLE
58=======================
59
60Perl is a large and complex system that's used for everything from
61knitting to rocket science.  If you run into trouble, it's quite
62likely that someone else has already solved the problem you're
63facing. Once you've exhausted the documentation, please report bugs to us
64at the GitHub issue tracker at https://github.com/Perl/perl5/issues
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 https://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
107https://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 overridden 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
431L<http://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 document contains instructions
12to cross-compile Perl for Android 2.0 and later, using the
13binaries provided by Google.  The latter portions describe 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 C<PATH>, where C<$ANDROID_NDK> is the location where you unpacked the
51NDK, and C<$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.
72
73Perl can be cross-compiled using either adb or a normal ssh connection;
74in general, if you can connect your device to the host using a USB port,
75or if you don't feel like installing an sshd app on your device,
76you may want to use adb, although you may be forced to switch to ssh if
77your device is not rooted and you're unlucky -- more on that later.
78Alternatively, if you're cross-compiling to an emulator, you'll have to
79use adb.
80
81=head3 adb
82
83To use adb, download the Android SDK from L<https://developer.android.com/sdk/index.html>.
84The "SDK Tools Only" version should suffice -- if you downloaded the ADT
85Bundle, you can find the sdk under F<$ADT_BUNDLE/sdk/>.
86
87Add F<$ANDROID_SDK/platform-tools> to your C<PATH>, which should give you access
88to adb.  You'll now have to find your device's name using C<adb devices>,
89and later pass that to Configure through C<-Dtargethost=$DEVICE>.
90
91However, before calling Configure, you need to check if using adb is a
92viable choice in the first place.  Because Android doesn't have a F</tmp>,
93nor does it allow executables in the sdcard, we need to find somewhere in
94the device for Configure to put some files in, as well as for the tests
95to run in. If your device is rooted, then you're good.  Try running these:
96
97    $ export TARGETDIR=/mnt/asec/perl
98    $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
99
100Which will create the directory we need, and you can move on to the next
101step.  F</mnt/asec> is mounted as a tmpfs in Android, but it's only
102accessible to root.
103
104If your device is not rooted, you may still be in luck. Try running this:
105
106    $ export TARGETDIR=/data/local/tmp/perl
107    $ adb -s $DEVICE shell "mkdir $TARGETDIR"
108
109If the command works, you can move to the next step, but beware:
110B<You'll have to remove the directory from the device once you are done!
111Unlike F</mnt/asec>, F</data/local/tmp> may not get automatically garbage
112collected once you shut off the phone>.
113
114If neither of those work, then you can't use adb to cross-compile to your
115device.  Either try rooting it, or go for the ssh route.
116
117=head3 ssh
118
119To use ssh, you'll need to install and run a sshd app and set it up
120properly.  There are several paid and free apps that do this rather
121easily, so you should be able to spot one on the store.
122Remember that Perl requires a passwordless connection, so set up a
123public key.
124
125Note that several apps spew crap to stderr every time you
126connect, which can throw off Configure.  You may need to monkeypatch
127the part of Configure that creates C<run-ssh> to have it discard stderr.
128
129Since you're using ssh, you'll have to pass some extra arguments to
130Configure:
131
132  -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
133
134=head2 Configure and beyond
135
136With all of the previous done, you're now ready to call Configure.
137
138If using adb, a "basic" Configure line will look like this:
139
140  $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
141      -Dcc=$TARGETARCH-gcc   \
142      -Dsysroot=$SYSROOT     \
143      -Dtargetdir=$TARGETDIR \
144      -Dtargethost=$DEVICE
145
146If using ssh, it's not too different -- we just change targetrun to ssh,
147and pass in targetuser and targetport.  It ends up looking like this:
148
149  $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
150      -Dcc=$TARGETARCH-gcc        \
151      -Dsysroot=$SYSROOT          \
152      -Dtargetdir=$TARGETDIR      \
153      -Dtargethost="$TARGETHOST"  \
154      -Dtargetuser=$TARGETUSER    \
155      -Dtargetport=$TARGETPORT
156
157Now you're ready to run C<make> and C<make test>!
158
159As a final word of warning, if you're using adb, C<make test> may appear to
160hang; this is because it doesn't output anything until it finishes
161running all tests.  You can check its progress by logging into the
162device, moving to F<$TARGETDIR>, and looking at the file F<output.stdout>.
163
164=head3 Notes
165
166=over
167
168=item *
169
170If you are targetting x86 Android, you will have to change C<$TARGETARCH-gcc>
171to C<i686-linux-android-gcc>.
172
173=item *
174
175On some older low-end devices -- think early 2.2 era -- some tests,
176particularly F<t/re/uniprops.t>, may crash the phone, causing it to turn
177itself off once, and then back on again.
178
179=back
180
181=head1 Native Builds
182
183While Google doesn't provide a native toolchain for Android,
184you can still get one from the Play Store.
185
186=head2 CCTools
187
188You may be able to get the CCTools app, which is free.
189Keep in mind that you want a full toolchain;
190some apps tend to default to installing only a barebones
191version without some important utilities, like ar or nm.
192
193Once you have the toolchain set up properly, the only
194remaining hurdle is actually locating where in the device it was installed
195in.  For example, CCTools installs its toolchain in
196F</data/data/com.pdaxrom.cctools/root/cctools>.  With the path in hand,
197compiling perl is little more than:
198
199 export SYSROOT=<location of the native toolchain>
200 export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
201 sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"
202
203=head2 Termux
204
205L<Termux|https://termux.com/> provides an Android terminal emulator and Linux environment.
206It comes with a cross-compiled perl already installed.
207
208Natively compiling perl 5.30 or later should be as straightforward as:
209
210 sh Configure -des -Alibpth="/system/lib /vendor/lib"
211
212This certainly works on Android 8.1 (Oreo) at least...
213
214=head1 AUTHOR
215
216Brian Fraser <fraserbn@gmail.com>
217
218=cut
219

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 submit comments to L<https://github.com/Perl/perl5/issues>.>
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 0; # ^ Run only under a 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    https://lists.perl.org/list/perl-mvs.html
231
232There are web archives of the mailing list at:
233
234    https://www.nntp.perl.org/group/perl.mvs/
235
236=head1 HISTORY
237
238This document was originally written by Thomas Dorner for the 5.005
239release of Perl.
240
241This document was podified for the 5.6 release of perl 11 July 2000.
242
243=cut
244

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<https://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<https://www.perl.org/>
87
88=back
89
90Perl 的首页
91
92=over 4
93
94=item L<https://www.perl.com/>
95
96由 Perl 基金会运营的文章辑录
97
98=item L<https://www.cpan.org/>
99
100Perl 综合典藏网 (Comprehensive Perl Archive Network)
101
102=item L<https://lists.perl.org/>
103
104Perl 邮递论坛一览
105
106=back
107
108=head2 学习 Perl 的网址
109
110=over 4
111
112=item L<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>
113
114简体中文版的欧莱礼 Perl 书藉
115
116=back
117
118=head2 Perl 使用者集会
119
120=over 4
121
122=item L<https://www.pm.org/groups/asia.html>
123
124中国 Perl 推广组一览
125
126=back
127
128=head2 Unicode 相关网址
129
130=over 4
131
132=item L<https://www.unicode.org/>
133
134Unicode 学术学会 (Unicode 标准的制定者)
135
136=item L<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
137
138Unix/Linux 上的 UTF-8 及 Unicode 常见问题解答
139
140=back
141
142=head1 SEE ALSO
143
144L<Encode>, L<Encode::CN>, L<encoding>, L<perluniintro>, L<perlunicode>
145
146=head1 AUTHORS
147
148Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
149
150Audrey Tang (唐凤) E<lt>audreyt@audreyt.orgE<gt>
151
152Sizhe Zhao E<lt>prc.zhao@outlook.comE<gt>
153
154=cut
155

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

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 L<http://www.freebsd.org/cgi/query-pr.cgi?pr=misc/30631> )
21which has been integrated into FreeBSD 4.6.
22
23=head2 C<$^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 L<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
32C<argv[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
40L<https://github.com/Perl/perl5/issues>.
41
42

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

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 L<https://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,
37     99.98% okay.
38
39There are quite a few systems out there that do worse!
40
41However, since I am running a very recent Hurd snapshot, in which a lot of
42bugs that were exposed by the Perl test suite have been fixed, you may
43encounter more failures.  Likely candidates are: "op/stat", "lib/io_pipe",
44"lib/io_sock", "lib/io_udp" and "lib/time".
45
46In any way, if you're seeing failures beyond those mentioned in this
47document, please consider upgrading to the latest Hurd before reporting
48the failure as a bug.
49
50=head1 AUTHOR
51
52Mark Kettenis <kettenis@gnu.org>
53
54Last Updated: Fri, 29 Oct 1999 22:50:30 +0200
55
56

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, et cetera).  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
110        option 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,
124    99.90% okay.
125
126They are suspected to be compiler errors (at least the shuffle.t
127failure is known from some IRIX 6 setups) and math library errors
128(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
129further fixes for the IRIX are unlikely.  If you can get gcc for 5.3,
130you could try that, too, since gcc in IRIX 6 is a known workaround for
131at least the shuffle.t and sort.t failures.
132
133=head1 AUTHOR
134
135Jarkko Hietaniemi <jhi@iki.fi>
136
137Please report any errors, updates, or suggestions to
138L<https://github.com/Perl/perl5/issues>.
139
140

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 (jcode.pl|Jcode.pm|JPerl) からの移行
59
605.8以前の、スクリプトがEUC-JPであればリテラルだけは扱うことができました。また、入出力を扱うモジュールとしてはJcode.pmが( L<http://openlab.ring.gr.jp/Jcode/> )、perl4用のユーティリティとしてはjcode.plがそれぞれ存在し、日本語の扱えるCGIでよく利用されていることを御存じの方も少なくないかと思われます。ただし、日本語による正規表現をうまく扱うことは不可能でした。
61
625.005以前のPerlには、日本語に特化したローカライズ版、Jperlが存在しました( L<http://homepage2.nifty.com/kipp/perl/jperl/index.html> ※1)。また、Mac OS 9.x/Classic用のPerl、MacPerlの日本語版もMacJPerlとして存在してました。( L<https://habilis.net/macjperl/> ).これらでは文字コードとしてEUC-JPに加えShift_JISもそのまま扱うことができ、また日本語による正規表現を扱うことも可能でした。
63
64Perl5.8では、これらの機能がすべてPerl本体だけで実現できる上に、日本語のみならず上記114の文字コードをすべて、しかも同時に扱うことができます。さらに、CPANなどから新しい文字コード用のモジュールを入手することも簡単にできるようになっています。
65
66※1: ホスティングサービスの終了により現在は閲覧できません。 Vector( L<https://www.vector.co.jp/soft/win95/util/se098198.html> )からWindow用のバイナリを、CPAN( L<https://www.cpan.org/src/unsupported/4.036/jperl/> )からperl4用のパッチを入手することができます。
67
68=over 4
69
70=item *
71
72入出力
73
74以下の例はいずれもShift_JISの入力をEUC-JPに変換して出力します。
75
76  # jcode.pl
77  require "jcode.pl";
78  while(<>){
79    jcode::convert(*_, 'euc', 'sjis');
80    print;
81  }
82  # Jcode.pm
83  use Jcode;
84  while(<>){
85  	print Jcode->new($_, 'sjis')->euc;
86  }
87  # Perl 5.8
88  use Encode;
89  while(<>){
90    from_to($_, 'shiftjis', 'euc-jp');
91    print;
92  }
93  # Perl 5.8 - encoding を利用して
94  use encoding 'euc-jp', STDIN => 'shiftjis';
95  while(<>){
96  	print;
97  }
98
99=item *
100
101Jperl 互換スクリプト
102
103いわゆる"shebang"を変更するだけで、Jperl用のscriptのほとんどは変更なしに利用可能だと思われます。
104
105   #!/path/to/jperl
106107   #!/path/to/perl -Mencoding=euc-jp
108
109詳しくは perldoc encoding を参照してください。
110
111=back
112
113=head2 さらに詳しく
114
115Perlには膨大な資料が付属しており、Perlの新機能やUnicodeサポート、そしてEncodeモジュールの使用法などが細かく網羅されています(残念ながら、ほとんど英語ではありますが)。以下のコマンドでそれらの一部を閲覧することが可能です。
116
117  perldoc perlunicode # PerlのUnicodeサポート全般
118  perldoc Encode      # Encodeモジュールに関して
119  perldoc Encode::JP  # うち日本語文字コードに関して
120
121=head2 Perl全般に関する URL
122
123=over 4
124
125=item L<https://www.perl.org/>
126
127Perl ホームページ
128
129=item L<https://www.perl.com/>
130
131Perl 財団が営業する文章作品集
132
133=item L<https://www.cpan.org/>
134
135CPAN (Comprehensive Perl Archive Network)
136
137=item L<https://metacpan.org/>
138
139MetaCPAN CPANの検索エンジン
140
141=item L<https://lists.perl.org/>
142
143Perl メーリングリスト集
144
145=item L<https://perldoc.jp/>
146
147perldoc.jp Perl の公式ドキュメント、モジュールドキュメントの日本語訳
148
149=back
150
151=head2 Perlの修得に役立つ URL
152
153=over 4
154
155=item L<http://www.oreilly.com.cn/>
156
157O'Reilly 社のPerl関連書籍(簡体字中国語)
158
159=item L<https://www.oreilly.co.jp/catalog/>
160
161オライリー社のPerl関連書籍(日本語)
162
163=back
164
165=head2 Perl に関する団体
166
167=over 4
168
169=item L<https://www.pm.org/groups/asia.html>
170
171アジア地域の Perl Mongers (Perlのユーザーグループ) 一覧
172
173=item L<https://japan.perlassociation.org>
174
175一般社団法人Japan Perl Association (JPA) Perl技術及び文化の啓蒙・促進のための組織
176
177=back
178
179=head2 Unicode関連のURL
180
181=over 4
182
183=item L<https://www.unicode.org/>
184
185Unicode コンソーシアム (Unicode規格の選定団体)
186
187=item L<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
188
189UTF-8 and Unicode FAQ for Unix/Linux
190
191=item L<https://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>
192
193UTF-8 and Unicode FAQ for Unix/Linux (ハングル訳)
194
195=back
196
197=head1 AUTHORS
198
199=over
200
201=item * Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
202
203=item * Dan Kogai (小飼 弾) E<lt>dankogai@dan.co.jpE<gt>
204
205=item * Shogo Ichinose (一野瀬 翔吾) E<lt>shogo82148@gmail.comE<gt>
206
207=back
208
209=cut
210

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<https://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<https://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<https://www.perl.org/>
248
249Perl 공식 홈페이지
250
251=item * L<https://www.perl.com/>
252
253O'Reilly의 Perl 웹 페이지
254
255=item * L<https://www.cpan.org/>
256
257CPAN - Comprehensive Perl Archive Network, 통합적 Perl 파일 보관 네트워크
258
259=item * L<https://metacpan.org>
260
261메타 CPAN
262
263=item * L<https://lists.perl.org/>
264
265Perl 메일링 리스트
266
267=item * L<http://blogs.perl.org/>
268
269Perl 메타 블로그
270
271=item * L<https://www.perlmonks.org/>
272
273Perl 수도승들을 위한 수도원
274
275=item * L<https://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<https://perl.kr/>
291
292한국 Perl 커뮤니티 공식 포털
293
294=item * L<https://doc.perl.kr/>
295
296Perl 문서 한글화 프로젝트
297
298=item * L<https://cafe.naver.com/perlstudy.cafe>
299
300네이버 Perl 카페
301
302=item * L<http://www.perl.or.kr/>
303
304한국 Perl 사용자 모임
305
306=item * L<https://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=back
315
316
317=head1 라이센스
318
319F<README> 파일의 B<'LICENSING'> 항목을 참고하세요.
320
321
322=head1 AUTHORS
323
324=over
325
326=item * Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
327
328=item * 신정식 E<lt>jshin@mailaps.orgE<gt>
329
330=item * 김도형 E<lt>keedi@cpan.orgE<gt>
331
332=back
333
334
335=cut
336

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 Deploying Perl on Linux
15
16Normally one can install F</usr/bin/perl> on Linux using your distribution's
17package manager (e.g: C<sudo apt-get install perl>, or
18C<sudo dnf install perl>). Note that sometimes one needs to install some
19extra system packages in order to be able to use CPAN frontends, and that
20messing with the system's perl is not always recommended. One can use
21L<perlbrew|https://perlbrew.pl/> to avoid such issues.
22
23Otherwise, perl should build fine on Linux using the mainstream compilers
24GCC and clang, while following the usual instructions.
25
26=head2 Experimental Support for Sun Studio Compilers for Linux OS
27
28Sun Microsystems has released a port of their Sun Studio compilers for
29Linux.  As of May 2019, the last stable release took place on 2017, and one can
30buy support contracts for them.
31
32There are some special instructions for building Perl with Sun Studio on
33Linux.  Following the normal C<Configure>, you have to run make as follows:
34
35    LDLOADLIBS=-lc make
36
37C<LDLOADLIBS> is an environment variable used by the linker to link
38C</ext> modules to glibc.  Currently, that environment variable is not getting
39populated by a combination of C<Config> entries and C<ExtUtil::MakeMaker>.
40While there may be a bug somewhere in Perl's configuration or
41C<ExtUtil::MakeMaker> causing the problem, the most likely cause is an
42incomplete understanding of Sun Studio by this author.  Further investigation
43is needed to get this working better.
44
45=head1 AUTHOR
46
47Steve Peters <steve@fisharerojo.org>
48
49Please report any errors, updates, or suggestions to
50L<https://github.com/Perl/perl5/issues>.
51
52

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 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 https://www.cpan.org/src/perl-5.35.5.tar.gz
14  tar -xzf perl-5.35.5.tar.gz
15  cd perl-5.35.5
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.35.5 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               \
104                         -B$SDK/usr/include/gcc                      \
105                        -B$SDK/usr/lib/gcc -isystem$SDK/usr/include  \
106                        -F$SDK/System/Library/Frameworks"            \
107             -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK"   \
108             -de
109
110Keep in mind that these compiler and linker settings will also be used when
111building CPAN modules. For XS modules to be compiled as a universal binary, any
112libraries it links to must also be universal binaries. The system libraries that
113Apple includes with the 10.4u SDK are all universal, but user-installed libraries
114may need to be re-installed as universal binaries.
115
116=head2 64-bit PPC support
117
118Follow the instructions in F<INSTALL> to build perl with support for 64-bit
119integers (C<use64bitint>) or both 64-bit integers and 64-bit addressing
120(C<use64bitall>). In the latter case, the resulting binary will run only
121on G5-based hosts.
122
123Support for 64-bit addressing is experimental: some aspects of Perl may be
124omitted or buggy. Note the messages output by F<Configure> for further
125information. Please use L<https://github.com/Perl/perl5/issues> to submit a
126problem report in the event that you encounter difficulties.
127
128When building 64-bit modules, it is your responsibility to ensure that linked
129external libraries and frameworks provide 64-bit support: if they do not,
130module building may appear to succeed, but attempts to use the module will
131result in run-time dynamic linking errors, and subsequent test failures.
132You can use C<file> to discover the architectures supported by a library:
133
134    $ file libgdbm.3.0.0.dylib
135    libgdbm.3.0.0.dylib: Mach-O fat file with 2 architectures
136    libgdbm.3.0.0.dylib (for architecture ppc):      Mach-O dynamically linked shared library ppc
137    libgdbm.3.0.0.dylib (for architecture ppc64):    Mach-O 64-bit dynamically linked shared library ppc64
138
139Note that this issue precludes the building of many Macintosh-specific CPAN
140modules (C<Mac::*>), as the required Apple frameworks do not provide PPC64
141support. Similarly, downloads from Fink or Darwinports are unlikely to provide
14264-bit support; the libraries must be rebuilt from source with the appropriate
143compiler and linker flags. For further information, see Apple's
144I<64-Bit Transition Guide> at
145L<https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/64bitPorting/transition/transition.html>.
146
147=head2 libperl and Prebinding
148
149Mac OS X ships with a dynamically-loaded libperl, but the default for
150this release is to compile a static libperl. The reason for this is
151pre-binding. Dynamic libraries can be pre-bound to a specific address in
152memory in order to decrease load time. To do this, one needs to be aware
153of the location and size of all previously-loaded libraries. Apple
154collects this information as part of their overall OS build process, and
155thus has easy access to it when building Perl, but ordinary users would
156need to go to a great deal of effort to obtain the information needed
157for pre-binding.
158
159You can override the default and build a shared libperl if you wish
160(S<Configure ... -Duseshrplib>).
161
162With Mac OS X 10.4 "Tiger" and newer, there is almost no performance
163penalty for non-prebound libraries. Earlier releases will suffer a greater
164load time than either the static library, or Apple's pre-bound dynamic library.
165
166=head2 Updating Apple's Perl
167
168In a word - don't, at least not without a *very* good reason. Your scripts
169can just as easily begin with "#!/usr/local/bin/perl" as with
170"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
171part of installation packages and such have generally only been tested
172with the /usr/bin/perl that's installed by Apple.
173
174If you find that you do need to update the system Perl, one issue worth
175keeping in mind is the question of static vs. dynamic libraries. If you
176upgrade using the default static libperl, you will find that the dynamic
177libperl supplied by Apple will not be deleted. If both libraries are
178present when an application that links against libperl is built, ld will
179link against the dynamic library by default. So, if you need to replace
180Apple's dynamic libperl with a static libperl, you need to be sure to
181delete the older dynamic library after you've installed the update.
182
183
184=head2 Known problems
185
186If you have installed extra libraries such as GDBM through Fink
187(in other words, you have libraries under F</sw/lib>), or libdlcompat
188to F</usr/local/lib>, you may need to be extra careful when running
189Configure to not to confuse Configure and Perl about which libraries
190to use.  Being confused will show up for example as "dyld" errors about
191symbol problems, for example during "make test". The safest bet is to run
192Configure as
193
194    Configure ... -Uloclibpth -Dlibpth=/usr/lib
195
196to make Configure look only into the system libraries.  If you have some
197extra library directories that you really want to use (such as newer
198Berkeley DB libraries in pre-Panther systems), add those to the libpth:
199
200    Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'
201
202The default of building Perl statically may cause problems with complex
203applications like Tk: in that case consider building shared Perl
204
205    Configure ... -Duseshrplib
206
207but remember that there's a startup cost to pay in that case (see above
208"libperl and Prebinding").
209
210Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
211the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
212failures in the F<lib/locale> test. These failures have been suppressed
213in the current release of Perl by making the test ignore the broken locale.
214If you need to use the eu_ES locale, you should contact Apple support.
215
216
217=head2 Cocoa
218
219There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
220module, included with Mac OS X, can be used by standalone scripts to
221access Foundation (i.e. non-GUI) classes and objects.
222
223An alternative is CamelBones, a framework that allows access to both
224Foundation and AppKit classes and objects, so that full GUI applications
225can be built in Perl. CamelBones can be found on SourceForge, at
226L<https://www.sourceforge.net/projects/camelbones/>.
227
228
229=head1 Starting From Scratch
230
231Unfortunately it is not that difficult somehow manage to break one's
232Mac OS X Perl rather severely.  If all else fails and you want to
233really, B<REALLY>, start from scratch and remove even your Apple Perl
234installation (which has become corrupted somehow), the following
235instructions should do it.  B<Please think twice before following
236these instructions: they are much like conducting brain surgery to
237yourself.  Without anesthesia.>  We will B<not> come to fix your system
238if you do this.
239
240First, get rid of the libperl.dylib:
241
242    # cd /System/Library/Perl/darwin/CORE
243    # rm libperl.dylib
244
245Then delete every .bundle file found anywhere in the folders:
246
247    /System/Library/Perl
248    /Library/Perl
249
250You can find them for example by
251
252    # find /System/Library/Perl /Library/Perl -name '*.bundle' -print
253
254After this you can either copy Perl from your operating system media
255(you will need at least the /System/Library/Perl and /usr/bin/perl),
256or rebuild Perl from the source code with C<Configure -Dprefix=/usr
257-Duseshrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
258works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
259settings were not quite right.
260
261"Pacifist" from CharlesSoft (L<https://www.charlessoft.com/>) is a nice
262way to extract the Perl binaries from the OS media, without having to
263reinstall the entire OS.
264
265
266=head1 AUTHOR
267
268This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
269and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>
270and Breno G. de Oliveira E<lt>garu@cpan.orgE<gt>. The "Starting From Scratch"
271recipe was contributed by John Montbriand E<lt>montbriand@apple.comE<gt>.
272
273=head1 DATE
274
275Last modified 2013-04-29.
276

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.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
30L<https://github.com/Perl/perl5/issues>.
31
32

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</"F<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</"C<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 C<L</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</"C<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
483L</"C<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</"C<PERL_BADLANG>">.
539
540=item C<PERL_BADFREE>
541
542see L</"C<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</"C<PERLLIB_PREFIX>">.
619
620=item Additional Perl modules
621
622  unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.35.5/
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</"C<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 overwritable (see
699L</"C<PERLLIB_PREFIX>">, L</"C<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<os2/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</"C<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</"C<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,
1010    99.98% okay.
1011
1012The reasons for most important skipped tests are:
1013
1014=over 8
1015
1016=item F<op/fs.t>
1017
1018=over 4
1019
1020=item Z<>18
1021
1022Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1023provides only 2sec time granularity (for compatibility with FAT?).
1024
1025=item Z<>25
1026
1027Checks C<truncate()> on a filehandle just opened for write - I do not
1028know why this should or should not work.
1029
1030=back
1031
1032=item F<op/stat.t>
1033
1034Checks C<stat()>. Tests:
1035
1036=over 4
1037
1038=item 4
1039
1040Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1041provides only 2sec time granularity (for compatibility with FAT?).
1042
1043=back
1044
1045=back
1046
1047=head2 Installing the built perl
1048
1049If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now.
1050
1051Run
1052
1053  make install
1054
1055It would put the generated files into needed locations. Manually put
1056F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
1057PATH, F<perl.dll> to a location on your LIBPATH.
1058
1059Run
1060
1061  make installcmd INSTALLCMDDIR=d:/ir/on/path
1062
1063to convert perl utilities to F<.cmd> files and put them on
1064PATH. You need to put F<.EXE>-utilities on path manually. They are
1065installed in C<$prefix/bin>, here C<$prefix> is what you gave to
1066F<Configure>, see L</Making>.
1067
1068If you use C<man>, either move the installed F<*/man/> directories to
1069your C<MANPATH>, or modify C<MANPATH> to match the location.  (One
1070could have avoided this by providing a correct C<manpath> option to
1071F<./Configure>, or editing F<./config.sh> between configuring and
1072making steps.)
1073
1074=head2 C<a.out>-style build
1075
1076Proceed as above, but make F<perl_.exe> (see L</"F<perl_.exe>">) by
1077
1078  make perl_
1079
1080test and install by
1081
1082  make aout_test
1083  make aout_install
1084
1085Manually put F<perl_.exe> to a location on your PATH.
1086
1087B<Note.> The build process for C<perl_> I<does not know> about all the
1088dependencies, so you should make sure that anything is up-to-date,
1089say, by doing
1090
1091  make perl_dll
1092
1093first.
1094
1095=head1 Building a binary distribution
1096
1097[This section provides a short overview only...]
1098
1099Building should proceed differently depending on whether the version of perl
1100you install is already present and used on your system, or is a new version
1101not yet used.  The description below assumes that the version is new, so
1102installing its DLLs and F<.pm> files will not disrupt the operation of your
1103system even if some intermediate steps are not yet fully working.
1104
1105The other cases require a little bit more convoluted procedures.  Below I
1106suppose that the current version of Perl is C<5.8.2>, so the executables are
1107named accordingly.
1108
1109=over
1110
1111=item 1.
1112
1113Fully build and test the Perl distribution.  Make sure that no tests are
1114failing with C<test> and C<aout_test> targets; fix the bugs in Perl and
1115the Perl test suite detected by these tests.  Make sure that C<all_test>
1116make target runs as clean as possible.  Check that F<os2/perlrexx.cmd>
1117runs fine.
1118
1119=item 2.
1120
1121Fully install Perl, including C<installcmd> target.  Copy the generated DLLs
1122to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>)
1123to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>.  Think whether
1124you need backward-compatibility DLLs.  In most cases you do not need to install
1125them yet; but sometime this may simplify the following steps.
1126
1127=item 3.
1128
1129Make sure that C<CPAN.pm> can download files from CPAN.  If not, you may need
1130to manually install C<Net::FTP>.
1131
1132=item 4.
1133
1134Install the bundle C<Bundle::OS2_default>
1135
1136 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
1137
1138This may take a couple of hours on 1GHz processor (when run the first time).
1139And this should not be necessarily a smooth procedure.  Some modules may not
1140specify required dependencies, so one may need to repeat this procedure several
1141times until the results stabilize.
1142
1143 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
1144 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
1145
1146Even after they stabilize, some tests may fail.
1147
1148Fix as many discovered bugs as possible.  Document all the bugs which are not
1149fixed, and all the failures with unknown reasons.  Inspect the produced logs
1150F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events.
1151
1152Keep in mind that I<installation> of some modules may fail too: for example,
1153the DLLs to update may be already loaded by F<CPAN.pm>.  Inspect the C<install>
1154logs (in the example above F<00cpan_i_1> etc) for errors, and install things
1155manually, as in
1156
1157  cd $CPANHOME/.cpan/build/Digest-MD5-2.31
1158  make install
1159
1160Some distributions may fail some tests, but you may want to install them
1161anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode).
1162
1163Since this procedure may take quite a long time to complete, it makes sense
1164to "freeze" your CPAN configuration by disabling periodic updates of the
1165local copy of CPAN index: set C<index_expire> to some big value (I use 365),
1166then save the settings
1167
1168  CPAN> o conf index_expire 365
1169  CPAN> o conf commit
1170
1171Reset back to the default value C<1> when you are finished.
1172
1173=item 5.
1174
1175When satisfied with the results, rerun the C<installcmd> target.  Now you
1176can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build
1177executables: C<perl__.exe> etc.  They are ready to be used.
1178
1179=item 6.
1180
1181Change to the C<./pod> directory of the build tree, download the Perl logo
1182F<CamelGrayBig.BMP>, and run
1183
1184  ( perl2ipf > perl.ipf ) |& tee 00ipf
1185  ipfc /INF perl.ipf |& tee 00inf
1186
1187This produces the Perl docs online book C<perl.INF>.  Install in on
1188C<BOOKSHELF> path.
1189
1190=item 7.
1191
1192Now is the time to build statically linked executable F<perl_.exe> which
1193includes newly-installed via C<Bundle::OS2_default> modules.  Doing testing
1194via C<CPAN.pm> is going to be painfully slow, since it statically links
1195a new executable per XS extension.
1196
1197Here is a possible workaround: create a toplevel F<Makefile.PL> in
1198F<$CPANHOME/.cpan/build/> with contents being (compare with L</Making
1199executables with a custom collection of statically loaded extensions>)
1200
1201  use ExtUtils::MakeMaker;
1202  WriteMakefile NAME => 'dummy';
1203
1204execute this as
1205
1206  perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
1207  make -k all test <nul |& 00aout_t1
1208
1209Again, this procedure should not be absolutely smooth.  Some C<Makefile.PL>'s
1210in subdirectories may be buggy, and would not run as "child" scripts.  The
1211interdependency of modules can strike you; however, since non-XS modules
1212are already installed, the prerequisites of most modules have a very good
1213chance to be present.
1214
1215If you discover some glitches, move directories of problematic modules to a
1216different location; if these modules are non-XS modules, you may just ignore
1217them - they are already installed; the remaining, XS, modules you need to
1218install manually one by one.
1219
1220After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
1221usually this procedure converges soon.  (But be sure to convert all the
1222necessary external C libraries from F<.lib> format to F<.a> format: run one of
1223
1224  emxaout foo.lib
1225  emximp -o foo.a foo.lib
1226
1227whichever is appropriate.)  Also, make sure that the DLLs for external
1228libraries are usable with executables compiled without C<-Zmtd> options.
1229
1230When you are sure that only a few subdirectories
1231lead to failures, you may want to add C<-j4> option to C<make> to speed up
1232skipping subdirectories with already finished build.
1233
1234When you are satisfied with the results of tests, install the build C libraries
1235for extensions:
1236
1237  make install |& tee 00aout_i
1238
1239Now you can rename the file F<./perl.exe> generated during the last phase
1240to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency
1241between some XS modules, you may need to repeat the C<test>/C<install> loop
1242with this new executable and some excluded modules - until the procedure
1243converges.
1244
1245Now you have all the necessary F<.a> libraries for these Perl modules in the
1246places where Perl builder can find it.  Use the perl builder: change to an
1247empty directory, create a "dummy" F<Makefile.PL> again, and run
1248
1249  perl_5.8.2.exe Makefile.PL |& tee 00c
1250  make perl		     |& tee 00p
1251
1252This should create an executable F<./perl.exe> with all the statically loaded
1253extensions built in.  Compare the generated F<perlmain.c> files to make sure
1254that during the iterations the number of loaded extensions only increases.
1255Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>.
1256
1257When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it
1258to C<perl_.exe>.  You are done with generation of the local Perl installation.
1259
1260=item 8.
1261
1262Make sure that the installed modules are actually installed in the location
1263of the new Perl, and are not inherited from entries of @INC given for
1264inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
1265redirect the new version of Perl to a new location, and copy the installed
1266files to this new location.  Redo the tests to make sure that the versions of
1267modules inherited from older versions of Perl are not needed.
1268
1269Actually, the log output of L<pod2ipf(1)> during the step 6 gives a very detailed
1270info about which modules are loaded from which place; so you may use it as
1271an additional verification tool.
1272
1273Check that some temporary files did not make into the perl install tree.
1274Run something like this
1275
1276  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
1277
1278in the install tree (both top one and F<sitelib> one).
1279
1280Compress all the DLLs with F<lxlite>.  The tiny F<.exe> can be compressed with
1281C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a
1282page (?); since the tiny executables are much smaller than a page, the bug
1283will not hit).  Do not compress C<perl_.exe> - it would not work under DOS.
1284
1285=item 9.
1286
1287Now you can generate the binary distribution.  This is done by running the
1288test of the CPAN distribution C<OS2::SoftInstaller>.  Tune up the file
1289F<test.pl> to suit the layout of current version of Perl first.  Do not
1290forget to pack the necessary external DLLs accordingly.  Include the
1291description of the bugs and test suite failures you could not fix.  Include
1292the small-stack versions of Perl executables from Perl build directory.
1293
1294Include F<perl5.def> so that people can relink the perl DLL preserving
1295the binary compatibility, or can create compatibility DLLs.  Include the diff
1296files (C<diff -pu old new>) of fixes you did so that people can rebuild your
1297version.  Include F<perl5.map> so that one can use remote debugging.
1298
1299=item 10.
1300
1301Share what you did with the other people.  Relax.  Enjoy fruits of your work.
1302
1303=item 11.
1304
1305Brace yourself for thanks, bug reports, hate mail and spam coming as result
1306of the previous step.  No good deed should remain unpunished!
1307
1308=back
1309
1310=head1 Building custom F<.EXE> files
1311
1312The Perl executables can be easily rebuilt at any moment.  Moreover, one can
1313use the I<embedding> interface (see L<perlembed>) to make very customized
1314executables.
1315
1316=head2 Making executables with a custom collection of statically loaded extensions
1317
1318It is a little bit easier to do so while I<decreasing> the list of statically
1319loaded extensions.  We discuss this case only here.
1320
1321=over
1322
1323=item 1.
1324
1325Change to an empty directory, and create a placeholder <Makefile.PL>:
1326
1327  use ExtUtils::MakeMaker;
1328  WriteMakefile NAME => 'dummy';
1329
1330=item 2.
1331
1332Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to
1333rebuild.
1334
1335  perl_ Makefile.PL
1336
1337=item 3.
1338
1339Ask it to create new Perl executable:
1340
1341  make perl
1342
1343(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on
1344some versions of Perl; the symptom is that the command-line globbing does not
1345work from OS/2 shells with the newly-compiled executable; check with
1346
1347  .\perl.exe -wle "print for @ARGV" *
1348
1349).
1350
1351=item 4.
1352
1353The previous step created F<perlmain.c> which contains a list of newXS() calls
1354near the end.  Removing unnecessary calls, and rerunning
1355
1356  make perl
1357
1358will produce a customized executable.
1359
1360=back
1361
1362=head2 Making executables with a custom search-paths
1363
1364The default perl executable is flexible enough to support most usages.
1365However, one may want something yet more flexible; for example, one may want
1366to find Perl DLL relatively to the location of the EXE file; or one may want
1367to ignore the environment when setting the Perl-library search patch, etc.
1368
1369If you fill comfortable with I<embedding> interface (see L<perlembed>), such
1370things are easy to do repeating the steps outlined in L</Making
1371executables with a custom collection of statically loaded extensions>, and
1372doing more comprehensive edits to main() of F<perlmain.c>.  The people with
1373little desire to understand Perl can just rename main(), and do necessary
1374modification in a custom main() which calls the renamed function in appropriate
1375time.
1376
1377However, there is a third way: perl DLL exports the main() function and several
1378callbacks to customize the search path.  Below is a complete example of a
1379"Perl loader" which
1380
1381=over
1382
1383=item 1.
1384
1385Looks for Perl DLL in the directory C<$exedir/../dll>;
1386
1387=item 2.
1388
1389Prepends the above directory to C<BEGINLIBPATH>;
1390
1391=item 3.
1392
1393Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was
1394loaded on step 1; e.g., another process could have loaded it from C<LIBPATH>
1395or from a different value of C<BEGINLIBPATH>.  In these cases one needs to
1396modify the setting of the system so that this other process either does not
1397run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available
1398with kernels after September 2000).
1399
1400=item 4.
1401
1402Loads Perl library from C<$exedir/../dll/lib/>.
1403
1404=item 5.
1405
1406Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>.
1407
1408=back
1409
1410For best results compile the C file below with the same options as the Perl
1411DLL.  However, a lot of functionality will work even if the executable is not
1412an EMX applications, e.g., if compiled with
1413
1414  gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c \
1415    -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1416
1417Here is the sample C file:
1418
1419 #define INCL_DOS
1420 #define INCL_NOPM
1421 /* These are needed for compile if os2.h includes os2tk.h, not
1422  * os2emx.h */
1423 #define INCL_DOSPROCESS
1424 #include <os2.h>
1425
1426 #include "EXTERN.h"
1427 #define PERL_IN_MINIPERLMAIN_C
1428 #include "perl.h"
1429
1430 static char *me;
1431 HMODULE handle;
1432
1433 static void
1434 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1435 {
1436    ULONG c;
1437    char *s = " error: ";
1438
1439    DosWrite(2, me, strlen(me), &c);
1440    DosWrite(2, s, strlen(s), &c);
1441    DosWrite(2, msg1, strlen(msg1), &c);
1442    DosWrite(2, msg2, strlen(msg2), &c);
1443    DosWrite(2, msg3, strlen(msg3), &c);
1444    DosWrite(2, msg4, strlen(msg4), &c);
1445    DosWrite(2, "\r\n", 2, &c);
1446    exit(255);
1447 }
1448
1449 typedef ULONG (*fill_extLibpath_t)(int type,
1450                                    char *pre,
1451                                    char *post,
1452                                    int replace,
1453                                    char *msg);
1454 typedef int (*main_t)(int type, char *argv[], char *env[]);
1455 typedef int (*handler_t)(void* data, int which);
1456
1457 #ifndef PERL_DLL_BASENAME
1458 #  define PERL_DLL_BASENAME "perl"
1459 #endif
1460
1461 static HMODULE
1462 load_perl_dll(char *basename)
1463 {
1464     char buf[300], fail[260];
1465     STRLEN l, dirl;
1466     fill_extLibpath_t f;
1467     ULONG rc_fullname;
1468     HMODULE handle, handle1;
1469
1470     if (_execname(buf, sizeof(buf) - 13) != 0)
1471         die_with("Can't find full path: ", strerror(errno), "", "");
1472     /* XXXX Fill 'me' with new value */
1473     l = strlen(buf);
1474     while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1475         l--;
1476     dirl = l - 1;
1477     strcpy(buf + l, basename);
1478     l += strlen(basename);
1479     strcpy(buf + l, ".dll");
1480     if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle))
1481                                                                    != 0
1482          && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1483         die_with("Can't load DLL ", buf, "", "");
1484     if (rc_fullname)
1485         return handle;    /* was loaded with short name; all is fine */
1486     if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1487         die_with(buf,
1488                  ": DLL exports no symbol ",
1489                  "fill_extLibpath",
1490                  "");
1491     buf[dirl] = 0;
1492     if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1493           0 /* keep old value */, me))
1494         die_with(me, ": prepending BEGINLIBPATH", "", "");
1495     if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1496         die_with(me,
1497                  ": finding perl DLL again via BEGINLIBPATH",
1498                  "",
1499                  "");
1500     buf[dirl] = '\\';
1501     if (handle1 != handle) {
1502         if (DosQueryModuleName(handle1, sizeof(fail), fail))
1503             strcpy(fail, "???");
1504         die_with(buf,
1505                  ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1506                  fail,
1507                  "\n\tYou may need to manipulate global BEGINLIBPATH"
1508                     " and LIBPATHSTRICT"
1509                     "\n\tso that the other copy is loaded via"
1510                     BEGINLIBPATH.");
1511     }
1512     return handle;
1513 }
1514
1515 int
1516 main(int argc, char **argv, char **env)
1517 {
1518     main_t f;
1519     handler_t h;
1520
1521     me = argv[0];
1522     /**/
1523     handle = load_perl_dll(PERL_DLL_BASENAME);
1524
1525     if (DosQueryProcAddr(handle,
1526                          0,
1527                          "Perl_OS2_handler_install",
1528                          (PFN*)&h))
1529         die_with(PERL_DLL_BASENAME,
1530                  ": DLL exports no symbol ",
1531                  "Perl_OS2_handler_install",
1532                  "");
1533     if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1534          || !h((void *)"~dll", Perlos2_handler_perllib_to)
1535          || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1536         die_with(PERL_DLL_BASENAME,
1537                  ": Can't install @INC manglers",
1538                  "",
1539                  "");
1540     if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1541         die_with(PERL_DLL_BASENAME,
1542                  ": DLL exports no symbol ",
1543                  "dll_perlmain",
1544                  "");
1545     return f(argc, argv, env);
1546 }
1547
1548=head1 Build FAQ
1549
1550=head2 Some C</> became C<\> in pdksh.
1551
1552You have a very old pdksh. See L</Prerequisites>.
1553
1554=head2 C<'errno'> - unresolved external
1555
1556You do not have MT-safe F<db.lib>. See L</Prerequisites>.
1557
1558=head2 Problems with tr or sed
1559
1560reported with very old version of tr and sed.
1561
1562=head2 Some problem (forget which ;-)
1563
1564You have an older version of F<perl.dll> on your LIBPATH, which
1565broke the build of extensions.
1566
1567=head2 Library ... not found
1568
1569You did not run C<omflibs>. See L</Prerequisites>.
1570
1571=head2 Segfault in make
1572
1573You use an old version of GNU make. See L</Prerequisites>.
1574
1575=head2 op/sprintf test failure
1576
1577This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
1578
1579=head1 Specific (mis)features of OS/2 port
1580
1581=head2 C<setpriority>, C<getpriority>
1582
1583Note that these functions are compatible with *nix, not with the older
1584ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1585lower is quicker. 0 is the default priority.
1586
1587B<WARNING>.  Calling C<getpriority> on a non-existing process could lock
1588the system before Warp3 fixpak22.  Starting with Warp3, Perl will use
1589a workaround: it aborts getpriority() if the process is not present.
1590This is not possible on older versions C<2.*>, and has a race
1591condition anyway.
1592
1593=head2 C<system()>
1594
1595Multi-argument form of C<system()> allows an additional numeric
1596argument. The meaning of this argument is described in
1597L<OS2::Process>.
1598
1599When finding a program to run, Perl first asks the OS to look for executables
1600on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
1601If not found, it looks for a script with possible extensions
1602added in this order: no extension, F<.cmd>, F<.btm>,
1603F<.bat>, F<.pl>.  If found, Perl checks the start of the file for magic
1604strings C<"#!"> and C<"extproc ">.  If found, Perl uses the rest of the
1605first line as the beginning of the command line to run this script.  The
1606only mangling done to the first line is extraction of arguments (currently
1607up to 3), and ignoring of the path-part of the "interpreter" name if it can't
1608be found using the full path.
1609
1610E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
1611F<C:/emx/bin/foo.cmd> with the first line being
1612
1613 extproc /bin/bash    -x   -c
1614
1615If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
1616C<PATH>.  If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
1617translated to
1618
1619  system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1620
1621One additional translation is performed: instead of F</bin/sh> Perl uses
1622the hardwired-or-customized shell (see L</"C<PERL_SH_DIR>">).
1623
1624The above search for "interpreter" is recursive: if F<bash> executable is not
1625found, but F<bash.btm> is found, Perl will investigate its first line etc.
1626The only hardwired limit on the recursion depth is implicit: there is a limit
16274 on the number of additional arguments inserted before the actual arguments
1628given to system().  In particular, if no additional arguments are specified
1629on the "magic" first lines, then the limit on the depth is 4.
1630
1631If Perl finds that the found executable is of PM type when the
1632current session is not, it will start the new process in a separate session of
1633necessary type.  Call via C<OS2::Process> to disable this magic.
1634
1635B<WARNING>.  Due to the described logic, you need to explicitly
1636specify F<.com> extension if needed.  Moreover, if the executable
1637F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
1638[This may change in the future.]
1639
1640=head2 C<extproc> on the first line
1641
1642If the first chars of a Perl script are C<"extproc ">, this line is treated
1643as C<#!>-line, thus all the switches on this line are processed (twice
1644if script was started via cmd.exe).  See L<perlrun/DESCRIPTION>.
1645
1646=head2 Additional modules:
1647
1648L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
1649modules provide access to additional numeric argument for C<system>
1650and to the information about the running process,
1651to DLLs having functions with REXX signature and to the REXX runtime, to
1652OS/2 databases in the F<.INI> format, and to Extended Attributes.
1653
1654Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
1655C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
1656Other OS/2-related extensions are available too.
1657
1658=head2 Prebuilt methods:
1659
1660=over 4
1661
1662=item C<File::Copy::syscopy>
1663
1664used by C<File::Copy::copy>, see L<File::Copy>.
1665
1666=item C<DynaLoader::mod2fname>
1667
1668used by C<DynaLoader> for DLL name mangling.
1669
1670=item  C<Cwd::current_drive()>
1671
1672Self explanatory.
1673
1674=item  C<Cwd::sys_chdir(name)>
1675
1676leaves drive as it is.
1677
1678=item  C<Cwd::change_drive(name)>
1679
1680changes the "current" drive.
1681
1682=item  C<Cwd::sys_is_absolute(name)>
1683
1684means has drive letter and is_rooted.
1685
1686=item  C<Cwd::sys_is_rooted(name)>
1687
1688means has leading C<[/\\]> (maybe after a drive-letter:).
1689
1690=item  C<Cwd::sys_is_relative(name)>
1691
1692means changes with current dir.
1693
1694=item  C<Cwd::sys_cwd(name)>
1695
1696Interface to cwd from EMX. Used by C<Cwd::cwd>.
1697
1698=item  C<Cwd::sys_abspath(name, dir)>
1699
1700Really really odious function to implement. Returns absolute name of
1701file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
1702current dir.
1703
1704=item  C<Cwd::extLibpath([type])>
1705
1706Get current value of extended library search path. If C<type> is
1707present and positive, works with C<END_LIBPATH>, if negative, works
1708with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
1709
1710=item  C<Cwd::extLibpath_set( path [, type ] )>
1711
1712Set current value of extended library search path. If C<type> is
1713present and positive, works with <END_LIBPATH>, if negative, works
1714with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
1715
1716=item C<OS2::Error(do_harderror,do_exception)>
1717
1718Returns	C<undef> if it was not called yet, otherwise bit 1 is
1719set if on the previous call do_harderror was enabled, bit
17202 is set if on previous call do_exception was enabled.
1721
1722This function enables/disables error popups associated with
1723hardware errors (Disk not ready etc.) and software exceptions.
1724
1725I know of no way to find out the state of popups I<before> the first call
1726to this function.
1727
1728=item C<OS2::Errors2Drive(drive)>
1729
1730Returns C<undef> if it was not called yet, otherwise return false if errors
1731were not requested to be written to a hard drive, or the drive letter if
1732this was requested.
1733
1734This function may redirect error popups associated with hardware errors
1735(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
1736the root directory of the specified drive.  Overrides OS2::Error() specified
1737by individual programs.  Given argument undef will disable redirection.
1738
1739Has global effect, persists after the application exits.
1740
1741I know of no way to find out the state of redirection of popups to the disk
1742I<before> the first call to this function.
1743
1744=item OS2::SysInfo()
1745
1746Returns a hash with system information. The keys of the hash are
1747
1748	MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1749	MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1750	MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1751	VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1752	MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1753	TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1754	MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1755	FOREGROUND_PROCESS
1756
1757=item OS2::BootDrive()
1758
1759Returns a letter without colon.
1760
1761=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
1762
1763Transforms the current application into a PM application and back.
1764The argument true means that a real message loop is going to be served.
1765OS2::MorphPM() returns the PM message queue handle as an integer.
1766
1767See L</"Centralized management of resources"> for additional details.
1768
1769=item C<OS2::Serve_Messages(force)>
1770
1771Fake on-demand retrieval of outstanding PM messages.  If C<force> is false,
1772will not dispatch messages if a real message loop is known to
1773be present.  Returns number of messages retrieved.
1774
1775Dies with "QUITing..." if WM_QUIT message is obtained.
1776
1777=item C<OS2::Process_Messages(force [, cnt])>
1778
1779Retrieval of PM messages until window creation/destruction.
1780If C<force> is false, will not dispatch messages if a real message loop
1781is known to be present.
1782
1783Returns change in number of windows.  If C<cnt> is given,
1784it is incremented by the number of messages retrieved.
1785
1786Dies with "QUITing..." if WM_QUIT message is obtained.
1787
1788=item C<OS2::_control87(new,mask)>
1789
1790the same as L<_control87(3)> of EMX.  Takes integers as arguments, returns
1791the previous coprocessor control word as an integer.  Only bits in C<new> which
1792are present in C<mask> are changed in the control word.
1793
1794=item OS2::get_control87()
1795
1796gets the coprocessor control word as an integer.
1797
1798=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
1799
1800The variant of OS2::_control87() with default values good for
1801handling exception mask: if no C<mask>, uses exception mask part of C<new>
1802only.  If no C<new>, disables all the floating point exceptions.
1803
1804See L</"Misfeatures"> for details.
1805
1806=item C<OS2::DLLname([how [, \&xsub]])>
1807
1808Gives the information about the Perl DLL or the DLL containing the C
1809function bound to by C<&xsub>.  The meaning of C<how> is: default (2):
1810full name; 0: handle; 1: module name.
1811
1812=back
1813
1814(Note that some of these may be moved to different libraries -
1815eventually).
1816
1817
1818=head2 Prebuilt variables:
1819
1820=over 4
1821
1822=item $OS2::emx_rev
1823
1824numeric value is the same as _emx_rev of EMX, a string value the same
1825as _emx_vprt (similar to C<0.9c>).
1826
1827=item $OS2::emx_env
1828
1829same as _emx_env of EMX, a number similar to 0x8001.
1830
1831=item $OS2::os_ver
1832
1833a number C<OS_MAJOR + 0.001 * OS_MINOR>.
1834
1835=item $OS2::is_aout
1836
1837true if the Perl library was compiled in AOUT format.
1838
1839=item $OS2::can_fork
1840
1841true if the current executable is an AOUT EMX executable, so Perl can
1842fork.  Do not use this, use the portable check for
1843$Config::Config{dfork}.
1844
1845=item $OS2::nsyserror
1846
1847This variable (default is 1) controls whether to enforce the contents
1848of $^E to start with C<SYS0003>-like id.  If set to 0, then the string
1849value of $^E is what is available from the OS/2 message file.  (Some
1850messages in this file have an C<SYS0003>-like id prepended, some not.)
1851
1852=back
1853
1854=head2 Misfeatures
1855
1856=over 4
1857
1858=item *
1859
1860Since L<flock(3)> is present in EMX, but is not functional, it is
1861emulated by perl.  To disable the emulations, set environment variable
1862C<USE_PERL_FLOCK=0>.
1863
1864=item *
1865
1866Here is the list of things which may be "broken" on
1867EMX (from EMX docs):
1868
1869=over 4
1870
1871=item *
1872
1873The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
1874implemented.
1875
1876=item *
1877
1878L<sock_init(3)> is not required and not implemented.
1879
1880=item *
1881
1882L<flock(3)> is not yet implemented (dummy function).  (Perl has a workaround.)
1883
1884=item *
1885
1886L<kill(3)>:  Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1887
1888=item *
1889
1890L<waitpid(3)>:
1891
1892      WUNTRACED
1893	      Not implemented.
1894      waitpid() is not implemented for negative values of PID.
1895
1896=back
1897
1898Note that C<kill -9> does not work with the current version of EMX.
1899
1900=item *
1901
1902See L</"Text-mode filehandles">.
1903
1904=item *
1905
1906Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
1907To avoid a failure to create a socket with a name of a different form,
1908C<"/socket/"> is prepended to the socket name (unless it starts with this
1909already).
1910
1911This may lead to problems later in case the socket is accessed via the
1912"usual" file-system calls using the "initial" name.
1913
1914=item *
1915
1916Apparently, IBM used a compiler (for some period of time around '95?) which
1917changes FP mask right and left.  This is not I<that> bad for IBM's
1918programs, but the same compiler was used for DLLs which are used with
1919general-purpose applications.  When these DLLs are used, the state of
1920floating-point flags in the application is not predictable.
1921
1922What is much worse, some DLLs change the floating point flags when in
1923_DLLInitTerm() (e.g., F<TCP32IP>).  This means that even if you do not I<call>
1924any function in the DLL, just the act of loading this DLL will reset your
1925flags.  What is worse, the same compiler was used to compile some HOOK DLLs.
1926Given that HOOK dlls are executed in the context of I<all> the applications
1927in the system, this means a complete unpredictability of floating point
1928flags on systems using such HOOK DLLs.  E.g., F<GAMESRVR.DLL> of B<DIVE>
1929origin changes the floating point flags on each write to the TTY of a VIO
1930(windowed text-mode) applications.
1931
1932Some other (not completely debugged) situations when FP flags change include
1933some video drivers (?), and some operations related to creation of the windows.
1934People who code B<OpenGL> may have more experience on this.
1935
1936Perl is generally used in the situation when all the floating-point
1937exceptions are ignored, as is the default under EMX.  If they are not ignored,
1938some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
1939
1940To circumvent this, Perl uses two hacks.  They help against I<one> type of
1941damage only: FP flags changed when loading a DLL.
1942
1943One of the hacks is to disable floating point exceptions on Perl startup (as
1944is the default with EMX).  This helps only with compile-time-linked DLLs
1945changing the flags before main() had a chance to be called.
1946
1947The other hack is to restore FP flags after a call to dlopen().  This helps
1948against similar damage done by DLLs _DLLInitTerm() at runtime.  Currently
1949no way to switch these hacks off is provided.
1950
1951=back
1952
1953=head2 Modifications
1954
1955Perl modifies some standard C library calls in the following ways:
1956
1957=over 9
1958
1959=item C<popen>
1960
1961C<my_popen> uses F<sh.exe> if shell is required, cf. L</"C<PERL_SH_DIR>">.
1962
1963=item C<tmpnam>
1964
1965is created using C<TMP> or C<TEMP> environment variable, via
1966C<tempnam>.
1967
1968=item C<tmpfile>
1969
1970If the current directory is not writable, file is created using modified
1971C<tmpnam>, so there may be a race condition.
1972
1973=item C<ctermid>
1974
1975a dummy implementation.
1976
1977=item C<stat>
1978
1979C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1980
1981=item C<mkdir>, C<rmdir>
1982
1983these EMX functions do not work if the path contains a trailing C</>.
1984Perl contains a workaround for this.
1985
1986=item C<flock>
1987
1988Since L<flock(3)> is present in EMX, but is not functional, it is
1989emulated by perl.  To disable the emulations, set environment variable
1990C<USE_PERL_FLOCK=0>.
1991
1992=back
1993
1994=head2 Identifying DLLs
1995
1996All the DLLs built with the current versions of Perl have ID strings
1997identifying the name of the extension, its version, and the version
1998of Perl required for this DLL.  Run C<bldlevel DLL-name> to find this
1999info.
2000
2001=head2 Centralized management of resources
2002
2003Since to call certain OS/2 API one needs to have a correctly initialized
2004C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
2005C<HMQ>s.  If an extension would do it on its own, another extension could
2006fail to initialize.
2007
2008Perl provides a centralized management of these resources:
2009
2010=over
2011
2012=item C<HAB>
2013
2014To get the HAB, the extension should call C<hab = perl_hab_GET()> in C.  After
2015this call is performed, C<hab> may be accessed as C<Perl_hab>.  There is
2016no need to release the HAB after it is used.
2017
2018If by some reasons F<perl.h> cannot be included, use
2019
2020  extern int Perl_hab_GET(void);
2021
2022instead.
2023
2024=item C<HMQ>
2025
2026There are two cases:
2027
2028=over
2029
2030=item *
2031
2032the extension needs an C<HMQ> only because some API will not work otherwise.
2033Use C<serve = 0> below.
2034
2035=item *
2036
2037the extension needs an C<HMQ> since it wants to engage in a PM event loop.
2038Use C<serve = 1> below.
2039
2040=back
2041
2042To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
2043After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
2044
2045To signal to Perl that HMQ is not needed any more, call
2046C<perl_hmq_UNSET(serve)>.  Perl process will automatically morph/unmorph itself
2047into/from a PM process if HMQ is needed/not-needed.  Perl will automatically
2048enable/disable C<WM_QUIT> message during shutdown if the message queue is
2049served/not-served.
2050
2051B<NOTE>.  If during a shutdown there is a message queue which did not disable
2052WM_QUIT, and which did not process the received WM_QUIT message, the
2053shutdown will be automatically cancelled.  Do not call C<perl_hmq_GET(1)>
2054unless you are going to process messages on an orderly basis.
2055
2056=item Treating errors reported by OS/2 API
2057
2058There are two principal conventions (it is useful to call them C<Dos*>
2059and C<Win*> - though this part of the function signature is not always
2060determined by the name of the API) of reporting the error conditions
2061of OS/2 API.  Most of C<Dos*> APIs report the error code as the result
2062of the call (so 0 means success, and there are many types of errors).
2063Most of C<Win*> API report success/fail via the result being
2064C<TRUE>/C<FALSE>; to find the reason for the failure one should call
2065WinGetLastError() API.
2066
2067Some C<Win*> entry points also overload a "meaningful" return value
2068with the error indicator; having a 0 return value indicates an error.
2069Yet some other C<Win*> entry points overload things even more, and 0
2070return value may mean a successful call returning a valid value 0, as
2071well as an error condition; in the case of a 0 return value one should
2072call WinGetLastError() API to distinguish a successful call from a
2073failing one.
2074
2075By convention, all the calls to OS/2 API should indicate their
2076failures by resetting $^E.  All the Perl-accessible functions which
2077call OS/2 API may be broken into two classes: some die()s when an API
2078error is encountered, the other report the error via a false return
2079value (of course, this does not concern Perl-accessible functions
2080which I<expect> a failure of the OS/2 API call, having some workarounds
2081coded).
2082
2083Obviously, in the situation of the last type of the signature of an OS/2
2084API, it is must more convenient for the users if the failure is
2085indicated by die()ing: one does not need to check $^E to know that
2086something went wrong.  If, however, this solution is not desirable by
2087some reason, the code in question should reset $^E to 0 before making
2088this OS/2 API call, so that the caller of this Perl-accessible
2089function has a chance to distinguish a success-but-0-return value from
2090a failure.  (One may return undef as an alternative way of reporting
2091an error.)
2092
2093The macros to simplify this type of error propagation are
2094
2095=over
2096
2097=item C<CheckOSError(expr)>
2098
2099Returns true on error, sets $^E.  Expects expr() be a call of
2100C<Dos*>-style API.
2101
2102=item C<CheckWinError(expr)>
2103
2104Returns true on error, sets $^E.  Expects expr() be a call of
2105C<Win*>-style API.
2106
2107=item C<SaveWinError(expr)>
2108
2109Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false.
2110
2111=item C<SaveCroakWinError(expr,die,name1,name2)>
2112
2113Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false,
2114and die()s if C<die> and $^E are true.  The message to die is the
2115concatenated strings C<name1> and C<name2>, separated by C<": "> from
2116the contents of $^E.
2117
2118=item C<WinError_2_Perl_rc>
2119
2120Sets C<Perl_rc> to the return value of WinGetLastError().
2121
2122=item C<FillWinError>
2123
2124Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E
2125to the corresponding value.
2126
2127=item C<FillOSError(rc)>
2128
2129Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value.
2130
2131=back
2132
2133=item Loading DLLs and ordinals in DLLs
2134
2135Some DLLs are only present in some versions of OS/2, or in some
2136configurations of OS/2.  Some exported entry points are present only
2137in DLLs shipped with some versions of OS/2.  If these DLLs and entry
2138points were linked directly for a Perl executable/DLL or from a Perl
2139extensions, this binary would work only with the specified
2140versions/setups.  Even if these entry points were not needed, the
2141I<load> of the executable (or DLL) would fail.
2142
2143For example, many newer useful APIs are not present in OS/2 v2; many
2144PM-related APIs require DLLs not available on floppy-boot setup.
2145
2146To make these calls fail I<only when the calls are executed>, one
2147should call these API via a dynamic linking API.  There is a subsystem
2148in Perl to simplify such type of calls.  A large number of entry
2149points available for such linking is provided (see C<entries_ordinals>
2150- and also C<PMWIN_entries> - in F<os2ish.h>).  These ordinals can be
2151accessed via the APIs:
2152
2153 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
2154 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
2155 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
2156 DeclWinFuncByORD_CACHE_resetError_survive(),
2157 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
2158 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
2159
2160See the header files and the C code in the supplied OS/2-related
2161modules for the details on usage of these functions.
2162
2163Some of these functions also combine dynaloading semantic with the
2164error-propagation semantic discussed above.
2165
2166=back
2167
2168=head1 Perl flavors
2169
2170Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
2171same basket (though EMX environment tries hard to overcome this
2172limitations, so the situation may somehow improve). There are 4
2173executables for Perl provided by the distribution:
2174
2175=head2 F<perl.exe>
2176
2177The main workhorse. This is a chimera executable: it is compiled as an
2178C<a.out>-style executable, but is linked with C<omf>-style dynamic
2179library F<perl.dll>, and with dynamic CRT DLL. This executable is a
2180VIO application.
2181
2182It can load perl dynamic extensions, and it can fork().
2183
2184B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
2185
2186=head2 F<perl_.exe>
2187
2188This is a statically linked C<a.out>-style executable. It cannot
2189load dynamic Perl extensions. The executable supplied in binary
2190distributions has a lot of extensions prebuilt, thus the above restriction is
2191important only if you use custom-built extensions. This executable is a VIO
2192application.
2193
2194I<This is the only executable with does not require OS/2.> The
2195friends locked into C<M$> world would appreciate the fact that this
2196executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
2197appropriate extender. See L</"Other OSes">.
2198
2199=head2 F<perl__.exe>
2200
2201This is the same executable as F<perl___.exe>, but it is a PM
2202application.
2203
2204B<Note.> Usually (unless explicitly redirected during the startup)
2205STDIN, STDERR, and STDOUT of a PM
2206application are redirected to F<nul>. However, it is possible to I<see>
2207them if you start C<perl__.exe> from a PM program which emulates a
2208console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
2209possible> to use Perl debugger (see L<perldebug>) to debug your PM
2210application (but beware of the message loop lockups - this will not
2211work if you have a message queue to serve, unless you hook the serving
2212into the getc() function of the debugger).
2213
2214Another way to see the output of a PM program is to run it as
2215
2216  pm_prog args 2>&1 | cat -
2217
2218with a shell I<different> from F<cmd.exe>, so that it does not create
2219a link between a VIO session and the session of C<pm_porg>.  (Such a link
2220closes the VIO window.)  E.g., this works with F<sh.exe> - or with Perl!
2221
2222  open P, 'pm_prog args 2>&1 |' or die;
2223  print while <P>;
2224
2225The flavor F<perl__.exe> is required if you want to start your program without
2226a VIO window present, but not C<detach>ed (run C<help detach> for more info).
2227Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
2228
2229Note also that the differences between PM and VIO executables are only
2230in the I<default> behaviour.  One can start I<any> executable in
2231I<any> kind of session by using the arguments C</fs>, C</pm> or
2232C</win> switches of the command C<start> (of F<CMD.EXE> or a similar
2233shell).  Alternatively, one can use the numeric first argument of the
2234C<system> Perl function (see L<OS2::Process>).
2235
2236=head2 F<perl___.exe>
2237
2238This is an C<omf>-style executable which is dynamically linked to
2239F<perl.dll> and CRT DLL. I know no advantages of this executable
2240over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
2241that the build process is not so convoluted as with C<perl.exe>.
2242
2243It is a VIO application.
2244
2245=head2 Why strange names?
2246
2247Since Perl processes the C<#!>-line (cf.
2248L<perlrun/DESCRIPTION>, L<perlrun/Command Switches>,
2249L<perldiag/"No Perl script found in input">), it should know when a
2250program I<is a Perl>. There is some naming convention which allows
2251Perl to distinguish correct lines from wrong ones. The above names are
2252almost the only names allowed by this convention which do not contain
2253digits (which have absolutely different semantics).
2254
2255=head2 Why dynamic linking?
2256
2257Well, having several executables dynamically linked to the same huge
2258library has its advantages, but this would not substantiate the
2259additional work to make it compile. The reason is the complicated-to-developers
2260but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
2261
2262There are two distinctive features of the dyna-linking model of OS/2:
2263first, all the references to external functions are resolved at the compile time;
2264second, there is no runtime fixup of the DLLs after they are loaded into memory.
2265The first feature is an enormous advantage over other models: it avoids
2266conflicts when several DLLs used by an application export entries with
2267the same name.  In such cases "other" models of dyna-linking just choose
2268between these two entry points using some random criterion - with predictable
2269disasters as results.  But it is the second feature which requires the build
2270of F<perl.dll>.
2271
2272The address tables of DLLs are patched only once, when they are
2273loaded. The addresses of the entry points into DLLs are guaranteed to be
2274the same for all the programs which use the same DLL.  This removes the
2275runtime fixup - once DLL is loaded, its code is read-only.
2276
2277While this allows some (significant?) performance advantages, this makes life
2278much harder for developers, since the above scheme makes it impossible
2279for a DLL to be "linked" to a symbol in the F<.EXE> file.  Indeed, this
2280would need a DLL to have different relocations tables for the
2281(different) executables which use this DLL.
2282
2283However, a dynamically loaded Perl extension is forced to use some symbols
2284from the perl
2285executable, e.g., to know how to find the arguments to the functions:
2286the arguments live on the perl
2287internal evaluation stack. The solution is to put the main code of
2288the interpreter into a DLL, and make the F<.EXE> file which just loads
2289this DLL into memory and supplies command-arguments.  The extension DLL
2290cannot link to symbols in F<.EXE>, but it has no problem linking
2291to symbols in the F<.DLL>.
2292
2293This I<greatly> increases the load time for the application (as well as
2294complexity of the compilation). Since interpreter is in a DLL,
2295the C RTL is basically forced to reside in a DLL as well (otherwise
2296extensions would not be able to use CRT).  There are some advantages if
2297you use different flavors of perl, such as running F<perl.exe> and
2298F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
2299
2300B<NOTE>.  There is one additional effect which makes DLLs more wasteful:
2301DLLs are loaded in the shared memory region, which is a scarse resource
2302given the 512M barrier of the "standard" OS/2 virtual memory.  The code of
2303F<.EXE> files is also shared by all the processes which use the particular
2304F<.EXE>, but they are "shared in the private address space of the process";
2305this is possible because the address at which different sections
2306of the F<.EXE> file are loaded is decided at compile-time, thus all the
2307processes have these sections loaded at same addresses, and no fixup
2308of internal links inside the F<.EXE> is needed.
2309
2310Since DLLs may be loaded at run time, to have the same mechanism for DLLs
2311one needs to have the address range of I<any of the loaded> DLLs in the
2312system to be available I<in all the processes> which did not load a particular
2313DLL yet.  This is why the DLLs are mapped to the shared memory region.
2314
2315=head2 Why chimera build?
2316
2317Current EMX environment does not allow DLLs compiled using Unixish
2318C<a.out> format to export symbols for data (or at least some types of
2319data). This forces C<omf>-style compile of F<perl.dll>.
2320
2321Current EMX environment does not allow F<.EXE> files compiled in
2322C<omf> format to fork(). fork() is needed for exactly three Perl
2323operations:
2324
2325=over 4
2326
2327=item *
2328
2329explicit fork() in the script,
2330
2331=item *
2332
2333C<open FH, "|-">
2334
2335=item *
2336
2337C<open FH, "-|">, in other words, opening pipes to itself.
2338
2339=back
2340
2341While these operations are not questions of life and death, they are
2342needed for a lot of
2343useful scripts. This forces C<a.out>-style compile of
2344F<perl.exe>.
2345
2346
2347=head1 ENVIRONMENT
2348
2349Here we list environment variables with are either OS/2- and DOS- and
2350Win*-specific, or are more important under OS/2 than under other OSes.
2351
2352=head2 C<PERLLIB_PREFIX>
2353
2354Specific for EMX port. Should have the form
2355
2356  path1;path2
2357
2358or
2359
2360  path1 path2
2361
2362If the beginning of some prebuilt path matches F<path1>, it is
2363substituted with F<path2>.
2364
2365Should be used if the perl library is moved from the default
2366location in preference to C<PERL(5)LIB>, since this would not leave wrong
2367entries in @INC.  For example, if the compiled version of perl looks for @INC
2368in F<f:/perllib/lib>, and you want to install the library in
2369F<h:/opt/gnu>, do
2370
2371  set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
2372
2373This will cause Perl with the prebuilt @INC of
2374
2375  f:/perllib/lib/5.00553/os2
2376  f:/perllib/lib/5.00553
2377  f:/perllib/lib/site_perl/5.00553/os2
2378  f:/perllib/lib/site_perl/5.00553
2379  .
2380
2381to use the following @INC:
2382
2383  h:/opt/gnu/5.00553/os2
2384  h:/opt/gnu/5.00553
2385  h:/opt/gnu/site_perl/5.00553/os2
2386  h:/opt/gnu/site_perl/5.00553
2387  .
2388
2389=head2 C<PERL_BADLANG>
2390
2391If 0, perl ignores setlocale() failing. May be useful with some
2392strange I<locale>s.
2393
2394=head2 C<PERL_BADFREE>
2395
2396If 0, perl would not warn of in case of unwarranted free(). With older
2397perls this might be
2398useful in conjunction with the module DB_File, which was buggy when
2399dynamically linked and OMF-built.
2400
2401Should not be set with newer Perls, since this may hide some I<real> problems.
2402
2403=head2 C<PERL_SH_DIR>
2404
2405Specific for EMX port. Gives the directory part of the location for
2406F<sh.exe>.
2407
2408=head2 C<USE_PERL_FLOCK>
2409
2410Specific for EMX port. Since L<flock(3)> is present in EMX, but is not
2411functional, it is emulated by perl.  To disable the emulations, set
2412environment variable C<USE_PERL_FLOCK=0>.
2413
2414=head2 C<TMP> or C<TEMP>
2415
2416Specific for EMX port. Used as storage place for temporary files.
2417
2418=head1 Evolution
2419
2420Here we list major changes which could make you by surprise.
2421
2422=head2 Text-mode filehandles
2423
2424Starting from version 5.8, Perl uses a builtin translation layer for
2425text-mode files.  This replaces the efficient well-tested EMX layer by
2426some code which should be best characterized as a "quick hack".
2427
2428In addition to possible bugs and an inability to follow changes to the
2429translation policy with off/on switches of TERMIO translation, this
2430introduces a serious incompatible change: before sysread() on
2431text-mode filehandles would go through the translation layer, now it
2432would not.
2433
2434=head2 Priorities
2435
2436C<setpriority> and C<getpriority> are not compatible with earlier
2437ports by Andreas Kaiser. See C<"setpriority, getpriority">.
2438
2439=head2 DLL name mangling: pre 5.6.2
2440
2441With the release 5.003_01 the dynamically loadable libraries
2442should be rebuilt when a different version of Perl is compiled. In particular,
2443DLLs (including F<perl.dll>) are now created with the names
2444which contain a checksum, thus allowing workaround for OS/2 scheme of
2445caching DLLs.
2446
2447It may be possible to code a simple workaround which would
2448
2449=over
2450
2451=item *
2452
2453find the old DLLs looking through the old @INC;
2454
2455=item *
2456
2457mangle the names according to the scheme of new perl and copy the DLLs to
2458these names;
2459
2460=item *
2461
2462edit the internal C<LX> tables of DLL to reflect the change of the name
2463(probably not needed for Perl extension DLLs, since the internally coded names
2464are not used for "specific" DLLs, they used only for "global" DLLs).
2465
2466=item *
2467
2468edit the internal C<IMPORT> tables and change the name of the "old"
2469F<perl????.dll> to the "new" F<perl????.dll>.
2470
2471=back
2472
2473=head2 DLL name mangling: 5.6.2 and beyond
2474
2475In fact mangling of I<extension> DLLs was done due to misunderstanding
2476of the OS/2 dynaloading model.  OS/2 (effectively) maintains two
2477different tables of loaded DLL:
2478
2479=over
2480
2481=item Global DLLs
2482
2483those loaded by the base name from C<LIBPATH>; including those
2484associated at link time;
2485
2486=item specific DLLs
2487
2488loaded by the full name.
2489
2490=back
2491
2492When resolving a request for a global DLL, the table of already-loaded
2493specific DLLs is (effectively) ignored; moreover, specific DLLs are
2494I<always> loaded from the prescribed path.
2495
2496There is/was a minor twist which makes this scheme fragile: what to do
2497with DLLs loaded from
2498
2499=over
2500
2501=item C<BEGINLIBPATH> and C<ENDLIBPATH>
2502
2503(which depend on the process)
2504
2505=item F<.> from C<LIBPATH>
2506
2507which I<effectively> depends on the process (although C<LIBPATH> is the
2508same for all the processes).
2509
2510=back
2511
2512Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
25132000/09/01), such DLLs are considered to be global.  When loading a
2514global DLL it is first looked in the table of already-loaded global
2515DLLs.  Because of this the fact that one executable loaded a DLL from
2516C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
2517I<which> DLL is loaded when I<another> executable requests a DLL with
2518the same name.  I<This> is the reason for version-specific mangling of
2519the DLL name for perl DLL.
2520
2521Since the Perl extension DLLs are always loaded with the full path,
2522there is no need to mangle their names in a version-specific ways:
2523their directory already reflects the corresponding version of perl,
2524and @INC takes into account binary compatibility with older version.
2525Starting from C<5.6.2> the name mangling scheme is fixed to be the
2526same as for Perl 5.005_53 (same as in a popular binary release).  Thus
2527new Perls will be able to I<resolve the names> of old extension DLLs
2528if @INC allows finding their directories.
2529
2530However, this still does not guarantee that these DLL may be loaded.
2531The reason is the mangling of the name of the I<Perl DLL>.  And since
2532the extension DLLs link with the Perl DLL, extension DLLs for older
2533versions would load an older Perl DLL, and would most probably
2534segfault (since the data in this DLL is not properly initialized).
2535
2536There is a partial workaround (which can be made complete with newer
2537OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2538the older version of Perl, which forwards the entry points to the
2539newer Perl's DLL.  Make this DLL accessible on (say) the C<BEGINLIBPATH> of
2540the new Perl executable.  When the new executable accesses old Perl's
2541extension DLLs, they would request the old Perl's DLL by name, get the
2542forwarder instead, so effectively will link with the currently running
2543(new) Perl DLL.
2544
2545This may break in two ways:
2546
2547=over
2548
2549=item *
2550
2551Old perl executable is started when a new executable is running has
2552loaded an extension compiled for the old executable (ouph!).  In this
2553case the old executable will get a forwarder DLL instead of the old
2554perl DLL, so would link with the new perl DLL.  While not directly
2555fatal, it will behave the same as new executable.  This beats the whole
2556purpose of explicitly starting an old executable.
2557
2558=item *
2559
2560A new executable loads an extension compiled for the old executable
2561when an old perl executable is running.  In this case the extension
2562will not pick up the forwarder - with fatal results.
2563
2564=back
2565
2566With support for C<LIBPATHSTRICT> this may be circumvented - unless
2567one of DLLs is started from F<.> from C<LIBPATH> (I do not know
2568whether C<LIBPATHSTRICT> affects this case).
2569
2570B<REMARK>.  Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
2571do not), this mess cannot be completely cleaned.  (It turns out that
2572as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and
2573it has the same effect.)
2574
2575
2576B<REMARK>.  C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
2577not environment variables, although F<cmd.exe> emulates them on C<SET
2578...> lines.  From Perl they may be accessed by
2579L<Cwd::extLibpath|/Cwd::extLibpath([type])> and
2580L<Cwd::extLibpath_set|/Cwd::extLibpath_set( path [, type ] )>.
2581
2582=head2 DLL forwarder generation
2583
2584Assume that the old DLL is named F<perlE0AC.dll> (as is one for
25855.005_53), and the new version is 5.6.1.  Create a file
2586F<perl5shim.def-leader> with
2587
2588  LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2589  DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2590  CODE LOADONCALL
2591  DATA LOADONCALL NONSHARED MULTIPLE
2592  EXPORTS
2593
2594modifying the versions/names as needed.  Run
2595
2596 perl -wnle "next if 0../EXPORTS/; print qq(  \"$1\")
2597                                          if /\"(\w+)\"/" perl5.def >lst
2598
2599in the Perl build directory (to make the DLL smaller replace perl5.def
2600with the definition file for the older version of Perl if present).
2601
2602 cat perl5shim.def-leader lst >perl5shim.def
2603 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2604
2605(ignore multiple C<warning L4085>).
2606
2607=head2 Threading
2608
2609As of release 5.003_01 perl is linked to multithreaded C RTL
2610DLL.  If perl itself is not compiled multithread-enabled, so will not be perl's
2611malloc(). However, extensions may use multiple thread on their own
2612risk.
2613
2614This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
2615link with DLLs for other useful libraries, which typically are compiled
2616with C<-Zmt -Zcrtdll>.
2617
2618=head2 Calls to external programs
2619
2620Due to a popular demand the perl external program calling has been
2621changed wrt Andreas Kaiser's port.  I<If> perl needs to call an
2622external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
2623whatever is the override, see L</"C<PERL_SH_DIR>">.
2624
2625Thus means that you need to get some copy of a F<sh.exe> as well (I
2626use one from pdksh). The path F<F:/bin> above is set up automatically during
2627the build to a correct value on the builder machine, but is
2628overridable at runtime,
2629
2630B<Reasons:> a consensus on C<perl5-porters> was that perl should use
2631one non-overridable shell per platform. The obvious choices for OS/2
2632are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
2633with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
2634100% compatibility with the scripts coming from *nix. As an added benefit
2635this works as well under DOS if you use DOS-enabled port of pdksh
2636(see L</Prerequisites>).
2637
2638B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
2639via fork()/exec(), and there is I<no> functioning exec() on
2640OS/2. exec() is emulated by EMX by an asynchronous call while the caller
2641waits for child completion (to pretend that the C<pid> did not change). This
2642means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
2643which may lead to some resources taken from the system (even if we do
2644not count extra work needed for fork()ing).
2645
2646Note that this a lesser issue now when we do not spawn F<sh.exe>
2647unless needed (metachars found).
2648
2649One can always start F<cmd.exe> explicitly via
2650
2651  system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2652
2653If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
2654scripts, the long-term solution proposed on p5-p is to have a directive
2655
2656  use OS2::Cmd;
2657
2658which will override system(), exec(), C<``>, and
2659C<open(,'...|')>. With current perl you may override only system(),
2660readpipe() - the explicit version of C<``>, and maybe exec(). The code
2661will substitute the one-argument call to system() by
2662C<CORE::system('cmd.exe', '/c', shift)>.
2663
2664If you have some working code for C<OS2::Cmd>, please send it to me,
2665I will include it into distribution. I have no need for such a module, so
2666cannot test it.
2667
2668For the details of the current situation with calling external programs,
2669see L</Starting OSE<sol>2 (and DOS) programs under Perl>.  Set us
2670mention a couple of features:
2671
2672=over 4
2673
2674=item *
2675
2676External scripts may be called by their basename.  Perl will try the same
2677extensions as when processing B<-S> command-line switch.
2678
2679=item *
2680
2681External scripts starting with C<#!> or C<extproc > will be executed directly,
2682without calling the shell, by calling the program specified on the rest of
2683the first line.
2684
2685=back
2686
2687=head2 Memory allocation
2688
2689Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
2690for speed, but perl is not, since its malloc is lightning-fast.
2691Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
2692than EMX one.  I do not have convincing data about memory footprint, but
2693a (pretty random) benchmark showed that Perl's one is 5% better.
2694
2695Combination of perl's malloc() and rigid DLL name resolution creates
2696a special problem with library functions which expect their return value to
2697be free()d by system's free(). To facilitate extensions which need to call
2698such functions, system memory-allocation functions are still available with
2699the prefix C<emx_> added. (Currently only DLL perl has this, it should
2700propagate to F<perl_.exe> shortly.)
2701
2702=head2 Threads
2703
2704One can build perl with thread support enabled by providing C<-D usethreads>
2705option to F<Configure>.  Currently OS/2 support of threads is very
2706preliminary.
2707
2708Most notable problems:
2709
2710=over 4
2711
2712=item C<COND_WAIT>
2713
2714may have a race condition (but probably does not due to edge-triggered
2715nature of OS/2 Event semaphores).  (Needs a reimplementation (in terms of chaining
2716waiting threads, with the linked list stored in per-thread structure?)?)
2717
2718=item F<os2.c>
2719
2720has a couple of static variables used in OS/2-specific functions.  (Need to be
2721moved to per-thread structure, or serialized?)
2722
2723=back
2724
2725Note that these problems should not discourage experimenting, since they
2726have a low probability of affecting small programs.
2727
2728=head1 BUGS
2729
2730This description is not updated often (since 5.6.1?), see F<./os2/Changes>
2731for more info.
2732
2733=cut
2734
2735OS/2 extensions
2736~~~~~~~~~~~~~~~
2737I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
2738into my ftp directory, mirrored on CPAN. I made
2739some minor changes needed to compile them by standard tools. I cannot
2740test UPM and FTP, so I will appreciate your feedback. Other extensions
2741there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
2742files - and maybe some other extensions at the time you read it.
2743
2744Note that OS2 perl defines 2 pseudo-extension functions
2745OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
2746L</Prebuilt methods>).
2747
2748The -R switch of older perl is deprecated. If you need to call a REXX code
2749which needs access to variables, include the call into a REXX compartment
2750created by
2751	REXX_call {...block...};
2752
2753Two new functions are supported by REXX code,
2754	REXX_eval 'string';
2755	REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
2756
2757If you have some other extensions you want to share, send the code to
2758me.  At least two are available: tied access to EA's, and tied access
2759to system databases.
2760
2761=head1 AUTHOR
2762
2763Ilya Zakharevich, cpan@ilyaz.org
2764
2765=head1 SEE ALSO
2766
2767perl(1).
2768
2769=cut
2770
2771

README.os390

1This document is written in pod format hence there are punctuation
2characters in odd places.  Do not worry, you have 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 submit comments to L<https://github.com/Perl/perl5/issues>.>
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 have 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.
32L<http://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 did not 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 have 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=head3 Shell
123
124A message of the form:
125
126 (I see you are using the Korn shell.  Some ksh's blow up on Configure,
127 mainly on older exotic systems.  If yours does, try the Bourne shell instead.)
128
129is nothing to worry about at all.
130
131=head3 Samples
132
133Some of the parser default template files in /samples are needed in /etc.
134In particular be sure that you at least copy /samples/yyparse.c to /etc
135before running Perl's Configure.  This step ensures successful extraction
136of EBCDIC versions of parser files such as perly.c and perly.h.
137This has to be done before running Configure the first time.  If you failed
138to do so then the easiest way to re-Configure Perl is to delete your
139misconfigured build root and re-extract the source from the tar ball.
140Then you must ensure that /etc/yyparse.c is properly in place before
141attempting to re-run Configure.
142
143=head3 Dynamic loading
144
145Dynamic loading is required if you want to use XS modules from CPAN (like
146DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from
147CPAN with newer versions (like Encode) without rebuilding all of the perl
148binary.
149
150This port will support dynamic loading, but it is not selected by
151default.  If you would like to experiment with dynamic loading then
152be sure to specify -Dusedl in the arguments to the Configure script.
153See the comments in hints/os390.sh for more information on dynamic loading.
154If you build with dynamic loading then you will need to add the
155$archlibexp/CORE directory to your LIBPATH environment variable in order
156for perl to work.  See the config.sh file for the value of $archlibexp.
157If in trying to use Perl you see an error message similar to:
158
159 CEE3501S The module libperl.dll was not found.
160   From entry point __dllstaticinit at compile unit offset +00000194
161   at
162
163then your LIBPATH does not have the location of libperl.x and either
164libperl.dll or libperl.so in it.  Add that directory to your LIBPATH and
165proceed.
166
167In hints/os390.sh, selecting -Dusedl will default to *also* select
168-Duseshrplib.  Having a shared plib not only requires LIBPATH to be set to
169the correct location of libperl.so but also makes it close to impossible
170to run more than one different perl that was built this way at the same
171time.
172
173All objects that are involved in -Dusedl builds should be compiled for
174this, probably by adding to all ccflags
175
176 -qexportall -qxplink -qdll -Wc,XPLINK,dll,EXPORTALL -Wl,XPLINK,dll
177
178=head3 Optimizing
179
180Do not turn on the compiler optimization flag "-O".  There is
181a bug in either the optimizer or perl that causes perl to
182not work correctly when the optimizer is on.
183
184=head3 Config files
185
186Some of the configuration files in /etc used by the
187networking APIs are either missing or have the wrong
188names.  In particular, make sure that there's either
189an /etc/resolv.conf or an /etc/hosts, so that
190gethostbyname() works, and make sure that the file
191/etc/proto has been renamed to /etc/protocol (NOT
192/etc/protocols, as used by other Unix systems).
193You may have to look for things like HOSTNAME and DOMAINORIGIN
194in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to
195properly set up your /etc networking files.
196
197=head2 Build, Test, Install Perl on OS/390
198
199Simply put:
200
201    sh Configure
202    make
203    make test
204
205if everything looks ok (see the next section for test/IVP diagnosis) then:
206
207    make install
208
209this last step may or may not require UID=0 privileges depending
210on how you answered the questions that Configure asked and whether
211or not you have write access to the directories you specified.
212
213=head2 Build Anomalies with Perl on OS/390
214
215"Out of memory!" messages during the build of Perl are most often fixed
216by re building the GNU make utility for OS/390 from a source code kit.
217
218Building debugging-enabled binaries (with -g or -g3) will increase the
219chance of getting these errors. Prevent -g if possible.
220
221Another memory limiting item to check is your MAXASSIZE parameter in your
222'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space
223limits can be set on a per user ID basis in the USS segment of a RACF
224profile).  People have reported successful builds of Perl with MAXASSIZE
225parameters as small as 503316480 (and it may be possible to build Perl
226with a MAXASSIZE smaller than that).
227
228Within USS your /etc/profile or $HOME/.profile may limit your ulimit
229settings.  Check that the following command returns reasonable values:
230
231    ulimit -a
232
233To conserve memory you should have your compiler modules loaded into the
234Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
235
236If the c89 compiler complains of syntax errors during the build of the
237Socket extension then be sure to fix the syntax error in the system
238header /usr/include/sys/socket.h.
239
240=head2 Testing Anomalies with Perl on OS/390
241
242The "make test" step runs a Perl Verification Procedure, usually before
243installation.  You might encounter STDERR messages even during a successful
244run of "make test".  Here is a guide to some of the more commonly seen
245anomalies:
246
247=head3 Signals
248
249A message of the form:
250
251 io/openpid...........CEE5210S The signal SIGHUP was received.
252 CEE5210S The signal SIGHUP was received.
253 CEE5210S The signal SIGHUP was received.
254 ok
255
256indicates that the t/io/openpid.t test of Perl has passed but done so
257with extraneous messages on stderr from CEE.
258
259=head3 File::Temp
260
261A message of the form:
262
263 lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/)
264 is not safe (sticky bit not set when world writable?) at
265 lib/ftmp-security.t line 100
266 File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky
267 bit not set when world writable?) at lib/ftmp-security.t line 100
268 ok
269
270indicates a problem with the permissions on your /tmp directory within the HFS.
271To correct that problem issue the command:
272
273    chmod a+t /tmp
274
275from an account with write access to the directory entry for /tmp.
276
277=head3 Out of Memory!
278
279Recent perl test suite is quite memory hungry. In addition to the comments
280above on memory limitations it is also worth checking for _CEE_RUNOPTS
281in your environment. Perl now has (in miniperlmain.c) a C #pragma
282to set CEE run options, but the environment variable wins.
283
284The C code asks for:
285
286 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
287
288The important parts of that are the second argument (the increment) to HEAP,
289and allowing the stack to be "Above the (16M) line". If the heap
290increment is too small then when perl (for example loading unicode/Name.pl) tries
291to create a "big" (400K+) string it cannot fit in a single segment
292and you get "Out of Memory!" - even if there is still plenty of memory
293available.
294
295A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
296to get memory, and C<sbrk()> is limited to the first allocation so in this
297case something like:
298
299  HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
300
301is needed to get through the test suite.
302
303=head2 Installation Anomalies with Perl on OS/390
304
305The installman script will try to run on OS/390.  There will be fewer errors
306if you have a roff utility installed.  You can obtain GNU groff from the
307Redbook SG24-5944-00 ftp site.
308
309=head2 Usage Hints for Perl on OS/390
310
311When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
312character sets are different.  See perlebcdic.pod for more on such character
313set issues.  Perl builtin functions that may behave differently under
314EBCDIC are also mentioned in the perlport.pod document.
315
316Open Edition (UNIX System Services) from V2R8 onward does support
317#!/path/to/perl script invocation.  There is a PTF available from
318IBM for V2R7 that will allow shell/kernel support for #!.  USS
319releases prior to V2R7 did not support the #! means of script invocation.
320If you are running V2R6 or earlier then see:
321
322    head `whence perldoc`
323
324for an example of how to use the "eval exec" trick to ask the shell to
325have Perl run your scripts on those older releases of Unix System Services.
326
327If you are having trouble with square brackets then consider switching your
328rlogin or telnet client.  Try to avoid older 3270 emulators and ISHELL for
329working with Perl on USS.
330
331=head2 Floating Point Anomalies with Perl on OS/390
332
333There appears to be a bug in the floating point implementation on S/390
334systems such that calling int() on the product of a number and a small
335magnitude number is not the same as calling int() on the quotient of
336that number and a large magnitude number.  For example, in the following
337Perl code:
338
339    my $x = 100000.0;
340    my $y = int($x * 1e-5) * 1e5; # '0'
341    my $z = int($x / 1e+5) * 1e5;  # '100000'
342    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
343
344Although one would expect the quantities $y and $z to be the same and equal
345to 100000 they will differ and instead will be 0 and 100000 respectively.
346
347The problem can be further examined in a roughly equivalent C program:
348
349    #include <stdio.h>
350    #include <math.h>
351    main()
352    {
353    double r1,r2;
354    double x = 100000.0;
355    double y = 0.0;
356    double z = 0.0;
357    x = 100000.0 * 1e-5;
358    r1 = modf (x,&y);
359    x = 100000.0 / 1e+5;
360    r2 = modf (x,&z);
361    printf("y is %e and z is %e\n",y*1e5,z*1e5);
362    /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
363    }
364
365=head2 Modules and Extensions for Perl on OS/390
366
367Pure Perl (that is non XS) modules may be installed via the usual:
368
369    perl Makefile.PL
370    make
371    make test
372    make install
373
374If you built perl with dynamic loading capability then that would also
375be the way to build XS based extensions.  However, if you built perl with
376the default static linking you can still build XS based extensions for OS/390
377but you will need to follow the instructions in ExtUtils::MakeMaker for
378building statically linked perl binaries.  In the simplest configurations
379building a static perl + XS extension boils down to:
380
381    perl Makefile.PL
382    make
383    make perl
384    make test
385    make install
386    make -f Makefile.aperl inst_perl MAP_TARGET=perl
387
388In most cases people have reported better results with GNU make rather
389than the system's /bin/make program, whether for plain modules or for
390XS based extensions.
391
392If the make process encounters trouble with either compilation or
393linking then try setting the _C89_CCMODE to 1.  Assuming sh is your
394login shell then run:
395
396    export _C89_CCMODE=1
397
398If tcsh is your login shell then use the setenv command.
399
400=head1 AUTHORS
401
402David Fiander and Peter Prymmer with thanks to Dennis Longnecker
403and William Raffloer for valuable reports, LPAR and PTF feedback.
404Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
405Thanks to Ignasi Roca for pointing out the floating point problems.
406Thanks to John Goodyear for dynamic loading help.
407
408=head1 SEE ALSO
409
410L<INSTALL>, L<perlport>, L<perlebcdic>, L<ExtUtils::MakeMaker>.
411
412 http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
413
414 http://www.redbooks.ibm.com/redbooks/SG245944.html
415
416 http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
417
418 http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
419
420 http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
421
422 http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/
423
424=head2 Mailing list for Perl on OS/390
425
426If you are interested in the z/OS (formerly known as OS/390)
427and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
428To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
429
430See also:
431
432    https://lists.perl.org/list/perl-mvs.html
433
434There are web archives of the mailing list at:
435
436    https://www.nntp.perl.org/group/perl.mvs/
437
438=head1 HISTORY
439
440This document was originally written by David Fiander for the 5.005
441release of Perl.
442
443This document was podified for the 5.005_03 release of Perl 11 March 1999.
444
445Updated 12 November 2000 for the 5.7.1 release of Perl.
446
447Updated 15 January  2001 for the 5.7.1 release of Perl.
448
449Updated 24 January  2001 to mention dynamic loading.
450
451Updated 12 March    2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
452
453Updated 28 November 2001 for broken URLs.
454
455Updated 03 October  2019 for perl-5.33.3+
456
457=cut
458
459

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 submit comments to L<https://github.com/Perl/perl5/issues>.>
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 generally 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
155Additionally, 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<dist/Tie-File/t/09_gen_rs.t> 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,
698   98.17% okay.
699
700The alarm() test failure is caused by system() apparently blocking
701alarm().  That is probably a libc bug, and given that SunOS 4.x
702has been end-of-lifed years ago, don't hold your breath for a fix.
703In addition to that, don't try anything too Unicode-y, especially
704with Encode, and you should be fine in SunOS 4.x.
705
706=head1 AUTHOR
707
708The original was written by Andy Dougherty F<doughera@lafayette.edu>
709drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce,
710and many other Solaris users over the years.
711
712Please report any errors, updates, or suggestions to
713L<https://github.com/Perl/perl5/issues>.
714

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|https://kb.synology.com/en-global/DSM/tutorial/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.24.0 on DSM-6.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.24.1.
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 and RS815, Intel Atom x64).
37
38=head2 Setting up the build environment
39
40=head3 DSM 5
41
42As DSM is a trimmed-down Linux system, it lacks many of the tools and
43libraries commonly found on Linux. The basic tools like sh, cp, rm,
44etc. are implemented using
45L<BusyBox|https://en.wikipedia.org/wiki/BusyBox>.
46
47=over 4
48
49=item *
50
51Using your favourite browser open the DSM management page and start
52the Package Center.
53
54=item *
55
56If you want to smoke test Perl, install C<Perl>.
57
58=item *
59
60In Settings, add the following Package Sources:
61
62  https://www.cphub.net
63  http://packages.quadrat4.de
64
65=item *
66
67Still in Settings, in Channel Update, select Beta Channel.
68
69=item *
70
71Press Refresh. In the left panel the item "Community" will appear.
72Click it. Select "Bootstrap Installer Beta" and install it.
73
74=item *
75
76Likewise, install "iPKGui Beta".
77
78The application window should now show an icon for iPKGui.
79
80=item *
81
82Start iPKGui. Install the packages C<make>, C<gcc> and C<coreutils>.
83
84If you want to smoke test Perl, install C<patch>.
85
86=back
87
88The next step is to add some symlinks to system libraries. For
89example, the development software expect a library C<libm.so> that
90normally is a symlink to C<libm.so.6>. Synology only provides the
91latter and not the symlink.
92
93Here the actual architecture of the Synology system matters. You have
94to find out where the gcc libraries have been installed. Look in /opt
95for a directory similar to arm-none-linux-gnueab or
96powerpc-linux-gnuspe. In the instructions below I'll use
97powerpc-linux-gnuspe as an example.
98
99=over 4
100
101=item *
102
103On the DSM management page start the Control Panel.
104
105=item *
106
107Click Terminal, and enable SSH service.
108
109=item *
110
111Close Terminal and the Control Panel.
112
113=item *
114
115Open a shell on the Synology using ssh and become root.
116
117=item *
118
119Execute the following commands:
120
121  cd /lib
122  ln -s libm.so.6 libm.so
123  ln -s libcrypt.so.1 libcrypt.so
124  ln -s libdl.so.2 libdl.so
125  cd /opt/powerpc-linux-gnuspe/lib  (or
126                                    /opt/arm-none-linux-gnueabi/lib)
127  ln -s /lib/libdl.so.2 libdl.so
128
129=back
130
131B<WARNING:> When you perform a system software upgrade, these links
132will disappear and need to be re-established.
133
134=head3 DSM 6
135
136Using iPkg has been deprecated on DSM 6, but an alternative is available
137for DSM 6: entware/opkg. For instructions on how to use that, please read
138L<Install Entware-ng on Synology NAS|https://github.com/Entware-ng/Entware-ng/wiki/Install-on-Synology-NAS>
139
140That sadly does not (yet) work on QorIQ. At the moment of writing, the
141supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64.
142Check L<here|https://pkg.entware.net/binaries/> for supported platforms.
143
144Entware-ng comes with a precompiled 5.24.1 (June 2017) that allowes
145building shared XS code. Note that this installation does B<not> use
146a site_perl folder. The available C<cpan> works. If all required
147development packages are installed too, also for XS.
148
149=head2 Compiling Perl 5
150
151When the build environment has been set up, building and testing Perl
152is straightforward. The only thing you need to do is download the
153sources as usual, and add a file Policy.sh as follows:
154
155  # Administrivia.
156  perladmin="your.email@goes.here"
157
158  # Install Perl in a tree in /opt/perl instead of /opt/bin.
159  prefix=/opt/perl
160
161  # Select the compiler. Note that there is no 'cc' alias or link.
162  cc=gcc
163
164  # Build flags.
165  ccflags="-DDEBUGGING"
166
167  # Library and include paths.
168  libpth="/lib"
169  locincpth="/opt/include"
170  loclibpth="/lib"
171
172You may want to create the destination directory and give it the right
173permissions before installing, thus eliminating the need to build Perl
174as a super user.
175
176In the directory where you unpacked the sources, issue the familiar
177commands:
178
179  ./Configure -des
180  make
181  make test
182  make install
183
184=head2 Known problems
185
186=head3 Configure
187
188No known problems yet
189
190=head3 Build
191
192=over 4
193
194=item Error message "No error definitions found".
195
196This error is generated when it is not possible to find the local
197definitions for error codes, due to the uncommon structure of the
198Synology file system.
199
200This error was fixed in the Perl development git for version 5.19,
201commit 7a8f1212e5482613c8a5b0402528e3105b26ff24.
202
203=back
204
205=head3 Failing tests
206
207=over 4
208
209=item F<ext/DynaLoader/t/DynaLoader.t>
210
211One subtest fails due to the uncommon structure of the Synology file
212system. The file F</lib/glibc.so> is missing.
213
214B<WARNING:> Do not symlink F</lib/glibc.so.6> to F</lib/glibc.so> or
215some system components will start to fail.
216
217=back
218
219=head2 Smoke testing Perl 5
220
221If building completes successfully, you can set up smoke testing as
222described in the Test::Smoke documentation.
223
224For smoke testing you need a running Perl. You can either install the
225Synology supplied package for Perl 5.8.6, or build and install your
226own, much more recent version.
227
228Note that I could not run successful smokes when initiated by the
229Synology Task Scheduler. I resorted to initiating the smokes via a
230cron job run on another system, using ssh:
231
232  ssh nas1 wrk/Test-Smoke/smoke/smokecurrent.sh
233
234=head3 Local patches
235
236When local patches are applied with smoke testing, the test driver
237will automatically request regeneration of certain tables after the
238patches are applied. The Synology supplied Perl 5.8.6 (at least on the
239DS413) B<is NOT capable> of generating these tables. It will generate
240opcodes with bogus values, causing the build to fail.
241
242You can prevent regeneration by adding the setting
243
244  'flags' => 0,
245
246to the smoke config, or by adding another patch that inserts
247
248  exit 0 if $] == 5.008006;
249
250in the beginning of the C<regen.pl> program.
251
252=head2 Adding libraries
253
254The above procedure describes a basic environment and hence results in
255a basic Perl. If you want to add additional libraries to Perl, you may
256need some extra settings.
257
258For example, the basic Perl does not have any of the DB libraries (db,
259dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to
260set environment variable LD_LIBRARY_PATH to the appropriate value:
261
262  LD_LIBRARY_PATH=/lib:/opt/lib
263  export LD_LIBRARY_PATH
264
265This setting needs to be in effect while Perl is built, but also when
266the programs are run.
267
268=head1 REVISION
269
270June 2017, for Synology DSM 5.1.5022 and DSM 6.1-15101-4.
271
272=head1 AUTHOR
273
274Johan Vromans <jvromans@squirrel.nl>
275H. Merijn Brand <h.m.brand@xs4all.nl>
276
277=cut
278

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<https://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<https://www.perl.org/>
83
84Perl 的首頁
85
86=item L<https://www.perl.com/>
87
88由 Perl 基金會所營運的文章輯錄
89
90=item L<https://www.cpan.org/>
91
92Perl 綜合典藏網 (Comprehensive Perl Archive Network)
93
94=item L<https://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<https://www.pm.org/groups/taiwan.html>
115
116臺灣 Perl 推廣組一覽
117
118=item L<irc://chat.freenode.org/#perl.tw>
119
120Perl.tw 線上聊天室
121
122=back
123
124=head2 Unicode 相關網址
125
126=over 4
127
128=item L<https://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=back
147
148=head1 SEE ALSO
149
150L<Encode>, L<Encode::TW>, L<perluniintro>, L<perlunicode>
151
152=head1 AUTHORS
153
154Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
155
156Audrey Tang (唐鳳) E<lt>audreyt@audreyt.orgE<gt>
157
158=cut
159

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) 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
49VSI (formerly DEC/Compaq/HP/HPE) C for VMS (Alpha or Itanium). Various
50ancient versions of DEC C had some caveats, so if you're using a version
51older than 7.x, you may need to upgrade to get a successful build.
52
53There have been no recent reports of builds using Gnu C, but latent
54(and most likely outdated) support for it is still present in various
55parts of the sources.
56
57There is rudimentary but not quite complete support for HP C++; to try it out,
58configure with C<-"Dusecxx" -"Duser_c_flags=/WARN=INFORMATIONAL=NOCTOBUTCONREFM">.
59
60=item 2  A make tool.
61
62You will need the free MMS analog MMK (available from
63L<http://ftp.endlesssoftware.com.au/mmk/kits/> or
64L<https://github.com/endlesssoftware/mmk>). HP's MMS has not been known to work for
65some time as Perl's automatically-generated description files are too complex for it,
66but MMS support may return in the future.  Gnu Make might work, but it's been so long
67since anyone's tested it that we're not sure.
68
69=item 3  ODS-5 and Extended Parse
70
71All development and testing of Perl on VMS takes place on ODS-5 volumes with
72extended parse enabled in the environment via the command C<SET PROCESS/PARSE=EXTENDED>.
73Latent support for ODS-2 volumes is still present, but there have been some reports
74that it no longer works, and even if it builds, there will be many test failures,
75mostly related to the failure to preserve filename case. ODS-2 support may be
76explicity disabled in a future release.
77
78=back
79
80=head2 Additional software that is optional for Perl on VMS
81
82You may also want to have on hand:
83
84=over 4
85
86=item 1  gunzip/gzip for VMS
87
88A de-compressor for *.gz and *.tgz files available from a number
89of web/ftp sites such as:
90
91    L<http://www.antinode.info/dec/sw/gzip.html>
92    L<http://vms.process.com/scripts/fileserv/fileserv.com?GZIP>
93
94=item 2  VMS tar
95
96For reading and writing Unix tape archives (*.tar files).  Vmstar is also
97available from a number of sites such as:
98
99    L<http://www.antinode.info/dec/sw/vmstar.html>
100    L<http://vms.process.com/scripts/fileserv/fileserv.com?VMSTAR>
101
102A port of GNU tar is also available as part of the GNV package:
103
104    L<http://h71000.www7.hp.com/opensource/gnv.html>
105
106=item 3  unzip for VMS
107
108A combination decompressor and archive reader/writer for *.zip files.
109Unzip is available from a number of web/ftp sites.
110
111    L<http://www.info-zip.org/UnZip.html>
112    L<http://www.hp.com/go/openvms/freeware/>
113    L<http://vms.process.com/fileserv-software.html>
114
115=item 5 GNU patch and diffutils for VMS
116
117Patches to Perl are usually distributed as GNU unified or contextual diffs.
118Such patches are created by the GNU diff program (part of the diffutils
119distribution) and applied with GNU patch.  VMS ports of these utilities are
120available here:
121
122    L<http://www.antinode.info/dec/sw/diffutils.html>
123    L<http://vms.pdv-systeme.de/users/martinv/gnupatch.zip>
124
125=back
126
127Please note that unzip and gunzip are not the same thing (they work with
128different formats).  Many of the useful files from CPAN (the Comprehensive
129Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies
130of the source code for perl as well as modules and scripts that you may
131wish to add later) hence you probably want to have GUNZIP.EXE and
132VMSTAR.EXE on your VMS machine.
133
134=head1 Unpacking the Perl source code
135
136You may need to set up a foreign symbol for the unpacking utility of
137choice.  Once you have done so, use a command like the following to
138unpack the archive:
139
140    vmstar -xvf perl-5^.35^.5.tar
141
142Then set default to the top-level source directory like so:
143
144    set default [.perl-5^.35^.5]
145
146and proceed with configuration as described in the next section.
147
148
149=head1 Configuring the Perl build
150
151To configure perl (a necessary first step), issue the command
152
153   @configure.com
154
155from the top of an unpacked perl source directory.  You will be asked a
156series of questions, and the answers to them (along with the capabilities
157of your C compiler and network stack) will determine how perl is custom-
158built for your machine.
159
160If you have any symbols or logical names in your environment that may
161interfere with the build or regression testing of perl then F<configure.com>
162will try to warn you about them.  If a logical name is causing
163you trouble but is in an LNM table that you do not have write access to
164then try defining your own to a harmless equivalence string in a table
165such that it is resolved before the other (e.g. if TMP is defined in the
166SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table)
167otherwise simply deassign the dangerous logical names.  The potentially
168troublesome logicals and symbols include:
169
170    COMP    "LOGICAL"
171    EXT     "LOGICAL"
172    FOO     "LOGICAL"
173    LIB     "LOGICAL"
174    LIST    "LOGICAL"
175    MIME    "LOGICAL"
176    POSIX   "LOGICAL"
177    SYS     "LOGICAL"
178    T       "LOGICAL"
179    THREAD  "LOGICAL"
180    THREADS "LOGICAL"
181    TIME    "LOGICAL"
182    TMP     "LOGICAL"
183    UNICODE "LOGICAL"
184    UTIL    "LOGICAL"
185    TEST    "SYMBOL"
186
187As a handy shortcut, the command:
188
189    @configure "-des"
190
191(note the quotation marks and case) will choose reasonable defaults
192automatically.  Some options can be given explicitly on the command line;
193the following example specifies a non-default location for where Perl
194will be installed:
195
196    @configure "-d" "-Dprefix=dka100:[utils.perl5.]"
197
198Note that the installation location would be by default where you unpacked
199the source with a "_ROOT." appended.  For example if you unpacked the perl
200source into:
201
202   F<DKA200:[PERL-5^.18^.0...]>
203
204Then the F<PERL_SETUP.COM> that gets written out by F<configure.com> will
205try to DEFINE your installation PERL_ROOT to be:
206
207   F<DKA200:[PERL-5^.18^.0_ROOT.]>
208
209More help with configure.com is available from:
210
211    @configure "-h"
212
213If you find yourself reconfiguring and rebuilding  then be sure to also follow
214the advice in the "Cleaning up and starting fresh (optional)" and the checklist
215of items in the "CAVEATS" sections below.
216
217=head2 Changing compile-time options (optional) for Perl on VMS
218
219Most of the user-definable features of Perl are enabled or disabled in
220configure.com, which processes the hints file config_h.SH.  There is
221code in there to Do The Right Thing, but that  may end up being the
222wrong thing for you.  Make sure you understand what you are doing since
223inappropriate changes to configure.com or config_h.SH can render perl
224unbuildable; odds are that there's nothing in there you'll need to
225change. Note also that non-default options are tested less than default
226options, so you may end up being more of a pioneer than you intend to be.
227
228=head1 Building Perl
229
230The configuration script will print out, at the very end, the MMS or MMK
231command you need to compile perl.  Issue it (exactly as printed) to start
232the build.
233
234Once you issue your MMS or MMK command, sit back and wait.  Perl should
235compile and link without a problem.  If a problem does occur check the
236"CAVEATS" section of this document.  If that does not help send some
237mail to the VMSPERL mailing list.  Instructions are in the L</"Mailing Lists">
238section of this document.
239
240=head1 Testing Perl
241
242Once Perl has built cleanly you need to test it to make sure things work.
243This step is very important since there are always things that can go wrong
244somehow and yield a dysfunctional Perl for you.
245
246Testing is very easy, though, as there's a full test suite in the perl
247distribution.  To run the tests, enter the I<exact> MMS line you used to
248compile Perl and add the word "test" to the end, like this:
249
250If the compile command was:
251
252    MMK
253
254then the test command ought to be:
255
256    MMK test
257
258MMK (or MMS) will run all the tests.  This may take some time, as there are
259a lot of tests.  If any tests fail, there will be a note made on-screen.
260At the end of all the tests, a summary of the tests, the number passed and
261failed, and the time taken will be displayed.
262
263The test driver invoked via MMK TEST has a DCL wrapper ([.VMS]TEST.COM) that
264downgrades privileges to NETMBX, TMPMBX for the duration of the test run,
265and then restores them to their prior state upon completion of testing.
266This is done to ensure that the tests run in a private sandbox and can do no
267harm to your system even in the unlikely event something goes badly wrong in
268one of the test scripts while running the tests from a privileged account.
269A side effect of this safety precaution is that the account used to run the
270test suite must be the owner of the directory tree in which Perl has been
271built; otherwise the manipulations of temporary files and directories
272attempted by some of the tests will fail.
273
274If any tests fail, it means something is wrong with Perl, or at least
275with the particular module or feature that reported failure. If the test suite
276hangs (some tests can take upwards of two or three minutes, or more if
277you're on an especially slow machine, depending on your machine speed, so
278don't be hasty), then the test I<after> the last one displayed failed. Don't
279install Perl unless you're confident that you're OK. Regardless of how
280confident you are, make a bug report to the VMSPerl mailing list.
281
282If one or more tests fail, you can get more information on the failure by
283issuing this command sequence:
284
285    @[.vms]test .typ "" "-v" [.subdir]test.t
286
287where ".typ" is the file type of the Perl images you just built (if you
288didn't do anything special, use .EXE), and "[.subdir]test.t" is the test
289that failed. For example, with a normal Perl build, if the test indicated
290that t/op/time failed, then you'd do this:
291
292    @ .vms]test .EXE "" "-v" [.op]time.t
293
294Note that test names are reported in UNIX syntax and relative to the
295top-level build directory.  When supplying them individually to the test
296driver, you must specify them in Unix format if they are outside of the [.t]
297directory; otherwise VMS syntax is ok. Note that you must also give the path
298relative to the [.t] directory and you must also add the .t extension to the
299filename.  So, for example if the test lib/warnings.t fails, you would run:
300
301    @[.vms]test .EXE "" -"v" "../lib/warnings.t"
302
303When you send in a bug report for failed tests, please include the output
304from this command, which is run from the main source directory:
305
306    MCR []MINIPERL "-Ilib" "-V"
307
308Note that -"V" really is a capital V in double quotes. This will dump out a
309couple of screens worth of configuration information, and can help us
310diagnose the problem.  If (and only if) that did not work then try enclosing
311the output of:
312
313    MMK printconfig
314
315If (and only if) that did not work then try enclosing the output of:
316
317    @[.vms]myconfig
318
319You may also be asked to provide your C compiler version ("CC/VERSION NL:"
320with DEC C, "gcc --version" with GNU CC).  To obtain the version of MMS or
321MMK you are running try "MMS/ident" or "MMK /ident".  The GNU make version
322can be identified with "make --version".
323
324=head2 Cleaning up and starting fresh (optional) installing Perl on VMS
325
326If you need to recompile from scratch, you have to make sure you clean up
327first.  There is a procedure to do it--enter the I<exact> MMK line you used
328to compile and add "realclean" at the end, like this:
329
330if the compile command was:
331
332    MMK
333
334then the cleanup command ought to be:
335
336    MMK realclean
337
338If you do not do this things may behave erratically during the subsequent
339rebuild attempt.  They might not, too, so it is best to be sure and do it.
340
341=head1 Installing Perl
342
343There are several steps you need to take to get Perl installed and
344running.
345
346=over 4
347
348=item 1
349
350Check your default file protections with
351
352     SHOW PROTECTION /DEFAULT
353
354and adjust if necessary with C<SET PROTECTION=(code)/DEFAULT>.
355
356=item 2
357
358Decide where you want Perl to be installed (unless you have already done so
359by using the "prefix" configuration parameter -- see the example in the
360"Configuring the Perl build" section).
361
362The DCL script PERL_SETUP.COM that is written by configure.com will help you
363with the definition of the PERL_ROOT and PERLSHR logical names and the PERL
364foreign command  symbol.  Take a look at PERL_SETUP.COM and modify it if you
365want to.  The installation process will execute PERL_SETUP.COM and copy
366files to the directory tree pointed to by the PERL_ROOT logical name defined
367there, so make sure that you have write access to the parent directory of
368what will become the root of your Perl installation.
369
370=item 3
371
372Run the install script via:
373
374    MMK install
375
376If for some reason it complains about target INSTALL being up to date,
377throw a /FORCE switch on the MMS or MMK command.
378
379=back
380
381Installation will copy F<PERL_SETUP.COM> to the root of your installation
382tree.  If you want to give everyone on the system  access to Perl (and you
383have, for example, installed to F<dsa0:[utils.perl_root]>) then add a line
384that reads:
385
386    $ @dsa0:[utils.perl_root]perl_setup
387
388to F<SYS$MANAGER:SYLOGIN.COM>.  Or for your own use only, simply place
389that line in F<SYS$LOGIN:LOGIN.COM>.
390
391Two alternatives to the foreign symbol would be to install PERL into
392DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES
393(optional)" for more information), or put the image in a
394directory that's in your DCL$PATH.
395
396See also the "INSTALLing images (optional)" section.
397
398=head2 Installing Perl into DCLTABLES (optional) on VMS
399
400Execute the following command file to define PERL as a DCL command.
401You'll need CMKRNL privilege to install the new dcltables.exe.
402
403    $ create perl.cld
404    !
405    ! modify to reflect location of your perl.exe
406    !
407    define verb perl
408      image perl_root:[000000]perl.exe
409      cliflags (foreign)
410    $!
411    $ set command perl /table=sys$common:[syslib]dcltables.exe -
412     /output=sys$common:[syslib]dcltables.exe
413    $ install replace sys$common:[syslib]dcltables.exe
414    $ exit
415
416=head2 INSTALLing Perl images (optional) on VMS
417
418On systems that are using perl quite a bit, and particularly those with
419minimal RAM, you can boost the performance of perl by INSTALLing it as
420a known image.  PERLSHR.EXE is typically larger than 3000 blocks
421and that is a reasonably large amount of IO to load each time perl is
422invoked.
423
424   INSTALL ADD PERLSHR/SHARE
425   INSTALL ADD PERL/HEADER
426
427should be enough for F<PERLSHR.EXE> (/share implies /header and /open),
428while /HEADER should do for FPERL.EXE> (perl.exe is not a shared image).
429
430If your code 'use's modules, check to see if there is a shareable image for
431them, too.  In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File,
432DCLsym, and Stdio, and other extensions all have shared images that can be
433installed /SHARE.
434
435How much of a win depends on your memory situation, but if you are firing
436off perl with any regularity (like more than once every 20 seconds or so)
437it is probably beneficial to INSTALL at least portions of perl.
438
439While there is code in perl to remove privileges as it runs you are advised
440to NOT INSTALL F<PERL.EXE> with PRIVs!
441
442=head2 Running h2ph to create perl header files (optional) on VMS
443
444If using HP C, ensure that you have extracted loose versions of your
445compiler's header or *.H files.  Be sure to check the contents of:
446
447    SYS$LIBRARY:DECC$RTLDEF.TLB
448    SYS$LIBRARY:SYS$LIB_C.TLB
449    SYS$LIBRARY:SYS$STARLET_C.TLB
450
451etcetera.
452
453If using GNU cc then also check your GNU_CC:[000000...] tree for the locations
454of the GNU cc headers.
455
456=head1 Reporting Bugs
457
458If you come across what you think might be a bug in Perl, please report
459it. The issue tracker at L<https://github.com/Perl/perl5/issues> walks you
460through the process of creating a bug report and including details of your
461installation.
462
463=head1 CAVEATS
464
465Probably the single biggest gotcha in compiling Perl is giving the wrong
466switches to MMS/MMK when you build. Use I<exactly> what the configure.com
467script prints!
468
469Be sure that the process that you use to build Perl has a PGFLQUO of at
470least 400000.  Be sure to have a correct local time zone to UTC offset
471defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before
472running the regression test suite.  The SYS$MANAGER:UTC$CONFIGURE_TDF.COM
473procedure will help you set that logical for your system but may require
474system privileges.  For example, a location 5 hours west of UTC (such as
475the US East coast while not on daylight savings time) would have:
476
477    DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000"
478
479A final thing that causes trouble is leftover pieces from a failed
480build.  If things go wrong make sure you do a "(MMK|MMS|make) realclean"
481before you rebuild.
482
483=head2 Floating Point Considerations
484
485Prior to 5.8.0, Perl simply accepted the default floating point options of the
486C compiler, namely representing doubles with G_FLOAT on Alpha.  Single
487precision floating point values are represented in F_FLOAT format when either
488D_FLOAT or G_FLOAT is in use for doubles.  Beginning with 5.8.0, Alpha builds
489now use IEEE floating point formats by default, which in VMS parlance are S_FLOAT
490for singles and T_FLOAT for doubles.  Itanium builds have always used IEEE by
491default. The  available non-default options are D_FLOAT or G_FLOAT on Alpha
492or Itanium.
493
494The use of IEEE introduces NaN, infinity, and denormalization capabilities not
495available with D_FLOAT and G_FLOAT.  When using one of those non-IEEE formats,
496silent underflow and overflow are emulated in the conversion of strings to
497numbers, but it is preferable to get the real thing by using IEEE where possible.
498You are likely to see quite a few test failures when not using IEEE floating point.
499
500Regardless of what floating point format you consider preferable, be aware
501that the choice may have an impact on compatibility with external libraries,
502such as database interfaces, and with existing data, such as data created with
503the C<pack> function and written to disk, or data stored via the Storable
504extension.  For example, a C<pack("d", $foo)")> will create a D_FLOAT,
505G_FLOAT, or T_FLOAT depending on what your Perl was configured with.  When
506written to disk, the value can only be retrieved later by a Perl configured
507with the same floating point option that was in effect when it was created.
508
509To obtain a non-IEEE build, simply answer no to the "Use IEEE math?" question
510during the configuration or specify -"Uuseieee" as a parameter to configure.com
511on the command line.
512
513=head1 Mailing Lists
514
515There are several mailing lists available to the Perl porter.  For VMS
516specific issues (including both Perl questions and installation problems)
517there is the VMSPERL mailing list.  It is usually a low-volume (10-12
518messages a week) mailing list.
519
520To subscribe, send a mail message to VMSPERL-SUBSCRIBE@PERL.ORG. The VMSPERL
521mailing list address is VMSPERL@PERL.ORG.  Any mail sent there gets echoed
522to all subscribers of the list.  There is an archive of the list
523on the web at:
524
525    L<https://www.nntp.perl.org/group/perl.vmsperl/>
526
527To unsubscribe from VMSPERL send a message to VMSPERL-UNSUBSCRIBE@PERL.ORG.
528Be sure to do so from the subscribed account that you are canceling.
529
530=head2 Web sites for Perl on VMS
531
532Vmsperl pages on the web include:
533
534    L<http://www.sidhe.org/vmsperl/index.html>
535    L<https://www.cpan.org/modules/by-module/VMS/>
536    L<https://www.nntp.perl.org/group/perl.vmsperl/>
537    L<https://sourceforge.net/projects/vmsperlkit/>
538
539=head1 SEE ALSO
540
541Perl information for users and programmers about the port of perl to VMS is
542available from the [.pod]perlvms.pod file that gets installed as L<perlvms>.
543For administrators the perlvms document also includes a detailed discussion
544of extending vmsperl with CPAN modules after Perl has been installed.
545
546=head1 AUTHORS
547
548Originally by Charles Bailey bailey@newman.upenn.edu.  See the git repository
549for history.
550
551=head1 ACKNOWLEDGEMENTS
552
553A real big thanks needs to go to Charles Bailey
554bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004
555running on VMS. Without him, nothing the rest of us have done would be at
556all important.
557
558There are, of course, far too many people involved in the porting and testing
559of Perl to mention everyone who deserves it, so please forgive us if we've
560missed someone.  That said, special thanks are due to the following:
561
562  Tim Adye T.J.Adye@rl.ac.uk
563     for the VMS emulations of getpw*()
564  David Denholm denholm@conmat.phys.soton.ac.uk
565     for extensive testing and provision of pipe and SocketShr code,
566  Mark Pizzolato mark@infocomm.com
567     for the getredirection() code
568  Rich Salz rsalz@bbn.com
569     for readdir() and related routines
570  Peter Prymmer pvhp@best.com
571     for extensive testing, as well as development work on
572     configuration and documentation for VMS Perl,
573  Dan Sugalski dan@sidhe.org
574     for extensive contributions to recent version support,
575     development of VMS-specific extensions, and dissemination
576     of information about VMS Perl,
577  the Stanford Synchrotron Radiation Laboratory and the
578     Laboratory of Nuclear Studies at Cornell University for
579     the opportunity to test and develop for the AXP,
580  John Hasstedt John.Hasstedt@sunysb.edu
581     for VAX VMS V7.2 support
582  John Malmberg wb8tyw@qsl.net
583     for ODS-5 filename handling and other modernizations
584
585and to the entire VMSperl group for useful advice and suggestions.  In
586addition the perl5-porters deserve credit for their creativity and
587willingness to work with the VMS newcomers.  Finally, the greatest debt of
588gratitude is due to Larry Wall larry@wall.org, for having the ideas which
589have made our sleepless nights possible.
590
591Thanks,
592The VMSperl group
593
594=cut
595
596

README.vos

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
7perlvos - Perl for Stratus OpenVOS
8
9=head1 SYNOPSIS
10
11This file contains notes for building perl on the Stratus OpenVOS
12operating system.  Perl is a scripting or macro language that is
13popular on many systems.  See L<perlbook> for a number of good books
14on Perl.
15
16These are instructions for building Perl from source.  This version of
17Perl requires the dynamic linking support that is found in OpenVOS
18Release 17.1 and thus is not supported on OpenVOS Release 17.0 or
19earlier releases.
20
21If you are running VOS Release 14.4.1 or later, you can obtain a
22pre-compiled, supported copy of perl by purchasing the GNU Tools
23product from Stratus Technologies.
24
25=head1 BUILDING PERL FOR OPENVOS
26
27To build perl from its source code on the Stratus V Series platform
28you must have OpenVOS Release 17.1.0 or later, GNU Tools Release
293.5 or later, and the C/POSIX Runtime Libraries.
30
31Follow the normal instructions for building perl; e.g, enter bash, run
32the Configure script, then use "gmake" to build perl.
33
34=head1 INSTALLING PERL IN OPENVOS
35
36=over 4
37
38=item 1
39
40After you have built perl using the Configure script, ensure that you
41have modify and default write permission to C<< >system>ported >> and
42all subdirectories.  Then type
43
44     gmake install
45
46=item 2
47
48While there are currently no architecture-specific extensions or
49modules distributed with perl, the following directories can be
50used to hold such files (replace the string VERSION by the
51appropriate version number):
52
53     >system>ported>lib>perl5>VERSION>i786
54
55=item 3
56
57Site-specific perl extensions and modules can be installed in one of
58two places.  Put architecture-independent files into:
59
60     >system>ported>lib>perl5>site_perl>VERSION
61
62Put site-specific architecture-dependent files into one of the
63following directories:
64
65     >system>ported>lib>perl5>site_perl>VERSION>i786
66
67=item 4
68
69You can examine the @INC variable from within a perl program
70to see the order in which Perl searches these directories.
71
72=back
73
74=head1 USING PERL IN OPENVOS
75
76=head2 Restrictions of Perl on OpenVOS
77
78This port of Perl version 5 prefers Unix-style, slash-separated
79pathnames over OpenVOS-style greater-than-separated pathnames.
80OpenVOS-style pathnames should work in most contexts, but if you have
81trouble, replace all greater-than characters by slash characters.
82Because the slash character is used as a pathname delimiter, Perl
83cannot process OpenVOS pathnames containing a slash character in a
84directory or file name; these must be renamed.
85
86This port of Perl also uses Unix-epoch date values internally.
87As long as you are dealing with ASCII character string
88representations of dates, this should not be an issue.  The
89supported epoch is January 1, 1980 to January 17, 2038.
90
91See the file pod/perlport.pod for more information about the OpenVOS
92port of Perl.
93
94=head1 TEST STATUS
95
96A number of the perl self-tests fails for various reasons; generally
97these are minor and due to subtle differences between common
98POSIX-based environments and the OpenVOS POSIX environment.  Ensure
99that you conduct sufficient testing of your code to guarantee that it
100works properly in the OpenVOS environment.
101
102=head1 SUPPORT STATUS
103
104I'm offering this port "as is".  You can ask me questions, but I
105can't guarantee I'll be able to answer them.  There are some
106excellent books available on the Perl language; consult a book
107seller.
108
109If you want a supported version of perl for OpenVOS, purchase the
110OpenVOS GNU Tools product from Stratus Technologies, along with a
111support contract (or from anyone else who will sell you support).
112
113=head1 AUTHOR
114
115Paul Green (Paul.Green@stratus.com)
116
117=head1 LAST UPDATE
118
119February 28, 2013
120
121=cut
122

README.win32

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
7perlwin32 - Perl under Windows
8
9=head1 SYNOPSIS
10
11These are instructions for building Perl under Windows 2000 and later.
12
13=head1 DESCRIPTION
14
15Before you start, you should glance through the README file
16found in the top-level directory to which the Perl distribution
17was extracted.  Make sure you read and understand the terms under
18which this software is being distributed.
19
20Also make sure you read L</BUGS AND CAVEATS> below for the
21known limitations of this port.
22
23The INSTALL file in the perl top-level has much information that is
24only relevant to people building Perl on Unix-like systems.  In
25particular, you can safely ignore any information that talks about
26"Configure".
27
28You may also want to look at one other option for building a perl that
29will work on Windows: the README.cygwin file, which give a different
30set of rules to build a perl for Windows.  This method will probably
31enable you to build a more Unix-compatible perl, but you will also
32need to download and use various other build-time and run-time support
33software described in that file.
34
35This set of instructions is meant to describe a so-called "native"
36port of Perl to the Windows platform.  This includes both 32-bit and
3764-bit Windows operating systems.  The resulting Perl requires no
38additional software to run (other than what came with your operating
39system).  Currently, this port is capable of using one of the
40following compilers on the Intel x86 architecture:
41
42      Microsoft Visual C++    version 6.0 or later
43      Intel C++ Compiler      (experimental)
44      Gcc by mingw.org        gcc version 3.4.5-5.3.0
45      Gcc by mingw-w64.org    gcc version 4.4.3 or later
46
47Note that the last two of these are actually competing projects both
48delivering complete gcc toolchain for MS Windows:
49
50=over 4
51
52=item L<http://mingw.org>
53
54Delivers gcc toolchain targeting 32-bit Windows platform.
55
56=item L<http://mingw-w64.org>
57
58Delivers gcc toolchain targeting both 64-bit Windows and 32-bit Windows
59platforms (despite the project name "mingw-w64" they are not only 64-bit
60oriented). They deliver the native gcc compilers and cross-compilers
61that are also supported by perl's makefile.
62
63=back
64
65The Microsoft Visual C++ compilers are also now being given away free. They are
66available as "Visual C++ Toolkit 2003" or "Visual C++ 2005-2019 Express [or
67Community, from 2017] Edition" (and also as part of the ".NET Framework SDK")
68and are the same compilers that ship with "Visual C++ .NET 2003 Professional"
69or "Visual C++ 2005-2019 Professional" respectively.
70
71This port can also be built on IA64/AMD64 using:
72
73      Microsoft Platform SDK	Nov 2001 (64-bit compiler and tools)
74      MinGW64 compiler (gcc version 4.4.3 or later)
75
76The Windows SDK can be downloaded from L<https://developer.microsoft.com/windows/downloads/sdk-archive>.
77The MinGW64 compiler is available at L<http://mingw-w64.org>.
78The latter is actually a cross-compiler targeting Win64. There's also a trimmed
79down compiler (no java, or gfortran) suitable for building perl available at:
80L<http://strawberryperl.com/package/kmx/64_gcctoolchain/>
81
82NOTE: If you're using a 32-bit compiler to build perl on a 64-bit Windows
83operating system, then you should set the WIN64 environment variable to "undef".
84Also, the trimmed down compiler only passes tests when USE_ITHREADS *= define
85(as opposed to undef) and when the CFG *= Debug line is commented out.
86
87This port fully supports MakeMaker (the set of modules that
88is used to build extensions to perl).  Therefore, you should be
89able to build and install most extensions found in the CPAN sites.
90See L</Usage Hints for Perl on Windows> below for general hints about this.
91
92=head2 Setting Up Perl on Windows
93
94=over 4
95
96=item Make
97
98You need a "make" program to build the sources.  If you are using
99Visual C++ or the Windows SDK tools, you can use nmake supplied with Visual C++
100or Windows SDK. You may also use gmake instead of nmake.  Builds using gcc need
101gmake. nmake is not supported for gcc builds.  Parallel building is only
102supported with gmake, not nmake.
103
104=item Command Shell
105
106Use the default "cmd" shell that comes with Windows.  Some versions of the
107popular 4DOS/NT shell have incompatibilities that may cause you trouble.
108If the build fails under that shell, try building again with the cmd
109shell.
110
111Make sure the path to the build directory does not contain spaces.  The
112build usually works in this circumstance, but some tests will fail.
113
114=item Microsoft Visual C++
115
116The nmake that comes with Visual C++ will suffice for building. Visual C++
117requires that certain things be set up in the console before Visual C++ will
118successfully run. To make a console box be able to run the C compiler, you will
119need to beforehand, run C<vcvarsall.bat x86> to compile for x86-32 and for
120x86-64 C<vcvarsall.bat amd64>. On a typical install of a Microsoft C++
121compiler product, these batch files will already be in your C<PATH>
122environment variable so you may just type them without an absolute path into
123your console. If you need to find the absolute path to the batch file, it is
124usually found somewhere like
125C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC.
126With some newer Microsoft C products (released after ~2004), the installer will
127put a shortcut in the start menu to launch a new console window with the
128console already set up for your target architecture (x86-32 or x86-64 or IA64).
129With the newer compilers, you may also use the older batch files if you choose
130so.
131
132=item Microsoft Visual C++ 2008-2019 Express/Community Edition
133
134These free versions of Visual C++ 2008-2019 Professional contain the same
135compilers and linkers that ship with the full versions, and also contain
136everything necessary to build Perl, rather than requiring a separate download
137of the Windows SDK like previous versions did.
138
139These packages can be downloaded by searching in the Download Center at
140L<https://www.microsoft.com/downloads/search.aspx?displaylang=en>.  (Providing exact
141links to these packages has proven a pointless task because the links keep on
142changing so often.)
143
144Install Visual C++ 2008-2019 Express/Community, then setup your environment
145using, e.g.
146
147 C:\Program Files\Microsoft Visual Studio 12.0\Common7\Tools\vsvars32.bat
148
149(assuming the default installation location was chosen).
150
151Perl should now build using the win32/Makefile.  You will need to edit that
152file to set CCTYPE to one of MSVC90-MSVC142 first.
153
154=item Microsoft Visual C++ 2005 Express Edition
155
156This free version of Visual C++ 2005 Professional contains the same compiler
157and linker that ship with the full version, but doesn't contain everything
158necessary to build Perl.
159
160You will also need to download the "Windows SDK" (the "Core SDK" and "MDAC
161SDK" components are required) for more header files and libraries.
162
163These packages can both be downloaded by searching in the Download Center at
164L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>.  (Providing exact
165links to these packages has proven a pointless task because the links keep on
166changing so often.)
167
168Try to obtain the latest version of the Windows SDK.  Sometimes these packages
169contain a particular Windows OS version in their name, but actually work on
170other OS versions too.  For example, the "Windows Server 2003 R2 Platform SDK"
171also runs on Windows XP SP2 and Windows 2000.
172
173Install Visual C++ 2005 first, then the Platform SDK.  Setup your environment
174as follows (assuming default installation locations were chosen):
175
176 SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
177
178 SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages;%PlatformSDKDir%\Bin
179
180 SET INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;%PlatformSDKDir%\include
181
182 SET LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;%PlatformSDKDir%\lib
183
184 SET LIBPATH=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
185
186(The PlatformSDKDir might need to be set differently depending on which version
187you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
188while the latest versions install into version-specific locations such as
189"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
190
191Perl should now build using the win32/Makefile.  You will need to edit that
192file to set
193
194 CCTYPE = MSVC80
195
196and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
197
198=item Microsoft Visual C++ Toolkit 2003
199
200This free toolkit contains the same compiler and linker that ship with
201Visual C++ .NET 2003 Professional, but doesn't contain everything
202necessary to build Perl.
203
204You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
205SDK" components are required) for header files, libraries and rc.exe, and
206".NET Framework SDK" for more libraries and nmake.exe.  Note that the latter
207(which also includes the free compiler and linker) requires the ".NET
208Framework Redistributable" to be installed first.  This can be downloaded and
209installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
210
211These packages can all be downloaded by searching in the Download Center at
212L<https://www.microsoft.com/downloads/search.aspx?displaylang=en>.  (Providing exact
213links to these packages has proven a pointless task because the links keep on
214changing so often.)
215
216Try to obtain the latest version of the Windows SDK.  Sometimes these packages
217contain a particular Windows OS version in their name, but actually work on
218other OS versions too.  For example, the "Windows Server 2003 R2 Platform SDK"
219also runs on Windows XP SP2 and Windows 2000.
220
221Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
222Setup your environment as follows (assuming default installation locations
223were chosen):
224
225 SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
226
227 SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;%PlatformSDKDir%\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
228
229 SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;%PlatformSDKDir%\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
230
231 SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;%PlatformSDKDir%\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
232
233(The PlatformSDKDir might need to be set differently depending on which version
234you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
235while the latest versions install into version-specific locations such as
236"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
237
238Several required files will still be missing:
239
240=over 4
241
242=item *
243
244cvtres.exe is required by link.exe when using a .res file.  It is actually
245installed by the .NET Framework SDK, but into a location such as the
246following:
247
248 C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
249
250Copy it from there to %PlatformSDKDir%\Bin
251
252=item *
253
254lib.exe is normally used to build libraries, but link.exe with the /lib
255option also works, so change win32/config.vc to use it instead:
256
257Change the line reading:
258
259	ar='lib'
260
261to:
262
263	ar='link /lib'
264
265It may also be useful to create a batch file called lib.bat in
266C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
267
268	@echo off
269	link /lib %*
270
271for the benefit of any naughty C extension modules that you might want to build
272later which explicitly reference "lib" rather than taking their value from
273$Config{ar}.
274
275=item *
276
277setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
278option is enabled).  The Platform SDK supplies this object file in source form
279in %PlatformSDKDir%\src\crt.  Copy setargv.c, cruntime.h and
280internal.h from there to some temporary location and build setargv.obj using
281
282	cl.exe /c /I. /D_CRTBLD setargv.c
283
284Then copy setargv.obj to %PlatformSDKDir%\lib
285
286Alternatively, if you don't need perlglob.exe and don't need to enable the
287USE_SETARGV option then you can safely just remove all mention of $(GLOBEXE)
288from win32/Makefile and setargv.obj won't be required anyway.
289
290=back
291
292Perl should now build using the win32/Makefile.  You will need to edit that
293file to set
294
295	CCTYPE = MSVC70FREE
296
297and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
298
299=item Microsoft Platform SDK 64-bit Compiler
300
301The nmake that comes with the Platform SDK will suffice for building
302Perl.  Make sure you are building within one of the "Build Environment"
303shells available after you install the Platform SDK from the Start Menu.
304
305=item GCC
306
307Perl can be compiled with gcc from MinGW (version 3.4.5 or later) or from
308MinGW64 (version 4.4.3 or later).  It can be downloaded here:
309
310L<http://www.mingw.org/>
311L<http://www.mingw-w64.org/>
312
313You also need gmake. Usually it comes with MinGW but its executable may have
314a different name, such as mingw32-make.exe.
315
316Note that the MinGW build currently fails with version 6.3.0 or later.
317
318Note also that the C++ mode build currently fails with MinGW 3.4.5 and 4.7.2
319or later, and with MinGW64 64-bit 6.3.0 or later.
320
321=item Intel C++ Compiler
322
323Experimental support for using Intel C++ Compiler has been added. Edit
324win32/Makefile and pick the correct CCTYPE for the Visual C that Intel C was
325installed into. Also uncomment __ICC to enable Intel C on Visual C support.
326To set up the build environment, from the Start Menu run
327IA-32 Visual Studio 20__ mode or Intel 64 Visual Studio 20__ mode as
328appropriate. Then run nmake as usually in that prompt box.
329
330Only Intel C++ Compiler v12.1 has been tested. Other versions probably will
331work. Using Intel C++ Compiler instead of Visual C has the benefit of C99
332compatibility which is needed by some CPAN XS modules, while maintaining
333compatibility with Visual C object code and Visual C debugging infrastructure
334unlike GCC.
335
336=back
337
338=head2 Building
339
340=over 4
341
342=item *
343
344Make sure you are in the "win32" subdirectory under the perl toplevel.
345This directory contains a "Makefile" that will work with
346versions of nmake that come with Visual C++ or the Windows SDK, and
347a GNU make "GNUmakefile" that will work for all supported compilers.
348The defaults in the gmake makefile are setup to build using MinGW/gcc.
349
350=item *
351
352Edit the GNUmakefile (or Makefile, if you're using nmake) and change the values
353of INST_DRV and INST_TOP. You can also enable various build flags. These are
354explained in the makefiles.
355
356Note that it is generally not a good idea to try to build a perl with
357INST_DRV and INST_TOP set to a path that already exists from a previous
358build.  In particular, this may cause problems with the
359lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
360may end up building against the installed perl's lib/CORE directory rather
361than the one being tested.
362
363You will have to make sure that CCTYPE is set correctly and that
364CCHOME points to wherever you installed your compiler.  For GCC this
365should be the directory that contains the F<bin>, F<include> and
366F<lib> directories.
367
368If building with the cross-compiler provided by
369mingw-w64.org you'll need to uncomment the line that sets
370GCCCROSS in the GNUmakefile. Do this only if it's the cross-compiler - ie
371only if the bin folder doesn't contain a gcc.exe. (The cross-compiler
372does not provide a gcc.exe, g++.exe, ar.exe, etc. Instead, all of these
373executables are prefixed with 'x86_64-w64-mingw32-'.)
374
375The default value for CCHOME in the makefiles for Visual C++
376may not be correct for some versions.  Make sure the default exists
377and is valid.
378
379If you want build some core extensions statically into perl's dll, specify
380them in the STATIC_EXT macro.
381
382Be sure to read the instructions near the top of the makefiles carefully.
383
384=item *
385
386Type "gmake" (or "nmake" if you are using that make).
387
388This should build everything.  Specifically, it will create perl.exe,
389perl535.dll at the perl toplevel, and various other extension dll's
390under the lib\auto directory.  If the build fails for any reason, make
391sure you have done the previous steps correctly.
392
393To try gmake's parallel mode, type "gmake -j2", where 2, is the maximum number
394of parallel jobs you want to run. A number of things in the build process will
395run in parallel, but there are serialization points where you will see just 1
396CPU maxed out. This is normal.
397
398If you are advanced enough with building C code, here is a suggestion to speed
399up building perl, and the later C<make test>. Try to keep your PATH environmental
400variable with the least number of folders possible (remember to keep your C
401compiler's folders there). C<C:\WINDOWS\system32> or C<C:\WINNT\system32>
402depending on your OS version should be first folder in PATH, since "cmd.exe"
403is the most commonly launched program during the build and later testing.
404
405=back
406
407=head2 Testing Perl on Windows
408
409Type "gmake test" (or "nmake test").  This will run most
410of the tests from the testsuite (many tests will be skipped).
411
412There should be no test failures.
413
414If you build with Visual C++ 2013 then three tests currently may fail with
415Daylight Saving Time related problems: F<t/io/fs.t>,
416F<cpan/HTTP-Tiny/t/110_mirror.t> and F<lib/File/Copy.t>. The failures are
417caused by bugs in the CRT in VC++ 2013 which are fixed in VC++2015 and
418later, as explained by Microsoft here:
419L<https://connect.microsoft.com/VisualStudio/feedback/details/811534/utime-sometimes-fails-to-set-the-correct-file-times-in-visual-c-2013>. In the meantime,
420if you need fixed C<stat> and C<utime> functions then have a look at the
421CPAN distribution Win32::UTCFileTime.
422
423If you build with Visual C++ 2015 or later then F<ext/XS-APItest/t/locale.t>
424may crash (after all its tests have passed). This is due to a regression in the
425Universal CRT introduced in the Windows 10 April 2018 Update, and will be fixed
426in the May 2019 Update, as explained here: L<https://developercommunity.visualstudio.com/content/problem/519486/setlocalelc-numeric-iso-latin-16-fails-then-succee.html>.
427
428If you build with certain versions (e.g. 4.8.1) of gcc from www.mingw.org then
429F<ext/POSIX/t/time.t> may fail test 17 due to a known bug in those gcc builds:
430see L<https://sourceforge.net/p/mingw/bugs/2152/>.
431
432Some test failures may occur if you use a command shell other than the
433native "cmd.exe", or if you are building from a path that contains
434spaces.  So don't do that.
435
436If you are running the tests from a emacs shell window, you may see
437failures in op/stat.t.  Run "gmake test-notty" in that case.
438
439Furthermore, you should make sure that during C<make test> you do not
440have any GNU tool packages in your path: some toolkits like Unixutils
441include some tools (C<type> for instance) which override the Windows
442ones and makes tests fail. Remove them from your path while testing to
443avoid these errors.
444
445To see the output of specific failing tests run the harness from the t
446directory:
447
448  # assuming you're starting from the win32 directory
449  cd ..\win32
450  .\perl harness <list of tests>
451
452Please report any other failures as described under L</BUGS AND CAVEATS>.
453
454=head2 Installation of Perl on Windows
455
456Type "gmake install" ("nmake install").  This will
457put the newly built perl and the libraries under whatever C<INST_TOP>
458points to in the Makefile.  It will also install the pod documentation
459under C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same
460under C<$INST_TOP\$INST_VER\lib\pod\html>.
461
462To use the Perl you just installed you will need to add a new entry to
463your PATH environment variable: C<$INST_TOP\bin>, e.g.
464
465    set PATH=c:\perl\bin;%PATH%
466
467If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
468then the installation structure is a little more complicated and you will
469need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
470C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
471
472    set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
473
474=head2 Usage Hints for Perl on Windows
475
476=over 4
477
478=item Environment Variables
479
480The installation paths that you set during the build get compiled
481into perl, so you don't have to do anything additional to start
482using that perl (except add its location to your PATH variable).
483
484If you put extensions in unusual places, you can set PERL5LIB
485to a list of paths separated by semicolons where you want perl
486to look for libraries.  Look for descriptions of other environment
487variables you can set in L<perlrun>.
488
489You can also control the shell that perl uses to run system() and
490backtick commands via PERL5SHELL.  See L<perlrun>.
491
492Perl does not depend on the registry, but it can look up certain default
493values if you choose to put them there unless disabled at build time with
494USE_NO_REGISTRY.  On Perl process start Perl checks if
495C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>
496exist.  If the keys exists, they will be checked for remainder of the Perl
497process's run life for certain entries.  Entries in
498C<HKEY_CURRENT_USER\Software\Perl> override entries in
499C<HKEY_LOCAL_MACHINE\Software\Perl>.  One or more of the following entries
500(of type REG_SZ or REG_EXPAND_SZ) may be set in the keys:
501
502 lib-$]        version-specific standard library path to add to @INC
503 lib           standard library path to add to @INC
504 sitelib-$]    version-specific site library path to add to @INC
505 sitelib       site library path to add to @INC
506 vendorlib-$]  version-specific vendor library path to add to @INC
507 vendorlib     vendor library path to add to @INC
508 PERL*         fallback for all %ENV lookups that begin with "PERL"
509
510Note the C<$]> in the above is not literal.  Substitute whatever version
511of perl you want to honor that entry, e.g. C<5.6.0>.  Paths must be
512separated with semicolons, as usual on Windows.
513
514=item File Globbing
515
516By default, perl handles file globbing using the File::Glob extension,
517which provides portable globbing.
518
519If you want perl to use globbing that emulates the quirks of DOS
520filename conventions, you might want to consider using File::DosGlob
521to override the internal glob() implementation.  See L<File::DosGlob> for
522details.
523
524=item Using perl from the command line
525
526If you are accustomed to using perl from various command-line
527shells found in UNIX environments, you will be less than pleased
528with what Windows offers by way of a command shell.
529
530The crucial thing to understand about the Windows environment is that
531the command line you type in is processed twice before Perl sees it.
532First, your command shell (usually CMD.EXE) preprocesses the command
533line, to handle redirection, environment variable expansion, and
534location of the executable to run. Then, the perl executable splits
535the remaining command line into individual arguments, using the
536C runtime library upon which Perl was built.
537
538It is particularly important to note that neither the shell nor the C
539runtime do any wildcard expansions of command-line arguments (so
540wildcards need not be quoted).  Also, the quoting behaviours of the
541shell and the C runtime are rudimentary at best (and may, if you are
542using a non-standard shell, be inconsistent).  The only (useful) quote
543character is the double quote (").  It can be used to protect spaces
544and other special characters in arguments.
545
546The Windows documentation describes the shell parsing rules here:
547L<https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmd>
548and the C runtime parsing rules here:
549L<https://msdn.microsoft.com/en-us/library/17w5ykft%28v=VS.100%29.aspx>.
550
551Here are some further observations based on experiments: The C runtime
552breaks arguments at spaces and passes them to programs in argc/argv.
553Double quotes can be used to prevent arguments with spaces in them from
554being split up.  You can put a double quote in an argument by escaping
555it with a backslash and enclosing the whole argument within double quotes.
556The backslash and the pair of double quotes surrounding the argument will
557be stripped by the C runtime.
558
559The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
560double quotes (although there are suggestions that this may not always
561be true).  Single quotes are not treated as quotes by the shell or
562the C runtime, they don't get stripped by the shell (just to make
563this type of quoting completely useless).  The caret "^" has also
564been observed to behave as a quoting character, but this appears
565to be a shell feature, and the caret is not stripped from the command
566line, so Perl still sees it (and the C runtime phase does not treat
567the caret as a quote character).
568
569Here are some examples of usage of the "cmd" shell:
570
571This prints two doublequotes:
572
573    perl -e "print '\"\"' "
574
575This does the same:
576
577    perl -e "print \"\\\"\\\"\" "
578
579This prints "bar" and writes "foo" to the file "blurch":
580
581    perl -e "print 'foo'; print STDERR 'bar'" > blurch
582
583This prints "foo" ("bar" disappears into nowhereland):
584
585    perl -e "print 'foo'; print STDERR 'bar'" 2> nul
586
587This prints "bar" and writes "foo" into the file "blurch":
588
589    perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
590
591This pipes "foo" to the "less" pager and prints "bar" on the console:
592
593    perl -e "print 'foo'; print STDERR 'bar'" | less
594
595This pipes "foo\nbar\n" to the less pager:
596
597    perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
598
599This pipes "foo" to the pager and writes "bar" in the file "blurch":
600
601    perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
602
603
604Discovering the usefulness of the "command.com" shell on Windows 9x
605is left as an exercise to the reader :)
606
607One particularly pernicious problem with the 4NT command shell for
608Windows is that it (nearly) always treats a % character as indicating
609that environment variable expansion is needed.  Under this shell, it is
610therefore important to always double any % characters which you want
611Perl to see (for example, for hash variables), even when they are
612quoted.
613
614=item Building Extensions
615
616The Comprehensive Perl Archive Network (CPAN) offers a wealth
617of extensions, some of which require a C compiler to build.
618Look in L<https://www.cpan.org/> for more information on CPAN.
619
620Note that not all of the extensions available from CPAN may work
621in the Windows environment; you should check the information at
622L<https://www.cpantesters.org/> before investing too much effort into
623porting modules that don't readily build.
624
625Most extensions (whether they require a C compiler or not) can
626be built, tested and installed with the standard mantra:
627
628    perl Makefile.PL
629    $MAKE
630    $MAKE test
631    $MAKE install
632
633where $MAKE is whatever 'make' program you have configured perl to
634use.  Use "perl -V:make" to find out what this is.  Some extensions
635may not provide a testsuite (so "$MAKE test" may not do anything or
636fail), but most serious ones do.
637
638It is important that you use a supported 'make' program, and
639ensure Config.pm knows about it.
640
641Note that MakeMaker actually emits makefiles with different syntax
642depending on what 'make' it thinks you are using.  Therefore, it is
643important that one of the following values appears in Config.pm:
644
645    make='nmake'	# MakeMaker emits nmake syntax
646    any other value	# MakeMaker emits generic make syntax
647    			    (e.g GNU make, or Perl make)
648
649If the value doesn't match the 'make' program you want to use,
650edit Config.pm to fix it.
651
652If a module implements XSUBs, you will need one of the supported
653C compilers.  You must make sure you have set up the environment for
654the compiler for command-line compilation before running C<perl Makefile.PL>
655or any invocation of make.
656
657If a module does not build for some reason, look carefully for
658why it failed, and report problems to the module author.  If
659it looks like the extension building support is at fault, report
660that with full details of how the build failed using the GitHub
661issue tracker at L<https://github.com/Perl/perl5/issues>.
662
663=item Command-line Wildcard Expansion
664
665The default command shells on DOS descendant operating systems (such
666as they are) usually do not expand wildcard arguments supplied to
667programs.  They consider it the application's job to handle that.
668This is commonly achieved by linking the application (in our case,
669perl) with startup code that the C runtime libraries usually provide.
670However, doing that results in incompatible perl versions (since the
671behavior of the argv expansion code differs depending on the
672compiler, and it is even buggy on some compilers).  Besides, it may
673be a source of frustration if you use such a perl binary with an
674alternate shell that *does* expand wildcards.
675
676Instead, the following solution works rather well. The nice things
677about it are 1) you can start using it right away; 2) it is more
678powerful, because it will do the right thing with a pattern like
679*/*/*.c; 3) you can decide whether you do/don't want to use it; and
6804) you can extend the method to add any customizations (or even
681entirely different kinds of wildcard expansion).
682
683 C:\> copy con c:\perl\lib\Wild.pm
684 # Wild.pm - emulate shell @ARGV expansion on shells that don't
685 use File::DosGlob;
686 @ARGV = map {
687	      my @g = File::DosGlob::glob($_) if /[*?]/;
688	      @g ? @g : $_;
689	    } @ARGV;
690 1;
691 ^Z
692 C:\> set PERL5OPT=-MWild
693 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
694 p4view/perl/perl.c
695 p4view/perl/perlio.c
696 p4view/perl/perly.c
697 perl5.005/win32/perlglob.c
698 perl5.005/win32/perllib.c
699 perl5.005/win32/perlglob.c
700 perl5.005/win32/perllib.c
701 perl5.005/win32/perlglob.c
702 perl5.005/win32/perllib.c
703
704Note there are two distinct steps there: 1) You'll have to create
705Wild.pm and put it in your perl lib directory. 2) You'll need to
706set the PERL5OPT environment variable.  If you want argv expansion
707to be the default, just set PERL5OPT in your default startup
708environment.
709
710If you are using the Visual C compiler, you can get the C runtime's
711command line wildcard expansion built into perl binary.  The resulting
712binary will always expand unquoted command lines, which may not be
713what you want if you use a shell that does that for you.  The expansion
714done is also somewhat less powerful than the approach suggested above.
715
716=item Notes on 64-bit Windows
717
718Windows .NET Server supports the LLP64 data model on the Intel Itanium
719architecture.
720
721The LLP64 data model is different from the LP64 data model that is the
722norm on 64-bit Unix platforms.  In the former, C<int> and C<long> are
723both 32-bit data types, while pointers are 64 bits wide.  In addition,
724there is a separate 64-bit wide integral type, C<__int64>.  In contrast,
725the LP64 data model that is pervasive on Unix platforms provides C<int>
726as the 32-bit type, while both the C<long> type and pointers are of
72764-bit precision.  Note that both models provide for 64-bits of
728addressability.
729
73064-bit Windows running on Itanium is capable of running 32-bit x86
731binaries transparently.  This means that you could use a 32-bit build
732of Perl on a 64-bit system.  Given this, why would one want to build
733a 64-bit build of Perl?  Here are some reasons why you would bother:
734
735=over
736
737=item *
738
739A 64-bit native application will run much more efficiently on
740Itanium hardware.
741
742=item *
743
744There is no 2GB limit on process size.
745
746=item *
747
748Perl automatically provides large file support when built under
74964-bit Windows.
750
751=item *
752
753Embedding Perl inside a 64-bit application.
754
755=back
756
757=back
758
759=head2 Running Perl Scripts
760
761Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
762indicate to the OS that it should execute the file using perl.
763Windows has no comparable means to indicate arbitrary files are
764executables.
765
766Instead, all available methods to execute plain text files on
767Windows rely on the file "extension".  There are three methods
768to use this to execute perl scripts:
769
770=over 8
771
772=item 1
773
774There is a facility called "file extension associations".  This can be
775manipulated via the two commands "assoc" and "ftype" that come
776standard with Windows.  Type "ftype /?" for a complete example of how
777to set this up for perl scripts (Say what?  You thought Windows
778wasn't perl-ready? :).
779
780=item 2
781
782Since file associations don't work everywhere, and there are
783reportedly bugs with file associations where it does work, the
784old method of wrapping the perl script to make it look like a
785regular batch file to the OS, may be used.  The install process
786makes available the "pl2bat.bat" script which can be used to wrap
787perl scripts into batch files.  For example:
788
789	pl2bat foo.pl
790
791will create the file "FOO.BAT".  Note "pl2bat" strips any
792.pl suffix and adds a .bat suffix to the generated file.
793
794If you use the 4DOS/NT or similar command shell, note that
795"pl2bat" uses the "%*" variable in the generated batch file to
796refer to all the command line arguments, so you may need to make
797sure that construct works in batch files.  As of this writing,
7984DOS/NT users will need a "ParameterChar = *" statement in their
7994NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
800startup file to enable this to work.
801
802=item 3
803
804Using "pl2bat" has a few problems:  the file name gets changed,
805so scripts that rely on C<$0> to find what they must do may not
806run properly; running "pl2bat" replicates the contents of the
807original script, and so this process can be maintenance intensive
808if the originals get updated often.  A different approach that
809avoids both problems is possible.
810
811A script called "runperl.bat" is available that can be copied
812to any filename (along with the .bat suffix).  For example,
813if you call it "foo.bat", it will run the file "foo" when it is
814executed.  Since you can run batch files on Windows platforms simply
815by typing the name (without the extension), this effectively
816runs the file "foo", when you type either "foo" or "foo.bat".
817With this method, "foo.bat" can even be in a different location
818than the file "foo", as long as "foo" is available somewhere on
819the PATH.  If your scripts are on a filesystem that allows symbolic
820links, you can even avoid copying "runperl.bat".
821
822Here's a diversion:  copy "runperl.bat" to "runperl", and type
823"runperl".  Explain the observed behavior, or lack thereof. :)
824Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
825
826=back
827
828=head2 Miscellaneous Things
829
830A full set of HTML documentation is installed, so you should be
831able to use it if you have a web browser installed on your
832system.
833
834C<perldoc> is also a useful tool for browsing information contained
835in the documentation, especially in conjunction with a pager
836like C<less> (recent versions of which have Windows support).  You may
837have to set the PAGER environment variable to use a specific pager.
838"perldoc -f foo" will print information about the perl operator
839"foo".
840
841One common mistake when using this port with a GUI library like C<Tk>
842is assuming that Perl's normal behavior of opening a command-line
843window will go away.  This isn't the case.  If you want to start a copy
844of C<perl> without opening a command-line window, use the C<wperl>
845executable built during the installation process.  Usage is exactly
846the same as normal C<perl> on Windows, except that options like C<-h>
847don't work (since they need a command-line window to print to).
848
849If you find bugs in perl, you can report them to
850L<https://github.com/Perl/perl5/issues>.
851
852=head1 BUGS AND CAVEATS
853
854Norton AntiVirus interferes with the build process, particularly if
855set to "AutoProtect, All Files, when Opened". Unlike large applications
856the perl build process opens and modifies a lot of files. Having the
857AntiVirus scan each and every one slows build the process significantly.
858Worse, with PERLIO=stdio the build process fails with peculiar messages
859as the virus checker interacts badly with miniperl.exe writing configure
860files (it seems to either catch file part written and treat it as suspicious,
861or virus checker may have it "locked" in a way which inhibits miniperl
862updating it). The build does complete with
863
864   set PERLIO=perlio
865
866but that may be just luck. Other AntiVirus software may have similar issues.
867
868A git GUI shell extension for Windows such as TortoiseGit will cause the build
869and later C<make test> to run much slower since every file is checked for its
870git status as soon as it is created and/or modified. TortoiseGit doesn't cause
871any test failures or build problems unlike the antivirus software described
872above, but it does cause similar slowness. It is suggested to use Task Manager
873to look for background processes which use high CPU amounts during the building
874process.
875
876Some of the built-in functions do not act exactly as documented in
877L<perlfunc>, and a few are not implemented at all.  To avoid
878surprises, particularly if you have had prior exposure to Perl
879in other operating environments or if you intend to write code
880that will be portable to other environments, see L<perlport>
881for a reasonably definitive list of these differences.
882
883Not all extensions available from CPAN may build or work properly
884in the Windows environment.  See L</"Building Extensions">.
885
886Most C<socket()> related calls are supported, but they may not
887behave as on Unix platforms.  See L<perlport> for the full list.
888
889Signal handling may not behave as on Unix platforms (where it
890doesn't exactly "behave", either :).  For instance, calling C<die()>
891or C<exit()> from signal handlers will cause an exception, since most
892implementations of C<signal()> on Windows are severely crippled.
893Thus, signals may work only for simple things like setting a flag
894variable in the handler.  Using signals under this port should
895currently be considered unsupported.
896
897Please report detailed descriptions of any problems and solutions that
898you may find at E<lt>L<https://github.com/Perl/perl5/issues>E<gt>,
899along with the output produced by C<perl -V>.
900
901=head1 ACKNOWLEDGEMENTS
902
903The use of a camel with the topic of Perl is a trademark
904of O'Reilly and Associates, Inc. Used with permission.
905
906=head1 AUTHORS
907
908=over 4
909
910=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
911
912=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
913
914=item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
915
916=item Jan Dubois E<lt>jand@activestate.comE<gt>
917
918=item Steve Hay E<lt>steve.m.hay@googlemail.comE<gt>
919
920=back
921
922This document is maintained by Jan Dubois.
923
924=head1 SEE ALSO
925
926L<perl>
927
928=head1 HISTORY
929
930This port was originally contributed by Gary Ng around 5.003_24,
931and borrowed from the Hip Communications port that was available
932at the time.  Various people have made numerous and sundry hacks
933since then.
934
935GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
936
937Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
938
939Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
940
941Win9x support was added in 5.6 (Benjamin Stuhl).
942
943Support for 64-bit Windows added in 5.8 (ActiveState Corp).
944
945Last updated: 26 January 2020
946
947=cut
948