JMRI: Construction avec IntelliJ IDEA

IntelliJ IDEA Community Edition (disponible depuis www.jetbrains.com/idea/) est une grande plateforme pour travailler avec JMRI et Java sur OS X, Windows et *nix.

• Installation
• Obtenir Git
• La fenêtre Projet
• Pousser les changements
• Plus

Les développeurs JMRI utilisent Git pour le contrôle de source. Le contrôle de source utilisant Git est inclus comme un élément du téléchargement IntelliJ IDEA. Plus d'information sur l'obtention de la source JMRI voir JMRI: Obtention du Code.

Ces instructions sont développées et testées par l'utilisation de IntelliJ IDEA 15 et 16 Community Edition (libre).

Installation de IntelliJ IDEA

Préparations

1. Allez à GitHub.com et créer un compte.
2. sur le site web GitHub, allez sur le référentielI JMRI/JMRI et "Fork" le référentiel JMRI sur votre propre copie. Pour faire ceci, connectez-vous à votre compte sur GitHub.com et placez-vous sur le répertoire JMRI https://github.com/JMRI/JMRI. Dans le coin en haut à droite de la page, vous trouverezun bouton libellé "Fork". Pressez le bouton "Fork" pour créer votre propre répertoire de la source JMRI. ( Voir Obtenir le Code ).

Après le téléchargement et l'exécution de l'installateur pour votre OS, configurez l'application IntelliJ comme suit:

Définir vmoptions

Sur OS X

• Ouvrir IntelliJ
• Depuis le menu Help, selectionnez "Edit Custom VM Options":
  
• Dans la boite de dialogue, répondez "Yes" pour créer une copie du fichier vmoptions de l'application:
  
• Ajoutez la ligne "-Didea.native2ascii.lowercase=true" au contenu de ce fichier et sélectionnez Save All depuis le menu File:
  
• IntelliJ 2016 est maintenant prêt à être utilisé pour le développement de JMRI. Le fichier vmoptions est stocké dans˜/Users/Preferences/IdeaIC2016.1/
  Mais dans la version 15, IntelliJ sur OS X ne nommait pas correctement ce fichier vmoptions ( read more).
  Pour corriger ceci, fermez IntelliJ 15 et dans le localisateur allez au dossier ˜/Library/Preferences/IdeaIC15/.
  Renommez le nouveau fichier créé idea64.vmoptions en idea.vmoptions ( enlevant efficacement la partie"64" ).

Sur Windows et *nix

• Depuis le menu d'Aide, sélectionnez "Edit Custom VM Options".
• Ajoutez la ligne "-Didea.native2ascii.lowercase=true" au contenu de ce fichier et sélectionnez Save All depuis le menu File.
  Il sera sauvé à son emplacement sous le répertoire utilisateur. C'est $HOME/.IdeaICXX/idea$BITS.vmoptions pour *nix et %USERPROFILE%\.IdeaICXX\idea%BITS%.exe.vmoptions pour Windows (XX = le numéro de version, BITS = the chip version installed).

Si l'environnement de variable IDEA_VM_OPTIONS est défini, ou un fichier *.vmoptions existe, alors ce fichier est utilisé au lieu du fichier localisé dans le dossier d'installationin de IntelliJ IDEA.

Plus d'information sur la définitions de ces importantes vmoptions est disponible sur le site web Idea.
Note: Si vous avez un doute sur comment définir ceci au niveau du projet au lieu de bricoler avec les paramètres locaux de l'application, SVP contactez les utilisateurs JMRI group.

Définir les Préférences

Démarrer IntelliJ et choisir "Preferences" depuis le menu application (OS X) ou le menu Edit (Win).

1. Depuis l'Éditeur ->onglet File Encodings, cochez "Transparent native-to-ascii conversion":
   
2. Depuis le Contrôle de Version -> onglet GitHub, entrez "github.com" comme Host et entrez vos Identifiants:
   
3. Depuis le Build, Execution, Deployment -> onglet Java Compiler, sélectionnez "1.8" comme la Project bytecode version:
   
4. Cliquez OK pour cloturer les Preferences.

Obtention de la source JMRI en utilisant Git

Pour obtenir le code source depuis GitHub dans IntelliJ, suivre ces étapes:

1. Ouvrir IntelliJ.
2. Depuis la barre de menu principale sélectionnez File -> New -> Project from Version Control -> GitHub
   
3. Si vous êtes invité, entrez vos nom utilisateur et Mot de Passe pour GitHub dans le champ authentification et cliquez "Login":
   
4. Le volet duplication Repository doit apparaître maintenant. Sélectionnez un URL de Répertoire Gitdepuis votre compte et pointez vers votre dossier répertoire local comme "Répertoire Parent":
   
   Optionnellement "Test" en haut à droite pour vérifier votre connexion:
   
5. Cliquez "Clone" et suivez la progression dans l'indicateur en bas de la fenêtre Project:
   
6. Dans le volet qui s'ouvre après que le téléchargement soit terminé, vérifiez l'emplacement sur le disque,
   confirmez le nom du projet ( comme l'original ex: "JMRI" ) et cliquez "Next":
   
7. Sélectionnez "Create project from existing sources" et cliquez encore "Next":
   
8. Cliquez "Mark all" et puis "Finish":
   

Ceci ajoutera JMRI à la fenêtre IntelliJ Project.

La fenêtre Project

Après que la duplication est terminée, la fenêtre IntelliJ Project devrait ressembler à ceci ( exemple OS X ):

Le long des bords de la fenêtre, il y a plusieurs groupes d'outils, les plus souvent utilisés sont les suivants:

1. l'onglet Project sur la gauche
2. le répertoire JMRI dans la moitié gauche
3. l'onglet Ant Build sur la droite et
4. l'onglet Version Control en bas.
5. le Git: master dans le bas à droite, montrant la Branche ("master") actuelle avec un menu pour changer pour une autre Branche.

Vous pouvez aussi accéder à ce panneau depuis menu....Branches principales VCS -> Git -> Branches... menu ou clic-droit sur le dossie JMRI Project et sélection de Git -> Repository -> Branches...

Pour récupérer une autre Branche depuis le répertoire distant, sélectionnez son nom sous la rubrique «Branches à distance", clic-droit et sélectionnez "Checkout as new local branch":

quand l'information depuis la nouvelle Branche est téléchargée, le Centre des Messages confirmera:

Faire des Changements

Pour travailler sur le code JMRI, démarrez toujours une nouvelle Branche, ainsi votre "master" personnel restera intact.
Pour créer une nouvelle Branche dans IntelliJ, depuis le volet Git Branch, sélectionnez "New Branch":

Fournir un nom exemple: my-dialog-2 et cliquez OK.
Note: Le démarrage de votre nom de Branche avec une combinaison de deux lettres le fera se démarquer de la longue liste beaucoup mieux qu'un nom comme patch-1.

Construction et exécution de JMRI par l'utilisation de Ant

Nous recommandons qu'avant d'essayer de construitre et d'exécuter une des applications au sein d'IntelliJ, vous exécutiez Ant Build -> <cible par Défaut> en premier. Ceci créera les répertoires de travail nécessaires, chargera quelques ressources, icônes, et créra les fichiers Java nécessaires. Pour exécuter ant build.xml faire comme suit:

1. Ant nécessite un JDK (Java Development Kit) en ordre pour exécuter le fichier fournit "build.xml". Le téléchargement IntelliJ IDEA 15 vient avec un JDK, mais vous devez configurer ant pour utiliser le bon JDK.
   Pour vérifier que le JDK est configuré pour java 1.8, ouvrez l'onglet Ant Build [1], cliquez sur un fichier dans la liste Ant Build [3] et sélectionnez le bouton Properties [2] en haut à droite du volet:
   
2. Sélectionnez 1.8 comme "Run under JDK" si pas déjà défini
   
   Cliquez "OK" et sauvegarder votre JMRI Project (Cmd-S/Ctrl-S).
3. Sélectionnez le fichier <Default target> dans la liste Ant Build, clic-droit, et sélectionnez "Run", ou cliquez le bouton triangle vert "Run" en haut du volet. Ceci devrait démarrer le ant build. Suivez les messages dans le journal des Événements qui apparaissent à partir du bord inférieur de la fenêtre Project.

Si le ant build est réussi, vous pouvez lancer plusieurs applications JMRI depuis l'onglet Ant Build.

Construction et exécution de JMRI avec IntelliJ

Pour exécuter une application, soit

1. Depuis la barre de menu principal ouvrez le menu "Build" et sélectionnez un paquet JMRI comme panelpro ou
2. Ouvrez l'onglet Ant Build et depuis la list "Ant Build", cliquez-droit sur le paquet désirér exemple: decoderpro et sélectionnez "Run Target".

Note: Les deux premiers "JMRI" définis construiront les fichiers JHelpDev TOC & Index respectivement en Anglais et en Français. Passez votre souris sur eux et lire l'info-bulle pour apprendre qui est qui.

La Console Message Center listera toutes les étapes du processus de construction, après quoi une icône Java s'ouvrira avec l'application s'exécutant avec toutes vos nouvelles modifications ( Sauvegardées ).

Pousser ( Push ) les changement sur votre branche GitHub

La pratique standard pour obtenir que vos changements soient inclus dans le répertoire principal du code JMRI est de les "transmettre" ( commit ) vers votre répertoire local périodiquement et, quand c'est prêt à être entièrement publié, "Tirer" ( Push ) un jeu complet de "Transmissions" ( Commits ) vers votre propre répertoire distant sur GitHub, et finalement faire une "Requête Tirer" ( Pull Request ) pour les maintenanciers pour "Tirer" ( Pull ) vos changements dans le répertoire principal JMRI.
Quand le travail se fait sur plus d'un ordinateur ou différents IDEs, Committing et Pushing rendent vos nouveau changements disponibles sur les autres ordinateurs.
Voir la JMRI: Git FAQ "Définition d'un environnement Git pour des Développeurs JMRI" pour plus d'information.

Tirage ( Pulling )

Il est aussi de bonne practique de "Tirer" ( Pull ) tous les récents changement depuis le répertoire principal JMRI avant de réaliser vos transmissionss ( Commits ). Après un "tirer" "pull" votre espace de travail et éventuellement votre répertoire distant GitHub seront synchronisés avec le répertoire principale JMRI et vous verrez les travaux récents effectués par d'autres. Pour réaliser un "Tirage":

• Sélectionnez votre projet ex:. JMRI dans l'onglet Project, clic-droit et sélectionnez "Git" -> "Repository" -> "Pull..." depuis le menu contextuel:
  
• Vous pouvez avoir à confirmer l'origine de votre répertoire distant, dans notre cas "JMRI/JMRI":
  
• Sélectionnez la Branche distante appropriée à fusionner depuis la liste ( vous pouvez aussi "Tirer" une Branche supplémentaire pour commuter plus tard ), Cliquez "Pull" et répondez comment vous voulez combiner les nouvelles données dans le répertoire local existant :
  

Pousser ( Pushing )

Pousser ( "Push" ) vers votre Branche GitHub:

• Premièrement, transmettez (commit) vos changements dans votre répertoire local sur votre ordinateur.
  Pour transmettre un ensemble de changements, choisir "Save All" depuis le menu Edit, sélectionnez votre projet ex: JMRI dans l'onglet Project, clic-droitk et sélectionnez "Git" -> "Commit Directory..." depuis le menu contextuel:
  
• Dans le volet Commit Changes, entrez un Commit Message [1] décrivant vos changements/correctif ( la ligne 1 doit être utilisée comme titre court, ajoutez plus de détails depuis la ligne 2 ).
  Sélectionnez le fichier [2] que vous souhaitez livrer et désélectionnez ceux que vous ne voulez pas.
  Choisissez votre nom depuis la liste comme Auteur [3]:
  
• Cliquez le bouton "Commit" [4] pour ajouter vos modifications sauvegardées à la branche locale GitHub...
• Ou survolez le bouton Commit et choisir "Commit and Push..." pour continuer à "Pousser" cet ensemble de changements depuis votre répertoire locale vers votre répertoire à distance sur GitHub juste après la transmission (ainsi d'autres peuvent y accéder et l'étudier pour une inclusion dans JMRI).
  
• Dans le volet Push Commits, revoyez votre description et cliquez "Push".
• Pour "pousser" votre répertoire GitHub après une tranmission locale, sélectionnez juste "Push..." depuis le menu "VCS" Git:
  

Avant que vous puissiez "Pousser" vos changements dans GitHub pour la première fois, vous devez créer votre propre répertoire GitHub (que vous avez déjà fait à l'étape 1).

Trucs

Modifier les fichiers .properties

Soyez sûr que vous avez configuré IntelliJ pour convertir les caractères spéciaux utilisant les minuscules pour l'encodage des chaines, ainsi alors seulement vos modifications seront acceptées pour la fusion dans JMRI.

Pour modifier facilement les fichiers Resource Bundle .properties files, contenant les traductions en différentes langues, clic-droit sur un de ces dossiers (fermés) dans la liste des fichier Project et sélectionnez "Jump to Source":

Ceci ouvrir une fenêtre avec une liste de mots clés codés sur la gauche et une boite texte pour toutes les traductions à droite:

Réinitiliser HEAD

Quand lors de test de votre application vous concluez que vous aimeriez enlever le dernier couple de Commits, IntelliJ vous donne l'option de réinitialiser graphiquement votre HEAD.
Pour ce faire, ouvrez l'onglet "Version Control" -> "Log" en bas à gauche de la fenêtre Project pour voir un "Track Plan" de l'historique de votre Branche, tout le chemin de retour vers les différentes parties qui ont fait JMRI:

Cliquez sur n'importe quelle ligne pour voir les changements qui ont été "Transmis" à ce point dans le temps (listé à droite).
Pour réinitialiser votre répertoire ( HEAD ) de retour à un certain point, Clic-droit sur la ligne correspondante et sélectionnez Reset Current Branch to Here...".

Confirmez la manière que vous voulez pour sauvegarder ou jeter vos "transmissions" après ce point de dialogue :

Mot de Passe Principal

Pour stocker en toute sécurité votre login GitHub, vous pourriez être invité régulièrement à le déverrouiller:

Faire une Requête de tirage ( Pull Request )

Finalement, quand c'est prêt, soumettez un "Pull Request" au répertoire principale du code JMRI sur le site web GitHub ansi les maintenanciers de JMRI peuvent étudiés vos changements proposés et les fusionnés dans le répertoire maitre JMRI

Pour faire un PR à partir de IntelliJ IDEA, sélectionnez "Create Pull Request" depuis le menu "VCS" -> Git menu (c'es le dernier élément, supportéé par le plug in Git ).

Pour faire un PR ( Pull Request ) depuis le site web GitHub en dehord de IntelliJ - commencez en vous connectant au site web GitHub, sélectionnez votre répertoire & branch et cliquez sur le Bouton Pull Request. Pour plus d'information, voir la page Git Developer Help.

Aide supplémentaire

Voir la référence web IntelliJ IDEA et autres ressources pour plus d'information sur l'utilisation de cet IDE.