1 files changed, 66 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..826a6c1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# Qt for Python development environment
+
+Environnement PySide6 (binding Qt officiel) sur Python 3.13, versions
+alignées avec le C++ de `~/projects/qt-dev` (Qt 6.11).
+
+## Entrer dans l'environnement
+
+```bash
+cd ~/projects/qt-python-dev
+nix develop
+```
+
+## Lancer les exemples
+
+```bash
+python examples/hello_widgets.py   # app Widgets (signals/slots)
+python examples/hello_quick.py     # app QML/Qt Quick
+```
+
+Pas de compilation : Python + QML chargé à l'exécution. Itération
+instantanée — c'est l'avantage principal sur le C++.
+
+## Outils disponibles
+
+| Commande | Rôle |
+|----------|------|
+| `designer` | éditeur de fichiers .ui |
+| `uic -g python fichier.ui -o ui_fichier.py` | compiler un .ui en module Python |
+| `rcc -g python ressources.qrc -o rc.py` | compiler des ressources |
+| `linguist` | traduction (.ts) |
+| `assistant` | doc offline |
+
+Note : le paquet nixpkgs ne fournit pas les wrappers `pyside6-uic`/
+`pyside6-rcc` de PyPI — mais `uic`/`rcc` de qtbase (sur le PATH du
+shell) génèrent du Python nativement avec `-g python`, c'est le même
+résultat.
+
+Workflow Designer typique : dessiner dans `designer`, générer avec
+`uic -g python`, importer la classe générée dans son code.
+
+## Documentation
+
+- Doc Qt offline dans `$QT_DOCS` (enregistrer dans Assistant :
+  Préférences → Documentation → Ajouter).
+- Doc PySide6 spécifique (API Python) : https://doc.qt.io/qtforpython-6/
+- La doc C++ reste utile : l'API Python est un mapping quasi 1:1.
+
+## PySide6 vs PyQt6
+
+Les deux sont dans nixpkgs (`python3Packages.pyside6` / `.pyqt6`),
+mêmes versions. PySide6 choisi ici : binding **officiel** Qt, licence
+LGPL (PyQt6 est GPL/commercial). API quasi identique — migration
+triviale dans les deux sens (`Signal` vs `pyqtSignal`, etc.).
+
+## Notes NixOS
+
+- Les **plugins de plateforme** sont trouvés automatiquement (chemins
+  compilés dans le Qt de nixpkgs), mais **pas les imports QML** : sans
+  le `QML_IMPORT_PATH` exporté par le shellHook, tout `import QtQuick`
+  échoue avec « module is not installed ».
+- **Ne pas faire `pip install pyside6`** dans un venv sur NixOS : le
+  wheel PyPI embarque ses propres libs Qt liées contre une glibc/ABI
+  générique — segfaults et conflits garantis. Toujours passer par
+  `python3Packages.pyside6`.
+- Session Wayland GNOME : fonctionne nativement ; forcer X11 si besoin
+  avec `QT_QPA_PLATFORM=xcb`.