Plan a Perl QNX Build Without Mistaking perlqnx for a Command

You will finish with a checked build plan for Perl on QNX, including the toolchain, target temporary directory and Configure settings that the installed perlqnx(1) documentation describes. The first fact to establish is easy to miss: perlqnx is a manpage, not a program you run to launch Perl or configure a host.

Allow about 20 minutes for the read-only checks and planning. A real build needs a QNX development host or a separately installed QNX Native Development Kit, a Perl source tree and access to a target device or simulator. This guide does not install a toolchain, change a target, or run a cross-compiled binary.

The local manpage was generated with Perl v5.38.2 and is supplied by perl-doc version 5.38.2-3.2ubuntu0.6. Its QNX 4 test notes refer to Perl 5.7.2 and 5.8.1, and its QNX 6 notes refer to Perl 5.8.1 on QNX 6.2.0. Treat those test results as historical compatibility notes, not as a promise for a modern QNX release.

1. Confirm what is installed

Start with ordinary, read-only commands on the build machine:

$ command -v perlqnx || true
$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6
$ man -w perlqnx
/usr/share/man/man1/perlqnx.1.gz

There may be no output from command -v perlqnx. That is expected. The useful executable names in this document are build tools such as Configure, make, ar and the C compiler. The manpage itself explains how Perl has been ported to QNX and what the old port expects.

Checkpoint: if man -w perlqnx fails, the documentation package is not installed on this host. Install it through your normal package-management process, or read the official Perl documentation at perldoc.perl.org/perlqnx. Do not substitute a similarly named binary.

2. Choose the QNX generation before choosing tools

The manpage describes two different families of work. QNX 4 uses Watcom tooling and expects Unix-like utilities that may not be standard there. QNX 6.2.0 has separate test caveats. The cross-compilation section targets QNX Neutrino through the Blackberry 10 Native Development Kit, for ARM or x86 devices.

Write down these three facts before touching a source tree:

• The exact QNX release and target architecture.
• Whether you are compiling on the target or cross-compiling from another host.
• The NDK or compiler package version that supplies the target compiler and sysroot.

Do not use the QNX 4 instructions for a Neutrino target. They mention Watcom 10.6, wlib and socket3r.lib; those are not generic Linux build prerequisites. Likewise, do not infer modern support from the old statement that tests passed on QNX 4.24G.

Checkpoint: keep the exact source version beside this plan. The installed page is from Perl 5.38.2, but the compatibility paragraphs describe much older releases. Read the source tree's INSTALL file for the Perl release you actually intend to build.

3. Check the QNX 4 prerequisites if that is your target

For a QNX 4 build, the page calls out /bin/sh, ar, nm, cpp and GNU make. Check them on the QNX build host, not on an unrelated Linux workstation:

$ command -v sh ar nm cpp make
$ make --version | sed -n '1p'

On QNX 4.22, the documented workaround is to link /bin/sh to /bin32/ksh because Configure cannot use the 16-bit shell. That is a system-wide change. Warn the machine owner and take a recovery copy of the existing link before changing it. A safer first check is simply:

$ ls -l /bin/sh /bin32/ksh

For Watcom 10.6, the page says ar can be linked to wlib. With Watcom 9.5 it describes a cover script. The Perl source repository keeps QNX helper files such as qnx/ar and qnx/cpp; inspect those files and place copies in a project-local directory before considering a system-wide installation.

Do not overwrite an existing ar, cpp or shell link as a trial. If a wrapper is needed, put it first in a temporary build PATH, record the old value, and remove that directory from PATH to undo the test.

4. Prepare a cross-compile environment without losing host tools

For the QNX NDK workflow described by the page, source the vendor environment script, but preserve the original PATH. The reason is practical: the script may make gcc or ar resolve to cross tools, which can confuse parts of the build process that must use host utilities.

orig_path=$PATH
source /path/to/ndk/bbndk-env.sh
export PATH="$orig_path:$PATH"
printf 'QNX_TARGET=%s\n' "$QNX_TARGET"
command -v gcc
command -v ar

Replace /path/to/ndk/bbndk-env.sh with the real path. The shell variables affect this shell and its children only. To undo them, close the shell or start a fresh one. Do not add them to a global profile until you have proved which compiler each command resolves to.

For an ARM target, the manpage gives arm-unknown-nto-qnx8.0.0eabi-gcc as the compiler name. For an x86 target or simulator, it gives ntox86-gcc. Verify the names supplied by your installed NDK before using them:

command -v arm-unknown-nto-qnx8.0.0eabi-gcc || true
command -v ntox86-gcc || true
test -n "$QNX_TARGET" && test -d "$QNX_TARGET" && printf '%s\n' 'sysroot is present'

5. Give the target a private temporary directory

The documented cross-build expects a target directory and a target temporary directory. This matters when the target has no usable /tmp. The example below changes target state and therefore needs an account with permission to create the directories. Do not paste it until TARGETHOST and TARGETUSER identify the intended device:

ssh TARGETUSER@TARGETHOST 'mkdir -p perl/tmp'
export TARGETDIR="$(ssh TARGETUSER@TARGETHOST pwd)/perl"
export TARGETENV="export TMPDIR=$TARGETDIR/tmp; "
printf 'TARGETDIR=%s\nTARGETENV=%s\n' "$TARGETDIR" "$TARGETENV"

This uses mkdir -p, so it does not remove an existing directory. If you need to abandon the attempt, remove only the exact directory you created after checking it with ssh TARGETUSER@TARGETHOST 'ls -ld perl perl/tmp'. Do not use the older manpage example's rm -rf perl unless you have positively confirmed that the path contains only disposable build data. That command is irreversible through the shell.

6. Run Configure with explicit target settings

From the top of the matching Perl source tree, the page's shape is:

./Configure -des -Dusecrosscompile \
    -Dsysroot="$QNX_TARGET" \
    -Dtargetdir="$TARGETDIR" \
    -Dtargetenv="$TARGETENV" \
    -Dcc=ntox86-gcc \
    -Dtarghost=...

Replace ntox86-gcc with the compiler for your target. The ellipsis is not a value to paste: it stands for the other cross-compilation options required by the source release and NDK. Read that release's INSTALL and inspect Configure's questions before accepting defaults. Never point -Dsysroot at a host directory merely because it exists.

Keep the Configure output. A failed probe is useful evidence, while a successful Configure run does not prove that the target can execute the result. Build and test only after confirming the compiler, sysroot, target directory and temporary directory all refer to the same target.

7. Interpret tests and stop at known port limitations

The old QNX 4 notes explain several expected failures: a current-directory test can differ from pwd, a taint test can complain when . is in PATH, non-blocking socket status may not be readable, and one tell subtest was still failing. For QNX 6.2.0, the page records failures in op/sprintf and lib/Benchmark caused by the C library's exponential-format output.

Record the Perl release, QNX release, compiler, NDK and complete test output beside each failure. Do not mark a build healthy just because the failures resemble the historical list. A different failure, a changed target library or a missing target-side temporary directory needs investigation.