add examples to preeseeds, overhaul make.md

jensens · jensens · commit ecfc28f57aab · 2025-03-20T23:25:29.000+01:00
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -29,5 +29,4 @@ extending
 dependencies
 make
 contributing
-usage-old
 ```
diff --git a/docs/source/make.md b/docs/source/make.md
@@ -19,24 +19,26 @@ If the dependencies are up-to-date, "make" will skip the build process for the t
 
 This way, "make" can handle the complex and interdependent steps to form processes of a project, automatically handling the correct order of steps and avoiding unnecessary execution of steps.
 
-## The "phony" target
+## The "PHONY" target
 
-In "make", a "phony" target is a special type of target that is used to define a target that is not a file or directory. Phony targets are used to describe actions that need to be performed but do not result in a file that can be used as a target in another rule.
+In "make", a "PHONY" target is a special type of target that is used to define a target that is not a file or directory.
+Phony targets are used to describe actions that need to be performed but do not result in a file that can be used as a target in another rule.
 
-For example, a common use case for a phony target is to define a "clean" target that removes all generated files.
-A makefile could have a rule like the following:
+For example, a common use case for a PHONY target is to define a "clean" target that removes all generated files.
+A Makefile could have a rule like the following:
 
-```makefile
+```Makefile
 .PHONY: clean
 
 clean:
     rm -rf build
 ```
 
-The ".PHONY" line indicates that the "clean" target is a phony target. When "make clean" is run, the command in the rule will be executed to remove the "build" directory.
+The ".PHONY" line indicates that the "clean" target is a PHONY target.
+When "make clean" is run, the command in the rule will be executed to remove the "build" directory.
 
-Phony targets are useful because they provide a way to define targets that don't correspond to files and can be used to perform arbitrary actions such as cleaning the build directory or running tests.
-Additionally, "make" considers phony targets to always be out-of-date, so the commands for a phony target will always be executed, even if its dependencies are up-to-date.
+PHONY targets are useful because they provide a way to define targets that don't correspond to files and can be used to perform arbitrary actions such as cleaning the build directory or running tests.
+Additionally, "make" considers PHONY targets to always be out-of-date, so the commands for a PHONY target will always be executed, even if its dependencies are up-to-date.
 This can be useful when you want to guarantee that an action is performed, such as cleaning the build directory before a build.
 
 (make-sentinel-files)=
@@ -52,32 +54,32 @@ To overcome this challenge, other methods, such as using sentinel files, can be
 Sentinel files are used to indicate whether a target has been built, or if a process has been completed.
 ```
 
-For example, a makefile could use a sentinel file to track the state of a build process.
-The makefile could contain a rule like the following:
+For example, a Makefile could use a sentinel file to track the state of a build process.
+The Makefile could contain a rule like the following:
 
-```makefile
+```Makefile
 
 build: sentinel
     # build commands go here
 
 sentinel:
-    # build commands go here
     touch sentinel
 ```
 
-In this example, the "sentinel" file is used to track the state of the build. If the "sentinel" file exists, it means that the build has been completed and the build commands will be skipped.
+In this example, the "sentinel" file is used to track the state of the build.
+If the "sentinel" file exists, it means that the build has been completed and the build commands will be skipped.
 If the "sentinel" file does not exist, the build commands will be executed and the "sentinel" file will be created to indicate that the build has been completed.
 
 Sentinel files are useful in "make" because they provide a way to track the state of a build or process, allowing "make" to determine if a target needs to be rebuilt.
 This helps to avoid unnecessary rebuilds, which can save time and resources.
 
 ## Variables
 
-In "make", variables are used to store values that can be referenced in multiple places throughout the makefile. Variables are defined by assigning a value to a name and can be used in rules, dependencies, and commands.
+In "make", variables are used to store values that can be referenced in multiple places throughout the Makefile. Variables are defined by assigning a value to a name and can be used in rules, dependencies, and commands.
 
-For example, the following makefile uses a variable to store the name of the compiler:
+For example, the following Makefile uses a variable to store the name of the compiler:
 
-```makefile
+```Makefile
 
 CC = gcc
 
@@ -86,11 +88,11 @@ main: main.c
 ```
 
 In this example, the "CC" variable is defined with the value "gcc", which is then used in the command to compile the "main.c" file.
-This allows for easy modification of the compiler if needed, as the change only needs to be made in one place, instead of throughout the entire makefile.
+This allows for easy modification of the compiler if needed, as the change only needs to be made in one place, instead of throughout the entire Makefile.
 
 Variables can also be used to store values that are generated dynamically, such as the result of a shell command. For example:
 
-```makefile
+```Makefile
 
 OBJECTS = $(shell ls *.c | sed s/.c/.o/g)
 
@@ -102,13 +104,13 @@ In this example, the "OBJECTS" variable is defined as the result of a shell comm
 The "OBJECTS" variable can then be used in the dependencies and command of the "main" target.
 
 Variables in "make" can also be overridden on the command line, allowing for easy customization of the build process.
-For example, the following command would use a different compiler than the one defined in the makefile:
+For example, the following command would use a different compiler than the one defined in the Makefile further above:
 
 ```shell
 make CC=clang
 ```
 
-This way, "make" variables provide a flexible and convenient way to manage build configurations and reuse values throughout the makefile.
+This way, "make" variables provide a flexible and convenient way to manage build configurations and reuse values throughout the Makefile.
 
 There are many more details about variables in the GNU Make Manual.
 
diff --git a/docs/source/preseeds.md b/docs/source/preseeds.md
@@ -1,5 +1,7 @@
 # Preseeds
 
+## Introduction
+
 It is possible to pass configuration preseeds when creating a new project
 with `mxmake init`. This is useful if you have recurring default settings
 when creating projects with `mxmake`.
@@ -33,3 +35,110 @@ Now initialize the project with the preseeds:
 ```shell
 $ mxmake init -p preseeds.yaml
 ```
+
+## Examples
+
+### Create a simple Python project
+
+mxmake was made for the easy management of Python projects.
+
+This example shows how to create a very minimal project structure to build on.
+[mxdev][https://pypi.org/project/mxdev/] is integrated to manage versions, sources and more.
+
+Preconditions for this example:
+[uv](https://docs.astral.sh/uv/) is installed in the `PATH`.
+
+Use `uv init hello-world` to generate a minimal skeleton package.
+
+Enter the `hello-world-` directory and create a file `preseed.yaml`:
+
+```yaml
+topics:
+  core:
+    mxenv:
+      PYTHON_MIN_VERSION: "3.10"
+      PYTHON_PACKAGE_INSTALLER: uv
+      MXENV_UV_GLOBAL: true
+    sources:
+  qa:
+    ruff
+    mypy
+    test
+
+mx-ini: true
+```
+
+Then run:
+
+```bash
+uv mxmake init -p preseed.yaml
+```
+
+Edit the `mx.ini` and insert after the first line a new line: `main-package = -e .`.
+
+Now run:
+```bash
+make install
+```
+
+Now you have a basic environment to build on.
+`make format` wont work, because it looks in the `./src` directory, but this can be fixed by restrcuturing the code.
+You may want to use a different skeleton generator than "uv" here.
+
+
+### Create a Makefile for a simple Plone backend
+
+[Plone](https://plone.org) is an enterprise CMS written in Python (backend) and Javascript (frontend).
+mxmake helps to create the backend.
+It helps to develop and manage code for integrations and distributions, Plone-add-ons and the Plone-core-development itself.
+
+Preconditions for this example:
+[uv](https://docs.astral.sh/uv/) is installed in the `PATH`.
+
+Go in a fresh directory and create a file `plone-preseed.yaml`:
+
+```yaml
+topics:
+  core:
+    base:
+      RUN_TARGET: zope-start
+    mxenv:
+      PYTHON_MIN_VERSION: "3.10"
+      PYTHON_PACKAGE_INSTALLER: uv
+      MXENV_UV_GLOBAL: true
+  applications:
+    zope:
+    plone:
+mx-ini: true
+```
+
+Run:
+```bash
+mxmake init -p plone-preseed.yaml
+echo "-c https://dist.plone.org/release/6.1-latest/constraints.txt" >requirements.txt
+echo "Plone" >>requirements.txt
+```
+
+In the
+- 1st line the `Makefile` and the `mx.ini` configuration is generated,
+- 2nd line a Python requirements is created with a reference to a Plone release file, pinning the versions,
+- 3rd line the Plone package is declared as the main package.
+
+Now "make" is now ready to run.
+
+After the first command watch out for a line with the generated password.
+It looks like so:
+
+> Generated password for initial user 'admin' is: SOME-CRYPTIC-PASSWORD
+
+Execute:
+
+```bash
+make plone-site-create
+make run
+```
+
+In your browser go to [localhost:8080](http://localhost:8080).
+There runs a Plone with a backend ready for Volto (the frontend application for Plone) installed.
+
+This can be combined with the above example for a Python package to create self-contained reproducible environments for development and deployment.
