Topics and Domains#

Topics are collections of domains.

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

i18n#

Contains domains for managing translations.

Gettext#

Provide targets for working with gettext

FQN

i18n.gettext

Targets
gettext-create

Create message catalogs for all defined languages if not exists.

gettext-update

Update translations.

gettext-compile

Compile message catalogs.

Settings
GETTEXT_LOCALES_PATH

Path of directory containing the message catalogs.

Default: locale

GETTEXT_DOMAIN

Translation domain to use.

Default: ``

GETTEXT_LANGUAGES

Space separated list of language identifiers.

Default: ``

Lingua#

Extract translatable texts from your code.

FQN

i18n.lingua

Depends on

core.mxenv

i18n.gettext

Targets
lingua-extract

Extract translatable texts from your code.

lingua

Extract translatable texts from your code and create, update and compile message catalogs.

Settings
LINGUA_SEARCH_PATH

Path of directory to extract translatable texts from.

Default: src

LINGUA_PLUGINS

Python packages containing lingua extensions.

Default: ``

LINGUA_OPTIONS

Command line options passed to pot-create

Default: ``

LDAP#

LDAP topics description.

OpenLDAP#

Builds OpenLDAP from source

FQN

ldap.openldap

Depends on

core.base

Targets
openldap

Download and build OpenLDAP from source.

openldap-dirty

Rebuild OpenLDAP on next make run.

openldap-clean

Remove local OpenLDAP build.

Settings
OPENLDAP_VERSION

OpenLDAP version to download

Default: 2.4.59

OPENLDAP_URL

OpenLDAP base download URL

Default: https://www.openldap.org/software/download/OpenLDAP/openldap-release/

OPENLDAP_DIR

Build directory for OpenLDAP

Default: $(shell echo $(realpath .))/openldap

OPENLDAP_ENV

Build environment for OpenLDAP

Default: PATH=/usr/local/bin:/usr/bin:/bin

Python LDAP#

Builds and installs python-ldap against local OpenLDAP

FQN

ldap.python-ldap

Depends on

core.mxenv

ldap.openldap

Targets
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

Core#

Core topic description.

Base#

Defines common build targets and basic settings for project.

FQN

core.base

Targets
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 related targets, e.g. code style or type checks. Only gets included if any qa topic related domain is used.

Settings
DEPLOY_TARGETS

deploy target dependencies.

Default: ``

RUN_TARGET

target to be executed when calling make run

Default: ``

CLEAN_FS

Additional files and folders to remove when running clean target

Default: ``

INCLUDE_MAKEFILE

Optional makefile to include before default targets. This can be used to provide custom targets or hook up to existing targets.

Default: 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.

Default: ``

MX Environment#

Python environment management.

FQN

core.mxenv

Depends on

core.base

Targets
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
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.

Default: python3

PYTHON_MIN_VERSION

Minimum required Python version.

Default: 3.9

PYTHON_PACKAGE_INSTALLER

Install packages using the given package installer method. Supported are pip and uv. If uv is used, its global availability is checked. Otherwise, it is installed, either in the virtual environment or using the PRIMARY_PYTHON, dependent on the VENV_ENABLED setting. If VENV_ENABLED and uv is selected, uv is used to create the virtual environment.

Default: pip

MXENV_UV_GLOBAL

Flag whether to use a global installed ‘uv’ or install it in the virtual environment.

Default: false

VENV_ENABLED

Flag whether to use virtual environment. If false, the interpreter according to PRIMARY_PYTHON found in PATH is used.

Default: 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.

Default: 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.

Default: .venv

MXDEV

mxdev to install in virtual environment.

Default: mxdev

MXMAKE

mxmake to install in virtual environment.

Default: mxmake

MX Files#

Project file generation.

FQN

core.mxfiles

Depends on

core.mxenv

Soft depends on

core.sources

Targets
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
PROJECT_CONFIG

The config file to use.

Default: mx.ini

Packages#

Install python packages.

FQN

core.packages

Depends on

core.mxfiles

Targets
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
PACKAGES_ALLOW_PRERELEASES

Allow prerelease and development versions. By default, the package installer only finds stable versions.

Default: 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.

FQN

core.proxy

Depends on

core.mxfiles

Sources#

Source package management.

FQN

core.sources

Depends on

core.mxenv

Targets
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.

Javascript#

Javascript topic description.

Karma tests#

Run JavaScript tests using karma.

FQN

js.karma

Depends on

js.nodejs

Targets
karma

Run karma.

Settings
KARMA_CONFIG

Karma config file.

Default: karma.conf.js

KARMA_OPTIONS

Karma additional command line options.

Default: --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.

FQN

js.nodejs

Depends on

core.base

Targets
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
NODEJS_PACKAGE_MANAGER

The package manager to use. Defaults to npm. Possible values are npm and pnpm

Default: npm

NODEJS_PREFIX

Value for --prefix option when installing packages.

Default: .

NODEJS_PACKAGES

Packages to install with --no-save option.

Default: ``

NODEJS_DEV_PACKAGES

Packages to install with --save-dev option.

Default: ``

NODEJS_PROD_PACKAGES

Packages to install with --save-prod option.

Default: ``

NODEJS_OPT_PACKAGES

Packages to install with --save-optional option.

Default: ``

NODEJS_INSTALL_OPTS

Additional install options. Possible values are --save-exact and --save-bundle.

Default: ``

Rollup JavaScript module bundler#

Create JavaScript bundles with rollup.

FQN

js.rollup

Depends on

js.nodejs

Targets
rollup

Run rollup JavaScript bundler.

Settings
ROLLUP_CONFIG

Rollup config file.

Default: rollup.conf.js

SCSS Compiler#

Compile Stylesheets using SCSS.

FQN

js.scss

Depends on

js.nodejs

Targets
scss

Run SCSS Stylesheet Compiler.

Settings
SCSS_SOURCE

The SCSS root source file.

Default: scss/styles.scss

SCSS_TARGET

The target file for the compiles Stylesheet.

Default: scss/styles.css

SCSS_MIN_TARGET

The target file for the compressed Stylesheet.

Default: scss/styles.min.css

SCSS_OPTIONS

Additional options to be passed to SCSS compiler.

Default: --no-source-map=none

Web test runner#

Run JavaScript tests using web test runner.

FQN

js.wtr

Depends on

js.nodejs

Targets
wtr

Execute web test runner.

Settings
WTR_CONFIG

Web test runner config file.

Default: wtr.config.mjs

WTR_OPTIONS

Web test runner additional command line options.

Default: --coverage

Docs#

Docs topic description.

JSDoc Documentation#

JSDoc installation and integration into Sphinx.

FQN

docs.jsdoc

Depends on

js.nodejs

Sphinx Documentation#

Documentation generation with Sphinx.

FQN

docs.sphinx

Depends on

core.mxenv

Soft depends on

docs.jsdoc

Targets
docs

Generate Sphinx docs.

docs-live

Rebuild Sphinx documentation on changes, with live-reload in the browser using sphinx-autobuild.

docs-clean

Removes generated docs.

Settings
DOCS_SOURCE_FOLDER

Documentation source folder.

Default: docs/source

DOCS_TARGET_FOLDER

Documentation generation target folder.

Default: docs/html

DOCS_REQUIREMENTS

Documentation Python requirements to be installed (via pip).

Default: ``

QA#

QA topic description.

black#

Code formatting with black.

FQN

qa.black

Depends on

core.mxenv

Targets
black

Run black.

black-dirty

Marks black dirty

black-clean

Uninstall black.

Settings
BLACK_SRC

Source folder to scan for Python files to run black on.

Default: src

Coverage#

Project coverage testing.

FQN

qa.coverage

Depends on

qa.test

Targets
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
COVERAGE_COMMAND

The command which gets executed. Defaults to the location the :ref:run-coverage template gets rendered to if configured.

Default: .mxmake/files/run-coverage.sh

isort#

Import sorting with isort.

FQN

qa.isort

Depends on

core.mxenv

Targets
isort

Run isort.

isort-dirty

Marks isort dirty

isort-clean

Uninstall isort.

Settings
ISORT_SRC

Source folder to scan for Python files to run isort on.

Default: src

mypy#

Static code analysis with mypy.

FQN

qa.mypy

Depends on

core.packages

Targets
mypy

Run mypy.

mypy-dirty

Marks mypy dirty

mypy-clean

Uninstall mypy and removes cached data.

Settings
MYPY_SRC

Source folder for code analysis.

Default: src

MYPY_REQUIREMENTS

Mypy Python requirements to be installed (via pip).

Default: types-setuptools

pyupgrade#

Automatically upgrade syntax for newer versions of the language.

FQN

qa.pyupgrade

Depends on

core.mxenv

Targets
pyupgrade

Run pyupgrade.

pyupgrade-dirty

Marks pyupgrade dirty

pyupgrade-clean

Uninstall pyupgrade.

Settings
PYUPGRADE_SRC

Source folder to scan for XML and ZCML files.

Default: src

PYUPGRADE_PARAMETERS

Additional parameters for pyupgrade, see https://github.com/asottile/pyupgrade for details.

Default: --py38-plus

ruff#

Code formatting with ruff.

FQN

qa.ruff

Depends on

core.mxenv

Targets
ruff

Run ruff.

ruff-dirty

Marks ruff dirty

ruff-clean

Uninstall ruff.

Settings
RUFF_SRC

Source folder to scan for Python files to run ruff on.

Default: src

Test#

Project testing.

FQN

qa.test

Depends on

core.packages

Targets
test

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

Settings
TEST_COMMAND

The command which gets executed. Defaults to the location the :ref:run-tests template gets rendered to if configured.

Default: .mxmake/files/run-tests.sh

TEST_REQUIREMENTS

Additional Python requirements for running tests to be installed (via pip).

Default: pytest

TEST_DEPENDENCY_TARGETS

Additional make targets the test target depends on.

Default: ``

zpretty#

Format XML and ZCML with zpretty.

FQN

qa.zpretty

Depends on

core.mxenv

Targets
zpretty

Run zpretty.

zpretty-dirty

Marks zpretty dirty

zpretty-clean

Uninstall zpretty.

Settings
ZPRETTY_SRC

Source folder to scan for XML and ZCML files.

Default: src

System#

Sytem topic description.

System dependencies#

System dependency management.

FQN

system.dependencies

Depends on

core.base

Targets
system-dependencies

Install system dependencies.

Settings
SYSTEM_DEPENDENCIES

Space separated system package names.

Default: ``

Applications#

Application specific domains.

cookiecutter#

Tool to generate skeletons and configuration from cookiecutter templates.

FQN

applications.cookiecutter

Depends on

core.packages

Targets
cookiecutter

Install cookiecutter.

cookiecutter-dirty

Marks cookiecutter dirty.

cookiecutter-clean

Uninstall cookiecutter.

plone#

Plone application related

FQN

applications.plone

Depends on

applications.zope

Targets
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
PLONE_SITE_SCRIPT

Path to the script to create or purge a Plone site

Default: .mxmake/files/plone-site.py

PLONE_SITE_CREATE_FAIL_IF_EXISTS

Exit with an error if the Plone site already exists

Default: True

PLONE_SITE_PURGE_FAIL_IF_NOT_EXISTS

Exit with an error if the Plone site does not exists

Default: True

Twisted Server#

Install and start Twisted Server.

FQN

applications.twisted

Depends on

core.packages

Targets
twisted-start

Run Twisted Server

Settings
TWISTED_TWISTD_OPTIONS

The Twisted Application Configuration file.

Default: -ny

TWISTED_TAC_FILE

The Twisted Application Configuration file.

Default: twisted.tac

zest.releaser#

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

FQN

applications.zest-releaser

Depends on

core.mxenv

Targets
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
ZEST_RELEASER_PRERELEASE_OPTIONS

Options to pass to zest.releaser prerelease command.

Default: ``

ZEST_RELEASER_RELEASE_OPTIONS

Options to pass to zest.releaser release command.

Default: ``

ZEST_RELEASER_POSTRELEASE_OPTIONS

Options to pass to zest.releaser postrelease command.

Default: ``

ZEST_RELEASER_FULLRELEASE_OPTIONS

Options to pass to zest.releaser fullrelease command.

Default: ``

zope#

Zope and Plone application related

FQN

applications.zope

Depends on

applications.cookiecutter

Targets
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-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
ZOPE_CONFIGURATION_FILE

cookiecutter configuration file to use

Default: instance.yaml

ZOPE_TEMPLATE

cookiecutter configuration file to use

Default: 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.

Default: main

ZOPE_BASE_FOLDER

The Zope folder “instance” will be generated relative to this existing folder.

Default: .

ZOPE_SCRIPTNAME

script to run

Default: No Default

On this page