======================= Installation sous macOS ======================= .. Attention:: Il y a moins de contributeurs·trices sur macOS que sur d’autres plateformes. Il se peut que l’installation et les tests unitaires fonctionnent correctement, partiellement ou pas du tout. Bref, en cas de problème n’hésitez pas à venir demander de l’aide sur le `forum des Devs’ de Zeste de Savoir `_ ! Les instructions ci-dessous ont été testées avec succès sur un MacBook Pro fin-2021, avec processeur M1 Pro, sous macOS 12 (Monterey) et 13 (Ventura). Pour installer une version locale de ZdS sur macOS, veuillez suivre les instructions suivantes. Si une commande ne passe pas, essayez de savoir pourquoi avant de continuer. macOS étant un système UNIX proche de Linux, l’installation fonctionne quasiment comme pour cet OS, à quelques détails près. La principale différence est que macOS étant basé sur BSD, il faut remplacer les outils BSD par ceux de GNU (les ``gnu-coreutils``, utilisés sous Linux), et avec lesquels ``zds-site`` est conçu. .. note:: Les instructions ci-dessous sont écrites pour macOS, mais il se peut que leur philosophie (utiliser les ``gnu-coreutils`` au lieu de ceux de BSD) permette d’installer ``zds-site`` sur un système \*BSD. Pré-requis ========== .. admonition:: Avis aux utilisateurs·trices avancé·es Ces instructions expliquent comment installer XCode, Homebrew, Python, pip, et les utilitaires GNU, sur macOS. Si vous avez déjà : - une installation fonctionnelle de Homebrew et de Python 3.7+ ; - configuré votre terminal pour utiliser les utilitaires GNU à la place de ceux de BSD (avec `linuxify `_, par exemple) ; alors vous pouvez `passer à la section suivante <#dependances-systeme>`_ concernant l’installation de ``zds-site``. XCode ----- Pour installer ou lancer ``zds-site`` sur macOS, vous devrez utiliser un terminal pour pouvoir y entrer des commandes servant à installer ou lancer le site et ses composants annexes. `macOS intègre un terminal nativement `_, que vous pouvez utiliser. Pour utiliser complètement le terminal sous macOS, vous devez installer quelques outils supplémentaires qui ne sont pas installés de base avec macOS. Depuis votre terminal, exécutez cette commande pour les installer. .. sourcecode:: bash xcode-select --install Homebrew -------- Vous aurez ensuite besoin d’**Homebrew**, un système permettant de télécharger et d’installer des logiciels sous macOS depuis la ligne de commande, et de les mettre à jour. Nous nous en servirons pour installer Python (si nécessaire) et les dépendances de ``zds-site``. `Les instructions d’installation d’Homebrew sont sur leur site web `_. Python 3 -------- ``zds-site`` dépend d’une version récente de Python 3. Sous macOS Ventura et plus récent (macOS 13+), Python 3 est installé avec XCode, qu’on a installé plus haut. Pour vérifier, exécutez la commande suivante : .. sourcecode:: bash python --version Si vous obtenez une version inférieure à Python 3.9 (et notamment si vous voyez ``Python 2.7``), il vous faudra installer une version récente de Python avec Homebrew. Sinon, vous pouvez utiliser la version intégrée avec macOS de Python, mais vous devrez installer ``pip``. Si votre version de Python est trop vieille ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Il vous faut installer Python avec Homebrew. Exécutez dans un terminal : .. sourcecode:: bash brew install python Puis revérifiez la version de Python avec ``python --version``. Si elle n’a pas changé, tentez de redémarrer votre terminal. Si vous gardez la version native de Python ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Si vous avez décidé de garder la version native de Python, si elle est assez récente, vous allez quand même devoir installer ``pip``, un logiciel compagnon de Python servant à installer des bibliothèques externes en Python — des extensions permettant d’augmenter ses possibilités facilement. Pour vérifier que vous disposez de ``pip``, exécutez l’une de ces commandes : .. sourcecode:: bash pip --version # ou pip3 --version # ou python -m pip --version Vous devriez obtenir un numéro de version de pip et de Python, comme cela : .. sourcecode:: bash $ pip --version # ou une des autres commandes pip 22.3.1 from /opt/homebrew/lib/python3.10/site-packages/pip (python 3.10) Si ces commandes retournent toutes une erreur, et non un numéro de version, vous devez installer ``pip``. `Les instructions d’installation sont sur le site web de pip. `_ Utilitaires GNU/Linux au lieu de BSD ------------------------------------ ``zds-site`` est conçu pour fonctionner avec les utilitaires de Linux (les ``gnu-coreutils``), différents des utilitaires natifs de \*BSD (et donc de macOS, qui en est un lointain descendant). Le plus simple est le projet ``linuxify``, qui installe toutes les versions GNU de divers logiciels avec Homebrew. Par défaut, ces versions viennent préfixées, pour ne pas entrer en conflit avec les versions du système. En pratique, ce n’est pas un problème d’utiliser dans votre environnement local les versions de GNU, donc vous pouvez utiliser en permanence ces versions à la place de celles de BSD. Dans le doute, remplacez en permanence par les versions de GNU : c’est sans impact négatif et ça permet à ``zds-site`` de fonctionner sans manipulation particulière. `Commencez par installer linuxify `_, tel que précisé sur leur site. Si vous avez une erreur disant ``command not found: git``, exécutez dans votre terminal la commande ``brew install git``. Lorsqu’il vous demande *Do you want to change your shell to the latest bash*, répondez non (``n``). Ensuite, si vous choisissez de remplacer en permanence les utilitaires BSD par ceux de GNU, exécutez la commande suivante pour automatiquement utiliser les utilitaires GNU quand vous utilisez votre terminal, puis redémarrez votre terminal. .. sourcecode:: bash echo ". ~/.linuxify" >> ~/.zshrc Si vous choisissez de ne **pas** le faire, alors il vous faudra exécuter cette commande dans *chaque* terminal où vous exécuterez des commandes d’installation ou de mise à jour de ``zds-site`` (une fois par terminal, pas besoin de la ré-exécuter à chaque fois) : .. sourcecode:: bash . ~/.linuxify Dépendances système =================== Le script d’installation n’installant pas encore les paquets automatiquement sur macOS, vous devez le faire à la main, via Homebrew. Exécutez la commande suivante pour tout installer. .. sourcecode:: bash brew install curl gettext cairo Une fois les pré-requis terminés, vous pouvez vous lancer dans l‘installation de l’environnement de ``zds-site``. Installation de ``zds-site`` ============================ Commencez par cloner le dépôt de ``zds-site``, ou idéalement, votre fork sur lequel vous travaillerez avant d’envoyer des *Pull-Requests*. .. sourcecode:: bash git clone git@github.com:VOTRE-PSEUDO-GITHUB/zds-site.git cd zds-site ``zds-site`` peut s’installer de deux façons : - une version minimale, qui ne contient que le site lui-même, mais pas le moteur de recherche ni le système d’export des PDF ; - une version complète, qui contient tout, et qui est aussi plus lourde à installer. .. Attention:: La version complète **ne peut être automatiquement installée pour le moment** car l’installeur télécharge une version de Java (pour ElasticSearch) spécifique à Linux. Cependant, vous pouvez remplacer la version de Java installée dans ``zds-site/zdsenv/lib/jdk`` par une version fonctionnant sous macOS et ElasticSearch fonctionnera. Le système de génération et d’export des PDF devrait fonctionner normalement. La version minimale a été testée avec succès. .. seealso:: - `Installation d’Elasticsearch `_ ; - `installation de LaTeX `_. Pour installer la version minimale, exécutez depuis la racine du dépôt que vous venez de cloner : .. sourcecode:: bash ./scripts/install_zds.sh +base -packages Si vous voulez la version complète : .. sourcecode:: bash ./scripts/install_zds.sh +full -packages .. note:: L’option ``-packages`` désactive l’installation automatique des dépendances système, qui n’est pour le moment supportée que sous Linux. .. note:: Vous pouvez relire le script avant de l’exécuter pour savoir ce qu’il fait. Mais dans l’idée, ce script va : - installer ``virtualenv`` (via ``pip``), un logiciel Python permettant de créer des environnements virtuels cloisonnés en Python ; - créer un environnement virtuel dans le sous-dossier ``zdsenv`` ; - installer dans votre dossier utilisateur le logiciel ``nvm`` (*Node Versions Manager*), un outil permettant d’installer différentes versions de NodeJS ; - installer la bonne version de NodeJS localement (uniquement pour ``zds-site``) et intégrer le chargement de la cette bonne version à l’environnement virtuel ; - installer les dépendances de ``zds-site`` dans l’environnement virtuel ; - installer ``zmarkdown``, le moteur de rendu Markdown utilisé par ``zds-site`` ; - installer les dépendances du *front-end* avec ``npm`` puis compiler le *font-end* ; - créer la base de données utilisée par ``zds-site`` (avec SQLite) et la remplir de données de test ; - intégrer au dépôt local un *pre-commit hook* `vérifiant que le code Python est correctement formaté à chaque commit <../utils/git-pre-hook.html>`_ (et le formatant le cas échéant). Si vous installez la version complète, le script va, en plus : - installer une version de Java pour Linux dans le dossier ``zds-site/zdsenv/lib/jdk`` et modifier l’environnement virtuel pour que cette version de Java soit utilisée ; - installer ElasticSearch dans le dossier ``zds-site/.local/elasticsearch`` ; - installer TeXLive (permettant de compiler du LaTeX en PDF, utilisé pour les exports PDF) dans le dossier ``zds-site/.local/texlive`` ; - cloner le dépôt contenant le modèle LaTeX utilisé par l’export PDF dans le dossier ``zds-site/latex-template``. Lancement de ``zds-site`` ========================= Une fois dans votre environnement Python et toutes les dépendances installées, lançons ZdS. Il faut d’abord lancer ``zmarkdown``, le moteur de rendu Markdown utilisé par Zeste de Savoir. Ce moteur fonctionne sur un modèle client-serveur : ``zds-site`` envoie une requête HTTP (en local) pour obtenir le rendu d’un document Markdown en HTML, ePub, ou LaTeX. Il faut donc démarrer le serveur ``zmarkdown`` en arrière-plan. Ensuite, on démarre ``zds-site``. .. sourcecode:: bash # Depuis la racine du dépôt zds-site make zmd-start make run Le démarrage de ``zds-site`` entraîne celui du *backend* Python dans un mode optimisé pour le développement. Notamment, le cache est totalement désactivé et des outils de débogage rendent disponible plein d’informations sur chaque page, les données techniques envoyées (paramètres de templates, …) et les requêtes SQL envoyées. Ces outils sont pratiques mais ils peuvent être lourds. Si vous avez une machine peu puissante et que vous voulez une version plus légère, mais sans tous ces outils de développement, vous pouvez démarrer une version plus légère de ``zds-site`` ainsi. .. sourcecode:: bash make run-fast Ces deux façons de lancer ``zds-site`` lancent aussi la compilation automatique à la moindre modification des fichiers du *front-end* (SCSS, JS, etc.). Si vous voulez également désactiver cela, car vous ne travaillez pas sur le *front-end* et/ou que vous voulez une version plus légère du site, vous pouvez ne lancer que le *back-end* : .. sourcecode:: bash make run-back # ou (cf. plus haut) make run-back-fast Pour lister toutes les options disponibles, exécutez simplement, sans argument : .. sourcecode:: bash make Données de test =============== L’installeur a créé pour nous le `jeu de données utile au développement <../utils/fixture_loaders.html>`_. Si pour une raison ou pour une autre, vous voulez repartir de zéro en écrasant toutes les données de votre installation locale, vous pouvez le faire. .. warning:: Cette commande **supprime totalement votre base de données, ainsi que tous les contenus que vous avez pu créer, sur votre instance locale**, puis recrée des données de test aléatoires à partir de zéro. **Il n’est pas possible d’annuler cette opération.** .. sourcecode:: bash make new-db Mettre à jour votre instance locale =================================== Pour rapidement mettre votre instance locale à jour, par exemple pour tester une *Pull-Request* ou si vous vous êtes mis à jour depuis le dépôt principal, lancez : .. sourcecode:: bash make update Cette commande va mettre à jour le *back-end* et le *front-end*, puis migrer la base de données (si nécessaire) et recompiler le *front-end*.