Specifikace balíčku

Tato část definuje formální specifikace balíčků aplikací pro TOS 7. Všechny aplikace musí splňovat tuto specifikaci.

Životní cyklus aplikace

Aplikace TOS 7 se řídí jasně definovaným životním cyklem:

  Install ──► Configure ──► Start ──► Running
     │            │            │           │
     │            │            │           ├── Stop ──► Stopped ──► Start (Restart)
     │            │            │
     │            │            └── Crash ──► Auto-restart (if configured)
     │            │
     │            └── Upgrade ──► Stop ──► Install New Version ──► Migrate ──► Start
     │
     └── Uninstall ──► Stop ──► Cleanup ──► Remove

Fáze životního cyklu aplikací Deb:

Fáze	Spouštěč	Skript/operace	Očekávané chování
Před instalací	`dpkg -i`	`DEBIAN/preinst`	Vytvoření uživatele, kontrola předpokladů, vytvoření adresářů
Instalace	`dpkg -i`	Extrakce balíčku	Soubory jsou nasazeny podle specifikace balení (viz kapitola 8); skutečná instalační cesta v TOS 7 je `/Volume*/@apps/<appid>/`
Po instalaci	`dpkg -i`	`DEBIAN/postinst`	Nastavení oprávnění, povolení služby, spuštění služby
Spuštění	`systemctl start`	systemd / init.d	Spustí se proces aplikace
Zastavení	`systemctl stop`	systemd / init.d	Proces aplikace se řádně zastaví
Před odinstalací	`dpkg --remove`	`DEBIAN/prerm`	Zastavení služby
Po odinstalaci	`dpkg --remove`	`DEBIAN/postrm`	Vyčištění uživatele, dat a zbytkových souborů
Upgrade	`dpkg -i` (nová verze)	prerm → Upgrade → postinst	Zastavení staré verze, instalace nové verze, migrace dat, spuštění

Fáze životního cyklu aplikací Docker:

Fáze	Spouštěč	Operace	Očekávané chování	Další poznámky
Instalace	App Center (uživatel klikne na tlačítko "Instalovat")	Stažení obrazu, vytvoření svazků	Obraz je k dispozici, datové adresáře jsou vytvořeny	Platforma automaticky provede proces instalace; není nutný žádný další zásah vývojáře
Spuštění	App Center (uživatel klikne na tlačítko "Spustit") / `docker-compose up`	Spuštění kontejneru	Služba je přístupná	Uživatelé mohou službu také spustit ručně z příkazového řádku, v souladu s logikou operací platformy
Zastavení	App Center (uživatel klikne na tlačítko "Zastavit") / `docker-compose down`	Zastavení kontejneru	Služba je zastavena, data jsou zachována	Zastaví se pouze proces kontejneru; připojené datové svazky nejsou smazány
Upgrade	App Center (uživatel klikne na tlačítko "Aktualizovat", když je k dispozici nová verze)	Stažení nového obrazu, přestavba kontejneru	Žádný nebo krátký výpadek	Doporučuje se, aby aplikace podporovaly plynulé upgrady, aby nedošlo k přerušení dat
Odinstalace	App Center (uživatel klikne na tlačítko "Odinstalovat")	Odstranění kontejneru, volitelné vyčištění svazků	Všechny prostředky jsou uvolněny	Uživatelé se mohou rozhodnout, zda zachovají datové svazky, aby se zabránilo náhodnému smazání dat

Poznámka: "App Center" označuje vestavěné rozhraní pro správu aplikací systému TOS. Operace instalace/spuštění/zastavení/upgradu/odinstalace prováděné uživateli prostřednictvím tohoto rozhraní spustí odpovídající procesy životního cyklu.

Specifikace čísla verze

TOS 7 se řídí sémantickou verzí (SemVer):

MAJOR.MINOR.PATCH

MAJOR: Incompatible API changes
MINOR: Backward-compatible new features
PATCH: Backward-compatible bug fixes

Pravidla:

Každé podané číslo verze musí být přísně vyšší než předchozí verze
Downgrade verze jsou zakázány
Čísla verzí musí být konzistentní napříč version v config.ini, Version v DEBIAN/control a version v app.lang
Platforma při podání validuje konzistenci verzí
Maximální délka čísla verze: 20 znaků. Překročení povede k zamítnutí.
Povolené znaky v číslech verzí: pouze číslice (0-9) a tečky (.). Příklad: "1.2.3"
Verze před vydáním / beta verze musí používat pole "beta": true v config.ini, nikoli přípony čísla verze.

Poznámky ke správě beta verzí:

Platforma nepodporuje přípony čísel verzí (např. -beta, -rc, -alpha)
Více beta verzí se rozlišuje zvyšováním čísla patch verze:
- První beta verze → "version": "1.0.0" + "beta": true
- Druhá beta verze → "version": "1.0.1" + "beta": true
- Třetí stabilní vydání → "version": "1.0.2" + "beta": false
Stabilní vydání: Nastavte "beta": false; číslo verze zvyšujte běžným způsobem
Vrácení verze: Platforma nepodporuje návrat k "nižšímu" číslu verze. Pokud je vrácení nutné, musí být na vývojářské platformě podána žádost o vrácení a platforma vrátí aplikaci na předchozí stabilní verzi
Podrobnosti viz Příloha N – Správa beta verzí aplikací

Specifikace pojmenování vydávaných souborů

Při nahrávání balíčků aplikací do GitHub/Gitee Releases musí soubor balíčku dodržovat níže uvedené konvence pojmenování.

Důležité

Čísla verzí nejsou zahrnuta v názvech souborů balíčků. Verze se určuje prostřednictvím tagu/verze Release při vytváření Release. Platforma přečte verzi z metadat Release a ověří ji proti poli version v config.ini.

Typ aplikace	Formát balíčku	Konvence pojmenování	Příklad
Deb (jeden balíček)	soubor `.deb`	`<app_id>_<platform>.deb`	`myapp_x86_64.deb`
Deb (duální balíček)	archiv `.tar.gz`	`<app_id>_<platform>.tar.gz`	`myapp_x86_64.tar.gz`
Aplikace Docker	archiv `.tar.gz`	`<app_id>.tar.gz`	`myapp.tar.gz`

Definice polí:

<app_id>: Musí přesně odpovídat poli id v config.ini
<platform>: Musí přesně odpovídat poli platform v config.ini (x86_64 nebo aarch64)

Požadavek na tag Release:

Tag/verze Release musí přesně odpovídat poli version v config.ini (formát: xx.yy.zzz)
Příklad: Pokud je config.ini.version = "1.0.0", tag Release musí být v1.0.0 nebo 1.0.0
Neshody mezi verzí Release a config.ini.version povedou k automatickému zamítnutí

Upgrady

Upgrady aplikací Deb:

Během upgradu obdrží preinst parametr $1 = "upgrade"
postinst obdrží parametr $1 = "configure", přičemž $2 je číslo staré verze
K detekci staré verze a provedení migrace dat použijte $2
Během procesu upgradu nikdy nemažte uživatelská data; pouze upravujte formáty konfigurace nebo migrujte datové struktury
Uživatelé ukládají perzistentní obchodní data do sdílené složky /Volume*/<appid>/, kterou aplikace vytvoří pomocí ter_share_add. Platforma během upgrade aplikace nebo reinstalace nesmaže ani nepřepíše uživatelská data v této sdílené složce
Běhová data (mezipaměti, dočasné soubory) se ukládají do /Volume*/@apps/<appid>/data/ a lze je bezpečně regenerovat
Nedoporučuje se ukládat data do běžných systémových adresářů, jako jsou /etc, /var, /usr/bin, protože tyto adresáře mohou být přepsány systémovými aktualizacemi nebo upgrady aplikací, což vede ke ztrátě dat

# Example: postinst with migration logic
case "$1" in
    configure)
        if [ -n "$2" ]; then
            # Upgrading from version $2
            if dpkg --compare-versions "$2" lt "2.0.0"; then
                # Migrate v1.x configuration format to v2.x
                /usr/local/<appid>/bin/migrate.sh "$2"
            fi
        else
            # Fresh install
            echo "Fresh install"
        fi
        ;;
esac

Upgrady aplikací Docker:

Stáhněte nové tagy obrazů
Přestavte kontejnery pomocí stávajících připojení svazků
Zachovejte data napříč upgrady prostřednictvím perzistentních svazků
V případě potřeby zahrňte migrační logiku do vstupního skriptu aplikace

Matice kompatibility

Verze TOS	Základní systém	glibc	Python3	Docker	Node.js
TOS 7.0	Kompatibilní s Ubuntu 22.04	2.35	3.10	20.10+	18.x
TOS 7.x	Kompatibilní s Ubuntu 22.04	2.35	3.10	20.10+ (nebo vyšší)	18.x (nebo vyšší)

Poznámka

Verze Node.js jsou určeny pouze pro referenci uvnitř kontejnerů Docker. Aplikace Deb na ně nesmějí přímo spoléhat.

Důležité

Aplikace musí deklarovat požadavek na minimální verzi TOS prostřednictvím pole low_version v config.ini. Platforma automaticky odfiltruje nekompatibilní zařízení.

Kompatibilita dílčích verzí TOS 7.x: Řada dílčích verzí TOS 7.x (včetně 7.1 a vyšších) zachová kompatibilitu ABI/API pro základní závislosti (glibc/Python3/Docker/Node.js) a zůstane kompatibilní s kořenovým souborovým systémem založeným na Ubuntu 22.04. Aplikace vyvinuté pro TOS 7.0 poběží bez dalšího přizpůsobení.

Kompatibilita dílčích verzí TOS 7:

Pole low_version musí určovat minimální požadovanou verzi TOS
Při podávání aktualizací testujte na nejnovější dílčí verzi TOS 7

Specifikace rozlišování velkých a malých písmen

TOS používá kořenový souborový systém kompatibilní s Ubuntu Linux a souborový systém přísně rozlišuje velká a malá písmena. Všechny aplikace musí dodržovat níže uvedená pravidla:

Prvek	Pravidlo
Názvy souborů	Přísná shoda velkých a malých písmen. `config.ini` ≠ `Config.ini` ≠ `CONFIG.INI`
Názvy adresářů	Přísná shoda velkých a malých písmen. `/images/icons/` ≠ `/Images/Icons/`
Názvy klíčů v config.ini	Všechny názvy klíčů musí být malými písmeny. `"version"` je správně, `"Version"` je nesprávně
ID aplikace (`id`)	Přísná shoda velkých a malých písmen. `MyApp` ≠ `myapp`. Po vytvoření je nelze změnit
Název služby systemd	Musí přesně odpovídat, rozlišují se velká a malá písmena

Zakázáno

Používání variant velkých a malých písmen stejného souboru nebo adresáře v rámci jednoho balíčku aplikace. To způsobuje na Linuxu chyby "soubor nenalezen" a "selhání spuštění služby".

Specifikace konců řádků pro více platforem (CRLF na LF)

Všechny skripty a konfigurační soubory běžící v systému TOS (prostředí Linux) musí používat jako konec řádku LF (\n). Používání výchozích konců řádků CRLF (\r\n) z Windows je zakázáno.

Dopad

Chyby provádění skriptů: bad interpreter: No such file or directory
Selhání analýzy konfiguračních souborů (např. souborů služeb systemd, konfigurací Nginx)
Cesty interpretu nesprávně rozpoznané jako neexistující binárky, jako je /bin/bash\r

Povinné požadavky

Všechny soubory .sh / .py / .ini / .lang / .service / .conf musí být před podáním převedeny na konce řádků LF
Skripty sestavení balíčků Deb musí zahrnovat logiku automatického převodu, aby se zabránilo zavedení CRLF během procesu sestavení

Doporučené opravy

Možnost 1: Automatický převod ve skriptu sestavení (doporučeno)

import os

def convert_crlf_to_lf(file_path):
    with open(file_path, "rb") as f:
        content = f.read()
    content = content.replace(b"\r\n", b"\n")
    with open(file_path, "wb") as f:
        f.write(content)

# Before packaging, iterate over all files that need conversion
for root, _, files in os.walk("your_app_source/"):
    for name in files:
        if name.endswith((".sh", ".py", ".ini", ".lang", ".service", ".conf")):
            convert_crlf_to_lf(os.path.join(root, name))

Možnost 2: Konfigurace lokálního vývojového nástroje

VS Code: Klikněte na CRLF ve stavovém řádku vpravo dole, přepněte na LF a poté uložte
Globální konfigurace Git (zabrání automatickému převodu následných souborů na CRLF):

git config --global core.autocrlf input

Životní cyklus aplikace​

Specifikace čísla verze​

Specifikace pojmenování vydávaných souborů​

Upgrady​

Matice kompatibility​

Specifikace rozlišování velkých a malých písmen​

Specifikace konců řádků pro více platforem (CRLF na LF)​

Dopad​

Povinné požadavky​

Doporučené opravy​

Možnost 1: Automatický převod ve skriptu sestavení (doporučeno)​

Možnost 2: Konfigurace lokálního vývojového nástroje​