This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
regcomp.c: Remove memory leak
[perl5.git] / README.qnx
... / ...
CommitLineData
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