README.qnx

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