Faire le Projet GL sur une machine personnelle : Différence entre versions

De Ensiwiki
Aller à : navigation, rechercher
m (Installation de Netbeans : Précision de la version. Ne pas se faire avoir en prenant une 8.0.2...)
(Installation de l'arborescence globale du projet (ima))
 
(65 révisions intermédiaires par 9 utilisateurs non affichées)
Ligne 11 : Ligne 11 :
  
 
Il faut notamment modifier le fichier pom.xml comme indiqué sur cette page [[Questions fréquentes avec Maven pour le projet GL#tools-jar]], afin de faire pointer correctement maven vers le fichier tools.jar.
 
Il faut notamment modifier le fichier pom.xml comme indiqué sur cette page [[Questions fréquentes avec Maven pour le projet GL#tools-jar]], afin de faire pointer correctement maven vers le fichier tools.jar.
 +
 +
Quelques conseils spécifiques pour OS X sont disponibles sur la page [[Projet GL sous Mac OS X]] .
  
 
== Installation de Java ==
 
== Installation de Java ==
  
Une installation de Java quelconque fera l'affaire. Il vous faudra au minimum Java 1.6, et il est fortement recommandé d'utiliser Java 1.7. Selon la distribution, un <code>apt-get install openjdk-7-jdk</code> ou un <code>yum install java-1.7.0-openjdk</code> devrait installer tout cela. Sinon, on peut télécharger Java sur [http://www.oracle.com/technetwork/java/javase/downloads/index.html le site d'Oracle] ou bien sur celui [http://openjdk.java.net/install/ d'OpenJDK].
+
Une installation de Java quelconque récente (au delà de java 7) fera l'affaire. la version installée actuellement en salle sur les PC est la 14
  
== Installation de Netbeans ==
+
1. Vérifiez la version java utilisée actuellement sur votre machine avec: <code>javac -version</code>
  
Les versions packagées pour Ubuntu et Debian sont en général cassées (le gestionnaire de plugins ne marche pas). Il est fortement recommandé de faire une installation manuelle. Pour pouvoir utiliser le plugin ANTLRWorks, il faut une version '''8.0.1''' au maximum.
+
2. Si java 14 n'est pas installé sur votre machine: selon la distribution, un <code>apt-get install openjdk-14-jdk</code> ou un <code>yum install openjdk-14-jdk</code> devrait installer tout cela. Sinon, on peut télécharger Java sur [http://openjdk.java.net/install/ le site d'OpenJDK] ou bien sur [http://www.oracle.com/technetwork/java/javase/downloads/index.html le site d'Oracle].
En effet, une version 8.0.2 (la plus récente à ce jour) vous donnera une erreur à l'installation du plugin ANTLRWorks (http://plugins.netbeans.org/plugin/53652/antlrworks-2).
+
  
Suivre les instructions de téléchargement et d'installation depuis cette page : https://netbeans.org/downloads/8.0/index.html
+
3. Si plusieurs versions de Java sont installées sur votre machine, positionnez la variable d'environnement <code>JAVA_HOME</code> sur le JDK 14 dans votre <code>.bash_rc</code> avec une ligne comme: <code>export JAVA_HOME=/usr/lib/jvm/java-14-openjdk-amd64</code>
 +
(en adaptant avec le nom du répertoire d'installation de JDK 1.8 sur votre machine, que vous pouvez trouver par exemple à l'aide de <code>dpkg-query -L openjdk-14-jdk</code> sous debian/ubuntu).
 +
<br>
 +
Positionner <code>JAVA_HOME</code> ne change pas la version de Java sur votre machine (<code>java -version</code> reste inchangé), ça change juste la version de Java utilisée dans maven (et netbeans).
  
== Installation du plugin ANTLRWorks pour Netbeans ==
+
4. Si la méthode du point 3 ne permet pas de faire fonctionner maven correctement, vous pouvez essayer <code>sudo update-alternatives --config javac</code> pour imposer le choix de java 14 à votre système (mais ça ne devrait pas être nécessaire).
 
+
Pour avoir la coloration syntaxique dans les fichiers .g4 (grammaires ANTLRv4), installez le plugin ANTLRWorks disponible dans les plugins officiels de Netbeans :
+
 
+
* Lancer netbeans
+
 
+
* Dans le « Tools », choisir « Plugins »
+
 
+
* Onglet « available plugins », choisir « ANTLRWorks editor », puis bouton « install » et se laisser guider.
+
  
 
== Installation de Maven ==
 
== Installation de Maven ==
Ligne 37 : Ligne 33 :
 
Maven est disponible dans Debian et Ubuntu : <code>apt-get install maven</code>
 
Maven est disponible dans Debian et Ubuntu : <code>apt-get install maven</code>
  
Installer Maven manuellement est très facile : il suffit de télécharger une archive « Binary » depuis cette page http://maven.apache.org/download.cgi, d'extraire l'archive et de placer le répertoire <code>bin/</code> au début de votre $PATH. Pour plus de détails, voir par exemple [http://johnathanmarksmith.com/linux/java/maven/programming/project%20management/2013/04/18/how-to-install-maven-on-fedora-centos-red-hat-and-scientific-linux/ cette page] si nécessaire.
+
Installer Maven manuellement est très facile : il suffit de télécharger une archive « Binary » depuis cette page http://maven.apache.org/download.cgi, d'extraire l'archive et de placer le répertoire <code>bin/</code> au début de votre $PATH. Pour plus de détails, voir par exemple [http://johnathanmarksmith.com/linux/java/maven/programming/project%20management/2013/04/18/how-to-install-maven-on-fedora-centos-red-hat-and-scientific-linux/ cette page] si nécessaire.
 +
 
 +
Une autre option est d'utiliser le Maven distribué avec Netbeans (netbeans/java/maven/bin/mvn): dans ce cas, voir l'installation de netbeans ci-dessous.
  
Une autre option est d'utiliser le Maven distribué avec Netbeans (netbeans/java/maven/bin/mvn).
+
Vérifiez que maven fonctionne avec Java version 1.8 en lançant <code>mvn -version</code>. Si ce n'est pas le cas, consultez le paragraphe [[Faire_le_Projet_GL_sur_une_machine_personnelle#Installation_de_Java]] ci-dessus.
  
 
== Installation de Git ==
 
== Installation de Git ==
Ligne 45 : Ligne 43 :
 
Votre distribution contient probablement [[Git]], et il suffira probablement d'un <code>apt-get install git-core gitk</code>, <code>yum install git</code>, ...
 
Votre distribution contient probablement [[Git]], et il suffira probablement d'un <code>apt-get install git-core gitk</code>, <code>yum install git</code>, ...
  
Sous Mac téléchargez la dernière version de Git depuis http://code.google.com/p/git-osx-installer/ puis ouvrez <code>git-*-intel-leopard.dmg</code> et suivez les indications de l'utilitaire.
+
Sous Mac téléchargez la dernière version de Git depuis https://git-scm.com/download/mac puis suivez les indications de l'utilitaire.
  
= Installation de l'environnement du projet =
+
== Installation de Netbeans (optionnelle) ==
  
<div id="clessh">
+
Les versions packagées pour Ubuntu et Debian sont en général cassées (le gestionnaire de plugins ne marche pas). Il est fortement recommandé d'installer une version récente d'Apache Netbeans (version 12 par exemple).
== Clés SSH ==
+
  
Vous devez dans un premier temps récupérer la clé privée qui vous permettra d'accéder au dépôt :
+
Suivre les instructions de téléchargement et d'installation de netbeans depuis cette page : https://netbeans.apache.org/download/index.html
  
rsync --chmod=go-rwx monlogin@pcserveur.ensimag.fr:/matieres/4MMPGL/GL/keys/'$LOGNAME' ~/.ssh/id_projet_gl
+
Pour plus de confort, sous Linux, n'hésitez pas à ajouter le chemin vers les binaires netbeans à votre PATH. Il suffit d'ajouter <code> export export PATH="/chemin/vers/dossier/netbeans-12.0-bin/bin:$PATH"</code>
  
(en remplaçant bien entendu <code>monlogin</code> par votre login Ensimag)
+
== Installation du plugin ANTLRWorks pour Netbeans (optionnelle, mais conseillée si votre IDE est netbeans) ==
  
Il faut ensuite dire à SSH d'utiliser cette clé. Cela peut se faire en créant un fichier <code>~/.ssh/config</code> sur la machine depuis laquelle vous vous connectez, avec le contenu suivant :
+
Pour avoir la coloration syntaxique dans les fichiers .g4 (grammaires ANTLRv4), installez le plugin ANTLRWorks disponible au téléchargement ici :  http://plugins.netbeans.org/plugin/73187/netbeans-antlr
  
Host depots.ensimag.fr
+
* Lancer netbeans
IdentityFile ~/.ssh/id_projet_gl
+
  
Si vous utilisiez déjà une clé pour vous connecter à votre propre compte Ensimag, vous pouvez au choix :
+
* Dans le « Tools », choisir « Plugins »
* utiliser <code>ssh-agent</code> et <code>ssh-add</code> sur cette clé. SSH va essayer toutes les clés actives dans l'agent avant d'essayer id_projet_gl.
+
* Ajouter plusieurs lignes <code>IdentityFile</code> derrière <code>Host depots.ensimag.fr</code>, ssh va les essayer en séquence. Par exemple, si votre clé habituelle est <code>id_rsa</code> :
+
  
Host depots.ensimag.fr
+
* Onglet « Downloaded plugins », choisir « Add plugin », puis bouton « install » et se laisser guider.
IdentityFile ~/.ssh/id_projet_gl
+
IdentityFile ~/.ssh/id_rsa
+
  
En dernier recours, demander de l'aide à votre enseignant ou à Matthieu.Moy@imag.fr.
+
= Installation de l'environnement du projet =
  
Pour plus d'information, lire l'article du wiki sur les [[Clés SSH]].
+
== Installation de l'arborescence globale du projet (ima) ==
  
== Installation de l'arborescence globale du projet ==
+
Récupérez l'arborescence GL/global/ de l'Ensimag sur votre machine. Dans l'exemple, on installe l'arborescence dans ~/ensimag, mais vous pouvez bien sûr adapter (dans ce cas, il faudra remplacer dans les commandes ultérieures $HOME/ensimag par le répertoire choisie) :
 
+
Récupérez l'arborescence GL/global/ de l'Ensimag sur votre machine. Dans l'exemple, on installe l'arborescence dans ~/ensimag, mais vous pouvez bien sûr adapter :
+
  
 
  laptop:~$ mkdir -p ensimag/GL; cd ensimag/GL
 
  laptop:~$ mkdir -p ensimag/GL; cd ensimag/GL
 +
 +
Puis, pour les 2A:
 +
 
  laptop:~/ensimag/GL$ git clone ssh://votrelogin@pcserveur.ensimag.fr/matieres/4MMPGL/GL/global/ global
 
  laptop:~/ensimag/GL$ git clone ssh://votrelogin@pcserveur.ensimag.fr/matieres/4MMPGL/GL/global/ global
 +
 +
Ou, pour les apprentis 1A:
 +
 +
laptop:~/ensimag/GL$ git clone ssh://votrelogin@pcserveur.ensimag.fr/matieres/3MM1PGL/global/ global
 +
 
Vérifiez que la commande <code>ima</code> fonctionne :
 
Vérifiez que la commande <code>ima</code> fonctionne :
  
 
  laptop:~/ensimag/GL$ ./global/bin/ima -v
 
  laptop:~/ensimag/GL$ ./global/bin/ima -v
  
Si ce n'est pas le cas, vous pouvez recompiler ima sur votre machine comme ceci (la version fournie devrait fonctionner sur architecture Intel 32 ou 64 bits, sous Linux ou Mac OS X) :
+
Si ce n'est pas le cas, vous pouvez recompiler ima sur votre machine comme ceci (la version fournie devrait fonctionner sur architecture 64 bits sous Linux) :
  
 
  laptop:~/ensimag/GL$ cd global/sources
 
  laptop:~/ensimag/GL$ cd global/sources
 
  laptop:~/ensimag/GL/global/sources$ make
 
  laptop:~/ensimag/GL/global/sources$ make
 +
 +
Si après avoir exéctuer make, la commande "gnatmake" n'est pas reconnue, c'est que vous devez récupérer la package ADA pour GCC (gcc-ada ou gnat selon la distribution Linux).
 +
'''ATTENTION (mai 2020): il semble que les Makefiles d'ima ne sont pas robustes aux caractères spéciaux (espaces, apostrophes, accents, etc) dans les noms de répertoire.'''
 +
En attendant, un patch des enseignants, il vaut mieux éviter ce type de caractères dans les noms de répertoire (utiliser juste un mélange de lettres, chiffres, points, soulignés). 
  
 
La dernière commande devrait compiler aflex, ayacc (qui sont nécessaires pour compiler ima), et ima sur votre machine.
 
La dernière commande devrait compiler aflex, ayacc (qui sont nécessaires pour compiler ima), et ima sur votre machine.
Ligne 126 : Ligne 128 :
 
  $ which mvn  
 
  $ which mvn  
 
  /usr/bin/mvn
 
  /usr/bin/mvn
$ which java
+
 
/usr/bin/java
+
Vérifiez aussi que <code>mvn -version</code> utilise bien la version Java 1.8.
  
 
La commande <code>which ima</code> doit renvoyer quelque chose comme <code>$HOME/ensimag/GL/global/bin/ima</code> selon l'endroit où vous avez installé <code>ima</code>.
 
La commande <code>which ima</code> doit renvoyer quelque chose comme <code>$HOME/ensimag/GL/global/bin/ima</code> selon l'endroit où vous avez installé <code>ima</code>.
Ligne 133 : Ligne 135 :
 
== Création du répertoire Projet_GL par rapatriement depuis l'archive ==
 
== Création du répertoire Projet_GL par rapatriement depuis l'archive ==
  
Il faut évidemment que la clé de connexion SSH soit admise sur le compte depotglXX de l'équipe (cf. section [[#clessh]]). On fait (comme dans <code>[SeanceMachine]</code>) :
+
Pour les 2A: commande git clone (remplacer NN par le numéro d'équipe et GG par votre numéro de groupe) :
  
  $ cd
+
   $ git clone git@gitlab.ensimag.fr:gl2021/gGG/glNN Projet_GL
   $ git clone ssh://depotglXX@depots.ensimag.fr/~/git/ Projet_GL
+
 
 +
Pour les apprentis: (remplacer N par le numéro d'équipe entre 1 et 6)
 +
  $ git clone git@gitlab.ensimag.fr:glapp2021/glN Projet_GL
  
 
<div id="debug">
 
<div id="debug">
 +
 +
= Image Docker (expérimental)=
 +
 +
Si vous souhaitez vous retrouver dans un environnement identique à celui des PC de l'école, il est possible de télécharger l'image pour machine virtuelle depuis le site intranet de l'école. Attention : cette image est très lourde. Une autre solution consiste à utiliser Docker qui peut être vu comme une solution de virtualisation légère. Docker est disponible sous Linux (son environnnement de prédilection) mais également sous Windows et MacOsX. Vous trouverez [https://docs.docker.com/get-started/overview/ ici] une présentation des principes de cette approche.
 +
 +
== Installation de Docker ==
 +
 +
Les instructions principales d'installation sont disponibles [https://docs.docker.com/engine/install/ ici]
 +
 +
* sous Linux : la plupart des distributions proposent des packages standards. Une installation docker consiste en la mise en place d'un démon devant être lancé au démarrage ainsi que des outils clients en ligne de commande. Il est également nécessaire d'ajouter votre compte utilisateur comme membre du groupe créé par docker afin de pouvoir l'utiliser dans être root. Le [https://wiki.archlinux.org/index.php/Dockerwiki d'Arch Linux] est une source précieuse d'information, y compris pour les autres distributions.
 +
* sous Windows : cela dépend de la version que vous utilisez. Pour une version Windows home, les instructions sont [https://docs.docker.com/docker-for-windows/install/ ici]. Pour une version Windows pro ou Windows Education, les instructions sont [https://docs.docker.com/docker-for-windows/install/ ici]
 +
* sous MacOs : [https://docs.docker.com/docker-for-mac/install/ ici]
 +
 +
== Mise en place de l'image Docker ==
 +
 +
L'image Docker proposant un environnement minimal identique à celui disponible en salle peut être soit re-construite localement depuis votre machine personnelle, soit téléchargée directement sur le gitlab de l'école. Les instructions correspondantes pour ces deux possibilités sont dans le fichier README.md du répertoire docker à la racine de votre dépôt du projet.
 +
 +
Trois modes de fonctionnement nous semblent envisageables (nous sommes ouverts à toutes autres suggestions ou améliorations....)
 +
 +
=== Chaîne de compilation externe à l'IDE ===
 +
 +
L'image Docker proposée n'embarque pas en interne le répertoire projet (vous pouvez néanmoins le faire si vous le souhaitez) mais accède par montage au répertoire du projet présent sur votre machine sur votre OS hôte (Windows, MacOs, Linux). Vous pouvez donc éditer votre projet avec votre environnement de développement préféré installé sur votre machine et bénéficier des aides au développement qu'il apporte. Le lancement de la chaîne de compilation et des tests (mvn ...., ... pouvant être par exemple clean, compile, verify, install etc.) ou le lancement de tests manuels (decac ... etc.) se fera en ligne de commande depuis le shell lancé dans le container.
 +
 +
=== Couplage de la chaîne de compilation et de l'IDE ===
 +
 +
Afin de pouvoir compiler, naviguer en hypertexte des erreurs de compilation vers le code source etc, depuis l'IDE, il faut que celui gère le lancement et les sorties de cette chaîne de compilation. On peut envisager à priori trois configurations :
 +
* l'IDE est installé à l'intérieur du container : on se retrouve dans le cadre du développement sur une seule machine mais cette machine est distante (le container)
 +
* l'IDE est installé sur l'OS hôte mais pilote via ssh la compilation sur la machine distance (le container).
 +
* la solution hybride : l'IDE est partiellement sur l'OS hôte et partiellement sur la machine distance (le container).
 +
 +
 +
 +
=== IDE installé dans le container ===
 +
 +
Si vous souhaitez bénéficier d'un environnement de développement totalement intégré et lancer en particulier la compilation et les tests depuis votre IDE, vous pouvez installer cet IDE à l'intérieur du container (la version CentOS de cet IDE donc). L'IDE sera alors lancé depuis la ligne de commande du shell du container.
 +
 +
Exécuter votre IDE depuis votre container nécessite que votre OS hôte soit capable d'afficher les fenêtres X-Windows et que votre container soit paramétré pour envoyer les instructions X-Windows vers votre OS hôte.
 +
 +
==== Serveur X-Window ====
 +
 +
Sous Windows, vous pouvez installer le serveur X-Windows open-source VcXsrv :
 +
[https://sourceforge.net/projects/vcxsrv/]
 +
 +
Sous MacOs, vous pouvez utiliser par exemple le serveur X-windows open-source XQuartz :
 +
[https://www.xquartz.org/]
 +
 +
Sous Windows et MacOS, il faudra également autoriser l'affichage de fenêtres venant d'une machine extérieur (le container docker est vu comme une autre machine). C'est l'équivalent du "xhost +" sous Linux.
 +
 +
Sous Linux, X-Windows étant le système graphique par défaut, il n'y a pas d’installation supplémentaire à prévoir. Le "xhost +" n'est pas nécessaire également, le container étant lancé en "re-mappant" le répertoire contenant les socket du serveur X de l'hôte sur le répertoire équivalent du container. Le container voit le serveur X de l'hôte comme si c'était son propre serveur.
 +
 +
==== Envoi des instructions X-Windows vers l'OS hôte ====
 +
 +
===== Linux =====
 +
 +
Comme cela a été expliqué dans la section précédente, le principe sous Linux consiste à "mapper" le serveur X de l'hôte dans le container (en montant le répertoire /tmp/.X11-unix de l'hôte sur le répertoire /tmp/.X11-unix du container). Il faut ensuite positionner la variable d'environnement $DISPLAY à la même valeur que celle utilisée dans votre session. La création du container devient donc (dans le cas du téléchargement de l'image) :
 +
 +
  $ docker create --interactive --tty -v /home/reignier/Documents/Cours/ENSIMAG/Compil:/home/gl/Compil  -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY --name projetgl projetgl
 +
 +
Sous MacOS et Windows, le principe est de considérer le container l'OS hôte comme deux systèmes distincts et de positionner la variable DISPLAY à l'adresse IP à laquelle le container voit le système hôte.
 +
 +
===== MacOS =====
 +
 +
Pas testé faute de machine à disposition
 +
 +
===== Windows =====
 +
 +
Pas testé faute de machine à disposition
 +
 +
=== IDE installé dans l'OS hôte ===
 +
 +
Cette solution nécessite deux points différents : ajouter un accès ssh au container et choisir un IDE capable de piloter par ssh une chaîne de compilation.
 +
 +
==== Accès ssh au container ====
 +
 +
L'image proposée par défaut dans le répertoire Docker (pour reconstruction ou récupération sur gitlab) offre un accès bash mais pas ssh. Vous trouverez également dans ce répertoire le fichier fichier Dockerfile.ssh permettant de reconstruire une image avec accès ssh. Au delà de l'IDE, ce scénario permet via ssh d'avoir un container où vous pouvez vous connecter par ssh depuis plusieurs terminaux différents et donc bénéficier de plusieurs accès simultané au même container). Pour utiliser ce fichier pour la construction, il faut utiliser l'option "-f".
 +
 +
* Reconstruction de l'image :
 +
 +
$ docker build -f Dockerfile.ssh -t projetgl_ssh .
 +
 +
* Création du container (il n'y a pas plus paramètres liés à l'interaction, ce container ne faisant que démarrer un serveur ssh et pas un shell interactif) :
 +
 +
$ docker create -v <your GL home dir absolute path>:/home/gl/Projet_GL --name projetgl_ssh projetgl_ssh
 +
 +
* Lancement
 +
 +
$ docker start projetgl_ssh
 +
 +
* Arrêt
 +
 +
$ docker stop projetgl_ssh
 +
 +
* Détermination de l'adresse IP du container pour se connecter en ssh :
 +
 +
<nowiki>$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' projetgl_ssh</nowiki>
 +
 +
projetgl_ssh est le nom du container. Pour voir l'ensemble des containers présents sur votre machine (lancés ou arrêtés) :
 +
 +
$ docker ps -a
 +
 +
* Connexion :
 +
 +
$ ssh gl@<ip address>
 +
 +
Netbeans permet de piloter par ssh le compilateur java (utilisé par exemple pour le développement sur raspberry depuis son PC) mais à ma connaissance pas Maven. Eclipse est un candidat potentiel avec en particulier le plugin Remote System Explorer (pas testé... merci de nous prévenir si vous le testez et pour quel résultat).
 +
 +
=== Installation hybride ===
 +
 +
 +
Les environnements de développement "classiques" comme Netbeans, Eclipse ou Idea sont des environnement monolithiques s'installant donc naturellement sur l'OS hôte ou dans le container. Il existe également des environnements reposant nativement sur une architecture client - serveur même si cela n'est pas apparent en tant qu'utilisateur. C'est le cas en particulier de [https://code.visualstudio.com/ Visual Studio Code] qui est un projet opensource de Microsoft disponible sur Windows, Linux et MacOS. Cette architecture permet en particulier plus facilement de déployer une partie serveur sur le container et le client sur l'OS hôte. Cette approche est expliquée sur le site [https://code.visualstudio.com/docs/remote/containers] et illustrée par le schéma d'architecture présent sur cette page.
 +
 +
Pour mettre en oeuvre cette approche, il faut dans un premier temps installer le plugin Docker fournit par Microsoft au sein de votre Visual Studio Code ([https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker]). Le lien entre Code et le container est ensuite décrit par un fichier .devcontainer.json qui doit se trouver dans le répertoire où vous lancez l'éditeur. Pour des raisons de facilitée, nous vous en fournissons un dans le répertoire docker de votre projet. C'est donc depuis ce répertoire que vous devez lancer Visual Studio Code si vous voulez utiliser cette solution. Le contenu de ce fichier est le suivant :
 +
<nowiki>
 +
{
 +
    "image" : "gitlab.ensimag.fr:5050/reigniep/dockergl",
 +
    "extensions": [
 +
"ms-azuretools.vscode-docker",
 +
"redhat.java",
 +
"VisualStudioExptTeam.vscodeintellicode",
 +
"vscjava.vscode-java-debug",
 +
"vscjava.vscode-java-dependency",
 +
"vscjava.vscode-java-pack",
 +
"vscjava.vscode-java-test",
 +
"vscjava.vscode-maven",
 +
"mike-lischke.vscode-antlr4"
 +
],
 +
    "workspaceMount": [
 +
"source=${localWorkspaceFolder}/..,target=/home/gl/Projet_GL,type=bind,consistency=cached"
 +
    ],
 +
    "workspaceFolder" : "/home/gl/Projet_GL"
 +
}
 +
</nowiki>
 +
 +
Cette configuration spécifie où Code doit télécharger l'image Docker si elle n'est pas présente sur votre système, quels plugins y ajouter (complétion java, antlr, etc.) et quelle configuration pour la création du container (montage des répertoires pour vous retrouver en particulier à la racine de votre projet). Il n'est donc pas nécessaire dans ce cadre de réaliser les différentes opérations docker de construction / pull, de création de container etc. Le lancement de Code depuis le répertoire docker réalisera tout ceci automatiquement. A la première ouverture, un popup en bas à droite doit vous proposer "Reopen in container" qu'il faudra sélectionner pour que Code utilise le fichier .devcontainer.json et se déploie dans le container.
 +
 +
Remarque : lorsque Code est connecté au container, le menu Terminal -> New Terminal permet d'ouvrir un nouveau shell à l'intérieur du container
  
 
= Problèmes et solutions =
 
= Problèmes et solutions =

Version actuelle en date du 4 janvier 2021 à 22:15

Cette page a pour but de vous aider à installer un environnement de développement, sous Linux, pour le Projet GL de l'Ensimag, 2ème année. Le projet devrait marcher sans trop d'effort sous Mac OS X (n'hésitez pas à remonter les problèmes que vous rencontrez à vos enseignants et/ou à mettre à jour cette page). Faire marcher le projet sous Windows serait bien plus compliqué en revanche (le projet utilise des scripts shell en plus de Java, ils marcheraient peut-être avec Mingw), il est sans doute plus simple d'installer Linux que de faire le portage.

Pour le projet « Projet GL Apprentissage », les instructions s'appliquent en adaptant l'arborescence globale : /matieres/4MMPGL/GL/global en 2A étudiant, /matieres/3MM1PGL/global en 1A apprentissage.

Installation des outils (Java, Git, ...)

Nous allons tout d'abord installer les outils nécessaires au projet. Si ces outils sont déjà installés sur votre machine, vous n'avez rien à faire.

Sous Mac OS X : Outils pour développeurs Apple

Si vous travaillez sous Mac pensez à installer les outils pour développeur Apple, soit en les téléchargeant soit à partir du DVD d'installation de Mac OS X.

Il faut notamment modifier le fichier pom.xml comme indiqué sur cette page Questions fréquentes avec Maven pour le projet GL#tools-jar, afin de faire pointer correctement maven vers le fichier tools.jar.

Quelques conseils spécifiques pour OS X sont disponibles sur la page Projet GL sous Mac OS X .

Installation de Java

Une installation de Java quelconque récente (au delà de java 7) fera l'affaire. la version installée actuellement en salle sur les PC est la 14

1. Vérifiez la version java utilisée actuellement sur votre machine avec: javac -version

2. Si java 14 n'est pas installé sur votre machine: selon la distribution, un apt-get install openjdk-14-jdk ou un yum install openjdk-14-jdk devrait installer tout cela. Sinon, on peut télécharger Java sur le site d'OpenJDK ou bien sur le site d'Oracle.

3. Si plusieurs versions de Java sont installées sur votre machine, positionnez la variable d'environnement JAVA_HOME sur le JDK 14 dans votre .bash_rc avec une ligne comme: export JAVA_HOME=/usr/lib/jvm/java-14-openjdk-amd64 (en adaptant avec le nom du répertoire d'installation de JDK 1.8 sur votre machine, que vous pouvez trouver par exemple à l'aide de dpkg-query -L openjdk-14-jdk sous debian/ubuntu).
Positionner JAVA_HOME ne change pas la version de Java sur votre machine (java -version reste inchangé), ça change juste la version de Java utilisée dans maven (et netbeans).

4. Si la méthode du point 3 ne permet pas de faire fonctionner maven correctement, vous pouvez essayer sudo update-alternatives --config javac pour imposer le choix de java 14 à votre système (mais ça ne devrait pas être nécessaire).

Installation de Maven

Maven est disponible dans Debian et Ubuntu : apt-get install maven

Installer Maven manuellement est très facile : il suffit de télécharger une archive « Binary » depuis cette page http://maven.apache.org/download.cgi, d'extraire l'archive et de placer le répertoire bin/ au début de votre $PATH. Pour plus de détails, voir par exemple cette page si nécessaire.

Une autre option est d'utiliser le Maven distribué avec Netbeans (netbeans/java/maven/bin/mvn): dans ce cas, voir l'installation de netbeans ci-dessous.

Vérifiez que maven fonctionne avec Java version 1.8 en lançant mvn -version. Si ce n'est pas le cas, consultez le paragraphe Faire_le_Projet_GL_sur_une_machine_personnelle#Installation_de_Java ci-dessus.

Installation de Git

Votre distribution contient probablement Git, et il suffira probablement d'un apt-get install git-core gitk, yum install git, ...

Sous Mac téléchargez la dernière version de Git depuis https://git-scm.com/download/mac puis suivez les indications de l'utilitaire.

Installation de Netbeans (optionnelle)

Les versions packagées pour Ubuntu et Debian sont en général cassées (le gestionnaire de plugins ne marche pas). Il est fortement recommandé d'installer une version récente d'Apache Netbeans (version 12 par exemple).

Suivre les instructions de téléchargement et d'installation de netbeans depuis cette page : https://netbeans.apache.org/download/index.html

Pour plus de confort, sous Linux, n'hésitez pas à ajouter le chemin vers les binaires netbeans à votre PATH. Il suffit d'ajouter export export PATH="/chemin/vers/dossier/netbeans-12.0-bin/bin:$PATH"

Installation du plugin ANTLRWorks pour Netbeans (optionnelle, mais conseillée si votre IDE est netbeans)

Pour avoir la coloration syntaxique dans les fichiers .g4 (grammaires ANTLRv4), installez le plugin ANTLRWorks disponible au téléchargement ici : http://plugins.netbeans.org/plugin/73187/netbeans-antlr

  • Lancer netbeans
  • Dans le « Tools », choisir « Plugins »
  • Onglet « Downloaded plugins », choisir « Add plugin », puis bouton « install » et se laisser guider.

Installation de l'environnement du projet

Installation de l'arborescence globale du projet (ima)

Récupérez l'arborescence GL/global/ de l'Ensimag sur votre machine. Dans l'exemple, on installe l'arborescence dans ~/ensimag, mais vous pouvez bien sûr adapter (dans ce cas, il faudra remplacer dans les commandes ultérieures $HOME/ensimag par le répertoire choisie) :

laptop:~$ mkdir -p ensimag/GL; cd ensimag/GL

Puis, pour les 2A:

laptop:~/ensimag/GL$ git clone ssh://votrelogin@pcserveur.ensimag.fr/matieres/4MMPGL/GL/global/ global

Ou, pour les apprentis 1A:

laptop:~/ensimag/GL$ git clone ssh://votrelogin@pcserveur.ensimag.fr/matieres/3MM1PGL/global/ global

Vérifiez que la commande ima fonctionne :

laptop:~/ensimag/GL$ ./global/bin/ima -v

Si ce n'est pas le cas, vous pouvez recompiler ima sur votre machine comme ceci (la version fournie devrait fonctionner sur architecture 64 bits sous Linux) :

laptop:~/ensimag/GL$ cd global/sources
laptop:~/ensimag/GL/global/sources$ make

Si après avoir exéctuer make, la commande "gnatmake" n'est pas reconnue, c'est que vous devez récupérer la package ADA pour GCC (gcc-ada ou gnat selon la distribution Linux). ATTENTION (mai 2020): il semble que les Makefiles d'ima ne sont pas robustes aux caractères spéciaux (espaces, apostrophes, accents, etc) dans les noms de répertoire. En attendant, un patch des enseignants, il vaut mieux éviter ce type de caractères dans les noms de répertoire (utiliser juste un mélange de lettres, chiffres, points, soulignés).

La dernière commande devrait compiler aflex, ayacc (qui sont nécessaires pour compiler ima), et ima sur votre machine.

Si des bugs sont trouvés et corrigés dans l'arborescence globale en cours de projet, il faudra simplement faire :

laptop:~$ cd ~/ensimag/GL/global
laptop:~/ensimag/GL/global$ git pull

pour récupérer ces corrections (et si vous aviez eu besoin de recompiler ima, vous devrez recompiler à nouveau)

Configuration de votre compte

Dans le fichier d'initialisation de votre shell :

  • si vous ne savez pas comment il s'appelle ou ce qu'il est, il s'agit sans doute de ~/.bashrc
  • sous Mac il s'agit de ~/.bash_profile


  • Modifier la variable PATH (à la FIN du fichier .bashrc) :
export PATH=$HOME/ensimag/GL/global/bin:$PATH

Vous aurez bien sûr besoin d'appliquer les autre consignes données dans [SeanceMachine] pour avoir les répertoires de votre projet dans le $PATH. $HOME/ensimag/GL/global/bin remplace simplement ~moy/GL/global/bin/.

Une fois ces opérations effectuées, il faut demander à votre shell de relire le fichier .bashrc (sinon, les modifications ne seront effectives qu'au prochain démarrage du shell) :

 $ . ~/.bashrc
  • Récupérer le ~/.gitconfig créé pendant la séance machine si vous n'en avez pas déjà un sur votre machine. Par exemple :
 rsync -v pcserveur.ensimag.fr:.gitconfig ~/.gitconfig

Il est recommandé de refaire les vérifications indiquées dans [SeanceMachine]

Les résultats peuvent être légèrement différents : sur Debian, on obtient, par exemple :

$ which mvn 
/usr/bin/mvn

Vérifiez aussi que mvn -version utilise bien la version Java 1.8.

La commande which ima doit renvoyer quelque chose comme $HOME/ensimag/GL/global/bin/ima selon l'endroit où vous avez installé ima.

Création du répertoire Projet_GL par rapatriement depuis l'archive

Pour les 2A: commande git clone (remplacer NN par le numéro d'équipe et GG par votre numéro de groupe) :

 $ git clone git@gitlab.ensimag.fr:gl2021/gGG/glNN Projet_GL

Pour les apprentis: (remplacer N par le numéro d'équipe entre 1 et 6)

 $ git clone git@gitlab.ensimag.fr:glapp2021/glN Projet_GL

Image Docker (expérimental)

Si vous souhaitez vous retrouver dans un environnement identique à celui des PC de l'école, il est possible de télécharger l'image pour machine virtuelle depuis le site intranet de l'école. Attention : cette image est très lourde. Une autre solution consiste à utiliser Docker qui peut être vu comme une solution de virtualisation légère. Docker est disponible sous Linux (son environnnement de prédilection) mais également sous Windows et MacOsX. Vous trouverez ici une présentation des principes de cette approche.

Installation de Docker

Les instructions principales d'installation sont disponibles ici

  • sous Linux : la plupart des distributions proposent des packages standards. Une installation docker consiste en la mise en place d'un démon devant être lancé au démarrage ainsi que des outils clients en ligne de commande. Il est également nécessaire d'ajouter votre compte utilisateur comme membre du groupe créé par docker afin de pouvoir l'utiliser dans être root. Le d'Arch Linux est une source précieuse d'information, y compris pour les autres distributions.
  • sous Windows : cela dépend de la version que vous utilisez. Pour une version Windows home, les instructions sont ici. Pour une version Windows pro ou Windows Education, les instructions sont ici
  • sous MacOs : ici

Mise en place de l'image Docker

L'image Docker proposant un environnement minimal identique à celui disponible en salle peut être soit re-construite localement depuis votre machine personnelle, soit téléchargée directement sur le gitlab de l'école. Les instructions correspondantes pour ces deux possibilités sont dans le fichier README.md du répertoire docker à la racine de votre dépôt du projet.

Trois modes de fonctionnement nous semblent envisageables (nous sommes ouverts à toutes autres suggestions ou améliorations....)

Chaîne de compilation externe à l'IDE

L'image Docker proposée n'embarque pas en interne le répertoire projet (vous pouvez néanmoins le faire si vous le souhaitez) mais accède par montage au répertoire du projet présent sur votre machine sur votre OS hôte (Windows, MacOs, Linux). Vous pouvez donc éditer votre projet avec votre environnement de développement préféré installé sur votre machine et bénéficier des aides au développement qu'il apporte. Le lancement de la chaîne de compilation et des tests (mvn ...., ... pouvant être par exemple clean, compile, verify, install etc.) ou le lancement de tests manuels (decac ... etc.) se fera en ligne de commande depuis le shell lancé dans le container.

Couplage de la chaîne de compilation et de l'IDE

Afin de pouvoir compiler, naviguer en hypertexte des erreurs de compilation vers le code source etc, depuis l'IDE, il faut que celui gère le lancement et les sorties de cette chaîne de compilation. On peut envisager à priori trois configurations :

  • l'IDE est installé à l'intérieur du container : on se retrouve dans le cadre du développement sur une seule machine mais cette machine est distante (le container)
  • l'IDE est installé sur l'OS hôte mais pilote via ssh la compilation sur la machine distance (le container).
  • la solution hybride : l'IDE est partiellement sur l'OS hôte et partiellement sur la machine distance (le container).


IDE installé dans le container

Si vous souhaitez bénéficier d'un environnement de développement totalement intégré et lancer en particulier la compilation et les tests depuis votre IDE, vous pouvez installer cet IDE à l'intérieur du container (la version CentOS de cet IDE donc). L'IDE sera alors lancé depuis la ligne de commande du shell du container.

Exécuter votre IDE depuis votre container nécessite que votre OS hôte soit capable d'afficher les fenêtres X-Windows et que votre container soit paramétré pour envoyer les instructions X-Windows vers votre OS hôte.

Serveur X-Window

Sous Windows, vous pouvez installer le serveur X-Windows open-source VcXsrv : [1]

Sous MacOs, vous pouvez utiliser par exemple le serveur X-windows open-source XQuartz : [2]

Sous Windows et MacOS, il faudra également autoriser l'affichage de fenêtres venant d'une machine extérieur (le container docker est vu comme une autre machine). C'est l'équivalent du "xhost +" sous Linux.

Sous Linux, X-Windows étant le système graphique par défaut, il n'y a pas d’installation supplémentaire à prévoir. Le "xhost +" n'est pas nécessaire également, le container étant lancé en "re-mappant" le répertoire contenant les socket du serveur X de l'hôte sur le répertoire équivalent du container. Le container voit le serveur X de l'hôte comme si c'était son propre serveur.

Envoi des instructions X-Windows vers l'OS hôte

Linux

Comme cela a été expliqué dans la section précédente, le principe sous Linux consiste à "mapper" le serveur X de l'hôte dans le container (en montant le répertoire /tmp/.X11-unix de l'hôte sur le répertoire /tmp/.X11-unix du container). Il faut ensuite positionner la variable d'environnement $DISPLAY à la même valeur que celle utilisée dans votre session. La création du container devient donc (dans le cas du téléchargement de l'image) :

 $ docker create --interactive --tty -v /home/reignier/Documents/Cours/ENSIMAG/Compil:/home/gl/Compil   -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY --name projetgl projetgl

Sous MacOS et Windows, le principe est de considérer le container l'OS hôte comme deux systèmes distincts et de positionner la variable DISPLAY à l'adresse IP à laquelle le container voit le système hôte.

MacOS

Pas testé faute de machine à disposition

Windows

Pas testé faute de machine à disposition

IDE installé dans l'OS hôte

Cette solution nécessite deux points différents : ajouter un accès ssh au container et choisir un IDE capable de piloter par ssh une chaîne de compilation.

Accès ssh au container

L'image proposée par défaut dans le répertoire Docker (pour reconstruction ou récupération sur gitlab) offre un accès bash mais pas ssh. Vous trouverez également dans ce répertoire le fichier fichier Dockerfile.ssh permettant de reconstruire une image avec accès ssh. Au delà de l'IDE, ce scénario permet via ssh d'avoir un container où vous pouvez vous connecter par ssh depuis plusieurs terminaux différents et donc bénéficier de plusieurs accès simultané au même container). Pour utiliser ce fichier pour la construction, il faut utiliser l'option "-f".

  • Reconstruction de l'image :
$ docker build -f Dockerfile.ssh -t projetgl_ssh .
  • Création du container (il n'y a pas plus paramètres liés à l'interaction, ce container ne faisant que démarrer un serveur ssh et pas un shell interactif) :
$ docker create -v <your GL home dir absolute path>:/home/gl/Projet_GL --name projetgl_ssh projetgl_ssh
  • Lancement
$ docker start projetgl_ssh
  • Arrêt
$ docker stop projetgl_ssh

  • Détermination de l'adresse IP du container pour se connecter en ssh :
$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' projetgl_ssh

projetgl_ssh est le nom du container. Pour voir l'ensemble des containers présents sur votre machine (lancés ou arrêtés) :

$ docker ps -a
  • Connexion :
$ ssh gl@<ip address>

Netbeans permet de piloter par ssh le compilateur java (utilisé par exemple pour le développement sur raspberry depuis son PC) mais à ma connaissance pas Maven. Eclipse est un candidat potentiel avec en particulier le plugin Remote System Explorer (pas testé... merci de nous prévenir si vous le testez et pour quel résultat).

Installation hybride

Les environnements de développement "classiques" comme Netbeans, Eclipse ou Idea sont des environnement monolithiques s'installant donc naturellement sur l'OS hôte ou dans le container. Il existe également des environnements reposant nativement sur une architecture client - serveur même si cela n'est pas apparent en tant qu'utilisateur. C'est le cas en particulier de Visual Studio Code qui est un projet opensource de Microsoft disponible sur Windows, Linux et MacOS. Cette architecture permet en particulier plus facilement de déployer une partie serveur sur le container et le client sur l'OS hôte. Cette approche est expliquée sur le site [3] et illustrée par le schéma d'architecture présent sur cette page.

Pour mettre en oeuvre cette approche, il faut dans un premier temps installer le plugin Docker fournit par Microsoft au sein de votre Visual Studio Code ([4]). Le lien entre Code et le container est ensuite décrit par un fichier .devcontainer.json qui doit se trouver dans le répertoire où vous lancez l'éditeur. Pour des raisons de facilitée, nous vous en fournissons un dans le répertoire docker de votre projet. C'est donc depuis ce répertoire que vous devez lancer Visual Studio Code si vous voulez utiliser cette solution. Le contenu de ce fichier est le suivant :

 {
     "image" : "gitlab.ensimag.fr:5050/reigniep/dockergl",
     "extensions": [
	 	"ms-azuretools.vscode-docker",
		"redhat.java",
		"VisualStudioExptTeam.vscodeintellicode",
		"vscjava.vscode-java-debug",
		"vscjava.vscode-java-dependency",
		"vscjava.vscode-java-pack",
		"vscjava.vscode-java-test",
		"vscjava.vscode-maven",
		"mike-lischke.vscode-antlr4"
	],
    "workspaceMount": [
	"source=${localWorkspaceFolder}/..,target=/home/gl/Projet_GL,type=bind,consistency=cached"
    ],
    "workspaceFolder" : "/home/gl/Projet_GL"
 }

Cette configuration spécifie où Code doit télécharger l'image Docker si elle n'est pas présente sur votre système, quels plugins y ajouter (complétion java, antlr, etc.) et quelle configuration pour la création du container (montage des répertoires pour vous retrouver en particulier à la racine de votre projet). Il n'est donc pas nécessaire dans ce cadre de réaliser les différentes opérations docker de construction / pull, de création de container etc. Le lancement de Code depuis le répertoire docker réalisera tout ceci automatiquement. A la première ouverture, un popup en bas à droite doit vous proposer "Reopen in container" qu'il faudra sélectionner pour que Code utilise le fichier .devcontainer.json et se déploie dans le container.

Remarque : lorsque Code est connecté au container, le menu Terminal -> New Terminal permet d'ouvrir un nouveau shell à l'intérieur du container

Problèmes et solutions

« S'il n'y a pas de solution, c'est qu'il n'y a pas de problème »

Historique

Fichier initial écrit par Matthieu MOY en janvier 2001 (ouch, ça fait un coup de vieux de relire ça maintenant ;-) ), puis amende par Xavier NICOLLIN, destiné à aider les étudiants à installer un environnement de développement chez eux sous Linux pour le projet GL.

Nous (les enseignants) ne pouvons pas tester toutes les distributions et configurations, mais les corrections pour votre distribution préférée sont les bienvenues !

Modification pour CygWin par Laurent Belcour (2008)

Modification pour Mac OS X par Amaury Balliet (2010)

La suite dans l'historique du Wiki...