From 282b4cfad61e023301b661eb8954e8274d02ada8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Nov 2025 18:57:52 +0000
Subject: [PATCH] =?UTF-8?q?Am=C3=A9lioration=20documentation=20pour=20envi?=
 =?UTF-8?q?ronnement=20Claude=20Code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Ajout d'un guide complet pour les sessions Claude Code
- Correction: cpal remplace rodio pour AudioSink
- Ajout de libasound2t64 dans les dépendances (bibliothèque partagée)
- Ajout de RUSTFLAGS dans la configuration des variables d'environnement
- Documentation du workflow pour chaque nouvelle session
- Ajout de setup-env.sh au .gitignore

Le guide inclut maintenant:
- Installation complète sans sudo
- Configuration des variables d'environnement
- Vérification de l'installation
- Compilation et test des exemples
- Résolution des erreurs communes
---
 .gitignore         |   4 +-
 INSTALL_LIBSOXR.md | 124 ++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 115 insertions(+), 13 deletions(-)

diff --git a/.gitignore b/.gitignore
index 05ec847c..2eec05c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,4 +36,6 @@ all.txt
 pmo_src.txt
 upmpdcli/
 /*.xml
-test_upnp
\ No newline at end of file
+test_upnp*.cargo/
+.cargo/
+setup-env.sh
diff --git a/INSTALL_LIBSOXR.md b/INSTALL_LIBSOXR.md
index 7c3ae88d..a3c4129f 100644
--- a/INSTALL_LIBSOXR.md
+++ b/INSTALL_LIBSOXR.md
@@ -5,11 +5,11 @@ Ce document explique comment installer les dépendances système de `pmoaudio` l
 ## Dépendances requises
 
 1. **libsoxr** - Nécessaire pour `ResamplingNode` (resampling audio haute qualité)
-2. **libasound2** (ALSA) - Nécessaire pour `AudioSink` via rodio (lecture audio sur Linux)
+2. **libasound2** (ALSA) - Nécessaire pour `AudioSink` via cpal (lecture audio sur Linux)
 
 ## Contexte
 
-Les crates `soxr` et `rodio` nécessitent des bibliothèques système. Dans un environnement sans droits sudo, voici comment les installer localement.
+Les crates `soxr` et `cpal` nécessitent des bibliothèques système. Dans un environnement sans droits sudo (comme Claude Code), voici comment les installer localement.
 
 ## Méthode : Installation locale via apt-get download
 
@@ -22,7 +22,8 @@ cd ~/.local
 apt-get download libsoxr-dev libsoxr0
 
 # Pour ALSA (AudioSink)
-apt-get download libasound2-dev
+# Note: libasound2t64 contient la bibliothèque partagée, libasound2-dev les headers
+apt-get download libasound2-dev libasound2t64
 ```
 
 Cela télécharge les fichiers `.deb` sans les installer système-wide.
@@ -36,6 +37,7 @@ dpkg -x libsoxr0_*.deb .
 
 # Extraire ALSA
 dpkg -x libasound2-dev_*.deb .
+dpkg -x libasound2t64_*.deb .
 ```
 
 Les fichiers sont extraits dans `~/.local/usr/lib/x86_64-linux-gnu/` et `~/.local/usr/include/`.
@@ -45,11 +47,12 @@ Les fichiers sont extraits dans `~/.local/usr/lib/x86_64-linux-gnu/` et `~/.loca
 Ajouter à votre `~/.bashrc` ou exporter dans votre session :
 
 ```bash
-export PKG_CONFIG_PATH="/root/.local/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
-export LD_LIBRARY_PATH="/root/.local/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
+export PKG_CONFIG_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
+export LD_LIBRARY_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
+export RUSTFLAGS="-L $HOME/.local/usr/lib/x86_64-linux-gnu"
 ```
 
-**IMPORTANT:** Remplacer `/root/` par le chemin de votre home directory (`$HOME` ou `~`).
+**IMPORTANT:** Ces variables doivent être définies dans chaque session où vous compilez le projet.
 
 ### 4. Vérifier l'installation
 
@@ -145,14 +148,111 @@ export LD_LIBRARY_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
 cargo test
 ```
 
-## Notes pour Claude Code sessions
+## Guide complet pour environnement Claude Code
 
-Pour les futures sessions Claude :
+### Configuration initiale (à faire une seule fois)
 
-1. Exporter les variables d'environnement en début de session
-2. NE PAS créer de fichiers `.cargo/config.toml` dans le projet
-3. Si nécessaire pour les tests, les créer localement mais ne pas les committer
-4. Documenter toute difficulté d'installation ici
+Dans une session Claude Code (https://claude.ai/code), vous n'avez pas de droits sudo. Suivez ces étapes :
+
+#### 1. Installation des dépendances
+
+```bash
+# Créer le répertoire local
+mkdir -p ~/.local
+cd ~/.local
+
+# Télécharger tous les packages nécessaires
+apt-get download libsoxr-dev libsoxr0 libasound2-dev libasound2t64
+
+# Extraire tous les packages
+dpkg -x libsoxr-dev_*.deb .
+dpkg -x libsoxr0_*.deb .
+dpkg -x libasound2-dev_*.deb .
+dpkg -x libasound2t64_*.deb .
+
+# Retourner au projet
+cd /home/user/pmomusic
+```
+
+#### 2. Configuration des variables d'environnement
+
+**IMPORTANT:** Ces variables doivent être exportées dans CHAQUE session Claude Code avant de compiler :
+
+```bash
+export PKG_CONFIG_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
+export LD_LIBRARY_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
+export RUSTFLAGS="-L $HOME/.local/usr/lib/x86_64-linux-gnu"
+```
+
+**Astuce :** Copier ces trois lignes dans un fichier `setup-env.sh` à la racine du projet :
+
+```bash
+cat > setup-env.sh << 'EOF'
+export PKG_CONFIG_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
+export LD_LIBRARY_PATH="$HOME/.local/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
+export RUSTFLAGS="-L $HOME/.local/usr/lib/x86_64-linux-gnu"
+EOF
+```
+
+Puis dans chaque session :
+
+```bash
+source setup-env.sh
+```
+
+⚠️ **NE PAS committer `setup-env.sh`** - ajouter au `.gitignore`
+
+#### 3. Vérifier l'installation
+
+```bash
+# Vérifier que pkg-config trouve les bibliothèques
+pkg-config --libs --cflags soxr
+pkg-config --libs --cflags alsa
+
+# Devrait afficher quelque chose comme :
+# -I/root/.local/usr/include -L/root/.local/usr/lib/x86_64-linux-gnu -lsoxr
+# -I/root/.local/usr/include -L/root/.local/usr/lib/x86_64-linux-gnu -lasound
+```
+
+#### 4. Compiler et tester
+
+```bash
+# Compiler le workspace complet
+cargo build
+
+# Tester l'exemple play_and_cache de pmoparadise
+cargo run --package pmoparadise --example play_and_cache --features full -- 0
+```
+
+### Workflow pour chaque nouvelle session
+
+À chaque fois que vous démarrez une nouvelle session Claude Code :
+
+1. **Exporter les variables d'environnement** (ou `source setup-env.sh`)
+2. Compiler avec `cargo build`
+3. Exécuter les exemples ou tests
+
+**IMPORTANT :** Si vous oubliez d'exporter les variables, vous obtiendrez des erreurs comme :
+```
+error: failed to run custom build command for `soxr-sys`
+Package 'soxr' was not found in the pkg-config search path
+```
+
+ou
+
+```
+rust-lld: error: unable to find library -lasound
+```
+
+Solution : Exporter les variables et recompiler.
+
+### Notes importantes
+
+- ✅ Les dépendances installées dans `~/.local` persistent entre les sessions
+- ✅ Les variables d'environnement doivent être réexportées à chaque nouvelle session
+- ❌ NE JAMAIS créer de fichiers `.cargo/config.toml` dans le projet (chemins spécifiques)
+- ❌ NE JAMAIS committer `setup-env.sh` (configuration locale)
+- 💡 Sur macOS (via Homebrew) : seul `libsoxr` est nécessaire (pas d'ALSA)
 
 ## Références