docs: add README with usage and troubleshooting details

- Introduces a README file with an overview of the SFX Builder tool - Includes sections on functionality, prerequisites, quickstart, and examples - Provides parameter explanations, file structure details, and troubleshooting tips - Adds licensing information under the MIT License
2025-06-15 16:33:31 +02:00
parent abe60210d2
commit ab763cc1bd
1 changed files with 129 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,129 @@
+# Self-Extracting Archive (SFX) Builder
+
+Dieses Projekt packt beliebige Dateien und ein Start-Skript (Entrypoint) zu
+einer einzigen, selbst-extrahierenden **`.run`**-Datei zusammen.
+Ideal, wenn du eine Anwendung, ein Install- oder Update-Paket ohne
+externe Abhängigkeiten verteilen möchtest.
+
+---
+
+## Inhalt
+
+1. [Funktionsweise](#funktionsweise)
+2. [Voraussetzungen](#voraussetzungen)
+3. [Schnellstart](#schnellstart)
+4. [Beispiele](#beispiele)
+5. [Erklärung der Parameter](#erklärung-der-parameter)
+6. [Dateiaufbau des SFX](#dateiaufbau-des-sfx)
+7. [Troubleshooting](#troubleshooting)
+8. [Lizenz](#lizenz)
+
+---
+
+## Funktionsweise
+
+1. **`build_sfx.sh`**  
+   *Erstellt* ein SFX-Archiv:  
+   - komprimiert das Payload-Verzeichnis mit **`tar`** + **`zstd`**  
+   - injiziert den komprimierten Stream und Metadaten in **`sfx_header.sh`**  
+   - liefert eine ausführbare **`*.run`**-Datei
+
+2. **`sfx_header.sh`**  
+   *Läuft* beim Entpacken auf dem Zielsystem:  
+   - extrahiert das Archiv in ein temporäres Verzeichnis  
+   - macht den angegebenen Entrypoint ausführbar  
+   - führt ihn mit sämtlichen an die `.run`-Datei übergebenen Argumenten aus  
+
+---
+
+## Voraussetzungen
+
+| Tool            | Zweck                       | Getestete Version |
+|-----------------|----------------------------|-------------------|
+| `bash`          | Shell-Interpreter          | ≥ 4.2             |
+| `tar`           | Paketierung                | _(coreutils)_     |
+| `zstd`          | Kompression                | ≥ 1.5             |
+| `numfmt`        | Menschliche Größenangaben  | _(coreutils)_     |
+| GNU `sed`, `grep`, `cut`, `wc`, `mktemp`      | Hilfs-Tools       | _(coreutils)_     |
+
+> **Tipp:** Unter Debian/Ubuntu genügt:  
+> `sudo apt install zstd coreutils`  
+
+---
+
+## Schnellstart
+
+```bash
+# 1) Projekt klonen
+git clone https://github.com/<user>/sfx-builder.git
+cd sfx-builder
+
+# 2) Payload vorbereiten
+mkdir payload && cp -r <deine_dateien> payload/
+chmod +x payload/start.sh          # dein Entrypoint
+
+# 3) SFX erzeugen
+./build_sfx.sh   --payload-dir payload   --entrypoint start.sh   --output cool_tool.run
+
+# 4) Verteilen & ausführen
+scp cool_tool.run user@host:/tmp
+ssh user@host "chmod +x /tmp/cool_tool.run && /tmp/cool_tool.run --help"
+```
+
+---
+
+## Beispiele
+
+```bash
+# Minimale Syntax (Standard-Ausgabe: sfx.run)
+./build_sfx.sh -p payload -e start.sh
+
+# Eigenen Ausgabepfad wählen
+./build_sfx.sh -p payload -e bin/app.sh -o dist/app_installer.run
+
+# Debug-Info des erzeugten Archivs prüfen
+bash -x cool_tool.run --version
+```
+
+---
+
+## Erklärung der Parameter
+
+| Option                     | Alias | Pflicht? | Beschreibung                                     |
+|----------------------------|-------|----------|--------------------------------------------------|
+| `--payload-dir <DIR>`      | `-p`  | ✅       | Verzeichnis mit allen zu verteilenden Dateien    |
+| `--entrypoint <FILE>`      | `-e`  | ✅       | Ausführbare Datei *innerhalb* von **DIR**        |
+| `--output <FILE>`          | `-o`  | ❌       | Zielpfad der erzeugten `.run`-Datei (Default: `sfx.run`) |
+
+---
+
+## Dateiaufbau des SFX
+
+```text
+┌─────────────┐  sfx_header.sh            (Bootstrap-Logik)
+├─────────────┤  __ARCHIVE_BEGIN__        (Marker)
+│  ZSTD-Tar   │  payload.tar.zst          (komprimierter Payload)
+└─────────────┘
+```
+
+- **`ARCHIVE_LINE`** = Zeilennummer, ab der das komprimierte Archiv beginnt  
+- **`ENTRYPOINT`**  = Dateiname des Start-Skripts im Payload-Archiv  
+
+Die Platzhalter werden beim Build automatisch ersetzt.
+
+---
+
+## Troubleshooting
+
+| Problem                               | Ursache / Lösung                                                  |
+|---------------------------------------|-------------------------------------------------------------------|
+| `zstd: command not found`             | Installiere das Paket `zstd`.                                     |
+| Entrypoint wird nicht ausgeführt      | Prüfe Ausführungsrechte (`chmod +x`).                             |
+| „Marker __ARCHIVE_BEGIN__ not found“  | Stelle sicher, dass der Header unverändert ist.                   |
+| `bad tar header` bei Ausführung       | Header im Repo vs. Build-Header gemischt? `make clean && make`.   |
+
+---
+
+## Lizenz
+
+Veröffentlicht unter der MIT-Lizenz – siehe `LICENSE` für Details.