Merge pull request #58 from mxstack/docs/uv-workflow-and-python-310

Document UV-only workflow and fix Python 3.10 minimum

Author: jensens

docs/source/getting-started.md

@@ -2,42 +2,94 @@
 
 ## How to bootstrap a project with mxmake
 
-Requirements:
+### Essential Requirements
 
-- [`make`](https://www.gnu.org/software/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.
+All installation methods require:
+- [`make`](https://www.gnu.org/software/make/) command-line tool
+  - Ubuntu/Debian: `sudo apt install make`
+  - macOS: `xcode-select --install`
+  - Windows: [See installation guide](https://gist.github.com/evanwill/0207876c3243bbb6863e65ec5dc3f058#make)
 
-Create a project folder and enter it:
+### Choose Your Installation Method
 
+mxmake supports two installation approaches:
+
+#### Option 1: UV-only (Modern, Recommended)
+
+**Requirements**: Only [UV](https://docs.astral.sh/uv/) - **NO Python installation needed!**
+
+UV automatically downloads Python when creating virtual environments, making it the simplest option for new projects.
+
+**Install UV**:
+```shell
+# Official installer (Linux/macOS)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or via pip (if you already have Python)
+pip install uv
+```
+
+**Bootstrap your project**:
 ```shell
-mkdir myproject
-cd myproject
+mkdir myproject && cd myproject
+
+# Run mxmake init (UV downloads Python automatically)
+uvx mxmake init
+
+# Answer prompts interactively or use --preseeds for automation
+# Select topics and configure settings
+
+# Run make install (UV creates venv with downloaded Python)
+make install
 ```
 
-You can either install *mxmake* globally or in a virtual environment.
+**Key advantages**:
+- No Python pre-installation required
+- UV downloads the exact Python version you specify
+- Faster package installation
+- Ideal for CI/CD environments
 
-For global installation do a `pip install mxmake`, otherwise create a virtual environment, activate it, and install it like so:
+```{note}
+When using UV, set `PYTHON_PACKAGE_INSTALLER=uv` and `UV_PYTHON=3.14` (or your preferred version) in the Makefile settings section. UV will automatically download and use that Python version.
+```
+
+#### Option 2: Traditional pip-based
 
+**Requirements**: Python 3.10+ with venv module
+- Ubuntu/Debian: `sudo apt install python3 python3-venv`
+- macOS: Python 3.10+ from [python.org](https://www.python.org/downloads/)
+- Windows: Python 3.10+ from [python.org](https://www.python.org/downloads/windows/)
+
+**Install mxmake**:
 ```shell
+mkdir myproject && cd myproject
+
+# Option A: Global installation
+pip install mxmake
+
+# Option B: In a virtual environment
 python3 -m venv venv
-. venv/bin/activate
+. venv/bin/activate  # On Windows: venv\Scripts\activate
 pip install mxmake
 ```
 
-Now create an initial `Makefile` with *mxmake*:
-
+**Bootstrap your project**:
 ```shell
 mxmake init
+
+# Answer prompts interactively
+# This creates mx.ini and Makefile
+
+make install
 ```
 
-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.
+### After Initialization
 
-This creates an empty `mx.ini` (only if it does not exist already) and a `Makefile`.
+Both methods create:
+- `Makefile` - Generated by mxmake with your selected topics/domains
+- `mx.ini` - Configuration for mxdev (if you selected that option)
 
-To update an existing Makefile without beeing prompted interactive, run `mxmake update`.
+To update an existing Makefile without interactive prompts, run `mxmake update`.
 
 ## How to change the settings
 
@@ -65,19 +117,39 @@ 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](https://docs.astral.sh/uv/) by setting `PYTHON_PACKAGE_INSTALLER=uv` in the settings section.
+mxmake supports two package installers:
 
-When using UV, mxmake automatically detects if UV is installed globally or installs it locally in the virtual environment.
+**UV (Recommended)**: Modern, fast package installer that can automatically download Python.
+- Set `PYTHON_PACKAGE_INSTALLER=uv` in the Makefile
+- UV is auto-detected if installed globally, or installed locally in the venv
+- **Specify `UV_PYTHON` explicitly** (e.g., `3.14`) to control which Python version UV downloads
 
-```{note}
-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.
-```
+**pip (Default)**: Traditional package installer, requires Python pre-installed.
+- Works with any Python 3.10+ installation
+- Uses the Python specified in `PRIMARY_PYTHON` setting
 
-Example:
+Example UV configuration:
 ```makefile
-PRIMARY_PYTHON?=python3
 PYTHON_PACKAGE_INSTALLER?=uv
-UV_PYTHON?=3.14
+UV_PYTHON?=3.14  # UV downloads Python 3.14 automatically
+```
+
+Example pip configuration:
+```makefile
+PRIMARY_PYTHON?=python3.12
+PYTHON_PACKAGE_INSTALLER?=pip  # Default
+```
+
+```{important}
+When using UV, **always set `UV_PYTHON` explicitly**. While it currently defaults to `PRIMARY_PYTHON` for backward compatibility, relying on this default is not recommended and may change in future versions.
+```
+
+```{note}
+With UV + `UV_PYTHON` explicitly set:
+- `PRIMARY_PYTHON` is **not needed** (only used as UV_PYTHON default)
+- `PYTHON_MIN_VERSION` is **not needed** (validation skipped with global UV)
+
+These settings are **only required** for pip-based workflows.
 ```
 
 ## How to use on the Windows operating system

docs/source/migration.md

@@ -49,15 +49,15 @@ topics:
 
 ## Version 1.0a6
 
-### Dropped: Python 3.8 support
+### Dropped: Python 3.8 and 3.9 support
 
-**Breaking Change**: Minimum Python version changed from 3.7/3.8 to 3.9.
+**Breaking Change**: Minimum Python version changed from 3.8 to 3.10.
 
 **Migration**:
-- Ensure your project uses Python 3.9 or later
+- Ensure your project uses Python 3.10 or later
 - Update `PYTHON_MIN_VERSION` setting if needed:
   ```makefile
-  PYTHON_MIN_VERSION?=3.9
+  PYTHON_MIN_VERSION?=3.10
   ```
 
 ## Version 1.0a4

docs/source/preseeds.md

@@ -15,8 +15,7 @@ topics:
   core:
     # include domain mxenv
     mxenv:
-      # set PYTHON_MIN_VERSION, PYTHON_PACKAGE_INSTALLER and UV_PYTHON
-      PYTHON_MIN_VERSION: 3.14
+      # Minimal UV configuration - UV downloads Python automatically!
       PYTHON_PACKAGE_INSTALLER: uv
       UV_PYTHON: "3.14"
   qa:
@@ -48,13 +47,26 @@ When using UV, you should explicitly set `UV_PYTHON` to specify which Python ver
 The `UV_PYTHON` setting accepts version specs like `3.13`, `3.14`, or `[email protected]`:
 
 ```yaml
+# Minimal UV configuration (recommended)
 topics:
   core:
     mxenv:
-      PYTHON_MIN_VERSION: "3.14"
-      PRIMARY_PYTHON: python3
       PYTHON_PACKAGE_INSTALLER: uv
-      UV_PYTHON: "3.14"  # Explicitly specify Python version for UV
+      UV_PYTHON: "3.14"  # UV downloads this Python version
+```
+
+**Note**: When using UV with `UV_PYTHON` explicitly set:
+- `PYTHON_MIN_VERSION` is **not needed** (validation skipped with global UV)
+- `PRIMARY_PYTHON` is **not needed** (only used if UV_PYTHON is not set)
+
+For traditional pip-based workflows, you would set:
+```yaml
+# Traditional pip configuration (requires Python pre-installed)
+topics:
+  core:
+    mxenv:
+      PRIMARY_PYTHON: python3.12
+      PYTHON_PACKAGE_INSTALLER: pip  # default
 ```
 
 ## Examples
@@ -77,14 +89,13 @@ Enter the `hello-world-` directory and create a file `preseed.yaml`:
 topics:
   core:
     mxenv:
-      PYTHON_MIN_VERSION: "3.14"
       PYTHON_PACKAGE_INSTALLER: uv
-      UV_PYTHON: "3.14"
+      UV_PYTHON: "3.14"  # UV downloads Python 3.14
     sources:
   qa:
-    ruff
-    mypy
-    test
+    ruff:
+    mypy:
+    test:
 
 mx-ini: true
 ```

src/mxmake/tests/expected/Makefile

@@ -44,8 +44,8 @@ EXTRA_PATH?=
 PRIMARY_PYTHON?=python3
 
 # Minimum required Python version.
-# Default: 3.9
-PYTHON_MIN_VERSION?=3.9
+# Default: 3.10
+PYTHON_MIN_VERSION?=3.10
 
 # Install packages using the given package installer method.
 # Supported are `pip` and `uv`. When `uv` is selected, a global installation

src/mxmake/tests/test_templates.py

@@ -562,7 +562,7 @@ def test_Makefile(self, tempdir):
             "core.base.INCLUDE_MAKEFILE": "include.mk",
             "core.base.EXTRA_PATH": "",
             "core.mxenv.PRIMARY_PYTHON": "python3",
-            "core.mxenv.PYTHON_MIN_VERSION": "3.9",
+            "core.mxenv.PYTHON_MIN_VERSION": "3.10",
             "core.mxenv.PYTHON_PACKAGE_INSTALLER": "pip",
             "core.mxenv.UV_PYTHON": "$(PRIMARY_PYTHON)",
             "core.mxenv.VENV_ENABLED": "true",

src/mxmake/topics/core/mxenv.mk

@@ -31,7 +31,7 @@
 #:
 #:[setting.PYTHON_MIN_VERSION]
 #:description = Minimum required Python version.
-#:default = 3.9
+#:default = 3.10
 #:
 #:[setting.PYTHON_PACKAGE_INSTALLER]
 #:description = Install packages using the given package installer method.