From 1fa2c72ef78f904f41dd1dd778ed6145d15bb946 Mon Sep 17 00:00:00 2001 From: fkDeath Date: Thu, 28 May 2026 22:41:32 +0200 Subject: [PATCH] refactor(INSTALLATION MD): Explain the installation precisly --- README.md | 240 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 201 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index dd3dd62..492b5b6 100644 --- a/README.md +++ b/README.md @@ -2,86 +2,248 @@ **FWS** est une distribution Linux live/installable basée sur **Arch Linux**, livrée sous forme d'ISO bootable BIOS/UEFI avec l'installeur graphique **Calamares** lancé automatiquement au démarrage. -Le projet est construit avec une chaîne `mkarchiso` adaptée pour fonctionner **depuis Windows via WSL** (Git Bash → WSL Arch), sans nécessiter de machine Linux dédiée. +Le projet est conçu pour être **construit depuis Windows via WSL** (les scripts détectent Git Bash et basculent automatiquement dans WSL), mais fonctionne aussi directement depuis une Arch Linux native. --- ## Aperçu - **Base** : Arch Linux (rolling release) -- **Installeur** : Calamares (compilé depuis l'AUR, servi via un repo local pacman) +- **Installeur** : Calamares 3.4.2 (compilé depuis l'AUR, servi via un repo pacman local) - **Affichage live** : Xorg + Openbox, lancement automatique de Calamares -- **Bureau installé** : XFCE + LightDM avec autologin du premier compte créé +- **Bureaux installables** : XFCE, KDE Plasma, GNOME, Hyprland (choix à l'installation) - **Boot** : BIOS (syslinux) + UEFI (systemd-boot) - **Compression** : squashfs (xz) -- **Build** : Windows + WSL (Arch) ou directement depuis Arch -## Prérequis +--- -### Côté Windows -- Windows 10/11 -- WSL 2 avec une distribution **Arch Linux** installée (`Arch`, `ArchLinux`, `ArchWSL`…) -- Git Bash (pour exécuter les scripts depuis Windows) +## Environnement requis — INSTALLATION ULTRA PRÉCISE -### Côté Arch (WSL ou natif) -Les scripts installent automatiquement les paquets nécessaires (`archiso`, `base-devel`, `git`, `reflector`, `dos2unix`). +### Côté Windows (machine hôte) + +| Composant | Version / état requis | Commande de vérif | +|---|---|---| +| Windows | 10 (22H2+) ou 11 | `winver` | +| WSL | **WSL 2** (pas WSL 1) | `wsl --status` | +| Virtualisation CPU | Activée dans le BIOS (VT-x / AMD-V) | Gestionnaire des tâches → Performance → CPU → "Virtualisation : Activé" | +| Git for Windows | ≥ 2.40 (fournit Git Bash) | `git --version` | +| Espace disque libre | ≥ 25 GB sur la partition WSL | — | +| RAM | ≥ 8 GB (16 GB recommandés) | — | + +#### 1. Activer WSL 2 + +Dans **PowerShell administrateur** : + +```powershell +wsl --install --no-distribution +wsl --set-default-version 2 +wsl --update +``` + +Puis **redémarrer Windows**. + +#### 2. Installer Arch Linux dans WSL + +Arch n'est pas dans le store Microsoft. Installer **ArchWSL** : + +```powershell +# Télécharger la dernière release +Invoke-WebRequest -Uri "https://github.com/yuk7/ArchWSL/releases/latest/download/Arch.zip" -OutFile "$env:TEMP\Arch.zip" +Expand-Archive "$env:TEMP\Arch.zip" -DestinationPath "$env:LOCALAPPDATA\ArchWSL" +& "$env:LOCALAPPDATA\ArchWSL\Arch.exe" +``` + +Au premier lancement, la distribution s'enregistre sous le nom **`Arch`** (ce nom est attendu par les scripts — il est paramétrable via `ARCH_WSL_DISTRO` si besoin). + +Vérifier : + +```powershell +wsl -l -v +# Doit afficher : +# NAME STATE VERSION +# * Arch Stopped 2 +``` + +#### 3. Installer Git for Windows + +Télécharger depuis https://git-scm.com/download/win et installer avec les options par défaut. **Git Bash** est inclus. + +--- + +### Côté WSL Arch (préparation système) + +Le **premier lancement** de la WSL ouvre une session root. Effectuer une seule fois : + +```bash +# 1. Initialiser le keyring (sinon pacman refuse tout install signé) +pacman-key --init +pacman-key --populate archlinux + +# 2. Mettre à jour le keyring AVANT toute autre opération +# (les WSL fraîches ont un keyring périmé) +pacman -Sy --noconfirm archlinux-keyring + +# 3. Mise à jour complète du système +pacman -Syu --noconfirm + +# 4. Vérifier que /tmp est bien un tmpfs (sinon mkarchiso lent) +mount | grep '/tmp' +``` + +> **Note** : le script `setup-calamares.sh` désactive automatiquement le sandbox landlock de pacman ≥ 7 (incompatible avec le kernel WSL) en ajoutant `DisableSandbox` dans `/etc/pacman.conf`. Tu n'as rien à faire. + +--- + +### Côté Arch Linux native (alternative) + +Si tu build depuis une vraie Arch (pas WSL) : + +```bash +sudo pacman -Syu +sudo pacman -S --needed base-devel git archiso reflector dos2unix +``` + +Les scripts détectent l'absence de WSL et s'exécutent en local. Il faut être **root** ou avoir `sudo` configuré. + +--- ## Démarrage rapide +Depuis **Git Bash sur Windows** (à la racine du repo) : + ```bash -# 1. Préparation : compile Calamares depuis l'AUR, crée le repo local, -# patche pacman.conf et configure les services systemd (Xorg + autostart). +# Étape 1 : compilation de Calamares + winboat depuis l'AUR +# → crée local-repo/ avec les .pkg.tar.zst signés ./setup-calamares.sh -# 2. Build de l'ISO via mkarchiso (fusionne configs/releng + configs/baseline) +# Étape 2 : build de l'ISO via mkarchiso +# → fusionne configs/releng + configs/baseline +# → injecte le repo local dans pacman.conf +# → sort l'ISO dans ./out/ ./build.sh ``` -L'ISO finale est générée dans `./out/`. +L'ISO finale est générée dans `./out/FWS-YYYY.MM.DD-x86_64.iso`. -Les deux scripts détectent automatiquement s'ils sont lancés depuis **Git Bash** (et basculent dans WSL en root) ou directement depuis **WSL/Arch**. +--- + +## Ce que fait `setup-calamares.sh` (étape par étape) + +1. **Détection environnement** : si lancé depuis Git Bash, bascule dans `wsl.exe -d Arch -u root`. +2. **Patch pacman** : désactive landlock sur WSL (`DisableSandbox`). +3. **Refresh keyring** : `pacman-key --init && --populate archlinux`, mise à jour `archlinux-keyring`. +4. **`pacman -Syu`** complet (obligatoire — sinon `makepkg` plante sur les "conflicting files" lors des splits de paquets type `gcc-libs`). +5. **Install des outils de build** : `base-devel git`. +6. **Création d'un utilisateur `fwsbuild`** non-root avec `sudo` NOPASSWD (makepkg refuse de tourner en root). +7. **Clone + build AUR** : `calamares` puis `winboat-bin` via `makepkg -s --noconfirm`. +8. **Création du repo local** : `repo-add local-repo/fws-local.db.tar.gz`. +9. **Cleanup** : suppression de l'utilisateur `fwsbuild`. + +**Durée** : 15–40 minutes (Calamares = ~12 dépendances Qt6 à compiler). + +--- + +## Ce que fait `build.sh` (étape par étape) + +1. **Détection environnement** : Git Bash → bascule dans WSL ; sinon exécution locale. +2. **Update miroirs** : `reflector --latest 10 --sort rate`. +3. **Install `archiso`**. +4. **Fusion configs** : `cp -ar configs/releng/* /tmp/fws-build/releng/` puis overlay `configs/baseline/*` par-dessus (baseline prioritaire). +5. **Activation NetworkManager** sur le live (symlink réel `multi-user.target.wants/`). +6. **Injection du repo local** : ajoute `[fws-local]` (`SigLevel = Optional TrustAll`) en tête de `pacman.conf`. +7. **`dos2unix`** sur l'arborescence (au cas où tu as édité depuis Windows). +8. **`mkarchiso -v -w /tmp/fws-build/work -o out/ /tmp/fws-build/releng`**. +9. **Cleanup** du workdir. + +**Durée** : 5–15 minutes selon la machine et le cache pacman. + +--- + +## Test rapide en QEMU + +```bash +./scripts/run_archiso.sh -i out/FWS-*.iso # BIOS +./scripts/run_archiso.sh -u -i out/FWS-*.iso # UEFI +``` + +--- ## Structure du projet | Chemin | Rôle | -|--------|------| -| `setup-calamares.sh` | Préparation one-shot : build Calamares (AUR), repo local, services systemd, autostart Xorg + Calamares | -| `build.sh` | Build de l'ISO via `mkarchiso` (utilisable depuis Git Bash ou WSL) | +|---|---| +| `setup-calamares.sh` | Build Calamares + winboat depuis l'AUR, crée `local-repo/` | +| `build.sh` | Build de l'ISO via `mkarchiso` | | `configs/releng/` | Profil principal (base ArchISO releng) | -| `configs/baseline/` | Overlay FWS appliqué par-dessus `releng` (prioritaire) | -| `local-repo/` | Repo pacman local généré (Calamares + dépendances AUR) | +| `configs/baseline/` | Overlay FWS (Calamares, branding, scripts desktop-init) — **prioritaire** sur releng | +| `local-repo/` | Repo pacman local (généré par `setup-calamares.sh`) | | `out/` | ISOs générées | | `fws/mkarchiso` | Binaire `mkarchiso` embarqué (fork) | +| `scripts/run_archiso.sh` | Lanceur QEMU | + +--- ## Séquence de boot de l'ISO 1. Démarrage de l'ISO FWS (BIOS ou UEFI) 2. `systemd` → autologin root sur `tty1` -3. `xorg-start.service` → `Xorg :0` -4. `calamares.service` → `DISPLAY=:0 calamares` -5. **Fallback** : si les services échouent, `.zprofile` relance Xorg + Openbox + Calamares manuellement -6. Après installation, le système démarre sur LightDM puis ouvre automatiquement la session XFCE du compte installé +3. `.zprofile` → `startx` +4. `.xinitrc` → Openbox + Calamares +5. Utilisateur choisit son bureau (XFCE / KDE / GNOME / Hyprland) via `packagechooser` +6. Calamares installe le système → `shellprocess` appelle `/usr/local/bin/fws-desktop-init-` qui installe les paquets et configure le display manager +7. Reboot → connexion automatique sur le bureau choisi -## Test rapide en QEMU - -```bash -./scripts/run_archiso.sh -i out/fws-*.iso # BIOS -./scripts/run_archiso.sh -u -i out/fws-*.iso # UEFI -``` +--- ## Personnalisation -- **Paquets** : éditer `configs/releng/packages.x86_64` -- **Overlay rootfs** : déposer les fichiers dans `configs/releng/airootfs/` ou `configs/baseline/airootfs/` -- **Modules / séquence Calamares** : `configs/baseline/airootfs/etc/calamares/` -- **Branding ISO** : `configs/releng/profiledef.sh` (`iso_name`, `iso_label`, `iso_publisher`…) +- **Paquets du live** : `configs/releng/packages.x86_64` +- **Paquets baseline** : `configs/baseline/packages.x86_64` +- **Overlay rootfs** : `configs/releng/airootfs/` ou `configs/baseline/airootfs/` +- **Modules / séquence Calamares** : `configs/baseline/airootfs/etc/calamares/settings.conf` +- **Choix des bureaux** : `configs/baseline/airootfs/etc/calamares/modules/packagechooser.conf` +- **Scripts d'install bureau** : `configs/releng/airootfs/usr/local/bin/fws-desktop-init-*` +- **Branding ISO** : `configs/releng/profiledef.sh` (`iso_name`, `iso_label`, `iso_publisher`) +- **Branding Calamares** : `configs/baseline/airootfs/etc/calamares/branding/fws/` + +--- ## Dépannage -- **`pacman.conf introuvable`** : vérifier que `configs/releng/pacman.conf` existe. -- **Calamares ne démarre pas dans l'ISO** : se logger en tty (autologin root) et lancer `journalctl -u xorg-start -u calamares`. -- **Erreurs de retours à la ligne** : `build.sh` lance `dos2unix` sur l'arborescence ; si vous éditez des fichiers depuis Windows, ce n'est pas un problème. -- **`mkarchiso` échoue sur un paquet AUR** : relancer `./setup-calamares.sh` pour reconstruire le repo local. +| Symptôme | Cause / fix | +|---|---| +| `setup-calamares.sh` : `wsl.exe -d Arch` introuvable | La distro WSL ne s'appelle pas `Arch`. Exporter `ARCH_WSL_DISTRO=NomDeMaDistro` ou renommer. | +| `pacman: signature unknown trust` | Keyring périmé → `pacman -Sy --noconfirm archlinux-keyring` puis relancer. | +| `makepkg: conflicting files` | `pacman -Syu` incomplet avant le build. Relancer `setup-calamares.sh`. | +| `mkarchiso` plante sur `[fws-local]` | Le repo local n'a pas été généré. Relancer `setup-calamares.sh`. | +| Calamares ne démarre pas dans l'ISO | Sur la VM, basculer en `tty2` (autologin root) et lancer `journalctl -b`. | +| `Calamares Initialization Failed: desktop@desktop` | Module mal configuré dans `settings.conf` — vérifier que la séquence utilise `packagechooser`, pas `desktop`. | +| `Variables manquantes : DESKTOP` | Les `$DESKTOP` dans `shellprocess.conf` sont interprétés par Calamares — utiliser une command substitution `$(cat /run/fws-desktop)` à la place. | +| Écran noir après login Hyprland | Tu testes dans VirtualBox → pas d'accélération GPU. Utiliser QEMU/KVM avec `virtio-gpu` ou bare-metal. | +| Retours à la ligne CRLF | `build.sh` lance `dos2unix` automatiquement, mais si tu modifies pendant le build, relancer. | + +### Logs utiles + +```bash +# Pendant le build +tail -f /tmp/fws-build/work/iso/arch/pkglist.x86_64.txt + +# Dans l'ISO (autologin tty1) +journalctl -b +cat /var/log/Calamares.log + +# Hyprland post-install +cat ~/.local/share/hyprland/hyprland.log +``` + +--- + +## Variables d'environnement supportées + +| Variable | Effet | Défaut | +|---|---|---| +| `ARCH_WSL_DISTRO` | Nom de la distro WSL Arch | `Arch` | +| `MSYS_NO_PATHCONV` | Désactive la conversion auto des chemins Git Bash | `1` (forcé dans les scripts) | ---