Topics and Domains¶

Topics are collections of domains.

A domain is a snippet of a Makefile defining a set of make targets.

Core¶

In the core are domains covering setup of the Python environment, script generation, sources/VCS handling and more.

Base¶

Defines common build targets and basic settings for project.

Property	Value
FQN	`core.base`

Targets:

Target	Description
`install`	Install project. Installs the entire project supposed for development.
`deploy`	Deploy project. Supposed to setup a production version of the project.
`run`	Run project. Depending on target defined in `RUN_TARGET`
`dirty`	Force make to rebuild targets on next make run.
`clean`	Clean project. Removes all installation related files.
`purge`	Purge project. Removes all installation related files and data. THIS IS AN OPERATION FOR POTENTIAL DATA LOSS! USE SPARINGLY AND AT YOUR OWN RISK!
`runtime-clean`	Remove runtime artifacts, like byte-code and caches.
`check`	Run all QA checkers related targets, e.g. code style Only gets included if any qa topic related domain is used.
`type-check`	Run all QA type-checkers related targets, e.g. type checks. Only gets included if any qa topic related domain is used.
`format`	Run all QA code formatters related targets, e.g. code style Only gets included if any qa topic related domain is used.

Settings:

Setting	Description	Default
`DEPLOY_TARGETS`	`deploy` target dependencies.	``
`RUN_TARGET`	target to be executed when calling `make run`	``
`CLEAN_FS`	Additional files and folders to remove when running clean target	``
`INCLUDE_MAKEFILE`	Optional makefile to include before default targets. This can be used to provide custom targets or hook up to existing targets.	`include.mk`
`EXTRA_PATH`	Optional additional directories to be added to PATH in format `/path/to/dir/:/path/to/other/dir`. Gets inserted first, thus gets searched first.	``
`PROJECT_PATH_PYTHON`	Path to Python project relative to Makefile (repository root). Leave empty if Python project is in the same directory as Makefile. For monorepo setups, set to subdirectory name (e.g., `backend`). Future-proofed for multi-language monorepos (e.g., PROJECT_PATH_NODEJS).	``

Help System¶

A system to provide the user of the Makefile an overview of the targets and all environment variable based arguments.

Property	Value
FQN	`core.help`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`help`	Print help for the Makefile.

Settings:

Setting	Description	Default
`HELP_DOMAIN`	Request to show all targets, descriptions and arguments for a given domain.	``

MX Environment¶

Python environment management.

Property	Value
FQN	`core.mxenv`
Dependencies	Hard: `core.base`

Targets:

Target	Description
`mxenv`	Setup the Python environment. Creates a Python virtual environment using the built-in `venv` module if `VENV_CREATE` is `true`. The following Python packages are installed respective updated: - pip - setuptools - wheel - mxdev - mxmake
`mxenv-dirty`	Build `mxenv` target on next make run.
`mxenv-clean`	Removes virtual environment if `VENV_CREATE` is `true`, otherwise uninstall environment related python packages.

Settings:

Setting	Description	Default
`PRIMARY_PYTHON`	Primary Python interpreter to use. It is used to create the virtual environment if `VENV_ENABLED` and `VENV_CREATE` are set to `true`. If global `uv` is used, this value is passed as `--python VALUE` to the venv creation. uv then downloads the Python interpreter if it is not available. for more on this feature read the uv python documentation	`python3`
`PYTHON_MIN_VERSION`	Minimum required Python version.	`3.10`
`PYTHON_PACKAGE_INSTALLER`	Install packages using the given package installer method. Supported are `pip` and `uv`. When `uv` is selected, a global installation is auto-detected and used if available. Otherwise, uv is installed in the virtual environment or using `PRIMARY_PYTHON`, depending on the `VENV_ENABLED` setting.	`pip`
`UV_PYTHON`	Python version for UV to install/use when creating virtual environments with global UV. Passed to `uv venv -p VALUE`. Supports version specs like `3.11`, `3.14`, `cpython@3.14`. Defaults to PRIMARY_PYTHON value for backward compatibility.	`$(PRIMARY_PYTHON)`
`VENV_ENABLED`	Flag whether to use virtual environment. If `false`, the interpreter according to `PRIMARY_PYTHON` found in `PATH` is used.	`true`
`VENV_CREATE`	Flag whether to create a virtual environment. If set to `false` and `VENV_ENABLED` is `true`, `VENV_FOLDER` is expected to point to an existing virtual environment.	`true`
`VENV_FOLDER`	The folder of the virtual environment. If `VENV_ENABLED` is `true` and `VENV_CREATE` is true it is used as the target folder for the virtual environment. If `VENV_ENABLED` is `true` and `VENV_CREATE` is false it is expected to point to an existing virtual environment. If `VENV_ENABLED` is `false` it is ignored.	`.venv`
`MXDEV`	mxdev to install in virtual environment.	`mxdev`
`MXMAKE`	mxmake to install in virtual environment.	`mxmake`

MX Files¶

Project file generation.

Property	Value
FQN	`core.mxfiles`
Dependencies	Hard: `core.mxenv` Soft: `core.sources`

Targets:

Target	Description
`mxfiles`	Create all project files by running `mxdev`. It does not checkout sources.
`mxfiles-dirty`	Build :ref:`mxfiles` target on next make run.
`mxfiles-clean`	Remove generated project files.

Settings:

Setting	Description	Default
`PROJECT_CONFIG`	The config file to use.	`mx.ini`

Packages¶

Install python packages.

Property	Value
FQN	`core.packages`
Dependencies	Hard: `core.mxfiles`

Targets:

Target	Description
`packages`	Install packages with pip after creating files and checking out sources.
`packages-dirty`	Build packages target on next make run.
`packages-clean`	Remove prior installed packages

Settings:

Setting	Description	Default
`PACKAGES_ALLOW_PRERELEASES`	Allow prerelease and development versions. By default, the package installer only finds stable versions.	`false`

Proxy targets¶

This domain includes proxy targets which are configured in mx.ini. It is expected that defined folder(s) contains a Makefile which is generated by mxmake and this Makefile contains the domains for which proxy targets are created. The proxy configuration in the mx.ini file looks as follows:

mxmake-templates = proxy

[mxmake-proxy]
foldername =
applications:plone,zest-releaser
i18n:*

Each setting in the mxmake-proxy section defines a child folder. The value contains the topic name and the desired domains as comma separated list. Wildcard * means to include all domains of this topic. Topic and domains are colon separated.

Property	Value
FQN	`core.proxy`
Dependencies	Hard: `core.mxfiles`

Sources¶

Source package management.

Property	Value
FQN	`core.sources`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`sources`	Checkout sources by running `mxdev`. It does not generate project files.
`sources-dirty`	Build :ref:`sources` target on next make run.
`sources-purge`	Removes sources folder.

Applications¶

Application specific domains.

cookiecutter¶

Tool to generate skeletons and configuration from cookiecutter templates.

Property	Value
FQN	`applications.cookiecutter`
Dependencies	Hard: `core.packages`

Targets:

Target	Description
`cookiecutter`	Install cookiecutter.
`cookiecutter-dirty`	Marks cookiecutter dirty.
`cookiecutter-clean`	Uninstall cookiecutter.

plone¶

Plone application related

Property	Value
FQN	`applications.plone`
Dependencies	Hard: `applications.zope`

Targets:

Target	Description
`plone-site-create`	Creates a Plone site using the script provided in `PLONE_SITE_SCRIPT` configuration.
`plone-site-purge`	Removes the Plone instance from the database, but the database itself is kept.
`plone-site-recreate`	Removes the Plone instance from the database like in plone-site-purge, then creates a new one like in plone-site-create.

Settings:

Setting	Description	Default
`PLONE_SITE_SCRIPT`	Path to the script to create or purge a Plone site	`.mxmake/files/plone-site.py`
`PLONE_SITE_CREATE_FAIL_IF_EXISTS`	Exit with an error if the Plone site already exists	`True`
`PLONE_SITE_PURGE_FAIL_IF_NOT_EXISTS`	Exit with an error if the Plone site does not exists	`True`

Twisted Server¶

Install and start Twisted Server.

Property	Value
FQN	`applications.twisted`
Dependencies	Hard: `core.packages`

Targets:

Target	Description
`twisted-start`	Run Twisted Server

Settings:

Setting	Description	Default
`TWISTED_TWISTD_OPTIONS`	The Twisted Application Configuration file.	`-ny`
`TWISTED_TAC_FILE`	The Twisted Application Configuration file.	`twisted.tac`

zest.releaser¶

A collection of command-line programs to help automate the task of releasing a Python project.

Property	Value
FQN	`applications.zest-releaser`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`zest-releaser-prerelease`	Run prerelease command of zest.releaser
`zest-releaser-release`	Run release command of zest.releaser
`zest-releaser-postrelease`	Run postrelease command of zest.releaser
`zest-releaser-fullrelease`	Run fullrelease command of zest.releaser
`zest-releaser-dirty`	Marks zest.releaser dirty
`zest-releaser-clean`	Uninstall zest.releaser.

Settings:

Setting	Description	Default
`ZEST_RELEASER_PRERELEASE_OPTIONS`	Options to pass to zest.releaser prerelease command.	``
`ZEST_RELEASER_RELEASE_OPTIONS`	Options to pass to zest.releaser release command.	``
`ZEST_RELEASER_POSTRELEASE_OPTIONS`	Options to pass to zest.releaser postrelease command.	``
`ZEST_RELEASER_FULLRELEASE_OPTIONS`	Options to pass to zest.releaser fullrelease command.	``

zope¶

Zope and Plone application related

Property	Value
FQN	`applications.zope`
Dependencies	Hard: `applications.cookiecutter`

Targets:

Target	Description
`zope-instance`	Use cookiecutter-zope-instance to create Zope- and its WSGI-configuration from values of the cookiecutter configuration file.
`zope-start`	Start Zope/Plone WSGI server.
`zope-debug`	Start Zope/Plone debug console.
`zope-runscript`	Run a script within Zope/plone context. ZOPE_SCRIPTNAME must be set to the script to run. This can be done by setting the environment variable or by setting the make variable in the header. Example: `make ZOPE_SCRIPTNAME=./my-script.py zope-runscript`
`zope-adduser`	Adds an emergency user to Zope. This is an user with the Manager role created in the Zope application roots user folder! This is not meant to do user management, but to get access to a Zope site if all other passwords are gone. The user name must not exist already in the application roots user folder. ZOPE_USER_NAME and ZOPE_USER_PASSWORD should not be set in the Makefile, but passed in as environment variables. Example: `make ZOPE_USER_NAME=emergency ZOPE_USER_PASSWORD=verysecret adduser`
`zope-dirty`	Touches the configuration file to force a rebuild of the Zope instance.
`zope-clean`	Removes generated configuration files but keeps Zope database.
`zope-purge`	Removes the whole Zope instance folder including database.

Settings:

Setting	Description	Default
`ZOPE_CONFIGURATION_FILE`	cookiecutter configuration file to use	`instance.yaml`
`ZOPE_TEMPLATE`	cookiecutter configuration file to use	`https://github.com/plone/cookiecutter-zope-instance`
`ZOPE_TEMPLATE_CHECKOUT`	cookiecutter branch, tag or commit to checkout from the ZOPE_TEMPLATE. If empty, `--checkout` is not passed to cookiecutter.	`main`
`ZOPE_BASE_FOLDER`	The Zope folder “instance” will be generated relative to this existing folder.	`.`
`ZOPE_SCRIPTNAME`	script to run	`No Default`
`ZOPE_USER_NAME`	user name to create	`No Default`
`ZOPE_USER_PASSWORD`	user name to create	`No Default`

Docs¶

Documentation related domains

JSDoc Documentation¶

JSDoc installation and integration into Sphinx.

Property	Value
FQN	`docs.jsdoc`
Dependencies	Hard: `js.nodejs`

Sphinx Documentation¶

Documentation generation with Sphinx.

Property	Value
FQN	`docs.sphinx`
Dependencies	Hard: `core.mxenv` Soft: `docs.jsdoc`

Targets:

Target	Description
`docs`	Generate Sphinx docs.
`docs-live`	Rebuild Sphinx documentation on changes, with live-reload in the browser using `sphinx-autobuild`.
`docs-linkcheck`	Run Sphinx linkcheck to verify external links in documentation.
`docs-clean`	Removes generated docs.

Settings:

Setting	Description	Default
`DOCS_SOURCE_FOLDER`	Documentation source folder.	`docs/source`
`DOCS_TARGET_FOLDER`	Documentation generation target folder.	`docs/html`
`DOCS_LINKCHECK_FOLDER`	Documentation linkcheck output folder.	`docs/linkcheck`
`DOCS_REQUIREMENTS`	Documentation Python requirements to be installed (via pip).	``

i18n¶

Contains domains for managing translations.

Gettext¶

Provide targets for working with gettext

Property	Value
FQN	`i18n.gettext`

Targets:

Target	Description
`gettext-create`	Create message catalogs for all defined languages if not exists.
`gettext-update`	Update translations.
`gettext-compile`	Compile message catalogs.

Settings:

Setting	Description	Default
`GETTEXT_LOCALES_PATH`	Path of directory containing the message catalogs.	`locale`
`GETTEXT_DOMAIN`	Translation domain to use.	``
`GETTEXT_LANGUAGES`	Space separated list of language identifiers.	``

Lingua¶

Extract translatable texts from your code.

Property	Value
FQN	`i18n.lingua`
Dependencies	Hard: `core.mxenv`, `i18n.gettext`

Targets:

Target	Description
`lingua-extract`	Extract translatable texts from your code.
`lingua`	Extract translatable texts from your code and create, update and compile message catalogs.

Settings:

Setting	Description	Default
`LINGUA_SEARCH_PATH`	Path of directory to extract translatable texts from.	`src`
`LINGUA_PLUGINS`	Python packages containing lingua extensions.	``
`LINGUA_OPTIONS`	Command line options passed to `pot-create`	``

Javascript¶

Javascript related domains.

Karma tests¶

Run JavaScript tests using karma.

Property	Value
FQN	`js.karma`
Dependencies	Hard: `js.nodejs`

Targets:

Target	Description
`karma`	Run karma.

Settings:

Setting	Description	Default
`KARMA_CONFIG`	Karma config file.	`karma.conf.js`
`KARMA_OPTIONS`	Karma additional command line options.	`--single-run`

Node.js¶

Provide targets for working with Node.js. A working version of Node.js is expected to be installed. We suggest using nvm for managing Node.JS installations.

Property	Value
FQN	`js.nodejs`
Dependencies	Hard: `core.base`

Targets:

Target	Description
`nodejs`	Installs Javascript packages using the current active node version with the configured package manager.
`nodejs-dirty`	Build :ref:`nodejs` target on next make run.
`nodejs-clean`	Remove installed Javascript packages.

Settings:

Setting	Description	Default
`NODEJS_PACKAGE_MANAGER`	The package manager to use. Defaults to `npm`. Possible values are `npm` and `pnpm`	`npm`
`NODEJS_PREFIX`	Value for `--prefix` option when installing packages.	`.`
`NODEJS_PACKAGES`	Packages to install with `--no-save` option.	``
`NODEJS_DEV_PACKAGES`	Packages to install with `--save-dev` option.	``
`NODEJS_PROD_PACKAGES`	Packages to install with `--save-prod` option.	``
`NODEJS_OPT_PACKAGES`	Packages to install with `--save-optional` option.	``
`NODEJS_INSTALL_OPTS`	Additional install options. Possible values are `--save-exact` and `--save-bundle`.	``

Rollup JavaScript module bundler¶

Create JavaScript bundles with rollup.

Property	Value
FQN	`js.rollup`
Dependencies	Hard: `js.nodejs`

Targets:

Target	Description
`rollup`	Run rollup JavaScript bundler.

Settings:

Setting	Description	Default
`ROLLUP_CONFIG`	Rollup config file.	`rollup.conf.js`

SCSS Compiler¶

Compile Stylesheets using SCSS.

Property	Value
FQN	`js.scss`
Dependencies	Hard: `js.nodejs`

Targets:

Target	Description
`scss`	Run SCSS Stylesheet Compiler.

Settings:

Setting	Description	Default
`SCSS_SOURCE`	The SCSS root source file.	`scss/styles.scss`
`SCSS_TARGET`	The target file for the compiles Stylesheet.	`scss/styles.css`
`SCSS_MIN_TARGET`	The target file for the compressed Stylesheet.	`scss/styles.min.css`
`SCSS_OPTIONS`	Additional options to be passed to SCSS compiler.	`--no-source-map=none`

Web test runner¶

Run JavaScript tests using web test runner.

Property	Value
FQN	`js.wtr`
Dependencies	Hard: `js.nodejs`

Targets:

Target	Description
`wtr`	Execute web test runner.

Settings:

Setting	Description	Default
`WTR_CONFIG`	Web test runner config file.	`wtr.config.mjs`
`WTR_OPTIONS`	Web test runner additional command line options.	`--coverage`

LDAP¶

LDAP related domains.

OpenLDAP¶

Builds OpenLDAP from source

Property	Value
FQN	`ldap.openldap`
Dependencies	Hard: `core.base`

Targets:

Target	Description
`openldap`	Download and build OpenLDAP from source.
`openldap-dirty`	Rebuild OpenLDAP on next make run.
`openldap-clean`	Remove local OpenLDAP build.

Settings:

Setting	Description	Default
`OPENLDAP_VERSION`	OpenLDAP version to download	`2.4.59`
`OPENLDAP_URL`	OpenLDAP base download URL	`https://www.openldap.org/software/download/OpenLDAP/openldap-release/`
`OPENLDAP_DIR`	Build directory for OpenLDAP	`$(shell echo $(realpath .))/openldap`
`OPENLDAP_ENV`	Build environment for OpenLDAP	`PATH=/usr/local/bin:/usr/bin:/bin`

Python LDAP¶

Builds and installs python-ldap against local OpenLDAP

Property	Value
FQN	`ldap.python-ldap`
Dependencies	Hard: `core.mxenv`, `ldap.openldap`

Targets:

Target	Description
`python-ldap`	Builds and installs python-ldap against local OpenLDAP
`python-ldap-dirty`	Builds and installs python-ldap against local OpenLDAP
`python-ldap-clean`	Builds and installs python-ldap against local OpenLDAP

QA¶

Quality Assurance related domains

black¶

Code formatting with black.

Property	Value
FQN	`qa.black`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`black`	Run black.
`black-dirty`	Marks black dirty
`black-clean`	Uninstall black.

Settings:

Setting	Description	Default
`BLACK_SRC`	Source folder to scan for Python files to run black on.	`src`

Coverage¶

Project coverage testing.

Property	Value
FQN	`qa.coverage`
Dependencies	Hard: `qa.test`

Targets:

Target	Description
`coverage`	Run project coverage. :ref:`run-coverage` template can be used for automatic coverage script creation.
`coverage-clean`	Remove coverage related files and directories.

Settings:

Setting	Description	Default
`COVERAGE_COMMAND`	The command which gets executed. Defaults to the location the :ref:`run-coverage` template gets rendered to if configured.	`.mxmake/files/run-coverage.sh`

isort¶

Import sorting with isort.

Property	Value
FQN	`qa.isort`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`isort`	Run isort.
`isort-dirty`	Marks isort dirty
`isort-clean`	Uninstall isort.

Settings:

Setting	Description	Default
`ISORT_SRC`	Source folder to scan for Python files to run isort on.	`src`

mypy¶

Static code analysis with mypy.

Property	Value
FQN	`qa.mypy`
Dependencies	Hard: `core.packages`

Targets:

Target	Description
`mypy`	Run mypy.
`mypy-dirty`	Marks mypy dirty
`mypy-clean`	Uninstall mypy and removes cached data.

Settings:

Setting	Description	Default
`MYPY_SRC`	Source folder for code analysis.	`src`
`MYPY_REQUIREMENTS`	Mypy Python requirements to be installed (via pip).	`types-setuptools`

pyrefly¶

Static code analysis with pyrefly https://pyrefly.org/

Property	Value
FQN	`qa.pyrefly`
Dependencies	Hard: `core.packages`

Targets:

Target	Description
`pyrefly`	Run pyrefly.
`pyrefly-dirty`	Marks pyrefly dirty
`pyrefly-clean`	Uninstall pyrefly and removes cached data.

Settings:

Setting	Description	Default
`PYREFLY_SRC`	Source folder for code analysis. Left empty to use value from pyproject.toml	`src`
`PYREFLY_REQUIREMENTS`	Python requirements to be installed (via pip).	``

pyupgrade¶

Automatically upgrade syntax for newer versions of the language.

Property	Value
FQN	`qa.pyupgrade`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`pyupgrade`	Run pyupgrade.
`pyupgrade-dirty`	Marks pyupgrade dirty
`pyupgrade-clean`	Uninstall pyupgrade.

Settings:

Setting	Description	Default
`PYUPGRADE_SRC`	Source folder to scan for XML and ZCML files.	`src`
`PYUPGRADE_PARAMETERS`	Additional parameters for pyupgrade, see https://github.com/asottile/pyupgrade for details.	`--py38-plus`

ruff¶

Code formatting with ruff.

Property	Value
FQN	`qa.ruff`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`ruff`	Run ruff.
`ruff-dirty`	Marks ruff dirty
`ruff-clean`	Uninstall ruff.

Settings:

Setting	Description	Default
`RUFF_SRC`	Source folder to scan for Python files to run ruff on.	`src`

Test¶

Project testing.

Property	Value
FQN	`qa.test`
Dependencies	Hard: `core.packages`

Targets:

Target	Description
`test`	Run project tests. The :ref:`run-tests` template can be used for automatic test script creation.

Settings:

Setting	Description	Default
`TEST_COMMAND`	The command which gets executed. Defaults to the location the :ref:`run-tests` template gets rendered to if configured.	`.mxmake/files/run-tests.sh`
`TEST_REQUIREMENTS`	Additional Python requirements for running tests to be installed (via pip).	`pytest`
`TEST_DEPENDENCY_TARGETS`	Additional make targets the test target depends on.	``

zpretty¶

Format XML and ZCML with zpretty.

Property	Value
FQN	`qa.zpretty`
Dependencies	Hard: `core.mxenv`

Targets:

Target	Description
`zpretty`	Run zpretty.
`zpretty-dirty`	Marks zpretty dirty
`zpretty-clean`	Uninstall zpretty.

Settings:

Setting	Description	Default
`ZPRETTY_SRC`	Source folder to scan for XML and ZCML files.	`src`

System¶

Operating System specific domains.

System dependencies¶

System dependency management.

Property	Value
FQN	`system.dependencies`
Dependencies	Hard: `core.base`

Targets:

Target	Description
`system-dependencies`	Install system dependencies.

Settings:

Setting	Description	Default
`SYSTEM_DEPENDENCIES`	Space separated system package names.	``