Build and Test Native Perl on Windows with perlwin32

This guide takes you from an extracted Perl source tree to a tested installation on Windows. It follows the native Windows build described by the installed perlwin32(1) manual, rather than the separate Cygwin route. Allow at least 30 minutes for setup and compilation, plus the time needed to download a compiler.

The local manual is from perl-doc 5.38.2 and is dated 14 September 2026. Its compiler examples include Visual C++ 2013 to 2022 and MinGW variants. The current online Perl documentation may describe a different release, so check the makefile shipped with your source tree before copying a version-specific value.

1. Prepare a clean Windows source tree

Extract the Perl source into a short path with no spaces, such as C:\src\perl-5.38.2. The build normally works in a path containing spaces, but the manual warns that some tests can fail there. Use the native cmd.exe shell while building and testing. Alternative shells can change parsing or replace Windows tools.

Read the source tree's top-level README and its licence terms first. You can ignore Unix-only instructions about Configure for this native port. If you specifically need a more Unix-compatible environment, stop here and read README.cygwin instead.

2. Choose the compiler and make program

Choose one supported pair before editing anything. Visual C++ uses nmake and the supplied win32\Makefile. GCC uses GNU make, often named gmake or mingw32-make.exe, and the supplied win32\GNUmakefile. nmake is not supported for GCC builds. Parallel jobs are supported by GNU make, not by nmake.

For Visual C++, start a developer command prompt for the target architecture, or run the appropriate environment batch file. The manual gives vcvarsall.bat x86 for 32-bit builds and vcvarsall.bat amd64 for 64-bit builds. For the compiler shipped with the documented Visual C++ 2013 to 2022 Community editions, set CCTYPE in win32\Makefile to the matching value from MSVC120 through MSVC143.

For MinGW or MinGW-w64, install GCC and GNU make from the project you selected. The local manual records compatibility limits, including failures with some newer MinGW versions, so do not assume that the newest compiler is the right one. A cross-compiler needs the GCCCROSS setting only when its bin directory lacks an ordinary gcc.exe.

Check the tools from the same prompt you will use for the build:

where nmake
where gmake
where gcc
where cl

Expected output is one path for each tool you intend to use. A missing command means the compiler environment is not ready; it is not a reason to edit the makefile blindly.

3. Set an isolated installation target

Change INST_DRV and INST_TOP in the selected makefile to a new target. For example, use C: for INST_DRV and \perl-build\5.38.2 for INST_TOP, or follow the exact syntax already present in your makefile.

Use a target that does not already contain another Perl build. Reusing an old installation can make lib\ExtUtils\t\Embed.t compile against the wrong lib\CORE directory. This is a correctness trap, not merely untidy output. If you need to discard an old test target, stop and inspect it first; do not remove a directory containing a Perl installation you still use.

Also verify CCTYPE and CCHOME. For GCC, CCHOME must point to the directory containing the compiler's bin, include and lib directories. Leave optional settings such as STATIC_EXT alone unless you have a specific extension to build into the Perl DLL.

4. Build from the win32 directory

Change to the Windows build directory:

cd /d C:\src\perl-5.38.2\win32

Run the make command matching your compiler:

gmake
nmake

Run only the applicable line. GNU make can use a small number of parallel jobs after the first serial build has succeeded:

gmake -j2

After a successful build, the manual says to expect perl.exe and a versioned Perl DLL at the source-tree top level, plus extension DLLs below lib\auto. Confirm the executable before moving on:

cd ..
perl.exe -v

The version printed should identify the source release you intended to build. If the command instead runs an older Perl from PATH, call the freshly built executable by its full path and fix the prompt before testing.

5. Run the test suite and investigate failures

From win32, run the matching test target:

gmake test
nmake test

The native suite runs most tests and skips some. The normal result is no test failures. Do not install a build merely because compilation completed.

If the test environment is an Emacs shell, use gmake test-notty where GNU make is in use. Remove Unix utility packages from PATH while testing: the manual specifically warns that replacements such as a Unix type command can alter results. A path containing spaces or a non-native shell can also create misleading failures.

For a focused failure, run the harness from the source-tree t directory as directed by the manual:

cd ..\t
..\win32\perl harness <test-name>

Compiler-specific failures have known explanations. Visual C++ 2013 can show daylight-saving-time failures in three tests; later Visual C++ releases avoid that particular CRT problem. Some MinGW versions can fail a POSIX time test. Record the compiler, make program, shell, source version and complete failing output before reporting a failure that does not match a documented caveat.

6. Install into the target and verify PATH

gmake install
nmake install

Use the same make variant as before. The files go below the INST_TOP selected in the makefile, including Perl libraries and documentation. Add its bin directory to the current prompt for a reversible trial:

set PATH=C:\perl-build\5.38.2\bin;%PATH%
where perl
perl -v

The first path from where perl should be the new installation, and perl -v should report the intended version. If it is wrong, close the prompt to undo this temporary set PATH change, then correct the target or PATH order before making a persistent environment change.

7. Build a Perl extension without mixing toolchains

For an extension that uses MakeMaker, keep the compiler environment active and check which make Perl expects:

perl -V:make
perl Makefile.PL
gmake
gmake test

Replace gmake with the make program reported by perl -V:make; a Perl configured for nmake emits different makefile syntax. XSUB extensions also need the compiler environment configured before perl Makefile.PL. Run the install step only after the extension tests pass:

gmake install

Some CPAN extensions do not support Windows or do not provide useful tests. Check the module's own documentation and CPAN Testers before treating a module-specific failure as a failure of the Perl build.