makefilet/REFERENCE.md

Reference of makefilet targets and variables

Targets

The following list of targets is not exhaustive (e.g. the detailed clean-* targets are omitted). Instead the list is focused on feature-oriented targets.

See make help for a full list of targets available for your specific project configuration.

• clean: remove built files
• dist: build distribution targets (e.g. a Python or deb package)
• dist-deb: build deb packages
• dist-python: build Python packages
• django-migrate: create and apply Django migrations
• django-translate: translate a Django project
• help: show available Makefile targets
• init-deb: populate the debian/ directory with example content
• install: install the project
• install-python: install the Python package
• lint: run all linter programs (check for style and other issues)
• lint-deb: check the style of the deb packages
• lint-python: check the style of Python files
• lint-python-black: check the style of Python files with black
• lint-python-flake8: check the style of Python files with flake8
• lint-shell: check the style of shell files
• release-major: increase the version to the next major release
• release-minor: increase the version to the next minor release
• release-patch: increase the version to the next patch release
• release-push: push git tags to the remote repository
• release-tar: create a release tarball
• release-tar-sign: create a release tarball and a hash checksum file
• release-undo: remove the current release commit
• report: create a code coverage report
• style: apply formatting rules (e.g. black for Python code)
• style-python: apply formatting rules for Python code
• tags: create a ctags file
• test: run tests
• test-python: run Python-based tests
• upload: upload distribution files (e.g. Python or deb packages)
• upload-deb: upload deb packages to a repository
• upload-python: upload Python packages to a pypi-like repository

Variables

• all locations are relative to the directory containing the Makefile
• boolean variables (e.g. DISABLE_*) are interpreted as true for the value 1

ACTIVATE_VIRTUALENV

Location of the activate script used for entering a virtualenv context for Python projects.

Default: bin/activate below the virtualenv

BLACK_ARGS

Arguments to be used when executing black.

Default: empty

BLACK_BIN

Command to be used for executing black.

Default: black

BLACK_FILES

List of files or directories to be checked by black. Project files or directories should be added manually.

Default: setup.py

BUMP_VERSION_CONFIG

Location of a bumpversion configuration file.

Default: .bumpversion.cfg

BUMP_VERSION_FILES

List of files which are expected to change during a release (i.e. all files containing the current version string). This automatically generated list of filenames rarely needs to be overwritten.

Default: automatically assembled list of related files

BUMP_VERSION_PARSE_REGEX

Regular expression used by bumpversion for parsing a release string.

Default: (?P<major>\d+)\.(?P<minor>\d+)(?:\.(?P<patch>\d+))?

COVERAGE_BROWSER_BIN

Browser name to be used for automatically opening html-based coverage reports. Set to an empty value in order to prevent the browser from being started.

Default: xdg-open

CURRENT_VERSION_FILE

Location of the file containing the raw version string of the latest release.

Default: VERSION

DEB_DPUT_CONFIG

Location of the dput configuration file used for uploading deb files.

Default: ~/.dput.cf

DEB_RELEASE_DISTRIBUTION

Override the default unstable release distribution name. Set to an empty value in order to fall back to debchange's default behavior (which is sadly unpredictable for Ubuntu-derived systems).

Default: unstable

DEB_UPLOAD_COMMAND

Command to be used for uploading deb packages to a repository.

Default: dput

DEBIAN_PACKAGE_SUBMODULE_DIRECTORIES

Directories which are not sourced from additional git repositories (git submodules). These directories require special treatment when building a deb package.

Default: empty

DEBIAN_BUILDPACKAGE_COMMAND

Command to be used for building deb packages.

This variable is commonly overwritten in CI contexts in order to skip gpg-based signatures (e.g. DEBIAN_BUILDPACKAGE_COMMAND = dpkg-buildpackage --unsigned-source --unsigned-changes).

Default: dpkg-buildpackage

DEBIAN_UPLOAD_TARGET

Hostname for uploading deb package files (via upload-deb). This value must be overwritten, if the upload feature is needed.

Default: custom

DESTDIR

Target directory for make install.

Default: root

DIR_BUILD

Directory to be used as a default location for files to be built.

Default: build

DIR_DEBIAN_BUILD

Target directory for deb packages being built.

Default: build/debian

DIR_DEBIAN_SIMPLIFIED_PACKAGE_FILES

Target directory for storing built deb files. The files in this directory are simplified (lacking the version number) in order to provide predictable filenames.

Default: build/debian/export

DIR_DJANGO_LOCALES

Target directory for locales manged in Django projects.

Default: locale

DIR_PYPI2DEB_BUILD

Target directory for files being built by pypi2deb.

Default: build/pypi2deb

DIR_PYTHON_BUILD

Target directory for storing built Python packages.

Default: build/python-lib

DIR_PYTHON_COVERAGE_HTML

Target directory for html-based coverage report.

Default: build/coverage-html

DIR_PYTHON_SETUP

Location of the directory containing the setup.py for a Python package.

Default: .

DIR_RELEASE_ARCHIVES

Target directory for storing release archives.

Default: .

DISABLE_CUSTOM_VIRTUALENV

Do not create a virtualenv for the project (e.g. below build/). By default a virtualenv is used, if a requirements.txt file is found.

Default: 0

DISABLE_PYTHON_LINT_FLAKE8

Disable flake8 for the lint-python target (enabled by default).

Default: 0

DISABLE_PYTHON_TESTS

Disable Python-based tests.

Default: 0

DISABLE_SHELL_CHECK

Any non-empty value prevents shellcheck from being used.

Default: 0

DJANGO_COMPILEMESSAGES_ARGS

Allow the customization of arguments for django-admin compilemessages.

Default: --ignore "$(DIR_BUILD)/*"

DJANGO_MAKEMESSAGES_ARGS

Allow the customization of arguments for django-admin makemessages.

Default: --ignore "$(DIR_BUILD)/*" --no-location

DJANGO_WANTED_LOCALES

List of locale names (e.g. de fr) to be compiled. The locales do not need to be specified, if they were compiled at least once. In this case the set of previously built locales is used again.

Default: determined automatically, if locales already exist

ENABLE_PYTHON_LINT_BLACK

Enable black --check for the lint-python target. black is disabled by default, since its --check is not guaranteed to be stable (not even with a given --target-version). You should enable it only, if you enforce a specific version of black to be used.

Default: 0

FLAKE8_BIN

Command for executing flake8 checks.

Default: either flake8 (if it exists) or python3 -m flake8

FLAKE8_FILES

List of files or directories to be checked by flake8. Project files or directories should be added manually.

Default: setup.py

LINTIAN_ARGS

Arguments for the lintian tool used by lint-deb.

Default: empty

MAKEFILET_DOWNLOAD_URL_TEMPLATES

The provided makefilet-download-ondemand.mk file uses this variable for determining the URL to be used for downloading makefilet.

The variable is expected to contain a space-separated list of URL templates. Each template should include the string __VERSION__., which will be replaced with the content of MAKEFILET_DOWNLOAD_VERSION.

The URLs are queried in the configured order until a download succeeds.

MAKEFILET_DOWNLOAD_URL_TEMPLATES is ignored, if MAKEFILET_DOWNLOAD_URLS is defined.

Default: URL patterns for all known download locations of makefilet

MAKEFILET_DOWNLOAD_URLS

This variable is similar to MAKEFILET_DOWNLOAD_URL_TEMPLATES. Instead of URL patterns it contains resolved URLs (without a __VERSION__ string).

If this variable is defined, then MAKEFILET_DOWNLOAD_URL_TEMPLATES and MAKEFILET_DOWNLOAD_VERSION are ignored.

MAKEFILET_DOWNLOAD_URL_TEMPLATES is preferable under most circumstances.

Default: empty

MAKEFILET_ENABLE_PYTHON

Force Python features to be enabled, even if no setup.py was found (e.g. for virtualenv support).

Default: empty

MAKEFILET_MODULES

Download additional makefilet modules, which are executed whenever makefilet is loaded.

The variable is expected to be a space-separated list of URLs. Makefilet will refuse to operate if any of these URLs cannot be downloaded.

The downloaded modules are cached as a complete collection (not individually). Any change of a single URL or a change of order will cause another download of all modules.

You may need to add cache-invalidating query arguments (e.g. ?foo) if a URL points to different content over time (i.e. the URL lacks an explicit version identifier).

Example:

MAKEFILET_MODULES += https://example.org/makefilet/foo_v1.0.2.mk
MAKEFILET_MODULES += https://example.org/makefilet/bar.mk?v1.3.0

Default: empty

MAKEFILET_OUTPUT_SYNCHRONIZATION

Configure make's output synchronization in case of parallel execution of multiple jobs (e.g. if multiple CPU cores are available).

See the FAQ ("Running a single target in single-job mode") for hints regarding interactive make targets (e.g. running a local development webserver).

Default: line

MAX_PARALLEL_JOBS

Number of make jobs to be executed in parallel.

Default: number of CPU cores

PO_EDITOR

Command to be used for executing an editor for maintaining a gettext translation file ("PO file").

Set to an empty value, if you do not want to run the PO editor automatically during the django-translate target.

Default: virtaal or poedit (if one of them is found)

PROJECT_NAME

The project name is used for the name of files created by makefilet (e.g. release archives).

Default: name of the directory containing the Makefile

PYPI2DEB_PACKAGES

Names of pypi packages to be used for building simple deb packages.

Default: empty

PYPI2DEB_PYTHON_PREFIX

Package name prefix to be used for packages generated via pypi2deb.

Default: python3

PYPI_UPLOAD_TARGET

Target for uploading Python packages.

Default: https://pypi.python.org/pypi

PYTHON_BIN

Python executable to be used.

Default: python3

PYTHON_BUILD_SYSTEM

Build system to be used for various operations in a Python project.

Options: setuptools / hatchling / poetry

Default: automatically determined based on the presence of PYTHON_SETUP_FILE or the content of PYTHON_PYPROJECT_FILE

PYTHON_LINT_RUNNER

Procedure for verifying formatting issues.

Options: hatch / generic

Default: automatically determined based on the content of PYTHON_PYPROJECT_FILE

PYTHON_PYPROJECT_FILE

PEP-0518 defines the content of this project description file.

Default: ./pyproject.toml

PYTHON_SETUP_FILE

Location of the setup.py-like file for a Python project.

Default: ./setup.py

PYTHON_STYLE_RUNNER

Procedure for applying automated formatting rules issues.

Options: hatch / generic

Default: automatically determined based on the content of PYTHON_PYPROJECT_FILE

PYTHON_TEST_ARGS

Arguments to be used when starting Python-based tests.

Default: -m unittest discover or manage.py test (for Django projects)

PYTHON_TEST_RUNNER

Runner to be used for executing tests in a Python project.

Options: tox / hatch / poetry / django / generic

Default: automatically determined based on the presence of PYTHON_TOX_FILE, the content of PYTHON_PYPROJECT_FILE or other properties.

PYTHON_TOX_FILE

Location of the tox.ini file to be used for a running tests in a Python project.

Default: ./tox.ini

PYTHON_TEST_POETRY_COMMAND

Command to be executed for running tests in a poetry-based Python project.

Default: pytest

PYTHON_VIRTUALENV_ENABLE

Create a virtualenv for the project (e.g. below build/) and use it for most Python-based operations.

This setting replaces the deprecated setting DISABLE_CUSTOM_VIRTUALENV. Set PYTHON_VIRTUALENV_ENABLE = 0 in order to disable virtual environments (until 'DISABLE_CUSTOM_VIRTUALENV' is removed).

Default: empty

RELEASE_TAR_COMPRESSION_BIN

Compression to be used for the release tarball.

Options: bzip2 / gzip / xz / zstd

Default: gzip

RELEASE_TAR_HASH_FUNC

Hash function to be used for generating the hash for a release tarball. The name is interpreted as an executable as well as a filename extension for the signature file.

Default: sha256sum

SHELLCHECK_ARGS

Arguments for shellcheck.

Default: -x

SHELL_FILES_ALL

Names of files to be checked via shellcheck.

Default: all files below SHELL_FILES_DIRECTORIES containing a shell-like shebang

SHELL_FILES_BASH

Names of files to be interpreted as bash scripts by shellcheck.

Default: automatically determined based on SHELL_FILES_ALL

SHELL_FILES_DASH

Names of files to be interpreted as dash scripts by shellcheck.

Default: automatically determined based on SHELL_FILES_ALL

SHELL_FILES_DIRECTORIES

Directory containing shell scripts, which should be scanned via shellcheck.

Default: .

SIGNATURE_EMAIL

Set this variable in order to use a specific GPG key for signing the release tarball (e.g. make release-tar-sign SIGNATURE_EMAIL=author@example.org). The local default GPG key is used, if the variable is empty.

Default: empty

TAGS_FILE

Target filename to be used for storing Ctags data.

Default: ./tags

TAGS_SOURCE_DIRS

Directories containing source files to be parsed for building a ctags file.

Default: src (if it exists)

VIRTUALENV_CREATE_ARGUMENTS

Arguments to be used when creating a virtualenv.

Default: empty

VIRTUALENV_PREDEPENDENCIES

List of Python packages which are required for creating a virtualenv. A helpful error message is emitted, if any of these packages are missing.

Default: venv wheel

VIRTUALENV_REQUIREMENTS_FILE

Location of a requirements file for Python dependencies.

Default: requirements.txt