Build and test custom Perl on Cygwin with its port caveats

You will finish with a locally built Perl on Cygwin, a log for each build stage, and a test result you can investigate rather than merely a green or red command prompt. Allow 30 to 60 minutes for a first build, plus longer if optional libraries or a test failure need attention.

This guide is for building from a Perl source tree. Cygwin already supplies a Perl package, so use that package when you do not need a customised build. The local perlcygwin manual is installed with Perl v5.38.2 and carries port information last updated on 14 November 2019. Its Cygwin notes are useful, but some details are version-specific: check your current Cygwin release before treating an old example as a current default.

1. Check the build environment

Run these ordinary, read-only checks inside a Cygwin terminal. Do not use a Windows Command Prompt for the build commands. You need a recent Cygwin installation, its development tools, Perl source, and enough disk space for the source, objects and logs.

$ uname -a
$ command -v sh make gcc Configure nroff
$ perl -v
$ printf 'PATH=%s\n' "$PATH"

The important result is that Cygwin's versions of the tools are found. The manual specifically warns that Windows directories can cause Configure to select the wrong programs; remove unnecessary Windows entries or move them after the Cygwin entries for this shell session. If nroff is missing, Configure will not offer to install man pages. That is a documentation gap, not necessarily a failed Perl build.

2. Keep the source and build outputs separate

Change to the directory containing the Perl source and use the recommended -Dmksymlinks option so the build can happen outside the source tree. Replace the example paths with directories you own. This changes files under the build directory, so do not point it at a directory containing unrelated work.

$ mkdir -p "$HOME/build/perl-cygwin"
$ cd "$HOME/build/perl-cygwin"
$ /path/to/perl-source/Configure -Dmksymlinks

Configure asks questions about the installation and feature set. Read each prompt. Accepting defaults is the simplest route; -de tells Configure to accept all defaults without prompting, but it is less useful when you are checking a new environment. Keep the transcript in a file so a later failure has context.

$ /path/to/perl-source/Configure -Dmksymlinks 2>&1 | tee log.configure
$ test -s log.configure && echo 'Configure log recorded'

The pipeline's visible status is normally tee's status, not Configure's. If a failed Configure matters to a script, enable Bash's pipeline status handling first and check ${PIPESTATUS[0]}. For an interactive build, inspect the log and the files Configure generated before continuing.

3. Select only options you can support

The Cygwin hints normally enable dynamic loading. Optional libraries add capabilities, but also add dependencies. The manual lists -lcrypt, GDBM compatibility, Berkeley DB and -lutil; the Cygwin installer provides packages for most of them. GDBM and Berkeley DB have NTFS limitations in the port notes, and SysV IPC through cygserver is explicitly marked unsupported there. Do not enable it because a module happens to mention IPC::SysV.

Keep the normal defaults unless you have a tested reason to change them. In particular, PerlIO is the default and disabling it with -Uuseperlio is not recommended. -Uusedl makes a static build, while -Uuseithreads trades threading support for a potentially faster non-threaded Perl. These are build decisions, not runtime switches.

If you want smaller binaries, the documented -s value is entered at the linker prompts, or the corresponding variables can be uncommented in hints/cygwin.sh. Treat that source edit as a deliberate build change and keep it in your build notes.

4. Compile and keep the output

Run make after Configure has completed. The manual uses -jn as a placeholder for the maximum number of simultaneous compilations; omitting it is the same as -j1. Start with one job when diagnosing a problem, then increase it if the machine has capacity.

$ make -j2 2>&1 | tee log.make
$ test -s log.make && echo 'Build log recorded'

Wait for the prompt to return and inspect the end of the log. Do not run make install just because compilation succeeded. Installation writes into the configured Perl directories and may require elevated privileges or write access. First test the uninstalled interpreter from the build tree.

5. Run both test passes

The port documentation describes two passes. The first is the normal Makefile test. The second runs the harness directly and gives more detail. Both exercise the same tests, and both can be affected by the host's Cygwin configuration.

$ make test 2>&1 | tee log.make-test
$ cd t
$ ./perl harness 2>&1 | tee ../log.harness
$ cd ..

For a parallel harness run, set a deliberate limit rather than letting a large machine start an unreviewed number of jobs:

$ cd t
$ TEST_JOBS=2 ./perl harness 2>&1 | tee ../log.harness
$ cd ..

A failed test is not automatically a broken Perl. The manual calls out permission differences, FAT filesystem behaviour, and fork() failures. NDBM_File and ODBM_File do not work correctly on FAT; if the target is FAT-only, the documented Configure options are -Ui_ndbm -Ui_dbm. NTFS is the safer choice for those databases.

6. Verify the Cygwin-specific runtime rules

Cygwin uses forward-slash POSIX paths, and file names are case-insensitive but case-preserving. Convert Windows paths rather than mixing drive letters and backslashes into Perl code. The port supplies conversion functions in the Cygwin module:

$ ./perl -MCygwin -e 'print Cygwin::win_to_posix_path("C:\\Temp\\input.txt"), "\n"'
$ ./perl -MCygwin -e 'print Cygwin::posix_to_win_path("/tmp/input.txt"), "\n"'

PerlIO treats files as binary by default, independently of the mount mode. Request CRLF output explicitly when a Windows consumer requires it:

$ ./perl -e 'open my $fh, ">:crlf", "output.txt" or die $!; print {$fh} "line\n"; close $fh or die $!'
$ od -An -tx1 output.txt

Do not set PERLIO=crlf casually in a shared shell startup file: it applies CRLF conversion to every Perl output from that environment. Remove that export from the startup file to undo it.

The port also has two easy-to-miss behaviours. Cygwin and Windows process IDs differ, so use the Cygwin::pid_to_winpid and Cygwin::winpid_to_pid helpers when crossing that boundary. In-place editing with perl -i automatically gets a .bak backup on Cygwin; preserve that backup until the replacement has been checked, then remove it deliberately if no longer needed.

7. Investigate fork and install only after review

If fork or system reports a DLL remapping or base-address conflict after several DLLs have loaded, stop the test rather than repeatedly launching children. The manual points to Cygwin's fork-failure guidance and the rebase utilities. Rebase changes DLL metadata and can affect other Cygwin programs, so treat it as a system-level repair: close Perl and other Cygwin processes first, read the current Cygwin instructions, and keep a record of what was changed.

When the tests and review are complete, installation is a separate state-changing action:

$ make install 2>&1 | tee log.make-install
$ test -s log.make-install && echo 'Install log recorded'
$ command -v perl
$ perl -V:version

Use an account with write access to the configured destination. Do not use elevated privileges merely to make the build convenient; if the destination is system-owned, review the install prefix and the file list before asking an administrator to perform that final step. To undo a test build, remove its separate build directory. To undo an installation, use the same Perl installation's documented uninstall or package-management process; do not delete a shared prefix by hand.