gh-106259: Add minimal help target to Makefile (#106260)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
This commit is contained in:
Skip Montanaro 2024-03-07 11:21:28 -06:00 committed by GitHub
parent 41457c7fdb
commit d9ccde28c4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 124 additions and 22 deletions

View File

@ -991,32 +991,99 @@ Main build steps
Main Makefile targets
---------------------
* ``make``: Build Python with the standard library.
* ``make platform:``: build the ``python`` program, but don't build the
standard library extension modules.
* ``make profile-opt``: build Python using Profile Guided Optimization (PGO).
You can use the configure :option:`--enable-optimizations` option to make
this the default target of the ``make`` command (``make all`` or just
``make``).
make
^^^^
* ``make test``: Build Python and run the Python test suite with ``--fast-ci``
option. Variables:
For the most part, when rebuilding after editing some code or
refreshing your checkout from upstream, all you need to do is execute
``make``, which (per Make's semantics) builds the default target, the
first one defined in the Makefile. By tradition (including in the
CPython project) this is usually the ``all`` target. The
``configure`` script expands an ``autoconf`` variable,
``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
all`` will build. The three choices are:
* ``TESTOPTS``: additional regrtest command line options.
* ``TESTPYTHONOPTS``: additional Python command line options.
* ``TESTTIMEOUT``: timeout in seconds (default: 20 minutes).
* ``profile-opt`` (configured with ``--enable-optimizations``)
* ``build_wasm`` (configured with ``--with-emscripten-target``)
* ``build_all`` (configured without explicitly using either of the others)
* ``make buildbottest``: Similar to ``make test``, but use ``--slow-ci``
option and default timeout of 20 minutes, instead of ``--fast-ci`` option
and a default timeout of 10 minutes.
Depending on the most recent source file changes, Make will rebuild
any targets (object files and executables) deemed out-of-date,
including running ``configure`` again if necessary. Source/target
dependencies are many and maintained manually however, so Make
sometimes doesn't have all the information necessary to correctly
detect all targets which need to be rebuilt. Depending on which
targets aren't rebuilt, you might experience a number of problems. If
you have build or test problems which you can't otherwise explain,
``make clean && make`` should work around most dependency problems, at
the expense of longer build times.
make platform
^^^^^^^^^^^^^
Build the ``python`` program, but don't build the standard library
extension modules. This generates a file named ``platform`` which
contains a single line describing the details of the build platform,
e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
make profile-opt
^^^^^^^^^^^^^^^^
Build Python using profile-guided optimization (PGO). You can use the
configure :option:`--enable-optimizations` option to make this the
default target of the ``make`` command (``make all`` or just
``make``).
make clean
^^^^^^^^^^
Remove built files.
make distclean
^^^^^^^^^^^^^^
In addition to the the work done by ``make clean``, remove files
created by the configure script. ``configure`` will have to be run
before building again. [#]_
make install
^^^^^^^^^^^^
Build the ``all`` target and install Python.
make test
^^^^^^^^^
Build the ``all`` target and run the Python test suite with the
``--fast-ci`` option. Variables:
* ``TESTOPTS``: additional regrtest command-line options.
* ``TESTPYTHONOPTS``: additional Python command-line options.
* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
make buildbottest
^^^^^^^^^^^^^^^^^
This is similar to ``make test``, but uses the ``--slow-ci``
option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
make regen-all
^^^^^^^^^^^^^^
Regenerate (almost) all generated files. These include (but are not
limited to) bytecode cases, and parser generator file.
``make regen-stdlib-module-names`` and ``autoconf`` must be run
separately for the remaining `generated files <#generated-files>`_.
* ``make install``: Build and install Python.
* ``make regen-all``: Regenerate (almost) all generated files;
``make regen-stdlib-module-names`` and ``autoconf`` must be run separately
for the remaining generated files.
* ``make clean``: Remove built files.
* ``make distclean``: Same than ``make clean``, but remove also files created
by the configure script.
C extensions
------------
@ -1311,3 +1378,14 @@ Linker flags
Linker flags used for building the interpreter object files.
.. versionadded:: 3.8
.. rubric:: Footnotes
.. [#] ``git clean -fdx`` is an even more extreme way to "clean" your
checkout. It removes all files not known to Git.
When bug hunting using ``git bisect``, this is
`recommended between probes <https://github.com/python/cpython/issues/114505#issuecomment-1907021718>`_
to guarantee a completely clean build. **Use with care**, as it
will delete all files not checked into Git, including your
new, uncommitted work.

View File

@ -653,6 +653,30 @@ all: @DEF_MAKE_ALL_RULE@
# all.
.PHONY: all
# Provide quick help for common Makefile targets.
.PHONY: help
help:
@echo "Run 'make' to build the Python executable and extension modules"
@echo ""
@echo "or 'make <target>' where <target> is one of:"
@echo " test run the test suite"
@echo " install install built files"
@echo " regen-all regenerate a number of generated source files"
@echo " clinic run Argument Clinic over source files"
@echo ""
@echo " clean to remove build files"
@echo " distclean 'clean' + remove other generated files (patch, exe, etc)"
@echo ""
@echo " recheck rerun configure with last cmdline options"
@echo " reindent reindent .py files in Lib directory"
@echo " tags build a tags file (useful for Emacs and other editors)"
@echo " list-targets list all targets in the Makefile"
# Display a full list of Makefile targets
.PHONY: list-targets
list-targets:
@grep -E '^[A-Za-z][-A-Za-z0-9]+:' Makefile | awk -F : '{print $$1}'
.PHONY: build_all
build_all: check-clean-src $(BUILDPYTHON) platform sharedmods \
gdbhooks Programs/_testembed scripts checksharedmods rundsymutil