From 73c97e380193ca247994d4f95a1143e1a72ed9da Mon Sep 17 00:00:00 2001
From: JGZYES <JGZYES@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:37:35 +0800
Subject: [PATCH] examples: add example-pdm package template (pdm-control +
 bin/share/README)

---
 examples/example-pdm/README.md             | 64 ++++++++++++++++++++++
 examples/example-pdm/bin/hello             | 10 ++++
 examples/example-pdm/pdm-control           |  5 ++
 examples/example-pdm/share/data/README.txt |  2 +
 4 files changed, 81 insertions(+)
 create mode 100644 examples/example-pdm/README.md
 create mode 100644 examples/example-pdm/bin/hello
 create mode 100644 examples/example-pdm/pdm-control
 create mode 100644 examples/example-pdm/share/data/README.txt

diff --git a/examples/example-pdm/README.md b/examples/example-pdm/README.md
new file mode 100644
index 0000000..135516b
--- /dev/null
+++ b/examples/example-pdm/README.md
@@ -0,0 +1,64 @@
+# example-pdm
+
+A minimal, packable `.pdm` package. This folder is the **source layout** you hand
+to `pmm pack` — it shows the directory style a package should have before it becomes
+a `.pdm` archive.
+
+## Layout
+
+```
+example-pdm/
+├── pdm-control                 # package metadata (REQUIRED)
+├── bin/
+│   └── hello                   # executable payload -> added to PATH after install
+├── share/
+│   └── data/
+│       └── README.txt          # arbitrary payload file (folder name is free-form, NOT the package name)
+└── README.md                   # this file
+```
+
+## `pdm-control`
+
+A `KEY: value` text file, one field per line, at the root of the package folder.
+Recognized fields: `Package`, `Version`, `Architecture`, `Description`, `Maintainer`.
+
+```ini
+Package: example
+Version: 1.0.0
+Architecture: all
+Description: An example PMM package demonstrating the .pdm source layout
+Maintainer: PMM example <example@pmm.dev>
+```
+
+- `Package`  — the lowercase package name (also becomes the folder name on install).
+- `Version`  — any version string; supports `==`, `>=`, `<=`, `>`, `<`, `!=` matching.
+- `Architecture` — `all`, or a specific arch (e.g. `amd64` / `x86_64`).
+- `Description` / `Maintainer` — optional, used for registry dots and the uninstall entry.
+
+## How the layout maps to a `.pdm`
+
+`pmm pack <dir>` wraps the folder into a tar archive with three members
+(mirroring a Debian `.deb`):
+
+| member           | contents                                |
+|------------------|-----------------------------------------|
+| `control.tar.gz` | just `pdm-control`                      |
+| `data.tar.gz`    | everything else in the folder           |
+| `sha256sums`     | SHA-256 of `control.tar.gz` + `data.tar.gz` |
+
+So anything you place in `example-pdm/` (except `pdm-control`) ends up in `data.tar.gz`
+and is extracted into the install root on install.
+
+## Pack + install
+
+```bash
+# from the repo root
+pmm pack examples/example-pdm example-1.0.0.pdm
+pmm install example-1.0.0.pdm
+
+# `hello` should now be on PATH
+hello
+```
+
+To publish it to a registry mirror, also add a registry entry pointing at the `.pdm`
+file — see `mirror/packages/<pkg>.json` for the variant format.
diff --git a/examples/example-pdm/bin/hello b/examples/example-pdm/bin/hello
new file mode 100644
index 0000000..d9cb79e
--- /dev/null
+++ b/examples/example-pdm/bin/hello
@@ -0,0 +1,10 @@
+#!/bin/sh
+# Placeholder executable for the example-pdm package.
+#
+# After `pmm pack examples/example-pdm example.pdm` and
+# `pmm install example.pdm`, this file is unpacked into the install root
+# and <root>/bin/ is added to PATH, so you can run `hello` directly.
+#
+# In a real package, replace this with your actual binary (or put the
+# platform-specific executable here for each variant you build).
+echo "hello from example-pdm (pmm package manager)"
diff --git a/examples/example-pdm/pdm-control b/examples/example-pdm/pdm-control
new file mode 100644
index 0000000..81efccc
--- /dev/null
+++ b/examples/example-pdm/pdm-control
@@ -0,0 +1,5 @@
+Package: example
+Version: 1.0.0
+Architecture: all
+Description: An example PMM package demonstrating the .pdm source layout
+Maintainer: PMM example <example@pmm.dev>
diff --git a/examples/example-pdm/share/data/README.txt b/examples/example-pdm/share/data/README.txt
new file mode 100644
index 0000000..f02556c
--- /dev/null
+++ b/examples/example-pdm/share/data/README.txt
@@ -0,0 +1,2 @@
+This is the shipped asset for the example-pdm package.
+It is part of the payload placed under share/example/.