Pena/docs/3-installation/3.4-Release-et-distribution.md

# Release et distribution

Cette page explique **comment fonctionne une release de Pena** : ce que produit réellement la
compilation, **si un binaire compilé sur une distribution Linux est utilisable sur n'importe
quelle autre**, et les différentes façons de **distribuer** l'application — avec un focus sur le
**paquet Flatpak** et ses avantages/inconvénients.

- Pour les commandes de compilation pures, voir [Build et compilation](3.3-Build.md).
- Pour la procédure pas-à-pas d'installation Flatpak sur système immuable, voir
  [Installation sur Bazzite OS](3.2-Installation-Bazzite.md).

---

## 1. Que produit une release ?

`cargo tauri build` (depuis `Pena-tauri/`) produit un **exécutable natif** :

```
src-tauri/target/release/pena-taury
```

C'est un binaire ELF compilé pour l'architecture de la machine de build (typiquement
`x86_64-linux-gnu`). Le frontend (HTML/CSS/JS de `src/`) y est **embarqué** dans le binaire :
il n'y a pas de fichiers web à distribuer à côté.

> Dans `tauri.conf.json`, `bundle.active` vaut `false` : `cargo tauri build` ne génère donc
> **pas** de `.deb`/`.rpm`/`.AppImage` automatiquement. Il produit l'exécutable seul. La
> génération de paquets est traitée plus bas (section 4).

### Ce que le binaire contient — et ce qu'il ne contient pas

| Embarqué dans le binaire | **Pas** embarqué (fourni par le système) |
|---|---|
| Code Rust de Pena (commandes Tauri) | **glibc** (bibliothèque C) |
| Frontend (HTML/CSS/JS) | **WebKitGTK** (le moteur de rendu de la fenêtre) |
| `comrak` + `syntect` (rendu Markdown) | **GTK 3/4**, GLib, Cairo, Pango… |
| Plugins Tauri liés statiquement | Pilotes graphiques, serveur d'affichage (X11/Wayland) |

C'est ce tableau qui répond à la question de la portabilité.

---

## 2. Un binaire compilé sur Linux marche-t-il sur **n'importe quelle** distribution ?

**Réponse courte : non, pas de façon fiable.** Un binaire « brut » (le `pena-taury` produit
ci-dessus) n'est **pas universel**. Il dépend de bibliothèques présentes sur le système cible,
et il ne tournera ailleurs que si ces bibliothèques sont **présentes et compatibles**.

Trois raisons concrètes :

### 2.1 — Le lien dynamique avec WebKitGTK

C'est la contrainte la plus dure pour une app Tauri. Le binaire est lié à
**`libwebkit2gtk-4.1`**. Sur la machine cible, il faut :

- que WebKitGTK soit **installé** ;
- que ce soit la **bonne version d'ABI** : `webkit2gtk-4.0` et `webkit2gtk-4.1` ont des
  *sonames* différents et **ne sont pas interchangeables**. Un binaire lié à `4.1` ne démarrera
  pas sur une machine qui n'a que `4.0`, et inversement.

Sur une distribution récente, WebKitGTK 4.1 est généralement disponible ; sur une
distribution plus ancienne ou minimaliste, il peut manquer.

### 2.2 — La version de la glibc

Les binaires liés à la glibc sont **compatibles vers l'avant, pas vers l'arrière** :

- un binaire compilé sur une **vieille** glibc tourne sur une machine ayant une glibc **plus
  récente** ✅ ;
- un binaire compilé sur une glibc **récente** échoue sur une machine ayant une glibc **plus
  ancienne** ❌, avec une erreur du type `version 'GLIBC_2.38' not found`.

**Conséquence pratique :** pour maximiser la portabilité d'un binaire brut, compilez-le sur la
distribution la **plus ancienne** que vous comptez supporter (par ex. dans un container
Ubuntu 22.04), pas sur la plus récente.

### 2.3 — Les autres bibliothèques système

GTK, GLib, Cairo, Pango, librsvg, libappindicator… doivent aussi être présentes. Sur un poste
de bureau classique elles le sont presque toujours (ce sont des dépendances de l'environnement
de bureau), mais sur un serveur, un système minimal ou immuable, ce n'est pas garanti.

### Récapitulatif portabilité

| Cible | Le binaire brut marche-t-il ? |
|---|---|
| Même distribution / version que la machine de build | ✅ Oui |
| Distribution différente mais récente, avec `webkit2gtk-4.1` et glibc ≥ celle du build | ✅ Généralement |
| Distribution avec une glibc **plus ancienne** que le build | ❌ Non (`GLIBC_x.y not found`) |
| Distribution qui n'a que `webkit2gtk-4.0` | ❌ Non (soname incompatible) |
| Système immuable (Bazzite, Silverblue…) | ❌ Pas directement — voir Flatpak |
| Architecture différente (ARM vs x86_64) | ❌ Non — il faut recompiler pour l'archi |

**Conclusion :** « compilé sur Linux » ne veut pas dire « marche sur tout Linux ». Pour une
distribution **réellement universelle**, il faut un format qui **embarque ses dépendances** :
c'est le rôle du **Flatpak** (recommandé ici) ou de l'**AppImage**.

---

## 3. Les formats de distribution possibles

| Format | Dépendances | Portabilité | Intégration bureau | Mise à jour |
|---|---|---|---|---|
| **Binaire brut** | Fournies par l'hôte | Faible (voir §2) | Manuelle (`.desktop`) | Manuelle |
| **`.deb` / `.rpm`** | Déclarées, résolues par le gestionnaire de paquets | Bonne **sur la famille visée** (Debian *ou* Fedora) | Automatique | Via le gestionnaire |
| **AppImage** | **Embarquées** dans un fichier exécutable | Bonne (un seul fichier portable) | Partielle | Manuelle (re-télécharger) |
| **Flatpak** | **Embarquées** via un *runtime* partagé (Flathub) | **Excellente** (toute distro avec `flatpak`) | Complète (menu, icône) | `flatpak update` |

Pour Pena, le format **recommandé est le Flatpak** : il résout d'un coup les trois problèmes du
§2 (WebKitGTK, glibc, libs système) en fournissant un **runtime** complet et identique partout.

---

## 4. Créer un paquet Flatpak

Le Flatpak rend l'application **vraiment portable** : le moteur WebKitGTK et toutes les
bibliothèques système viennent du **runtime `org.gnome.Platform`** (téléchargé depuis Flathub),
pas de l'hôte. Le même `pena.flatpak` s'installe alors sur n'importe quelle distribution dotée
de `flatpak`, immuable ou non.

> La procédure complète (installation côté machine cible, hébergement sur Gitea, alternative
> développeur) est détaillée dans [Installation sur Bazzite OS](3.2-Installation-Bazzite.md).
> On résume ici les étapes de **production** du paquet.

### 4.1 — Principe en trois temps

```
[ cargo tauri build ]        →  binaire natif  pena-taury
        │
        ▼
[ manifeste Flatpak ]        →  build dans un dépôt OSTree local "repo/"
        │
        ▼
[ flatpak build-bundle ]     →  fichier unique  pena.flatpak
```

### 4.2 — Outillage (une fois)

```bash
flatpak install -y flathub org.gnome.Platform//47 org.gnome.Sdk//47 org.flatpak.Builder
```

### 4.3 — Le manifeste

Le manifeste décrit l'identifiant de l'app, le runtime qui fournit les dépendances, et comment
installer le binaire dans le sandbox. Depuis `Pena-tauri/`, créer **`com.pena.app.yml`** :

```yaml
id: com.pena.app                 # = identifier de tauri.conf.json
runtime: org.gnome.Platform      # fournit WebKitGTK + GTK + glibc du runtime
runtime-version: '47'
sdk: org.gnome.Sdk
command: pena

finish-args:
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
  - --device=dri
  - --filesystem=home:ro         # lecture des fichiers Markdown de l'utilisateur

modules:
  - name: pena
    buildsystem: simple
    build-commands:
      - install -Dm755 pena-taury /app/bin/pena
      - install -Dm644 com.pena.app.desktop /app/share/applications/com.pena.app.desktop
      - install -Dm644 icon.png /app/share/icons/hicolor/512x512/apps/com.pena.app.png
    sources:
      - type: file
        path: src-tauri/target/release/pena-taury
      - type: file
        path: com.pena.app.desktop
      - type: file
        path: src-tauri/icons/icon.png
```

Et le fichier d'intégration au menu **`com.pena.app.desktop`** :

```ini
[Desktop Entry]
Type=Application
Name=Pena
Comment=Lecteur Markdown
Exec=pena
Icon=com.pena.app
Terminal=false
Categories=Utility;Office;
```

> Point clé sur la portabilité : `finish-args` définit le **sandbox**. Pena n'a besoin que de
> l'affichage (Wayland/X11), du GPU (`dri`) et d'un **accès en lecture seule** au `home`
> (`--filesystem=home:ro`) pour ouvrir les fichiers `.md`. C'est volontairement minimal.

### 4.4 — Construire le bundle

Depuis `Pena-tauri/`, après un `cargo tauri build` réussi :

```bash
# 1. Construire dans un dépôt OSTree local "repo/"
flatpak run org.flatpak.Builder --force-clean --repo=repo \
  --install-deps-from=flathub build-dir com.pena.app.yml

# 2. Exporter en UN SEUL fichier .flatpak autoportant
flatpak build-bundle repo pena.flatpak com.pena.app \
  --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo
```

On obtient **`pena.flatpak`** : un fichier unique, installable partout par
`flatpak install --user pena.flatpak`. L'option `--runtime-repo` y inscrit la référence
Flathub, pour que le runtime soit récupéré automatiquement à l'installation s'il manque.

---

## 5. Flatpak : avantages et inconvénients

### Avantages

- **Portabilité réelle.** Le runtime fournit WebKitGTK, GTK et une glibc cohérente : les trois
  blocages du §2 disparaissent. Le même fichier marche sur Fedora, Ubuntu, Arch, Bazzite,
  Silverblue… sans recompiler.
- **Aucune dépendance à installer sur l'hôte.** Idéal pour les systèmes **immuables** (Bazzite,
  Silverblue) où l'on ne peut pas faire `dnf install webkit2gtk-devel`.
- **Installation sans root** (`--user`).
- **Sandbox.** L'app n'a accès qu'à ce que `finish-args` autorise (ici : affichage + `home` en
  lecture seule). Surface d'attaque réduite.
- **Intégration de bureau** automatique (entrée de menu, icône) et **mises à jour** par
  `flatpak update`.
- **Reproductible.** Le runtime versionné (`//47`) garantit le même socle partout.

### Inconvénients

- **Taille.** Le **runtime** `org.gnome.Platform` pèse plusieurs centaines de Mo. Il n'est
  téléchargé qu'une fois et partagé entre toutes les apps Flatpak, mais c'est lourd pour une app
  aussi simple que Pena si c'est le seul Flatpak de la machine.
- **Premier lancement / première install** plus longs (téléchargement du runtime).
- **Le sandbox demande de la réflexion.** Tout accès fichier hors `home:ro` doit être déclaré
  explicitement ; un oubli se traduit par une fonctionnalité qui « ne voit pas » les fichiers.
- **Dépendance à Flathub** pour récupérer le runtime (réseau requis à l'installation).
- **Outillage de build** supplémentaire (`flatpak-builder`, SDK) par rapport à un simple
  `cargo tauri build`.

### Quand préférer une autre option

| Situation | Format conseillé |
|---|---|
| Diffusion large, multi-distributions, systèmes immuables | **Flatpak** |
| Un seul fichier à exécuter sans rien installer | **AppImage** (`bundle.active: true`, cible `appimage`) |
| Cible une seule famille (que Debian, ou que Fedora) avec gestion par paquets | **`.deb`** / **`.rpm`** |
| Usage perso sur sa propre machine, ou itération de dev | **Binaire brut** / `cargo tauri dev` |

> **AppImage** est l'autre format « un seul fichier ». Tauri sait en produire (activer le
> bundler dans `tauri.conf.json`), mais le **Flatpak** est privilégié ici pour son intégration
> au menu, ses mises à jour propres et la gestion automatique des dépendances via Flathub.

---

## 6. Liste de contrôle d'une release

1. Vérifier la version dans `src-tauri/tauri.conf.json` (`"version"`).
2. Compiler dans un environnement à **glibc ancienne** si l'on distribue un binaire brut
   (container Ubuntu 22.04), sinon directement.
3. `cargo tauri build` → vérifier `src-tauri/target/release/pena-taury`.
4. Construire le `pena.flatpak` (section 4).
5. Tester l'install sur une machine **vierge** : `flatpak install --user pena.flatpak` puis
   `flatpak run com.pena.app`.
6. Héberger le `.flatpak` sur **une release Gitea** (URL stable, n'alourdit pas le dépôt) —
   voir [3.2 §3.4](3.2-Installation-Bazzite.md).

---

## Voir aussi

- [Build et compilation](3.3-Build.md)
- [Installation sur Bazzite OS](3.2-Installation-Bazzite.md) — installation et hébergement du Flatpak
- [Installation (Linux générique / Fedora)](3.1-Installation.md)
- [Architecture](../2-technique/2.1-Architecture.md)