Utilisation du compilateur par lots

Recherche du compilateur par lots

La classe du compilateur par lots se situe dans le plug-in de l'API principale JDT. Le nom de la classe est le suivant : org.eclipse.jdt.compiler.batch.BatchCompiler. Elle est contenue dans le fichier plugins/org.eclipse.jdt.core_<version>.jar. Depuis la version 3.2, elle est également téléchargeable séparément. Le nom du fichier est ecj.jar. Sa source correspondante est également disponible. Pour les obtenir, accédez à la page de téléchargement et rechercher la section JDT Core Batch Compiler. Ce fichier jar contient le compilateur par lots et l'adaptateur javac ant.

Depuis la version 3.3, ce fichier jar contient également le support pour jsr199 (compilateur API) et pour jsr269 (traitement des annotations). Pour pouvoir utiliser le support de traitement des annotations, une machine virtuelle 1.6 est requise.

Ainsi vous pouvez l'utiliser comme une application autonome et à l'intérieur d'une génération Ant hors d'Eclipse.

Exécution du compilateur par lots

Quelles sont les options disponibles ?

Les options recommandées ont un arrière-plan orange.

Lorsque certaines options sont définies plusieurs fois, le compilateur par lots les applique de la gauche vers la droite. Si l'option d'avertissement (-warn:....) est utilisée sans '+' ou '-', elle remplace l'ensemble d'avertissements définis précédemment. Par conséquent, l'utilisateur doit s'assurer qu'une telle option est indiquée avant tout autre utilisation de l'option -warn.

La même règle s'applique à l'option -err:.

Nom Syntaxe
Options de chemin d'accès aux classes
-bootclasspath <dir 1>;<dir 2>;...;<dir P> Liste des répertoires ou des fichiers JAR utilisés pour amorcer les fichiers de classe utilisés par le compilateur. Par défaut, les bibliothèques de la machine virtuelle en cours d'exécution sont utilisées. Les entrées sont séparées par le séparateur de chemin de plateforme.
Chaque répertoire ou fichier peut définir des règles d'accès pour les types, ces derniers devant être alors placés entre crochets ("[" et "]").

Si aucun chemin d'accès aux classes d'amorçage (bootclasspath) n'est défini le compilateur le détermine en fonction des propriétés système suivantes : sun.boot.class.path, vm.boot.class.path ou org.apache.harmony.boot.class.path, dans l'ordre indiqué.

-cp
-classpath <dir 1>;<dir 2>;...;<dir P>
Liste des répertoires ou des fichiers JAR utilisés pour compiler les fichiers source. La valeur par défaut est la valeur de la propriété "java.class.path". Les entrées sont séparées par le séparateur de chemin de plateforme.
Chaque répertoire ou fichier peut définir des règles d'accès pour les types, ces derniers devant être alors placés entre crochets ("[" et "]") ; par exemple [-X] pour interdire l'accès au type X, [~X] pour déconseiller l'accès au type X, et [+p/X:-p/*] pour interdire l'accès à tous les types inclus dans le package p mais autoriser l'accès à p/X.
Le compilateur suit les clauses Class-Path des manifestes des fichiers jar de manière récursive et ajoute chaque fichier jar référencé à la fin du chemin d'accès aux classes, à condition qu'il ne soit pas déjà sur ce chemin.
-extdirs <dir 1>;<dir 2>;...;<dir P> Liste des répertoires utilisés pour définir l'emplacement des fichiers d'extension zip/jar. Les entrées sont séparées par le séparateur de chemin de plateforme.
-endorseddirs <dir 1>;<dir 2>;...;<dir P> Liste des répertoires utilisés pour définir l'emplacement des fichiers zip/jar validés. Les entrées sont séparées par le séparateur de chemin de plateforme.
-sourcepath <dir 1>;<dir 2>;...;<dir P> Liste des répertoires utilisés pour définir les fichiers source. Les entrées sont séparées par le séparateur de chemin de plateforme.
Chaque répertoire peut définir des règles d'accès pour les types, ces derniers devant être alors placés entre crochets ("[" et "]").
-d <dir 1>|none Permet de définir dans quel répertoire les fichiers .class générés doivent être vidés. En cas d'oubli, aucune structure de répertoire de package n'est créée.
Si vous ne souhaitez pas générer de fichier .class, utilisez -d none.
-encoding <nom du codage> Spécifiez le codage par défaut pour tous les fichiers source. Vous pouvez aussi spécifier un codage personnalisé fichier par fichier en ajoutant à chaque nom de dossier/fichier source en entrée le suffixe [<nom du codage>]. Par exemple, X.java[utf8] signifie que le codage est UTF-8 pour l'unité de compilation X.java située dans le répertoire de l'utilisateur courant.

Si plusieurs codages de fichier source par défaut sont spécifiés, le dernier est utilisé.

Exemple :

  • ... -encoding UTF-8 X.java[Cp1252] Y.java[UTF-16] Z.java ....
    Tous les fichiers source seront lus avec le codage UTF-8 (y compris Z.java). X.java sera lu avec le codage Cp1252 et Y.java sera lu avec le codage UTF-16.
  • ... -encoding UTF-8 -encoding UTF-16 ....
    Tous les fichiers source seront lus avec le codage UTF-16. L'option -encoding indiquant UTF-8 est ignorée.
  • ... -encoding Cp1252 /foo/bar/X.java[UTF-16] /foo/bar[UTF-8] ....
    Tous les fichiers source seront lus avec le codage Cp1252. X.java est le seul fichier du répertoire /foo/bar qui sera lu avec le codage UTF-16. Tous les autres fichiers de ce répertoire utiliseront le codage UTF-8.
Options de conformité
-target 1.1 à 1.7 ou (5, 5.0, etc.) Définit le paramètre cible du fichier .class. Les valeurs possibles sont les suivantes :
  • 1.1 (version majeure : 45 mineure : 3)
  • 1.2 (version majeure : 46 mineure : 0)
  • 1.3 (version majeure : 47 mineure : 0)
  • 1.4 (version majeure : 48 mineure : 0)
  • 1.5, 5 or 5.0 (version majeure : 49 mineure : 0)
  • 1.6, 6 or 6.0 (version majeure : 50 mineure : 0)
  • 1.7, 7 or 7.0 (version majeure : 51 mineure : 0)
La valeurs par défaut sont :
  • 1.1 en mode -1.3
  • 1.2 en mode -1.4
  • 1.5 en mode -1.5
  • 1.6 en mode -1.6
  • 1.7 en mode -1.7

clcd1.1 peut être utilisé pour générer l'attribut StackMap.

-1.3 Définit le niveau de conformité sur 1.3. Implicitement -source 1.3 -cible 1.1.
-1.4 Définit le niveau de conformité sur 1.4 (par défaut). Implicitement -source 1.3 -cible 1.2.
-1.5 Définit le niveau de conformité sur 1.5. Implicitement -source 1.5 -cible 1.5.
-1.6 Définit le niveau de conformité sur 1.6. Implicitement -source 1.6 -target 1.6.
-1.7 Définit le niveau de conformité sur 1.7. Implicitement -source 1.7 -target 1.7.
-source 1.1 à 1.7 ou (5, 5.0, etc.) Utilisé pour indiquer le niveau source attendu par le compilateur.
Les valeurs possibles sont les suivantes :
  • 1.3
  • 1.4
  • 1.5, 5 ou 5.0
  • 1.6, 6 ou6.0
  • 1.7, 7 ou7.0
La valeurs par défaut sont :
  • 1.3 en mode -1.3
  • 1.3 en mode -1.4
  • 1.5 en mode -1.5
  • 1.6 en mode -1.6
  • 1.7 en mode -1.7
Dans 1.4, assert est considéré comme un mot clé. Dans 1.5 et 1.6 , enum et assert sont considérés comme des mots clé.
Options d'avertissement
-?:warn -help:warn Affiche les options d'avertissement avancées.
-warn:... Spécifiez l'ensemble d'avertissements activés.
Exemple : -warn:unusedLocal,deprecation
-warn:none désactive tous les avertissements
-warn:<jetons d'avertissement séparés par ,> active les avertissements répertoriés
-warn:+<jetons d'avertissement séparés par ,> active des avertissements supplémentaires
-warn:-<jetons d'avertissement séparés par ,> désactive des avertissements spécifiques
Dans la colonne Par défaut ci-dessous, un signe "+/-" indique qu'une option couvre plusieurs variantes d'alerte affinées ; certaines sont activées par défaut, d'autres sont désactivées. Cela signifie qu'en ajoutant un "+" à l'option donnée, il y aura plus d'avertissements que par défaut, et en ajoutant un "-", il y en aura moins que par défaut.
Valeur par défaut Nom du jeton Description
+/- allDeadCode code mort incluant la vérification if(DEBUG) triviale
+/- allDeprecation obsolescence même au sein du code obsolète
- allJavadoc Javadoc non valide ou manquant
- allOver-ann toutes les annotations @Override manquantes (superclasse et superinterfaces)
- all-static-method toutes les méthodes peuvent être déclarées comme avertissements statiques
+ assertIdentifier occurrence de assert utilisé comme un identificateur
- boxing conversion autoboxing
+ charConcat lorsqu'un tableau de caractères est utilisé dans une concaténation de chaînes sans être explicitement converti en une chaîne
+ compareIdentical comparaison d'expressions identiques
- conditionAssign affectation booléenne accidentelle possible
+ constructorName méthode et nom du constructeur
+ deadCode code mort excluant la vérification if(DEBUG) triviale
- dep-ann annotation @obsolète manquante
+/- deprecation utilisation de type obsolète ou de membre hors du code obsolète
+ discouraged utilisation de types correspondant à une règle d'accès de type "déconseillé"
- emptyBlock bloc vide non renseigné
+ enumIdentifier occurrence de enum utilisée comme identificateur
+ enumSwitch Commutateur d'énumération incomplet
- enumSwitchPedantic signalement des cas switch d'énumération manquants même en présence d'un cas par défaut
- fallthrough cas de fall-through possible
- fieldHiding zone masquant une autre variable
+ finalBound paramètre de type et association finale
+ finally bloc ne se terminant pas normalement
+ forbidden utilisation de types correspondant à une règle d'accès de type "interdit"
- hashCode méthode hashCode() manquant lors du remplacement de equals()
+/- hiding macro pour fieldHiding, localHiding, typeHiding et maskedCatchBlock
- includeAssertNull émet des avertissements null pour des variables tachées dans une expression assert
- indirectStatic référence indirecte à un membre statique
+ intfAnnotation type d'annotation utilisé comme super interface
+ intfNonInherited compatibilité de méthode non héritée d'interface
- intfRedundant recherche des superinterfaces redondantes
- javadoc javadoc non valide
- localHiding variable locale masquant une autre variable
+ maskedCatchBlock bloc catch masqué
- nls libellés de chaîne non-nls (manque de balises //$NON-NLS-<n>)
+ noEffectAssign affectation sans effet
+/- null contrôle null manquant ou redondant
- nullAnnot activation de l'annotation basée sur l'analyse null.
Si vous le souhaitez, les types d'annotation qui doivent être interprétés par le compilateur peuvent être spécifiés en ajoutant (nullable|nonnull|nonnullbydefault), où chaque type d'annotation est spécifié à l'aide de son nom qualifié complet.
Voir aussi -nonNullByDefault ci-dessous.
- nullDereference contrôle null manquant
- over-ann annotation @Override manquante (superclasse uniquement)
- paramAssign affectation à un paramètre
+ pkgDefaultMethod tentative de substitution de la méthode de package par défaut
+ raw utilisation d'un type brut (raw) (au lieu d'un type paramétré)
+/- ressource (éventuellement) l'utilisation dangereuse de ressource de type Closeable
- semicolon point-virgule inutile ou instruction vide
+ serial serialVersionUID manquante
- specialParamHiding paramètre constructeur ou setter masquant une autre zone
+/- static-access macro pour indirectStatic et staticReceiver
- static-method méthode d'instance pouvant être similaire à une méthode statique
+ staticReceiver si un récepteur non statique est utilisé pour obtenir une zone statique ou appeler une méthode statique
- super remplace une méthode sans effectuer de super appel
+ suppress active @SuppressWarnings
- switchDefault instruction switch pour laquelle il manque un cas par défaut
- syncOverride synchronisé manquant dans le remplacement de méthode synchronisé
- syntheticAccess lorsqu'un accès synthétique est réalisé pour innerclass
- tasks active le support des balises de tâches du code source
+ typeHiding paramètre de type masquant un autre type
+ unavoidableGenericProblems ignore les problèmes de sécurité de type inévitable liés à des interfaces API brutes
+ Non sélectionné opération de type décochée
- unnecessaryElse clause else inutile
- unqualifiedField accès non qualifié à une zone
+/- unused macro pour unusedAllocation, unusedArgument, unusedImport, unusedLabel, unusedLocal, unusedPrivate, unusedThrown et unusedTypeArgs
- unusedAllocation attribution d'un objet qui n'est pas utilisé
- unusedArgument argument de méthode inutilisé
+ unusedImport référence d'importation inutilisée
+ unusedLabel Label inutilisé
+ unusedLocal variable locale inutilisée
+ unusedPrivate déclaration de membre privé non-utilisé
- unusedThrown exception émise déclarée et non-utilisée
+ unusedTypeArgs arguments de type non utilisés pour la méthode et le constructeur
- uselessTypeCheck transtypage/instance de l'opération non requis
+ varargsCast l'argument varargs requiert un transtypage explicite
+/- warningToken jeton d'avertissement non géré ou inutilisé dans @SuppressWarnings
-nowarn Pas d'avertissement (équivalent de -warn:none)
-err:... Spécifiez l'ensemble d'avertissements activés qui sont convertis en erreurs.
Exemple : -err:unusedLocal,deprecation
Les avertissements unusedLocal et deprecation seront convertis en erreurs. Les autres avertissements resteront des avertissements.
-err:<jetons d'avertissement séparés par ,> convertit les avertissements répertoriés en erreurs
-err:+<jetons d'avertissement séparés par ,> convertit des avertissements supplémentaires en erreurs
-err:-<jetons d'avertissement séparés par ,> empêche la conversion en erreurs d'avertissements spécifiques
-deprecation Equivalent de -warn:+deprecation.
-properties <fichier> Définissez l'option d'avertissements/erreurs en fonction du contenu du fichier de propriétés. Cette option peut être utilisée avec les options -nowarn, -err:.. ou -warn:.., mais la dernière sur la ligne de commande détermine les options à appliquer.

Vous pouvez générer le contenu du fichier de propriétés en définissant les paramètres propres au projet dans un projet Java existant et en utilisant le fichier qui se trouve dans .settings/org.eclipse.jdt.core.prefs comme fichier de propriétés, ou un simple fichier texte qui définit des paires entrée/valeur à l'aide des constantes définies dans la classe org.eclipse.jdt.core.JavaCore.

...
org.eclipse.jdt.core.compiler.problem.annotationSuperInterface=warning
org.eclipse.jdt.core.compiler.problem.assertIdentifier=warning
org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
...
Options de débogage
-g[:none|:lines,vars,source] Définit le niveau des attributs de débogage
-g Toutes les infos de débogage (équivalent de -g:lines,vars,source)
-g:none Aucune information de débogage
-g:[lines,vars,source] Informations de débogage sélectives
-preserveAllLocals Demande explicitement au compilateur de préserver toutes les variables locales (à des fins de débogage). En cas d'oubli, le compilateur supprime les variables locales inutilisées.
Options de traitement des annotations (machine virtuelle 1.6 ou supérieure requise, utilisées uniquement en cas de conformité 1.6)
-Akey[=value] Options des processeurs d'annotations transmises aux processeurs d'annotations. key est constitué d'identificateurs séparés par des points
-proc:[only|none] Si -proc:only est défini, les processeurs d'annotations seront exécutés mais aucune compilation ne sera effectuée. Si -proc:none est défini, les processeurs d'annotations ne seront pas recherchés ou exécutés. La compilation s'effectuera comme si aucun processeur d'annotations n'avait été trouvé. Par défaut, le compilateur doit rechercher le chemin d'accès aux classes pour les processeurs d'annotations et définir -proc:none peut donc accélérer la compilation si le traitement des annotations n'est pas requis.
-processor <class1[,class2,...]> Noms de classes qualifiés des processeurs d'annotations à exécuter. Si cette option est définie le processus de recherche de processeur normal est ignoré.
-processorpath <dir 1>;<dir 2>;...;<dir P> Liste des répertoires ou des fichiers JAR dans lesquels les processeurs d'annotation seront recherchés. Les entrées sont séparées par le séparateur de chemin de plateforme. Si cette option n'est pas définie, la recherche s'effectue sur le chemin d'accès aux classes.
-s <dir> Répertoire dans lequel les fichiers source générés seront créés.
-XprintProcessorInfo Imprime les informations relatives aux annotations et éléments qu'un processeur doit traiter
-XprintRounds Imprime les informations relatives aux cycles de traitement des annotations
-classNames <class1[,class2,...]> Noms qualifiés des types de fichiers binaires devant être traités
Options ignorées (pour des raisons de compatibilité avec les options javac)
-J<option> Transmet l'option à la machine virtuelle
-X<option> Indique une option non standard. -Xemacs n'est pas ignoré.
-X Imprime les options non standard et quitte
-O Optimisation du temps d'exécution
Options avancées
@<file> Arguments de ligne de commande de type lecture provenant du fichier
-maxProblems <n> Nombre maximal de problèmes par unité de compilation (100, par défaut)
-log <nom du fichier> Définit un fichier journal dans lequel sont vidées toutes les sorties du compilateur. Ceci s'avère particulièrement utile si vous souhaitez déboguer le compilateur par lots ou récupérer un fichier contenant toutes les erreurs et tous les avertissements ayant pour origine une compilation par lots. Si l'extension est .xml, le journal généré sera un fichier xml.
-Xemacs Utilisez le type emacs pour présenter les emplacements des erreurs et des avertissements dans la console et les journaux de texte classique. Les journaux XML ne sont pas affectés par cette option. Si cette option est activée, le message :
2. WARNING in /workspace/X.java
(at line 8)...

est présenté sous la forme :
/workspace/X.java:8: warning: The method...
-proceedOnError[:Fatal] Poursuit la compilation malgré les erreurs, en vidant les fichiers de classe comportant des méthodes ou des types à problèmes. Cette procédure est recommandée uniquement si vous souhaitez pouvoir exécuter votre application même si des erreurs persistent.
Avec ":Fatal", toutes les erreurs facultatives sont traitées comme étant fatales ; le code est abandonné si une erreur est rencontrée lors de l'exécution. Sans ":Fatal", les erreurs facultatives n'empêchent pas une génération de code correcte et les fichiers .class générés peuvent être exécutés sans problème.
-verbose Imprime les unités de compilation accédées/traitées dans la console ou le fichier journal si défini.
-referenceInfo Traite les informations de référence. Utile uniquement en cas de connexion au compilateur. Dans le cas contraire, les informations de référence ne sont d'aucune utilité.
-progress Affiche la progression (uniquement en mode -log).
-time Affiche les informations relatives à la vitesse.
-noExit N'appelle pas System.exit(n) au terme de la compilation (n=0 en l'absence d'erreur).
-repeat <n> Répète le processus de compilation <n> fois (analyse des performances).
-inlineJSR Intègre le bytecode JSR (implicite si cible >= 1.5).
-enableJavadoc Prend en compte les références contenues dans javadoc.
-missingNullDefault Quand une annotation basée sur une analyse null est activée (à l'aide de "nullAnnot", ci-dessus), cette option produira un avertissement à chaque fois qu'il n'y aura pas d'annotation par défaut sur un package ou un type.
Options d'aide
-? -help Affiche le message d'aide.
-v -version Affiche le numéro de version du compilateur. Cette information est particulièrement utile pour signaler un bogue.
-showversion Affiche le numéro de version du compilateur et poursuit. Cette information est particulièrement utile pour signaler un bogue.

Exemples

d:\temp -classpath rt.jar -time -g -d d:/tmp Compile tous les fichiers sources dans d:\temp et ses sous-dossiers. Le chemin d'accès aux classes est tout simplement rt.jar. Il génère tous les attributs de débogage et tous les fichiers .class générés sont vidés dans d:\tmp. La vitesse du compilateur est affichée une fois le processus par lots achevé.
d:\temp\Test.java -classpath d:\temp;rt.jar -g:none Compile uniquement Test.java et ses fichiers dépendants (le cas échéant), en extrayant les fichiers dépendants du répertoire d:\temp. Le chemin d'accès aux classes est d:\temp suivi de rt.jar, ce qui signifie que toute les classes nécessaires sont recherchées initialement dans d:\temp puis dans rt.jar. Ne génère aucun attribut de débogage. Tous les fichiers .class sont vidés dans d:\temp.