From 2d135ed06b2661584454b6dcb30280278b7626e1 Mon Sep 17 00:00:00 2001 From: fkDeath Date: Tue, 26 May 2026 14:38:23 +0200 Subject: [PATCH] docs(readme): replace rst readme with markdown fws documentation --- README.md | 92 ++++++++++++++++++++++++++ README.rst | 189 ----------------------------------------------------- 2 files changed, 92 insertions(+), 189 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..341925c --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# FWS + +**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. + +--- + +## Aperçu + +- **Base** : Arch Linux (rolling release) +- **Installeur** : Calamares (compilé depuis l'AUR, servi via un repo local pacman) +- **Affichage live** : Xorg + Openbox, lancement automatique de Calamares +- **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) + +### Côté Arch (WSL ou natif) +Les scripts installent automatiquement les paquets nécessaires (`archiso`, `base-devel`, `git`, `reflector`, `dos2unix`). + +## Démarrage rapide + +```bash +# 1. Préparation : compile Calamares depuis l'AUR, crée le repo local, +# patche pacman.conf et configure les services systemd (Xorg + autostart). +./setup-calamares.sh + +# 2. Build de l'ISO via mkarchiso (fusionne configs/releng + configs/baseline) +./build.sh +``` + +L'ISO finale est générée dans `./out/`. + +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**. + +## 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) | +| `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) | +| `out/` | ISOs générées | +| `fws/mkarchiso` | Binaire `mkarchiso` embarqué (fork) | + +## 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 + +## 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`…) + +## 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. + +--- + +## Licence & origine + +FWS est un fork de **[archiso](https://gitlab.archlinux.org/archlinux/archiso)** (Arch Linux), redistribué sous les termes de la **GPL-3.0-or-later**. + +Voir [LICENSE](LICENSE) pour le texte complet, et [AUTHORS.rst](AUTHORS.rst) pour la liste des auteurs originaux d'archiso. + +Les modifications spécifiques à FWS (scripts `build.sh`, `setup-calamares.sh`, overlay `configs/baseline/`, intégration Calamares + Xorg autostart, chaîne de build WSL) sont également distribuées sous GPL-3.0-or-later. diff --git a/README.rst b/README.rst deleted file mode 100644 index 7579f37..0000000 --- a/README.rst +++ /dev/null @@ -1,189 +0,0 @@ -======= -archiso -======= - -The archiso project features scripts and configuration templates to build installation media (*.iso* images and -*.tar bootstrap images) as well as netboot artifacts for BIOS and UEFI based systems. -Currently creating the images is only supported on Arch Linux but may work on other operating systems as well. - -Requirements -============ - -The following packages need to be installed to be able to create an image with the included scripts: - -* arch-install-scripts -* awk -* dosfstools -* e2fsprogs -* erofs-utils (optional) -* findutils -* grub -* gzip -* libarchive -* libisoburn -* mtools -* openssl -* pacman -* sed -* squashfs-tools - -For running the images in a virtualized test environment the following packages are required: - -* edk2-ovmf -* qemu - -For linting the shell scripts the following package is required: - -* shellcheck - -For generating the man pages: - -* python-docutils - -Profiles -======== - -Archiso comes with two profiles: **baseline** and **releng**. While both can serve as starting points for creating -custom live media, **releng** is used to create the monthly installation medium. -They can be found below `configs/baseline/ `_ and `configs/releng/ `_ -(respectively). Both profiles are defined by files to be placed into overlays (e.g. airootfs ‎→‎ the image's ``/``). - -Read `README.profile.rst `_ to learn more about how to create profiles. - -Create images -============= - -Usually the archiso tools are installed as a package. However, it is also possible to clone this repository and create -images without installing archiso system-wide. - -As filesystems are created and various mount actions have to be done when creating an image, **root** is required to run -the scripts. - -When archiso is installed system-wide and the modification of a profile is desired, it is necessary to copy it to a -writeable location, as ``/usr/share/archiso`` is tracked by the package manager and only writeable by root (changes will -be lost on update). - -The examples below will assume an unmodified profile in a system location (unless noted otherwise). - -It is advised to consult the help output of **mkarchiso**: - -.. code:: sh - - mkarchiso -h - -Create images with packaged archiso ------------------------------------ - -.. code:: sh - - mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile - -Create images with local clone ------------------------------- - -Clone this repository and run: - -.. code:: sh - - ./archiso/mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile - -Testing -======= - -The convenience script **run_archiso** is provided to boot into the medium using qemu. -It is advised to consult its help output: - -.. code:: sh - - run_archiso -h - -Run the following to boot the iso using BIOS: - -.. code:: sh - - run_archiso -i path/to/an/arch.iso - -Run the following to boot the iso using UEFI: - -.. code:: sh - - run_archiso -u -i path/to/an/arch.iso - -The script can of course also be executed from this repository: - - -.. code:: sh - - ./scripts/run_archiso.sh -i path/to/an/arch.iso - -Installation -============ - -To install archiso system-wide use the included ``Makefile``: - -.. code:: sh - - make install - -Optional features - -The iso image contains a GRUB environment block holding the iso name and version. This allows to -boot the iso image from GRUB with a version specific cow directory to mitigate overlay clashes. - -.. code:: sh - - loopback loop archlinux.iso - load_env -f (loop)/boot/grub/grubenv - linux (loop)/arch/boot/x86_64/vmlinuz-linux ... \ - cow_directory=${NAME}/${VERSION} ... - initrd (loop)/arch/boot/x86_64/initramfs-linux-lts.img - -Contribute -========== - -Development of archiso takes place on Arch Linux' Gitlab: https://gitlab.archlinux.org/archlinux/archiso. - -Please read our distribution-wide `Code of Conduct `_ before -contributing, to understand what actions will and will not be tolerated. - -Read our `contributing guide `_ to learn more about how to provide fixes or improvements for the code -base. - -Discussion around archiso takes place on the `arch-releng mailing list -`_ and in `#archlinux-releng -`_ on `Libera Chat `_. - -All past and present authors of archiso are listed in `AUTHORS `_. - -Releases -======== - -`Releases of archiso `_ are created by their current maintainers - -- `David Runge `_ (``991F6E3F0765CF6295888586139B09DA5BF0D338``) -- `nl6720 `_ (``BB8E6F1B81CF0BB301D74D1CBF425A01E68B38EF``) - -Tags are signed using respective PGP keys. - -To verify a tag, first import the relevant PGP key(s): - -.. code:: sh - - gpg --auto-key-locate wkd --search-keys dvzrv@archlinux.org - -or - -.. code:: sh - - gpg --auto-key-locate clear,dane --locate-external-keys devnull@nl6720.me - -Afterwards a tag can be verified from a clone of this repository: - -.. code:: sh - - git verify-tag - -License -======= - -Archiso is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE `_).