perlmaketargets - A guide to Perl's make targets
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.
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.
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.
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 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 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 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
TK
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.
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:
-
2 shell scripts,
./realclean.shand./veryclean.sh, which will be subsequently used in two othermaketargets. -
39 POD files:
./lib/CPAN/API/HOWTO.pod ./lib/CPAN/Meta/History/Meta_1_0.pod ./lib/CPAN/Meta/History/Meta_1_1.pod ./lib/CPAN/Meta/History/Meta_1_2.pod ./lib/CPAN/Meta/History/Meta_1_3.pod ./lib/CPAN/Meta/History/Meta_1_4.pod ./lib/Config.pod ./lib/ExtUtils/MakeMaker/FAQ.pod ./lib/ExtUtils/MakeMaker/Tutorial.pod ./lib/ExtUtils/ParseXS.pod ./lib/IO/Compress/FAQ.pod ./lib/Locale/Maketext.pod ./lib/Locale/Maketext/Cookbook.pod ./lib/Locale/Maketext/TPJ13.pod ./lib/Module/CoreList.pod ./lib/Net/libnetFAQ.pod ./lib/Pod/Simple.pod ./lib/Pod/Simple/Subclassing.pod ./lib/TAP/Harness/Beyond.pod ./lib/Test/Tutorial.pod ./lib/Test2/Transition.pod ./lib/perldoc.pod ./lib/perlfaq.pod ./lib/perlfaq1.pod ./lib/perlfaq2.pod ./lib/perlfaq3.pod ./lib/perlfaq4.pod ./lib/perlfaq5.pod ./lib/perlfaq6.pod ./lib/perlfaq7.pod ./lib/perlfaq8.pod ./lib/perlfaq9.pod ./lib/perlglossary.pod ./lib/perlxs.pod ./lib/perlxstut.pod ./lib/perlxstypemap.pod ./lib/version.pod ./lib/version/Internals.pod ./pod/perluniprops.pod -
7 generated executable files awaiting installation:
./cpan/IO-Compress/blib/script/streamzip ./cpan/IO-Compress/blib/script/zipdetails ./cpan/Pod-Checker/blib/script/podchecker ./cpan/Pod-Usage/blib/script/pod2usage ./cpan/podlators/blib/script/pod2man ./cpan/podlators/blib/script/pod2text ./dist/Module-CoreList/blib/script/corelist -
2
manfiles awaiting installation:./cpan/podlators/blib/man1/pod2man.1 ./cpan/podlators/blib/man1/pod2text.1 -
1 header file:
./git_version.h -
541
unicore/*.plfiles such as:./lib/unicore/CombiningClass.pl ./lib/unicore/Decomposition.pl ./lib/unicore/Name.pl -
1 other
unicore-related file:./lib/unicore/mktables.lst
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 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.
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
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 removes all other files above and beyond those which make distclean removes.