Split up jlmkr.py into smaller files as-is

.github/workflows/build.yml

@@ -0,0 +1,59 @@
+# Inspiration from <https://github.com/pypa/hatch/issues/669>
+
+name: Build
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+  workflow_dispatch:
+
+jobs:
+
+  build:
+    name: Build jlmkr tool
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"  # TrueNAS SCALE 24.04 Dragonfish
+    steps:
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up pip cache
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: ${{ runner.os }}-pip-
+
+      - name: Install Hatch
+        uses: pypa/hatch@install
+
+      - name: Run style check
+        run: hatch fmt --check
+
+#       - name: Run unit tests
+#         run: hatch run +py=${{ matrix.python-version }} test:test
+
+      - name: Build distribution
+        run: hatch build -t zipapp -t appzip
+
+#       - name: Upload artifacts
+#         uses: actions/upload-artifact@v4
+#         with:
+#           path:
+#             - dist/jlmkr
+#             - dist/jlmkr-*.zip
+#           if-no-files-found: error

.github/workflows/test.yml

@@ -87,6 +87,6 @@ jobs:
         env:
           PYTHONUNBUFFERED: 1
         run: |
-          sudo chown 0:0 jlmkr.py ./test/test-jlmkr
+          sudo chown -R 0:0 src jlmkr.py ./test/test-jlmkr
           sudo bash ./test/test-jlmkr
           sudo ./test/test.sh

.gitignore

@@ -1,3 +1,23 @@
+# SPDX-FileCopyrightText: © 2024 Jip-Hop and the Jailmakers <https://github.com/Jip-Hop/jailmaker>
+#
+# SPDX-License-Identifier: LGPL-3.0-only
+
+dist/
+
+# jail-specific
 /.lxc/
 /jails/
-.DS_Store
+
+# Mac-specific
+.DS_Store
+._.DS_Store
+
+# <https://github.com/github/gitignore/blob/main/Python.gitignore>
+
+/.venv/
+
+__pycache__/
+*.py[cod]
+
+.pytest_cache/
+.ruff_cache/

README.md

@@ -212,6 +212,51 @@ TODO: write comparison between systemd-nspawn (without `jailmaker`), LXC, VMs, D
 
 The rootfs image `jlmkr.py` downloads comes from the [Linux Containers Image server](https://images.linuxcontainers.org). These images are made for LXC. We can use them with systemd-nspawn too, although not all of them work properly. For example, the `alpine` image doesn't work well. If you stick with common systemd based distros (Debian, Ubuntu, Arch Linux...) you should be fine.
 
+## Development
+
+After cloning the project, navigate into its working directory and create a self-contained Python [virtual environment](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-and-using-virtual-environments). Traditionally you would do that using the following command. Unfortunately, TrueNAS SCALE has [left out](https://ixsystems.atlassian.net/browse/NAS-130029) a necessary library from the base installation and *this command will fail:*
+
+    python3 -m venv .venv
+
+The following workaround should accomplish the same task in more steps.
+```
+python3 -m venv --without-pip .venv
+curl -OL https://bootstrap.pypa.io/pip/pip.pyz
+.venv/bin/python3 pip.pyz install pip
+rm pip.pyz
+```
+*Note: This process and the resulting build environment will cache some items under `~/.local/share` in addition to the project directory.*
+
+Activate the venv into your *current* shell session.
+
+    source .venv/bin/activate
+
+Develop away. Note that when you're done, you can undo this activation and return to the system's default Python environment. Just call a function that activation has inserted into your shell session:
+
+    deactivate
+
+For more information on Python standard venvs, go to [the source](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-and-using-virtual-environments).
+
+### Hatching a build
+
+While in an *active* session, install the [Hatch](https://hatch.pypa.io) project manager. This will load quite a flurry of dependencies, but will only do so into the new `.venv` directory. *(And a bit into self-managed directories under `~/.local/share`.)*
+
+    pip install hatch
+
+Build the "zipapp" target. This will create a `dist/jlmkr` tool which is the direct descendant of Jip-Hop's original `jlmkr.py` script.
+
+    hatch build -t zipapp
+
+Now build the "appzip" target. This bundles the tool, `README.md` and `LICENSING` into a downloadable zip archive.
+
+    hatch build -t appzip
+
+If you make any changes *to the embedded builder plugins* that perform the above, then you will need to clear caches between builds. Otherwise and generally, you will not need to do so.
+
+    hatch env prune
+
+Hatch has oodles more features yet to be explored, such as: automated testing, code coverage, and style checking. For now, we've gotten it building.
+
 ## Filing Issues and Community Support
 
 When in need of help or when you think you've found a bug in `jailmaker`, [please start with reading this](https://github.com/Jip-Hop/jailmaker/discussions/135).