Documentation du Code
Outils de Développement
Structure du Code
Techniques et Standards
Comment Faire
Infos Fonctionnelles
Contexte Infos

Système d'Aide JMRI

Table des Matières Index
Glossaire FAQ *)
Des pages marqué *) sont en Anglais.

Donner à JMRI Faites un don à JMRI.org

JMRI: Construire avec NetBeans

Voir Aussi

Introduction

NetBeans 8 (disponible sur le site www.netbeans.org) est une plate-forme idéale pour travailler avec JMRI. Le code JMRI est configuré pour travailler avec NetBeans avec presque pas de configuration supplémentaire. (La description ci-dessous est exacte pour la version Windows de NetBeans 8. NetBeans est censé être identique sur toutes les plateformes, mais cela n'a pas été vérifié pour toutes).

NetBeans est un environnement très puissant de Développement Intégré (IDE), qui peut rendre le travail avec le code JMRI assez facile. Mais cela prend un peu de temps pour s'y habituer, et lire les tutoriels sur le site web depuis le site web NetBeans sera utile.

Obtention et Installation de NetBeans

Beaucoup de distribution Linux ont NetBeans disponible dans leur répertoire de logiciels - Chercher NetBeans dans votre logithèque (NetBeans 8.1 pour Ubuntu 16.04LTS).

Note Importante pour les utilisateurs de Windows

En raison d'une gestion différente des caractères de Fin de Ligne ( LF/CR LF ) entre Windows et les autres systèmes - nommément Unix et OS X ( voir Gestion des Fins de Lignes ) - il est de la plus haute importance que tous les utilisateurs Windows adoptent les réglages suivants pour leur environnement de développement. Ceci est absolument nécessaire pour que Git ppuisse suivre les modifications individuelles sur les fichiers que vous soumettez.

Si vous ne suivez pas ces instructions, vous aurez abîmer les terminaisons de ligne dans les fichiers que vous soumettez, qui à son tour va rendre leur historique de révision beaucoup plus difficile d'accès. Dans ces conditions, les fichiers ne serons pas acceptés lors d'un "pull request"

Comme première étape, comme JMRI a adopté LF comme convention de Fin de Ligne, il est nécessaire de régler le paramètre core.autocrlf à true (voir "Dealing with line endings" on GitHub Help)

Note Supplémentaire Importante pour les utilisateurs de NetBean sous Windows

En outre, si vous utilisez NetBeans sous Windows, vous installez le Plug-in "Change Line Endings on Save" avant d'utiliser Git via NetBeans.

Installez le plug-in pour être sûr que NetBeans maintienne proprement les caractères LF à la fin des lignes de code-source.

Actuellement le plug-in est déjà disponible dans la distribution NetBeans, donc allez Tools > Plugins > Available Plugins et là sélectionnez Change Line Endings on Save et ensuite Install.

Vous pouvez vérifier que le plug-in est proprement installé en allant à Tools > Plugins > Installed, où vous pouvez voir quelque chose comme ceci (les versions peuvent différées):

Une fois le plug-in installé et activé, il est nécessaire de le configurer pour le caractère de fin de ligne souhaité, via l'onglet Tools > Options > Editor > Line Endings.

Pour JMRI, nous voulons utiliser le caractère de fin de ligne du style Unix, LF.

Le plug-in peut être activé depuis un bouton sur la barre d'outil

Et le plug-in peut être desactivé depuis ce bouton

Quand un fichier est sauvegardé ( en supposant que le plug-in est configuré et est activé ) et ce fichier n'a pas les caractères de fin de ligne correspondant au type configuré par le plug-in, le message suivant s'affiche.

Quand "OK" est sélectionné, le plug-in actualise les fins de lignes pour la forme configurée et sauvegarde le fichier. Si "CANCEL" est sélectionné, le fichier sera sauvegarder SANS changement des fins de lignes.

Utilisation de NetBeans avec le répertoire Git du Code JMRI

Git fournit un répertoire de Code JMRI par l'utilisation de l'outil Git. Pour plus d'information sur la façon dont JMRI utilise Git, voir l'Aide JMRI dans Obtention du code via Git et FAQ Git.

une fois configuré, Netbeans fournit un support intégré pour l'utilisation de Git.

Pour plus d'information sur Git et NetBeans, voir la page d'aide NetBeans Git

Vérification du Code

Dans NetBeans, sous le menu "Team", sélectionnez Git, puis le Clone Repository. Entrez l'URL du répertoire https://github.com/JMRI/JMRI.git repository depuis la page JMRI GitHub dans le formulaire NetBeans "Repository URL". Nous vous recommendons également d'entrer vos identifiants GitHub, ainsi nous pourrons plus tard, vous attibuer vos contributions. Cliquze "Next". Soyez sûr que la case "master" est cochée pour récupérer la version principale du Code. Cliquez "Next", et ensuite cliquez"Finish".

La récupération de la copie du code peut prendre du temps ( notez la barre de progression un bas à droite).

Soumissions Locales

Quand vous utilisez Git, l'opération de" soumission" est localisée à votre ordinateur. Elle ne fait aucun changement dans le répertoire principal JMRI.

Vous êtes encouragés à soumettre souvent, ainsi vos changements seront stockés en toute sécurité loin de votre répertoire de travail et chaque petit changement est enregistré séparément.

Mise à jour du code depuis Git

De temps en temps, vous voudrez mettre à jour votre copie locale du code pour qu'elle corresponde au contenu de "HEAD" du répertoire principal JMRi Git. Le processus basique est de récupérer la version la plus récente depuis le répertoire principal JMRI faire toute fusion qui est nécessaire si vous avez apporté des modifications conflictuelles, et ensuite et mettre le résultat dans votre propre répertoire GitHub.

Pour le faire, utilisez le choix suivant du menu NetBeans: [Team] -> [Remote] -> [Pull from Upstream]. Demandez à NetBeans de récupérer depuis le "github" distant que vous avez défini ci-dessus.

Vous pouvez aussi actualiser un simple fichier ou le contenu d'un dossier, en clic droit sur un éléments de la fenêtre "Files", et ensuite en sélectionnant [Git] -> [Remote] -> [Pull from Upstream].

Création d'un Pull Request

Un "Pull Request" ( PR ) est un moyen aisé de rassembler tous vos changements, même s'ils couvrent plusieurs fichiers, dans quelque chose que vous pouvez ensuite soumettre pour inclusion dans le répertoire principal JMRI.

Premièrement, vous devez définir un compte GitHub et votre propre répertoire.

Ceci vous donne votre propre répertoire, avec lequel vous pouvez travailler librement

Ensuite, pousser les changements dans votre répertoire. ( Tout le monde peut pousser dans son répertoire personnel, mais tout le monde n'a pas la permission de modifier directement le répertoire principal JMRI; c'est pourquoi le "pull request" est nécessaire ). Pour le faire:

Vous pouvez répéter ceci aussi souvent que vous le voulez quand vous travaillez sur vos changements. À chaque fois, les changements les plus récents sont poussés et rendu disponibles.

Finalement, quand votre changement est prêt à être soumis, allez sur le site web de GitHub pour Remplir et soumettre un "Pull Request"

Éventuellement, quelqu'un regardera le "Pull Request" et décidera de fusionner. Parfois, ils vont demander des modifications supplémentaires. Dans ce cas vous pouvez actualiser le pull request en poussant juste vos derniers changements dans votre répertoire, d'où ils sont automatiquement prélevés.

Construction et Exécution de JMRI

Pour construire et exécuter DecoderPRo, tout ce que vous avez à faire est de sélectionner "Run Project" ( JMRI ) dans le menu Run, ou cliquer l'icòne Run dans la barre d'outil.

Si vous voulez exécuter le programme sous le débogueur NetBeans, premièrement configurez JMRI pour être le projet principal via [Run]->[Set Main Project]->[JMRI] puis sélectionnez "Debug Main Project" dans le menu "Debug".

Création d'un fichier Jar

La plupart du code dans une installation normale JMRI est dans un fichier appelé jmri.jar. Si vous voulez le remplacer par la version actualisée, vous avez besoin de créer un nouveau fichierjmri.jar à partir de votre code modifié.

Pour ce faire, ctrl-clic (ou un clic droit) sur le nom du projet "JMRI" dans la Fenêtre "Project". Cela ouvrira un menu contextuel, sur lequel vous trouverez "Make Jar File". Sélectionnez cela, et un nouveau fichier jmri.jar sera produit dans le répertoire principal du projet.

Sinon, à partir de la fenêtre "Files", cliquez-droit sur le fichier build.xml, et sélectionner "Run Target", puis "jar".

Faire un package de mise à disposition pour Windows en utilisant NSIS

Il est possible pour les utilisateurs de NetBeans de créer un package de mise à disposition sur la plate-forme Windows. Cela nécessite l'installation du Nullsoft Scriptable Install System (NSIS), qui peut être téléchargé à partir du site web du projet NSIS sur SourceForge.

Une fois que NSIS est installé sur l'ordinateur, il est nécessaire de créer un fichier appelé local.properties dans le même répertoire que le fichier build.xml de JMRI. Ce fichier n'est pas spécifiquement enregistré via SVN, aussi les chemins d'installation de l'outil de votre machine spécifique ne ne sont pas archivés dans SVN. Créez le fichier, et ajouter une définition de variable avec le chemin d'accès dans le répertoire qui comprend l'exécutable NSIS, tels que:

nsis.home = C:Program Files (x86)NSIS

ou

nsis.home=/opt/nsis/nsis-2.46/

Si vous installez un outil "spotbugs", vous définirez également spotbugs.home dans ce fichier. Vous pouvez également définir plusieurs autres machines spécifiques et les informations spécifiques utilisateur, comme décrit dans divers endroits du fichier build.xml.

Avec le paquet NSIS installé sur votre ordinateur, il est nécessaire de créer un fichier appelé local.properties dans le même répertoire que le fichier build.xml de JMRI. Ce fichier n'est spécifiquement pas vérifié via SVN afin que vos chemins d'installation d'outils spécifiques à la machine ne sont pas vérifié dans SVN. Créer ce fichier, et ajouter une définition de variable avec le chemin correcte pour le répertoire qui inclus les exécutables NSIS, tel que:

nsis.home=C:/Program Files (x86)/NSIS

ou

nsis.home=/opt/nsis/nsis-2.46/

Si vous installez un outil "spotbugs", vous devez aussi définir spotbugs.home dans ce fichier. Vous pouvez aussi définir plusieurs autres informations machine-specific ou user-specific, comme décrit dans des emplacements variés dans le fichier build.xml.

Avec le paquet NSIS installé sur votre ordinateur, et build.xml proprement modifié, le paquet Windows peut être créé en exécutant la cible ant "package-windows" dans build.xml.

Utilisation des outils NetBeans XML

NetBeans a de bons outils pour travailler avec des fichiers XML, y compris l'édition et leur validation. JMRI utilise XInclude pour inclure des "fragments" de fichiers XML dans d'autres via l'URL qui pointe sur le site web de JMRI: https://jmri.org/xml/decoders/types/foo.xml Les programmes JMRI les convertissent au moment de l'exécution en fichiers locaux de références, mais par défaut NetBeans ne sait pas faire cela.

Vous pouvez demander à NetBeans comment gérer cela en ajoutant le fichier xml/catalog.xml ( depuis la distribution JMRI pour NetBeans dans les Outils --> DTDs et Schémas XML. ) Ceci permet à NetBeans d'utiliser votre schéma local lors de la validation d'un document XML dans l'éditeur. Notez que ceci est un réglage global dans NetBeans, donc si vous travaillez sur de multiple branches JMRI, quelque soit la branche que vous ajoutez au catalogue, ce schéma de branche est celui qui est utilisé.

Exécution de SpotBugs

L'outil SpotBugs est un outil d'analyse de code statique qui examine le code source Java pour les questions de codage courantes. L'installation d'un outil SpotBugs permet une tâche ant définie dans le build.xml pour exécuter l'analyse SpotBugs à travers l'ensemble du code source Java dans JMRI.

Il semble que le fichier build.xml ne soit pas configuré pour permettre au "plug-in" NetBeans SpotBugs de lancer l'analyse sur le code JMRI sauf sur un one-file-at-a-time-basis. En tant que tel, il semble conseillé de télécharger et d'installer l'outil approprié SpotBugs autonome pour votre système d'exploitation. Les téléchargements SpotBugs peuvent être trouvés à l'adresse du Site web SpotBugs .

Une fois que vous avez l'outil SpotBugs installé, vous devez fournir un chemin vers le répertoire contenant l'exécutable pour une utilisation par le fichier ant build.xml. Si nécessaire, créez le fichier local.properties dans le même répertoire que le fichier JMRI build.xml. Dans le fichier local.properties, ajouter la variable spotbugs.home avec un chemin vers l'exécutable spotbugs, tels que:

spotbugs.home=C:/spotbugs-4.2.3

ou

spotbugs.home =/opt/spotbugs-4.2.3

Pour exécuter l'outil SpotBugs sur le code JMRI,exécutez la cible ant "spotbugs" qui est défini dans build.xml. Dans NetBeans cela peut être accompli par un clic droit sur le fichier build.xml dans le volet "Files" et " Run"ing La cible "SpotBugs". Quand SpotBugs est terminé, la fenêtre de sortie NetBeans va montrer le chemin vers un fichier de rapport au format HTML. Ouvrez ce fichier avec un navigateur pour examiner les résultats SpotBugs.

NetBeans et la compilation des fichiers individuels

L'IDE NetBeans affiche des icônes sur le côté de chaque objet dans la fenêtre Projects , et sur le côté de chaque fichier dans la fenêtre Files. Ces icônes peuvent refléter l' état de chaque élément, y compris le changement local et le véritable statut d'achèvement.

A cette époque, les fichiers ( dans project's nbproject/directory) qui contrôle la façon dont NetBeans effectue la compilation des fichiers individuels, ne reflètent pas correctement toutes les exigences du projet JMRI. Tant que ces fichiers ne sont correctement mis à jour, les icônes d'erreur vont persister dans le projet JMRI. Ces icônes d'erreur n'affectent pas la capacité de NetBeans de compiler les fichiers sources en utilisant les tâches Ant définies dans le fichier build.xml du projet.

Construire le fichier JMRI.jar, et l'exécution d'un outil JMRI de l'intérieur NetBeans est généralement effectuée via des tâches Ant, qui sont définies dans le fichier de projet build.xml. Les développeurs de JMRI ont généralement gardé ce dossier à jour, ainsi la création du fichier JMRI.jar et l'exécution d'un outil JMRI au sein de NetBeans généralement ne souffriront pas des lacunes de l'information de configuration trouvées dans les fichiers dans le nbproject/répertoire du projet.

Voir aussi

Le site Web d'Environnement de développement intégré NetBeans

Le site Web du projet Subversion de Apache.org

Le site web du projet NSIS

Le site web SpotBugs

Création d'un fichier patch

Un "diff patch file" est un moyen facile de rassembler toutes vos modifications, même si elles s'étendent sur plusieurs dossiers, en un seul fichier. Ça peut être utilisé par exemple pour soumettre un Patch. Maintenant que nous utilisons Git et GitHub, cependant, nous préférons que vous contribuez au changements de code par un GitHub Pull Requests.

Pour créer le fichier "patch diff" [deprecated]( obsolète ):