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.sh
and./veryclean.sh
, which will be subsequently used in two othermake
targets. -
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
man
files awaiting installation:./cpan/podlators/blib/man1/pod2man.1 ./cpan/podlators/blib/man1/pod2text.1
-
1 header file:
./git_version.h
-
541
unicore/*.pl
files 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.