---
sessionId: session-260606-124157-1wqx
---

# Requirements

### Overview & Goals
Migrer le projet `zipdirfs` d’`Autotools` (`configure.ac` + `Makefile.am`) vers `CMake` comme système de build principal, avec suppression du flux Autotools une fois la migration validée.

### Scope
#### In Scope
- Build CMake complet pour :
  - la librairie interne (équivalent `libzipdirfs.la`)
  - le binaire `zipdirfs` (seule cible incluse par défaut dans `all`)
  - les binaires de test (`gtest`, `gtest_helper`) construits uniquement via la cible native de test
- Reprise des dépendances actuelles : `Boost` (`filesystem`, `system`), `FUSE`, `fusekit`, `libzip`, pthread.
- Migration de la couverture vers une approche CMake standard (instrumentation dédiée + exécution `ctest` + rapport agrégé), sans dépendre des scripts historiques `bin/build-*.sh`.
- Installation des assets desktop/icons (`assets/zipdirfs.desktop`, `assets/zipdirfs.xpm`, `assets/zipdirfs.png`, `assets/zipdirfs.svg`).
- Adaptation packaging Debian pour un pipeline `dh` basé CMake.
- Adaptation de la CI (`.megami.gitlab-ci.yml` + scripts `bin/build/*.sh`) pour exécuter configure/build/test/package via CMake.
- Retrait du rôle central d’Autotools après validation.

#### Out of Scope
- Refonte fonctionnelle du code C++.
- Changement des dépendances applicatives.
- Réécriture de la suite de tests (hors ajustements de build).

### Functional Requirements
- Un build standard doit fonctionner via `cmake -S . -B out/build && cmake --build out/build`.
- Le build par défaut (`cmake --build out/build`) ne doit construire que l’exécutable principal et ses dépendances directes.
- Les binaires de test (`gtest`, `gtest_helper`) ne doivent pas être construits par défaut ; ils doivent être compilés automatiquement quand la cible native de test est invoquée (`ctest`/`test` via CMake).
- Le build doit échouer explicitement si une dépendance requise est absente.
- La version minimale CMake ciblée est `3.18+` (alignée Debian Bullseye).
- La CI de test doit lancer la chaîne CMake native (configure + build + `ctest`) au lieu de `autoreconf`/`./configure`/`make`.
- La CI de packaging doit produire les mêmes artefacts Debian, en s’appuyant sur la chaîne CMake (directement ou via `dpkg-buildpackage` + `debian/rules` migré).

### Non-Functional Requirements
- Préserver l’organisation actuelle des sources (`src/`, `include/`, `test/`, `assets/`).
- Rester lisible et maintenable avec structure modulaire (`CMakeLists.txt` racine + sous-modules).

# Technical Design

### Current Implementation
Le build actuel est centralisé dans :
- `configure.ac` :
  - détection outils (`AC_PROG_CXX`, `LT_INIT`)
  - dépendances (`AX_BOOST_*`, `PKG_CHECK_MODULES` pour `fuse`, `fusekit`, `libzip`)
  - activation conditionnelle tests (`--with-tests`, `AM_CONDITIONAL([USE_TESTS], ...)`)
- `Makefile.am` :
  - cibles principales : `zipdirfs`, `libzipdirfs.la`
  - très grande liste de sources/headers
  - bloc `if USE_TESTS` pour gtest/gmock + binaires `gtest` et `gtest_helper`
  - cibles coverage (`gtest-coverage*`) via scripts `bin/build-coverage.sh`, `bin/build-case-coverage.sh`, `bin/build-detailed-coverage.sh`
  - installation assets (`dist_application_DATA`, `dist_*icons_DATA`)
- Packaging Debian présent (`debian/control`, `debian/rules`) encore orienté flux standard non-CMake.
- CI attachée dans `.megami.gitlab-ci.yml` :
  - job `run_tests` exécute `bin/build/test-task.sh` (actuellement `autoreconf`, `./configure --with-tests`, `make`, `make gtest`, exécution `./gtest`)
  - job `generate_builds` exécute `bin/build/generate-tasks.sh` puis déclenche `run_build`.
  - caches CI encore orientés artefacts Autotools (`**/m4`, `**/*.lo`, `**/.deps`, `**/.libs`, `stamp-h1`).

### Key Decisions
- **CMake devient unique système de build** après validation, conformément à ton choix de bascule directe.
- **Architecture CMake modulaire et découpée par dossier** :
  - `CMakeLists.txt` racine
  - `src/CMakeLists.txt`, puis sous-`CMakeLists.txt` par sous-dossier de `src/ZipDirFs`
  - `test/CMakeLists.txt` (tests + enregistrement CTest)
  - `cmake/CodeCoverage.cmake` (instrumentation et génération de rapport coverage)
  - `assets/CMakeLists.txt` (installation resources)
- **Compilation par objets de dossier** : chaque sous-dossier de `src/ZipDirFs` produit une cible `OBJECT` dédiée, agrégée ensuite dans la librairie cœur.
- **Dépendances strictes** via `find_package` et `PkgConfig`/`pkg_check_modules`, avec erreur explicite si manquantes.
- **Version minimale CMake = 3.18** (disponible sur Debian Bullseye).

### Proposed Changes
- Ne pas introduire d’option `ZIPDIRFS_BUILD_TESTS` : utiliser le comportement natif CMake (`enable_testing`, `add_test`) et configurer les cibles de tests hors build par défaut (`EXCLUDE_FROM_ALL`/équivalent).
- Découper `src/` en sous-`CMakeLists.txt` par dossier et créer une cible `OBJECT` par dossier (par ex. `zipdirfs_components_obj`, `zipdirfs_containers_obj`, `zipdirfs_fuse_obj`, `zipdirfs_utilities_obj`, `zipdirfs_zip_obj`, `zipdirfs_zip_base_obj`, plus objets pour `src/Options.cpp` et `src/StateReporter.cpp`).
- Agréger ces objets dans une librairie interne (`zipdirfs_core`) consommée par `zipdirfs` et par les binaires de test.
- Gérer une variante d’objet uniquement pour les unités impactées par `BUILD_TEST` :
  - analyse du code : `include/ZipDirFs/Containers/EntryGenerator.h` expose des accès de test conditionnels (`friend HolderStateInitializer`) sous `#ifdef BUILD_TEST`.
  - impact build : compiler `src/ZipDirFs/Containers/EntryGenerator.cpp` en variante alternative avec `BUILD_TEST` pour les tests (`zipdirfs_containers_obj_test`), tout en conservant la variante standard pour l’application.
  - ne pas dupliquer les autres dossiers tant qu’aucun autre `#ifdef BUILD_TEST` n’est présent dans les headers/sources de production.
- Remplacer la logique coverage scriptée par une intégration CMake idiomatique :
  - module `cmake/CodeCoverage.cmake` pour centraliser les flags d’instrumentation (`--coverage` pour GCC/Clang) sur les cibles concernées ;
  - cible dédiée `coverage` (hors `all`) qui exécute les tests via `ctest --output-on-failure` puis génère le rapport ;
  - génération de rapport via outil standard (`gcovr` en priorité, fallback `lcov/genhtml` selon disponibilité), avec sortie dans `build/coverage/`.
- Conserver les scripts `bin/build-coverage.sh`, `bin/build-case-coverage.sh`, `bin/build-detailed-coverage.sh` uniquement comme compatibilité transitoire/documentation, puis les retirer en fin de migration.
- Reprendre les règles d’installation d’assets via `install(FILES ...)` vers les mêmes destinations.
- Mettre à jour `debian/rules` pour activer le workflow CMake (`dh_auto_configure`, `dh_auto_build`, `dh_auto_test`).
- Adapter la CI et ses scripts pour refléter la bascule CMake :
  - `bin/build/test-task.sh` : remplacer la séquence Autotools par `cmake -S . -B build`, `cmake --build build`, puis exécution des tests via `ctest --test-dir build --output-on-failure` (avec filtre d’exclusion équivalent si nécessaire).
  - `.megami.gitlab-ci.yml` : mettre à jour les clés de cache vers des artefacts CMake (`build/`, `CMakeCache.txt`, `CMakeFiles/`) et retirer les entrées spécifiques Autotools (`m4`, `.lo`, `.deps`, `.libs`, `stamp-h1`).
  - conserver `bin/build/generate-tasks.sh`/`build-task.sh` pour `dpkg-buildpackage`, mais vérifier que `debian/rules` CMake est bien le chemin unique utilisé en CI package.
- Déprécier puis retirer les points d’entrée Autotools (`configure.ac`, `Makefile.am`) selon stratégie de bascule directe validée.

### File Structure
- **Nouveaux fichiers**
  - `CMakeLists.txt` (racine)
  - `src/CMakeLists.txt`
  - `src/ZipDirFs/CMakeLists.txt`
  - `src/ZipDirFs/Components/CMakeLists.txt`
  - `src/ZipDirFs/Containers/CMakeLists.txt`
  - `src/ZipDirFs/Fuse/CMakeLists.txt`
  - `src/ZipDirFs/Utilities/CMakeLists.txt`
  - `src/ZipDirFs/Zip/CMakeLists.txt`
  - `src/ZipDirFs/Zip/Base/CMakeLists.txt`
  - `test/CMakeLists.txt`
  - `assets/CMakeLists.txt`
- **Fichiers modifiés**
  - `debian/rules`
  - `.megami.gitlab-ci.yml`
  - `bin/build/test-task.sh`
  - potentiellement `bin/build/generate-tasks.sh` (si ajustement des hypothèses de build)
  - potentiellement `README.md` (instructions build/CI)
- **Fichiers retirés/dépréciés**
  - `configure.ac`
  - `Makefile.am`

### Risks
- **Risque** : divergence de flags/link entre Autotools et CMake (notamment coverage/pthread).
  - **Mitigation** : valider parité des cibles finales (`zipdirfs`, `gtest`, `gtest_helper`) et des liens libs.
- **Risque** : détection `fusekit` inégale selon distro.
  - **Mitigation** : fallback `pkg_check_modules` strict et messages d’erreur explicites.
- **Risque** : variabilité des outils coverage disponibles selon environnement (ex. `gcovr` absent, différences GCC/Clang).
  - **Mitigation** : détection explicite des outils à la configuration CMake, message d’erreur clair si la cible `coverage` est demandée sans prérequis, et fallback `lcov` si `gcovr` indisponible.

### Architecture Diagram
```mermaid
graph LR
A[Root CMakeLists] --> B[src tree CMakeLists]
A --> C[test/CMakeLists]
A --> D[assets/CMakeLists]
B --> E[folder OBJECT libs]
E --> F[zipdirfs_core]
E --> G[containers BUILD_TEST variant]
F --> H[zipdirfs]
G --> I[gtest]
F --> I
C --> I
C --> J[gtest_helper]
C --> K[coverage targets]
D --> L[installed desktop/icons]
```

# Testing

### Validation Approach
- Vérifier la configuration CMake sur environnement propre avec dépendances système installées.
- Vérifier la parité fonctionnelle des artefacts générés vs build actuel.
- Vérifier la chaîne Debian après adaptation de `debian/rules`.
- Vérifier la chaîne CI GitLab après migration des scripts et caches Autotools vers CMake.

### Key Scenarios
- Build applicatif seul : configuration + compilation de `zipdirfs`.
- Build standard : seules les cibles applicatives (`zipdirfs` + dépendances) sont compilées.
- Exécution de la cible native de test : compilation de `gtest` et `gtest_helper` puis lancement via `ctest`.
- Exécution de la cible `coverage` CMake : instrumentation des cibles de test, lancement `ctest`, puis génération d’un rapport HTML/XML dans `out/build/coverage/`.
- Pipeline CI `run_tests` : exécute configure/build/test via CMake sans appel à `autoreconf`/`./configure`.
- Pipeline CI `generate_builds` + `run_build` : continue de générer et exécuter les jobs de packaging avec artefacts Debian attendus après bascule `debian/rules`.
- Installation des assets dans les chemins `applications`, `pixmaps`, `hicolor/*`.

### Edge Cases
- Dépendance absente (`libzip`, `fusekit`, `Boost`) : échec explicite en configuration.
- Build par défaut : absence de compilation des cibles tests/coverage sans casser le build principal.
- Invocation de `ctest` sans binaires précompilés : les dépendances de tests sont bien construites via la cible native de test.
- Build hors source (`-B out/build`) : les artefacts coverage sont générés dans l’arborescence de build sans hypothèse de chemins source fixes.

### Test Changes
- Ajuster l’intégration des tests au niveau CMake (enregistrement `add_test`/`ctest`).
- Ne pas modifier le contenu des tests unitaires existants sauf besoins de compilation liés à la migration build.

# Delivery Steps

### ✓ Step 1: Mettre en place l’ossature CMake modulaire (racine + src + assets)
Le projet compile avec CMake pour la librairie cœur et le binaire `zipdirfs`, avec installation des assets.

- Créer `CMakeLists.txt` racine avec politique CMake `3.18+`, inclusion des sous-répertoires, et configuration pour que seule la cible principale soit dans `all`.
- Implémenter `src/CMakeLists.txt` + sous-`CMakeLists.txt` par dossier (`src/ZipDirFs/*`) pour produire des cibles `OBJECT` par dossier.
- Agréger les objets dossier dans `zipdirfs_core`, puis lier l’exécutable `zipdirfs`.
- Mapper les dépendances `Boost`, `FUSE`, `fusekit`, `libzip` via `find_package`/`pkg_check_modules` en mode strict.
- Implémenter `assets/CMakeLists.txt` pour reproduire les règles d’installation desktop/icons existantes.

### ✓ Step 2: Migrer la chaîne de tests et la couverture avec les pratiques CMake usuelles
Les tests et la couverture sont exécutés via les cibles natives CMake/CTest, sans reproduire le pipeline shell historique.

- Créer `test/CMakeLists.txt` en s’appuyant sur la cible native de test CMake, avec cibles `gtest`/`gtest_helper` exclues du build par défaut.
- Introduire la variante d’objets `BUILD_TEST` uniquement pour `EntryGenerator` (dossier `Containers`) et utiliser cette variante dans le linkage de `gtest` lors de l’exécution des tests.
- Reprendre les sources fixtures/tests depuis `Makefile.am` et lier proprement aux libs internes et dépendances nécessaires (dont pthread).
- Enregistrer les tests exécutables dans `ctest`.
- Implémenter une cible `coverage` idiomatique (module `cmake/CodeCoverage.cmake`) qui instrumente, lance `ctest`, puis génère un rapport `gcovr`/`lcov` dans `out/build/coverage/`.

### * Step 3: Basculer le packaging Debian vers CMake
Le packaging Debian exécute le cycle configure/build/test via CMake au lieu d’Autotools.

- Adapter `debian/rules` pour passer par `dh_auto_configure`/`dh_auto_build`/`dh_auto_test` sur backend CMake.
- Vérifier l’alignement des dépendances de build Debian avec les besoins CMake.
- Confirmer que les artefacts produits et installés correspondent à ceux attendus par le paquet.

###   Step 4: Migrer les scripts et la configuration CI GitLab vers la chaîne CMake
La CI exécute tests et packaging sans aucun appel au flux Autotools.

- Mettre à jour `bin/build/test-task.sh` pour configurer/ construire avec CMake puis lancer les tests via `ctest`.
- Ajuster `.megami.gitlab-ci.yml` : commandes CI, caches d’artefacts CMake, et suppression des restes Autotools.
- Vérifier que `generate_builds`/`run_build` restent compatibles avec `dpkg-buildpackage` piloté par le nouveau `debian/rules` CMake.

###   Step 5: Finaliser la bascule et nettoyer les références Autotools
Le projet documente CMake comme chemin officiel et retire les points d’entrée Autotools.

- Retirer/déprécier `configure.ac` et `Makefile.am` conformément à la bascule directe validée.
- Mettre à jour `README.md` pour les commandes de build/test/install CMake.
- Vérifier qu’aucun script/doc interne ne dépend encore du flux Autotools.
