Initial Commit

database/perl/lib/pods/perlqnx.pod

@@ -0,0 +1,204 @@
+If you read this file _as_is_, just ignore the funny characters you see.
+It is written in the POD format (see pod/perlpod.pod) which is specially
+designed to be readable as is.
+
+=head1 NAME
+
+perlqnx - Perl version 5 on QNX
+
+=head1 DESCRIPTION
+
+As of perl5.7.2 all tests pass under:
+
+  QNX 4.24G
+  Watcom 10.6 with Beta/970211.wcc.update.tar.F
+  socket3r.lib Nov21 1996.
+
+As of perl5.8.1 there is at least one test still failing.
+
+Some tests may complain under known circumstances.
+
+See below and hints/qnx.sh for more information.
+
+Under QNX 6.2.0 there are still a few tests which fail.
+See below and hints/qnx.sh for more information.
+
+=head2 Required Software for Compiling Perl on QNX4
+
+As with many unix ports, this one depends on a few "standard"
+unix utilities which are not necessarily standard for QNX4.
+
+=over 4
+
+=item /bin/sh
+
+This is used heavily by Configure and then by
+perl itself. QNX4's version is fine, but Configure
+will choke on the 16-bit version, so if you are
+running QNX 4.22, link /bin/sh to /bin32/ksh
+
+=item ar
+
+This is the standard unix library builder.
+We use wlib. With Watcom 10.6, when wlib is
+linked as "ar", it behaves like ar and all is
+fine. Under 9.5, a cover is required. One is
+included in ../qnx
+
+=item nm
+
+This is used (optionally) by configure to list
+the contents of libraries. I will generate
+a cover function on the fly in the UU directory.
+
+=item cpp
+
+Configure and perl need a way to invoke a C
+preprocessor. I have created a simple cover
+for cc which does the right thing. Without this,
+Configure will create its own wrapper which works,
+but it doesn't handle some of the command line arguments
+that perl will throw at it.
+
+=item make
+
+You really need GNU make to compile this. GNU make
+ships by default with QNX 4.23, but you can get it
+from quics for earlier versions.
+
+=back
+
+=head2 Outstanding Issues with Perl on QNX4
+
+There is no support for dynamically linked libraries in QNX4.
+
+If you wish to compile with the Socket extension, you need
+to have the TCP/IP toolkit, and you need to make sure that
+-lsocket locates the correct copy of socket3r.lib. Beware
+that the Watcom compiler ships with a stub version of
+socket3r.lib which has very little functionality. Also
+beware the order in which wlink searches directories for
+libraries. You may have /usr/lib/socket3r.lib pointing to
+the correct library, but wlink may pick up
+/usr/watcom/10.6/usr/lib/socket3r.lib instead. Make sure
+they both point to the correct library, that is,
+/usr/tcptk/current/usr/lib/socket3r.lib.
+
+The following tests may report errors under QNX4:
+
+dist/Cwd/Cwd.t will complain if `pwd` and cwd don't give
+the same results. cwd calls `fullpath -t`, so if you
+cd `fullpath -t` before running the test, it will
+pass.
+
+lib/File/Find/taint.t will complain if '.' is in your
+PATH. The PATH test is triggered because cwd calls
+`fullpath -t`.
+
+ext/IO/lib/IO/t/io_sock.t: Subtests 14 and 22 are skipped due to
+the fact that the functionality to read back the non-blocking
+status of a socket is not implemented in QNX's TCP/IP. This has
+been reported to QNX and it may work with later versions of
+TCP/IP.
+
+t/io/tell.t: Subtest 27 is failing. We are still investigating.
+
+=head2 QNX auxiliary files
+
+The files in the "qnx" directory are:
+
+=over 4
+
+=item qnx/ar
+
+A script that emulates the standard unix archive (aka library)
+utility.  Under Watcom 10.6, ar is linked to wlib and provides the
+expected interface. With Watcom 9.5, a cover function is
+required. This one is fairly crude but has proved adequate for
+compiling perl.
+
+=item qnx/cpp
+
+A script that provides C preprocessing functionality.  Configure can
+generate a similar cover, but it doesn't handle all the command-line
+options that perl throws at it. This might be reasonably placed in
+/usr/local/bin.
+
+=back
+
+=head2 Outstanding issues with perl under QNX6
+
+The following tests are still failing for Perl 5.8.1 under QNX 6.2.0:
+
+  op/sprintf.........................FAILED at test 91
+  lib/Benchmark......................FAILED at test 26
+
+This is due to a bug in the C library's printf routine.
+printf("'%e'", 0. ) produces '0.000000e+0', but ANSI requires
+'0.000000e+00'. QNX has acknowledged the bug.
+
+=head2 Cross-compilation
+
+Perl supports cross-compiling to QNX NTO through the
+Native Development Kit (NDK) for the Blackberry 10.  This means that you
+can cross-compile for both ARM and x86 versions of the platform.
+
+=head3 Setting up a cross-compilation environment
+
+You can download the NDK from
+L<http://developer.blackberry.com/native/downloads/>.
+
+See
+L<http://developer.blackberry.com/native/documentation/cascades/getting_started/setting_up.html>
+for instructions to set up your device prior to attempting anything else.
+
+Once you've installed the NDK and set up your device, all that's
+left to do is setting up the device and the cross-compilation
+environment.  Blackberry provides a script, C<bbndk-env.sh> (occasionally
+named something like C<bbndk-env_10_1_0_4828.sh>) which can be used
+to do this.  However, there's a bit of a snag that we have to work through:
+The script modifies PATH so that 'gcc' or 'ar' point to their
+cross-compilation equivalents, which screws over the build process.
+
+So instead you'll want to do something like this:
+
+    $ orig_path=$PATH
+    $ source $location_of_bbndk/bbndk-env*.sh
+    $ export PATH="$orig_path:$PATH"
+
+Besides putting the cross-compiler and the rest of the toolchain in your
+PATH, this will also provide the QNX_TARGET variable, which
+we will pass to Configure through -Dsysroot.
+
+=head3 Preparing the target system
+
+It's quite possible that the target system doesn't have a readily
+available /tmp, so it's generall safer to do something like this:
+
+ $ ssh $TARGETUSER@$TARGETHOST 'rm -rf perl; mkdir perl; mkdir perl/tmp'
+ $ export TARGETDIR=`ssh $TARGETUSER@$TARGETHOST pwd`/perl
+ $ export TARGETENV="export TMPDIR=$TARGETDIR/tmp; "
+
+Later on, we'll pass this to Configure through -Dtargetenv
+
+=head3 Calling Configure
+
+If you are targetting an ARM device -- which currently includes the vast 
+majority of phones and tablets -- you'll want to pass
+-Dcc=arm-unknown-nto-qnx8.0.0eabi-gcc to Configure.  Alternatively, if you 
+are targetting an x86 device, or using the simulator provided with the NDK,
+you should specify -Dcc=ntox86-gcc instead.
+
+A sample Configure invocation looks something like this:
+
+    ./Configure -des -Dusecrosscompile \
+        -Dsysroot=$QNX_TARGET          \
+        -Dtargetdir=$TARGETDIR         \
+        -Dtargetenv="$TARGETENV"       \
+        -Dcc=ntox86-gcc                \
+        -Dtarghost=... # Usual cross-compilation options
+
+=head1 AUTHOR
+
+Norton T. Allen (allen@huarp.harvard.edu)
+