Info sur JMRI:
Outils de Développement
Structure
Techniques et Standards
Comment Faire
Infos Fonctionnelles
Contexte Infos

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.

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

Sur Windows et *nix

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":
    IntelliJ encoding prefs
  2. Depuis le Contrôle de Version -> onglet GitHub, entrez "github.com" comme Host et entrez vos Identifiants:
    IntelliJ build Git Login prefs
  3. Depuis le Build, Execution, Deployment -> onglet Java Compiler, sélectionnez "1.8" comme la Project bytecode version:
    IntelliJ build java SDK prefs
  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
    IntelliJ Git import pane
  3. Si vous êtes invité, entrez vos nom utilisateur et Mot de Passe pour GitHub dans le champ authentification et cliquez "Login":
    IntelliJ git 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":
    IntelliJ Git import pane3
    Optionnellement "Test" en haut à droite pour vérifier votre connexion:
    IntelliJ Git import pane3
  5. Cliquez "Clone" et suivez la progression dans l'indicateur en bas de la fenêtre Project:
    IntelliJ Git clone progress
  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":
    IntelliJ Git import pane1
  7. Sélectionnez "Create project from existing sources" et cliquez encore "Next":
    IntelliJ Git import pane2
  8. Cliquez "Mark all" et puis "Finish":
    IntelliJ Git import pane3

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 ):
IntelliJ main project window

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...
IntelliJ Project Git context menu

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":
IntelliJ checkout branch

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

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":
IntelliJ main project window
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:
    IntelliJ Ant menu
  2. Sélectionnez 1.8 comme "Run under JDK" si pas déjà défini
    IntelliJ Ant Settings
    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":

Pousser ( Pushing )

Pousser ( "Push" ) vers votre Branche GitHub:

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":
IntelliJ Bundle edit menu

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:
IntelliJ Bundle edit window

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:
IntelliJ VCS tab

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...".
IntelliJ History reset
Confirmez la manière que vous voulez pour sauvegarder ou jeter vos "transmissions" après ce point de dialogue :
IntelliJ Reset HEAD dialog

Mot de Passe Principal

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

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 ).
IntelliJ Git Create PR

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.