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
2. Voraussetzungen
3. Schnellstart
4. Beispiele
5. Erklärung der Parameter
6. Dateiaufbau des SFX
7. Troubleshooting
8. 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

# 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

# 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

┌─────────────┐  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.