NAME

perlmaketargets - A guide to Perl's make targets

DESCRIPTION

This document provides an introduction to the make targets you are most likely to use when building perl.

This document should be considered as tips for your work on the core distribution. It is not intended to tie the hands of Perl's maintainers (Perl 5 Porters) as to how perl might be built in the future. This document aspires to convey words of wisdom -- not authoritative pronouncements.

We begin with the most common make targets you will invoke on the command line as you hack on perl. We will then move to other targets which you will either use less frequently or that you will use for more fine-grained concerns. Within each of these two broad groups we will present targets in more of a logical order than alphabetically.

Programming Environment

The tips and examples which follow presume you are in a Unix-like programming environment. They presume that you can execute both shell and Perl programs a the command line, that you have make installed as well as a C-compiler such as gcc, g++ or clang.

We welcome patches which extend this discussion to Windows, VMS and other programming environments.

You can hack on perl either in a git checkout from our repository or in a directory tree created by unpacking a tarball released by Perl 5 Porters (whether that be a monthly development release, an annual production release or a maintenance release). While all the make targets discussed here can be used in either environment, some may be less useful in git checkouts because git commands do a better job.

In what follows we assume that you are in the top-level directory of either a git checkout or an unpacked tarball of the core distribution.

Configuration

make targets are specified in a Makefile, but in Perl, like most other significant software projects, a Makefile is not something which is hard-coded but which is generated dynamically by another program -- in this case the shell script Configure. How to use Configure is described in the INSTALL document which you can read with perldoc INSTALL. For the purpose of this document, we'll assume that you can configure simply with:

$ sh ./Configure -des -Dusedevel

Executing Configure will create a number of files in your top-level directory such as these:

./.config/README
./.config/instruct
./Makefile
./Policy.sh
./bitcount.h
./cflags
./config.h
./config.sh
./generate_uudmap
./generate_uudmap.o
./makedepend
./makefile
./makefile.old
./mg_data.h
./myconfig
./pod/Makefile
./runtests
./uudmap.h

We won't provide a detailed description of these files in this document but will provide specifics where needed.

COMMON make TARGETS

make

Calling make by itself builds the perl executable, compiles all libraries and utilities that will be installed with that executable and moves all files into their pre-installation position.

Synonym: make all

make test_prep

make test_prep does only one thing above and beyond what make does. make test_prep creates a symlink in the t/ subdirectory to the newly generated perl in the top-level directory.

Much of the core distribution test suite is written on the assumption that the tester is starting from the t/ directory. Having that symlink enables the tester to issue commands like this:

cd t; ./perl harness op/*.t; cd -

or:

cd t; ./perl harness ../cpan/File-Temp/t/*.t; cd -

make test

make test runs the perl executable created by make over each file in the test suite. The execution is serial; no tests are run in parallel.

You can run make test over selected files or directories by populating the TEST_FILES environmental variable with a path relative to the t/ subdirectory. Example:

TEST_FILES="../ext/Pod-Html/t/*.t" make test

Upon completion, make test will print a short summary to STDOUT. Example:

All tests successful.
Elapsed: 1097 sec
u=7.88  s=2.69  cu=693.26  cs=63.70  scripts=2553  tests=1199015

Synonym: make check

(Currently, make test is implemented by running a shell script, runtests, which is automatically generated during Configure from a template in source file runtests.SH. runtests, in turn, is mostly implemented by running the program t/TEST. However, this implementation may change in the future and you should not rely upon its details.)

make test_harness

make test_harness runs the perl executable created by make over each file in the test suite. The tests can be run in parallel by setting an appropriate value for environmental variable $TEST_JOBS and invoking make with the -j switch. For example:

TEST_JOBS=4 make -j${TEST_JOBS} test_harness

Upon completion, make test_harness will print a short summary to STDOUT. Example (slightly horizontally compressed):

All tests successful.

Test Summary Report
-------------------
../dist/Net-Ping/t/010_pingecho.t           (Wstat: 0 Tests: 2 Failed: 0)
  TODO passed:   2
../dist/Net-Ping/t/450_service.t            (Wstat: 0 Tests: 26 Failed: 0)
  TODO passed:   9, 18
Files=2679, Tests=1199037, 248 wallclock secs
    (84.45 usr 14.90 sys + 694.27 cusr 70.06 csys = 863.68 CPU)
Result: PASS

Synonym: make test-harness

make install

TK

OTHER make TARGETS

make miniperl

make miniperl calls your C compiler on what are currently 40 *.c source code files to build one binary executable, miniperl, and one Perl program, lib/buildcustomize.pl.

miniperl is then used in the balance of make to execute Perl programs which compile the libraries and utilities which ship with perl and which autogenerate documentation from templates. Unlike the full perl executable, miniperl cannot dynamically load modules. Hence, programs invoked by miniperl can include require and use statements provided there is no XS code involved. miniperl is invoked more than 150 times during make and thus is the major way in which perl's build is bootstrapped.

Generally speaking, you should consider running make miniperl and subsequently make minitest if you are making changes to any of the following *.c source code files:

av.c         gv.c              numeric.c    pp_hot.c     scope.c
caretx.c     hv.c              op.c         pp_pack.c    sv.c
deb.c        keywords.c        pad.c        pp_sort.c    taint.c
doio.c       locale.c          perl.c       pp_sys.c     time64.c
doop.c       mathoms.c         perlio.c     reentr.c     toke.c
dquote.c     mg.c              perly.c      regcomp.c    universal.c
dump.c       miniperlmain.c    pp.c         regexec.c    utf8.c
globals.c    mro_core.c        pp_ctl.c     run.c        util.c

lib/buildcustomize.pl is also used in the balance of make to identify the paths to source code of the Perl libraries which are needed in that compilation.

make minitest_prep

As its name suggests, make minitest_prep uses the miniperl executable to prepare a set of tests that do not require the full perl executable to run.

Roughly speaking, it traverses the cpan/, dist/, ext/ and lib/ directories, creates per-module Makefiles as needed, runs make with those Makefiles, and creates other files as needed.

For example, in the cpan/Archive-Tar/ directory, make minitest_prep creates these files:

./cpan/Archive-Tar/Makefile
./cpan/Archive-Tar/Makefile.PL
./cpan/Archive-Tar/blib/bin/.exists
./cpan/Archive-Tar/blib/man1/.exists
./cpan/Archive-Tar/blib/man3/.exists
./cpan/Archive-Tar/blib/script/.exists
./cpan/Archive-Tar/pm_to_blib

Currently this target creates a total of 1328 files.

Of these, 15 are Makefile.PL files, 25 are Makefile files, 136 are *.exist files and 99 are pm_to_blib files.

Many of the remaining files are .pm files found under cpan/, dist/, and ext/ which are copied into pre-installation position under lib/.

Among the other types of files generated are:

You will rarely need to invoke make minitest_prep directly. You will generally run make minitest immediately after (or in place of) make miniperl, but it interesting how much work has to be done to create meaningful tests.

make minitest

make minitest runs a test harness using the miniperl executable to run over 400 test files in these directories:

t/base
t/comp
t/run
t/cmd
t/io
t/re
t/opbasic
t/op
t/uni
t/perf

Approximately 80 such files are skipped because they presume functionality not yet built in miniperl.

No new files are created between make minitest_prep and make minitest.

make clean

The various make *clean targets are primarily useful if you are building perl from a source tarball rather than a git checkout. If you are working in a git checkout, you will almost always use git checkout -dfx.

make clean does not delete config.sh or Policy.sh. Note that since make clean removes all Makefiles, you cannot call any make commands thereafter.

Synonym: make realclean

make distclean

Above and beyond the files which make clean removes, make distclean removes config.sh, Policy.sh, t/test_state and files created as part of cross-compilation.

make veryclean

make veryclean removes all other files above and beyond those which make distclean removes.