Skip to content

getting-started.md

Latest commit

 

History

History
95 lines (63 loc) · 3.36 KB

getting-started.md

File metadata and controls

95 lines (63 loc) · 3.36 KB

Getting started

How to bootstrap a project with mxmake

Requirements:

  • make has to be installed. This is usually done by your system's package manager - as sudo apt install make on Debian-/Ubuntu-based systems.
  • Python 3 has to be installed with the venv module. Some system Python installations need extra action here - as sudo apt install python-venv on Debian-/Ubuntu-based systems.

Create a project folder and enter it:

mkdir myproject
cd myproject

You can either install mxmake globally or in a virtual environment.

For global installation do a pip install mxmake, otherwise create a virtual environment, activate it, and install it like so:

python3 -m venv venv
. venv/bin/activate
pip install mxmake

Now create an initial Makefile with mxmake:

mxmake init

This is an interactive session and some questions are to be answered. If in doubt select the core topic and then just hit {kbd}Return until done.

This creates an empty mx.ini (only if it does not exist already) and a Makefile.

To update an existing Makefile without beeing prompted interactive, run mxmake update.

How to change the settings

The Makefile consists of three sections:

  1. Header with configured topics/domains
  2. Settings (for customization)
  3. Makefile logic (do not edit)

The header is not intended for editing, thus it does not cause any harm by adding or removing domains here. It is considered during the execution of mxmake init respective mxmake update. Added or removed topics are checked or unchecked accordingly on the next run.

The settings section is where customization is happening. Domains can provide configurable settings. Setting names must be unique among all domains. Thus they are usually prefixed.

Each setting provides a description and an optional default value.

For details read the chapter on topics and it's domains.

Do not add custom settings to settings section. They will be lost on next mxmake init respective mxmake update run.

Python Package Installer

By default, mxmake uses pip as the package installer. You can switch to UV by setting PYTHON_PACKAGE_INSTALLER=uv in the settings section.

When using UV, mxmake automatically detects if UV is installed globally or installs it locally in the virtual environment.

When using UV, you should explicitly set `UV_PYTHON` to specify which Python version UV should use. While `UV_PYTHON` currently defaults to `PRIMARY_PYTHON` for backward compatibility, this default may change in future versions. Set `UV_PYTHON` explicitly to avoid surprises.

Example:

PRIMARY_PYTHON?=python3
PYTHON_PACKAGE_INSTALLER?=uv
UV_PYTHON?=3.14

How to use on the Windows operating system

mxmake works excellent on Windows!

On Windows it needs a Bash shell. Fortunately the GIT VCS comes with the a fully function Bash, the git-bash. Please follow GIT's official installation instructions.

Install make as described here

Further you need a Python >=3.10 installation..

Dependent on the topics and domains you use, you may need to install additional software, but this is no different from Linux/OSX.