Ce document explique comment installer Emacs et Org-mode sur votre machine et recense un certain nombre d'autres références utiles sur cet environnement.
Attention: Les sections Une configuration Emacs adaptée à la "recherche reproductible" et Un modèle d'article réplicable expliquent comment configurer Emacs/Org-Mode pour ce MOOC. Ce sont donc des sections très importantes qui sont illustrées dans deux des trois tutoriels vidéo de cette page. Nous vous encourageons vivement à suivre attentivement ces sections et ces vidéos avant de vous lancer dans les exercices. De même, nous vous encourageons vivement à regarder la vidéo "utilisation Emacs/git" disponible sur la même page.
Il y a beaucoup de façons différentes pour installer Emacs ainsi que les langages Python et R sur votre ordinateur. Celle que nous recommandons et décrivons par la suite est basée sur le gestionnaire de paquets conda. Elle a l'avantage de fonctionner de façon à peu près identique sous Linux, Windows, et macOS. Son deuxième avantage est que l'univers conda propose un grand choix de logiciels scientifiques, qui pourraient vous être utiles pour vos propres projets. Les aguerris en administration système sont bien sûr libres de choisir une autre approche, c'est seulement le résultat qui compte !
Téléchargez d'abord la dernière version de Miniconda. Miniconda est une version légère d'Anaconda, une suite logicielle incluant Python, Jupyter, R ainsi que les bibliothèques les plus couramment utilisées en calcul scientifique et en science des données.
Installez Miniconda en suivant les instructions fournies. Si le logiciel d'installation (ce n'est pas systématique) vous pose la question
Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]
acceptez avec yes
. Puis vous verrez le conseil
=> For changes to take effect, close and re-open your current shell. <=
qu'il faut absolument suivre pour que la suite se passe bien.
Important: il vous faudra lancer les commandes suivantes dans le shell conda. Comme expliqué dans la documentation Anaconda, pour ouvrir ce shell
La première commande à lancer est
conda update -n base -c defaults conda
pour mettre à jour tous les logiciels dans la distribution conda
.
Nous pouvons maintenant créer un environnement conda
pour le parcours Emacs/Org-Mode de ce MOOC :
conda create -n mooc-rr-emacs
et l'activer :
conda activate mooc-rr-emacs
Il n'est pas strictement nécessaire d'activer un environnement pour s'en servir, mais c'est la façon la plus facile qui suscite le moins d'erreurs. Vous devez répéter cette activation chaque fois que vous ouvrez un nouveau terminal, avant de pouvoir utiliser cet environnement.
Le prochain pas est l'installation de tous les logiciels dont nous avons besoin et qui font partie de la distribution Miniconda :
conda install python numpy matplotlib r r-ggplot2 r-dplyr r-hmisc
Nous avons également besoin d'un paquet que ne fait pas partie de Miniconda. Nous le récupérons de la source indépendante conda-forge :
conda install -c conda-forge emacs r-parsedate
Vous pouvez maintenant lancer emacs
directement de la ligne de commande :
emacs
Sous Windows et macOS, vous êtes peut-être tenté de lancer Emacs directement de l'interface graphique. Il n'est en effet pas difficile de trouver Emacs.app
dans l'environnement conda
et de le lancer en direct. Résistez à la tentation. Il faut bien lancer Emacs de la ligne de commande pour qu'il puisse détecter l'environnement que vous avez activé.
Si vous voulez convertir vos notebooks en PDF, vous devez aussi installer LaTeX sur votre ordinateur. Nous expliquons cette procédure dans une ressource spécifique.
Cette section est illustrée dans une vidéo de démonstration (Mise en place en place Emacs/Orgmode). Nous vous suggérons de la regarder avant de suivre les instructions données dans cette section.
Emacs s'installe avec une configuration par défaut très basique que chacun va donc vouloir personnaliser. Compte tenu de la flexibilité d'Emacs, sa configuration peut vite devenir assez complexe et pourrait même faire l'objet d'un paquet à part entière (voir par exemple les différents Emacs Starter Kits ici ou ici). Dans le contexte de ce MOOC, nous vous proposons une configuration relativement minimaliste orientée "recherche reproductible" avec Org-Mode. Si vous êtes peu familier d'Emacs, nous vous recommandons fortement de l'utiliser et de la modifier le moins possible. Il vous suffira de suivre les instructions données dans cette section. Si vous êtes un utilisateur Emacs plus expérimenté, vous pouvez vous contenter de regarder nos instructions et de ne récupérer que les parties qui vous sembleront utiles.
Quand vous lancez Emacs la première fois avec cette configuration, il téléchargera quelques extensions que nous utilisons dans ce MOOC. Ceci peut prendre un peu de temps (quelques minutes), et peut provoquer des messages d'erreur en cas de difficultés de connexion réseau. En ce cas, il suffit de quitter Emacs et de le relancer. Une fois que tout est correctement installé, Emacs n'affiche plus aucun message d'erreur au démarrage, et n'a plus besoin de connexion réseau.
Il est malheureusement assez probable que certains d'entre vous rencontreront des problèmes que nous n'avons pas anticipés. Si c'est votre cas, posez la question sur le forum. Nous ferons de notre mieux pour vous aider.
Si vous avez déjà utilisé Emacs auparavant, il se peut que vous ayez déjà un fichier de configuration personnel. Et même si ce n'est pas le cas, il se peut que vous en ayez un sans même le savoir puisque certains paquets peuvent créer ou modifier les fichiers de configuration d'Emacs. Afin d'éviter tout problème, nous vous recommandons donc d'enlever ces anciennes configurations.
Les fichiers que vous devez sauvegarder puis supprimer (s'ils existent) sont :
~/.emacs
~/.emacs.el
~/.emacs.elc
Il y a aussi un répertoire que vous devez sauvegarder puis supprimer (s'il existe), avec tout ce qu'il peut contenir :
~/.emacs.d
Dans les noms de fichiers ci-dessus, ~/
représente votre répertoire personnel. Sous Windows, les utilisateurs doivent le remplacer par C:\Users\MonNom
, remplaçant MonNom par leur nom d'utilisateur.
Télécharger cette archive et décompressez la. Elle contient les fichiers suivants et nous y ferons référence par la suite :
rr_org/init.el
rr_org/journal.org
rr_org/init.org
Si vous avez des problèmes avec cette archive, les fichiers dont vous aurez besoin sont également disponibles ici. Vous allez vite réaliser que la configuration (init.el
en emacs lisp) est assez difficile à suivre. C'est pourquoi nous le gérons via un fichier init.org
, qui bien plus lisible. C'est une astuce que vous voudrez peut-être aussi adopter (pour cela, modifiez le init.org
et régénérez le init.el
en tanglant le fichier avec M-x org-babel-tangle
comme expliqué dans les instructions au début de init.org
).
Si vous utilisez Windows, et si vous utilisez un raccourci du bureau pour démarrer Emacs, il vous faudra inclure le chemin d'accès au fichier init.el
dans la commande pour le fichier raccourci. Par exemple, si vous avez installé Emacs en tant que C:\Users\MonNom\emacs
, votre raccourci de bureau devrait exécuter la commande commande C:\Users\MonNom\emacs\bin\runemacs.exe -l .emacs.d/init.el
.
Créez un répertoire org/
à la racine de votre répertoire personnel:
mkdir -p ~/org/g/
# sous Windows, utilisez l'explorateur de fichiers pour créer le répertoire C:\Users\MonNom\org
Copiez ensuite le fichier rr_org/journal.org
dans votre répertoire ~/org/
. Ce sera votre cahier de laboratoire et toutes les notes que vous prendrez dans ce dossier avec C-c c
iront automatiquement dans ce fichier. La première entrée de ce carnet est remplie de nombreux de raccourcis claviers Emacs que nous vous encourageons à essayer.
Créez le répertoire ~/.emacs.d/
et copiez rr_org/init.el
dedans.
Il y a deux situations dans lesquelles il peut être nécessaire de modifier init.el
:
Voici comment évaluer votre installation :
conda
(comme nous le recommandons), activez l'environnement que vous avez créé pour ce MOOC. Puis essayez d'exécuter les commandes suivantes:
python3
et R
sous Linux et macOSPython
et R
sous Windowsinit.el
.Si vous devez modifier init.el
, regardez bien les commentaires dans le fichier init.org
pour comprendre comment ça marche.
Quittez Emacs s'il est en cours d'exécution, et redémarrez-le. Ce premier lancement devrait prendre un peu de temps parce qu'Emacs va télécharger quelques paquets supplémentaires. Il vous faudra donc vous assurer que votre ordinateur a une connexion internet pour cette étape. Notez également que le téléchargement peut échouer pour diverses raisons (surcharge des serveurs de paquets, connexion trop lente, …). Ces situations durent rarement bien longtemps. C'est pourquoi si cela arrive, nous vous recommandons de vous contenter de quittez Emacs (C-x C-c
, c'est-à-dire Ctrl + x
suivi de Ctrl + c
) et redémarrez-le. Au pire, répétez cette opération jusqu'à ce que vous n'obteniez plus d'erreur au démarrage.
Ensuite, créez un fichier foo.org
. Copiez les lignes suivantes dans ce fichier :
#+begin_src shell :session foo :results output :exports both
ls -la # ou dir sous Windows
#+end_src
Placez votre curseur à l'intérieur de ce bloc de code et exécutez-le avec le raccourci clavier suivante : C-c C-c
(cela signifie faire Ctrl + c
deux fois de suite rapidement).
Un bloc #+RESULTS:
avec le résultat de la commande devrait alors apparaître.
Dans la vidéo, nous avons déjà fait une petite démonstration des principales fonctionnalités d'emacs/org-mode qui vous aideront à tenir à jour un journal et à faire de la programmation lettrée. Une liste des principales fonctionnalités et des raccourcis est donnée dans le première entrée de votre labbook. N'hésitez pas à également suivre cette ressource pour découvrir ces raccourcis.
À l'étape 2, nous vous avons demandé de créer un journal dans le fichier ~org/journal.org
. C'est dans ce fichier que les notes prises avec le raccourci C-c c
(Ctrl + c
puis c
) atterrissent. Nous vous conseillons fortement de vous assurer que ce fichier est stocké dans un système de contrôle de version comme git. Nous vous laissons la responsabilité de mettre tout ceci en place mais si vous avez des problèmes, n'hésitez pas à poser des questions sur le forum du MOOC.
Cette section est illustrée dans une vidéo ("Écrire un article réplicable avec Emacs/Orgmode"). Nous vous suggérons de la regarder avant de suivre les instructions données dans cette section.
Pour travailler avec ce modèle d'article, vous aurez besoin d'installations fonctionnelles de LaTeX, R, et Python. Si vous ne pouvez pas ouvrir un terminal et exécuter les commandes R
, pdflatex
, et python3
, vous ne pourrez pas générer ce document. Lors de la compilation, l'article télécharge les paquets LaTeX correspondants. Vous devrez donc également disposer d'une connexion réseau fonctionnelle.
Note pour les utilisateurs de macOS : Puisque l'article est compilé à l'aide de make
, il vous faudra mettre l'exécutable Emacs dans le chemin de recherche de votre shell (voir la section dédiée à ce sujet).
Téléchargez l'archive suivante et décompressez-la. L'archive contient l'article compilé, vous pouvez donc commencer par le consulter.
Pour reconstruire l'article, supprimez article.pdf
, ou renommez-le en autre chose. Sinon, la procédure de reconstruction vous indiquera simplement que l'article est déjà à jour. Tapez ensuite make
pour tout construire à partir de zéro. Ouvrez l'article fraîchement construit article.pdf
pour voir s'il a l'air correct.
Si vous en avez assez de toujours réexécuter tout le code source lors de l'exportation, recherchez la ligne suivante dans article.org :
# #+PROPERTY: header-args :eval never-export
Si vous supprimez le #
au début de la ligne qui indique un commentaire, org-mode arrêtera d'évaluer chaque morceau de code à chaque exportation.
L'apprentissage d'Emacs et d'Org-Mode peut être difficile car il y a quantité de raccourcis clavier assez inhumaine. On trouve donc de nombreux pense-bêtes dont voici une sélection à toute fin utile :
Pour ceux d'entre vous qui préfèrent des explications vidéo, voici une chaîne Youtube avec de nombreux tutoriels emacs.
Pour des informations générales sur un certain nombre de paquets, vous pouvez également vouloir jeter un œil au blog Using Emacs.
Company-mode est un paquet permettant d'améliorer les capacités de complétion de texte pour Emacs. Il offre des capacités de complétion intelligente (et pas uniquement syntaxique) pour la plupart des langages. Si ce type de fonctionnalité vous parait utile, nous vous encourageons à suivre les instructions d'installation du site web officiel: page Web officielle : http://company-mode.github.io/.
Magit est une interface Emacs pour Git. Son utilisation est brièvement illustrée dans le contexte de ce MOOC dans un tutoriel vidéo. ("Utilisation Emacs/git").
C'est un outil vraiment très puissant et nous l'utilisons quotidiennement mais il est nécessaire de vraiment comprendre ce que fait git dans les coulisses. Si vous pensez que cela vous serait utile, vous devriez suivre ce petit tour du propriétaire ou bien cette brève introduction.
Si vous avez installé notre configuration "recherche reproductible", vous pouvez facilement invoquer magit en utilisant C-x g
. Si vous n'êtes pas déjà dans un répertoire sous contrôle de version avec git, Magit vous demandera le chemin de votre copie local du dépôt git (le chemin vers mooc-rr dans le contexte de ce MOOC).
Si vous n'utilisez pas notre configuration, vous devriez jeter un coup d'œil à comment installer magit à partir de l'archive MELPA.
La méthode suivante a été testée avec Windows et a fonctionné sans encombre :
Ajoutez le texte suivant dans votre fichier .emacs.d/init.el
:
Lancez Emacs et exécutez les commandes suivantes :
M-x package-refresh-contents RET
M-x package-install RET magit RET
NB : M-
(Meta) correspond à la touche <Alt>
et RET
correspond à la touche <Entrée>
.