1ecj(1) General Commands Manual ecj(1)
2
6 ecj - the eclipse JDT Batch Compiler
7
9 ecj [OPTION]... [SOURCEFILE]... ...
10
12 ecj is the batch compiler from Eclipse and is available as ecj.jar.
13 Since 3.3, this jar also contains the support for jsr199 (Compiler API)
14 and the support for jsr269 (Annotation processing). In order to use the
15 annotations processing support, a 1.6 VM is required.
16
19 Here is a summary of all the options, grouped by type. Explanations
20 are in the OPTIONS section.
21 ClassPath Options
23 -bootclasspath -cp|-classpath -extdirs -endorseddirs -sourcepath -d
25 -encoding
26 Compliance Options
28 -target -1.3 -1.4 -1.5 -1.6 -1.7 -1.8 -source
30 Warning Options
32 -?:warn -help:warn -warn:... -nowarn -err:... -deprecation -properties
34 Debug Options
36 -g -preserveAllLocals -parameters
38 Annotation Processing Options
40 -Akey[=value] -proc:[only|none] -processor -processorpath -s -Xprint‐
42 ProcessorInfo -XprintRounds -classNames
43 Ignored Options (for compatibility with javac options)
45 -J -X -O
47 Advanced Options
49 @<file> -maxProblems -log -Xemacs -proceedOnError -verbose -reference‐
51 Info -progress -time -noExit -repeat -inlineJSR -enableJavaDoc -miss‐
52 ingNullDefault
53 Helping Options
55 -? -help -v -version -showversion
57
60 ClassPath Options
61 -bootclasspath <dir 1>;<dir 2>;...;<dir P>
64 This is a list of directories or jar files used to bootstrap the
65 class files used by the compiler. By default the libraries of
66 the running VM are used. Entries are separated by the platform
67 path separator. Each directory or file can specify access rules
68 for types between '[' and ']'. If no bootclasspath is speci‐
69 fied, the compiler will infer it using the following system
70 properties sun.boot.class.path, vm.boot.class.path or
71 org.apache.harmony.boot.class.path in this order respectively
72 -cp|-classpath <dir 1>;dir2;...<dir P>
75 This is a list of directories or jar files used to compile the
76 source files. The default value is the value of the property
77 "java.class.path". Entries are separated by the platform path
78 separator. Each directory or file can specify access rules for
79 types between '[' and ']' (e.g. [-X] to forbid access to type X,
80 [~X] to discourage access to type X, [+p/X:-p/*] to forbid
81 access to all types in package p but allow access to p/X). The
82 compiler follows the Class-Path clauses of jar files' manifests
83 recursively and appends each referenced jar file to the end of
84 the classpath, provided it is not on the classpath yet.
85 -extdirs <dir 1>;<dir 2>;...;<dir P>
88 This is a list of directories used to specify the location of
89 extension zip/jar files. Entries are separated by the platform
90 path separator.
91 -endorseddirs <dir 1>;<dir 2>;...;<dir P>
94 This is a list of directories used to specify the location of
95 endorsed zip/jar files. Entries are separated by the platform
96 path separator.
97 -sourcepath <dir 1>;<dir 2>;...;<dir P>
100 This is a list of directories used to specify the source files.
101 Entries are separated by the platform path separator. Each
102 directory can specify access rules for types between '[' and
103 ']'.
104 -d <dir 1>|none
107 This is used to specify in which directory the generated .class
108 files should be dumped. If it is omitted, no package directory
109 structure is created. If you want to generate no .class file at
110 all, use -d none.
111 -encoding <encoding name>
114 Specify default encoding for all source files. Custom encoding
115 can also be specified on a per file basis by suffixing each
116 input source file/folder name with [<encoding name>]. For exam‐
117 ple X.java[UTF-8] would specify the UTF-8 encoding for the com‐
118 pilation unit X.java located in the current user directory. If
119 multiple default source file encodings are specified, the last
120 one will be used.
121 For example: ... -encoding UTF-8 X.java[Cp1252] Y.java[UTF-16]
123 Z.java ....
124 All source files will be read using UTF-8 encoding (this
125 includes Z.java). X.java will be read using Cp1252 encoding and
126 Y.java will be read using UTF-16 encoding.
127 ... -encoding UTF-8 -encoding UTF-16 ....
129 All source files will be read using UTF-16 encoding. The -encod‐
130 ing option for UTF-8 is ignored.
131 ... -encoding Cp1252 /foo/bar/X.java[UTF-16] /foo/bar[UTF-8]
133 ....
134 All source files will be read using Cp1252 encoding. X.java is
135 the only file inside the /foo/bar directory to be read using the
136 encoding UTF-16. All other files in that directory will use
137 UTF-8 encoding.
138 Compliance Options
141 -target 1.1 to 1.8 (or 8, 8.0, etc.)
144 This specifies the .class file target setting. The possible
145 value are:
146 1.1 (major version: 45 minor: 3)
147 1.2 (major version: 46 minor: 0)
148 1.3 (major version: 47 minor: 0)
149 1.4 (major version: 48 minor: 0)
150 1.5, 5 or 5.0 (major version: 49 minor: 0)
151 1.6, 6 or 6.0 (major version: 50 minor: 0)
152 1.7, 7 or 7.0 (major version: 51 minor: 0)
153 1.8, 8 or 8.0 (major version: 52 minor: 0)
154 Defaults are:
156 1.1 in -1.3 mode
157 1.2 in -1.4 mode
158 1.5 in -1.5 mode
159 1.6 in -1.6 mode
160 1.7 in -1.7 mode
161 1.8 in -1.8 mode clcd1.1 can be used to generate the StackMap
162 attribute.
163 -1.3 Set compliance level to 1.3. Implicit -source 1.3 -target 1.1.
166 -1.4 Set compliance level to 1.4 (default). Implicit -source 1.3
169 -target 1.2.
170 -1.5 Set compliance level to 1.5. Implicit -source 1.5 -target 1.5.
173 -1.6 Set compliance level to 1.6. Implicit -source 1.6 -target 1.6.
176 -1.7 Set compliance level to 1.7. Implicit -source 1.7 -target 1.7.
179 -1.8 Set compliance level to 1.8. Implicit -source 1.8 -target 1.8.
182 -source 1.1 to 1.8 (or 8, 8.0, etc.)
185 This is used to specify the source level expected by the com‐
186 piler. The possible value are:
187 1.3
188 1.4
189 1.5, 5 or 5.0
190 1.6, 6 or 6.0
191 1.7, 7 or 7.0
192 1.8, 8 or 8.0
193 Defaults are:
195 1.3 in -1.3 mode
196 1.3 in -1.4 mode
197 1.5 in -1.5 mode
198 1.6 in -1.6 mode
199 1.7 in -1.7 mode
200 1.8 in -1.8 mode
201 In 1.4, assert is treated as a keyword. In 1.5 and 1.6, enum and
202 assert are treated as keywords.
203 Warning Options
206 -?:warn -help:warn
209 Display advanced warning options
210 -warn:...
213 Specify the set of enabled warnings.
214 -warn:none disable all warnings
215 -warn:<warning tokens separated by ,> enable exactly the
216 listed warnings
217 -warn:+<warning tokens separated by ,> enable additional warn‐
218 ings
219 -warn:-<warning tokens separated by ,> disable specific warn‐
220 ings
221 Examples:
223 warn:unusedLocal,deprecation
225 enables only the given two warning options and disables all the
226 other options
227 warn:-unusedLocal,deprecation,+fallthrough
229 disables unusedLocal and deprecation, enables fallthrough, and
230 leaves the other warning options untouched
231 The first column below shows the default state for an option. A
233 mark "+/-" indicates that an option covers several fine grained
234 warning variants, some of which are enabled by default, others
235 disabled. This means that specifying the given option with "+"
236 will enable more warnings than the default, and specifying "-"
237 disables some that are enabled by default.
238 +/- allDeadCode dead code including trivial if (DEBUG) check
241 +/- allDeprecation deprecation even inside deprecated code
243 - allJavadoc invalid or missing Javadoc
245 - allOver-ann all missing @Override annotations (superclass
247 and superinterfaces)
248 - all-static-method all method can be declared as static warn‐
250 ings
251 + assertIdentifier occurrence of assert used as identifier
253 - boxing autoboxing conversion
255 + charConcat when a char array is used in a string concatena‐
257 tion without being converted explicitly to a string
258 + compareIdentical comparing identical expressions
260 - conditionAssign possible accidental boolean assignment
262 + constructorName method with constructor name
264 + deadCode dead code excluding trivial if (DEBUG) check
266 - dep-ann missing @Deprecated annotation
268 +/- deprecation usage of deprecated type or member outside dep‐
270 recated code
271 + discouraged use of types matching a discouraged access rule
273 - emptyBlock undocumented empty block
275 + enumIdentifier occurrence of enum used as identifier
277 + enumSwitch incomplete enum switch
279 - enumSwitchPedantic report missing enum switch cases even in
281 the presence of a default case
282 - fallthrough possible fall-through case
284 - fieldHiding field hiding another variable
286 + finalBound type parameter with final bound
288 + finally finally block not completing normally
290 + forbidden use of types matching a forbidden access rule
292 - hashCode missing hashCode() method when overriding equals()
294 +/- hiding macro for fieldHiding, localHiding, maskedCatchBlock,
296 and typeHiding
297 - includeAssertNull raise null warnings for variables that got
299 tainted in an assert expression
300 - indirectStatic indirect reference to static member
302 - inheritNullAnnot consider null annotations as being inher‐
304 ited from an overridden method to any overriding methods
305 + intfAnnotation annotation type used as super interface
307 + intfNonInherited interface non-inherited method compatibil‐
309 ity
310 - intfRedundant find redundant superinterfaces
312 - invalidJavadoc macro to toggle the 'malformed Javadoc com‐
314 ments' option and all its sub-options listed below
315 - invalidJavadocTag report invalid Javadoc tags in Javadoc
317 comments.
318 - invalidJavadocTagDep report invalid deprecated references in
320 Javadoc tag arguments
321 - invalidJavadocTagNotVisible report invalid non-visible ref‐
323 erences in Javadoc tag arguments
324 - invalidJavadocVisibility(<visibility>) specify visibility
326 modifier ("public", "protected" or "private") for malformed
327 Javadoc tag warnings. Usage example: invalidJavadocVisibil‐
328 ity(public)
329 - javadoc invalid Javadoc
331 - localHiding local variable hiding another variable
333 + maskedCatchBlock hidden catch block
335 - missingJavadocTags macro to toggle the 'missing Javadoc
337 tags' option and all its sub-options listed below
338 - missingJavadocTagsMethod report missing Javadoc tags for a
340 method's type parameters
341 - missingJavadocTagsOverriding report missing Javadoc tags in
343 overriding methods
344 - missingJavadocTagsVisibility(<visibility>) specify visibil‐
346 ity modifier ("public", "protected" or "private") for missing
347 Javadoc tags warnings. Usage example: missingJavadocTagsVisibil‐
348 ity(public)
349 - missingJavadocComments macro to toggle the 'missing Javadoc
351 comments' option and all its sub-options listed below
352 - missingJavadocCommentsOverriding report missing Javadoc com‐
354 ments in overriding methods
355 - missingJavadocCommentsVisibility(<visibility>) specify visi‐
357 bility modifier ("public", "protected" or "private") for missing
358 Javadoc comments warnings. Usage example: missingJavadocCom‐
359 mentsVisibility(public)
360 - nls non-nls string literals (lacking of tags //$NON-NLS-<n>)
362 + noEffectAssign assignment with no effect
364 + nonnullNotRepeated nonnull parameter annotation from over‐
366 ridden method is not repeated in an overriding method. Is effec‐
367 tive only with the nullAnnot option enabled.
368 +/- null potential missing or redundant null check
370 - nullAnnot enable annotation based null analysis. If
372 desired, the annotation types to be interpreted by the compiler
373 can be specified by appending (nullable|nonnull|nonnullbyde‐
374 fault), where each annotation type is specified using its fully
375 qualified name. Usage example: nullAnnot(p.Nullable|p.Non‐
376 Null|p.NonNullByDefault)
377 Enabling this option enables all null-annotation related sub-
379 options. These can be individually controlled using options
380 listed below
381 - nullAnnotConflict report conflicts between null annotation
383 specified and nullness inferred. Is effective only with the nul‐
384 lAnnot option enabled.
385 - nullAnnotRedundant report redundant specification of null
387 annotation. Is effective only with the nullAnnot option enabled.
388 - nullDereference missing null check
390 - nullUncheckedConversion report unchecked conversion from
392 unannotated type to @NonNull type. Is effective only with the
393 nullAnnot option enabled.
394 - over-ann missing @Override annotation (superclass only)
396 - paramAssign assignment to a parameter
398 + pkgDefaultMethod attempt to override package-default method
400 + raw usage a of raw type (instead of a parameterized type)
402 +/- resource (potentially) unsafe usage of resource of type
404 Closeable
405 - semicolon unnecessary semicolon or empty statement
407 + serial missing serialVersionUID
409 - specialParamHiding constructor or setter parameter hiding
411 another field
412 +/- static-access macro for indirectStatic and staticReceiver
414 - static-method an instance method that could be as a static
416 method
417 + staticReceiver if a non static receiver is used to get a
419 static field or call a static method
420 - super overriding a method without making a super invocation
422 + suppress enable @SuppressWarnings
424 - switchDefault switch statement lacking a default case
426 - syncOverride missing synchronized in synchronized method
428 override
429 - syntacticAnalysis perform syntax-based null analysis for
431 fields
432 - syntheticAccess when performing synthetic access for inner‐
434 class
435 - tasks enable support for tasks tags in source code
437 + typeHiding type parameter hiding another type
439 + unavoidableGenericProblems report even unavoidable type
441 safety problems due to raw APIs
442 + unchecked unchecked type operation
444 - unnecessaryElse unnecessary else clause
446 - unqualifiedField unqualified reference to field
448 +/- unused macro for unusedImport, unusedLabel, unusedLocal,
450 unusedPrivate, unusedThrown, unusedTypeArgs, and unusedTypePa‐
451 rameter
452 - unusedAllocation allocating an object that is not used
454 - unusedArgument unused method parameter (deprecated option;
456 use unusedParam instead)
457 + unusedImport unused import reference
459 + unusedLabel unused label
461 + unusedLocal unused local variable
463 + unusedParam unused method parameter
465 + unusedParamImplementing unused parameter for implementing
467 method
468 + unusedParamIncludeDoc unused parameter documented in a
470 Javadoc comment tag
471 + unusedParamOverriding unused parameter for overriding method
473 + unusedPrivate unused private member declaration
475 - unusedThrown unused declared thrown exception
477 - unusedThrownIncludeDocComment unused declared thrown excep‐
479 tion documented in a Javadoc comment tag
480 - unusedThrownExemptExceptionThrowable report unused declared
482 thrown exception but exempt Exception and Throwable
483 - unusedThrownWhenOverriding unused declared thrown exception
485 in overriding method
486 + unusedTypeArgs unused type arguments for method and con‐
488 structor
489 + unusedTypeParameter unused type parameter
491 - uselessTypeCheck unnecessary cast/instanceof operation
493 + varargsCast varargs argument need explicit cast
495 +/- warningToken unhandled or unused warning token in @Suppress‐
497 Warnings
498 -nowarn
501 No warning (equivalent to -warn:none)
502 -err:...
504 Specify the set of enabled warnings that are converted to
505 errors.
506 E.g.
507 -err:unusedLocal,deprecation
508 unusedLocal and deprecation warnings will be converted to
509 errors. All other warnings are still reported as warnings.
510 -err:<warning tokens separated by ,> convert exactly the
512 listed warnings to errors
513 -err:+<warning tokens separated by ,> convert additional warn‐
514 ings to errors
515 -err:-<warning tokens separated by ,> remove specific warnings
516 from being converted to errors
517 -deprecation
520 Equivalent to -warn:+deprecation.
521 -properties <file>
523 Set warnings/errors option based on the properties file con‐
524 tents. This option can be used with -nowarn, -err:.. or -warn:..
525 options, but the last one on the command line sets the options
526 to be used.
527 The properties file contents can be generated by setting project
529 specific settings on an existing java project and using the file
530 in .settings/org.eclipse.jdt.core.prefs file as a properties
531 file, or a simple text file that is defined entry/value pairs
532 using the constants defined in the org.eclipse.jdt.core.JavaCore
533 class. Of those constants declared in this class, all options
534 starting with "org.eclipse.jdt.core.compiler." are interpreted
535 by the batch compiler.
536 ...
538 org.eclipse.jdt.core.compiler.problem.annotationSuperInter‐
539 face=warning
540 org.eclipse.jdt.core.compiler.problem.assertIdentifier=warning
541 org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
542 ...
543 To ensure that a property file has the same effect when used in
545 the IDE and for the batch compiler, use of the -properties
546 option will change the defaults for a few options:
547 -g default changed to all enabled
549 -preserveAllLocals default changed to enabled
550 -enableJavadoc default changed to enabled
551 error/warning forbidden default changed to error
552 Debug Options
555 -g[:none|:lines,vars,source]
558 Set the debug attributes level
559 -g All debug info (equivalent to
560 -g:lines,vars,source)
561 -g:none No debug info
562 -g:[lines,vars,source] Selective debug info
563 Not specifying this option is equivalent to setting
564 -g:lines,source.
565 -preserveAllLocals
568 Explicitly request the compiler to preserve all local variables
569 (for debug purpose). If omitted, the compiler will remove unused
570 locals.
571 -parameters
573 Explicitly request the compiler to preserve information about
574 the formal parameters of a method (such as their names) to be
575 accessed from reflection libraries, annotation processing, code
576 weaving, and in the debugger. This option is supported from tar‐
577 get level 1.8 and later. Annotation processing options (require
578 a 1.6 VM or above and are used only if the compliance is 1.6)
579 Annotation Processing Options
582 -Akey[=value]
585 Annotation processors options that are passed to annotation pro‐
586 cessors. key is made of identifiers separated by dots
587 -proc:[only|none]
590 If -proc:only is specified, the annotation processors will run
591 but no compilation will be performed. If -proc:none is speci‐
592 fied, annotation processors will not be discovered or run; com‐
593 pilation will proceed as if no annotation processors were found.
594 By default the compiler must search the classpath for annotation
595 processors, so specifying -proc:none may speed compilation if
596 annotation processing is not required.
597 -processor <class1[,class2,...]>
599 Qualified class names of annotation processors to run. If speci‐
600 fied, the normal processor discovery process will be skipped.
601 -processorpath <dir 1>;<dir 2>;...;<dir P>
603 A list of directories or jar files which will be searched for
604 annotation processors. Entries are separated by the platform
605 path separator. If not specified, the classpath will be searched
606 instead.
607 -s <dir>
609 The directory where generated source files will be created.
610 -XprintProcessorInfo
612 Print information about which annotations and which elements a
613 processor is asked to process
614 -XprintRounds
616 Print information about annotation processing rounds
617 -classNames <class1[,class2,...]>
619 Qualified names of binary types that need to be processed
620 Ignored Options (for compatibility with javac options)
623 -J<option>
626 Pass option to the virtual machine
627 -X<option>
629 Specify non-standard option. -Xemacs is not ignored.
630 -X Print non-standard options and exit
632 -O Optimize for execution time
634 Advanced Options
637 @<file>
640 Read command-line arguments from file
641 -maxProblems <n>
643 Max number of problems per compilation unit (100 by default)
644 -log <filename>
646 Specify a log file in which all output from the compiler will be
647 dumped. This is really useful if you want to debug the batch
648 compiler or get a file which contains all errors and warnings
649 from a batch build. If the extension is .xml, the generated log
650 will be an xml file.
651 -genericsignature
653 Explicitly request the compiler to preserve information about
654 generic signature of lambda expressions.
655 -Xemacs
657 Use emacs style to present errors and warnings locations into
658 the console and regular text logs. XML logs are unaffected by
659 this option. With this option active, the message:
660 2. WARNING in /workspace/X.java
661 (at line 8)...
662 is presented as:
663 /workspace/X.java:8: warning: The method...
664 -proceedOnError[:Fatal]
667 Keep compiling in spite of errors, dumping class files with
668 problem methods or problem types. This is recommended only if
669 you want to be able to run your application even if you have
670 remaining errors. With ":Fatal", all optional errors are
671 treated as fatal and this leads to code that will abort if an
672 error is reached at runtime. Without ":Fatal", optional errors
673 don't prevent the proper code generation and the produced .class
674 files can be run without a problem.
675 -verbose
677 Print accessed/processed compilation units in the console or the
678 log file if specified.
679 -referenceInfo
681 Compute reference info. This is useful only if connected to the
682 builder. The reference infos are useless otherwise.
683 -progress
685 Show progress (only in -log mode).
686 -time Display speed information.
688 -noExit
690 Do not call System.exit(n) at end of compilation (n=0 if no
691 error).
692 -repeat <n>
694 Repeat compilation process <n> times (perf analysis).
695 -inlineJSR
697 Inline JSR bytecode (implicit if target >= 1.5).
698 -enableJavadoc
700 Consider references inside Javadoc. The Javadoc options are
701 effective only when this option is enabled.
702 -missingNullDefault
704 When annotation based null analysis is enabled (using "nullAn‐
705 not", above), this option will raise a warning whenever there is
706 no default annotation on a package or a type.
707 -annotationpath
709 When annotation based null analysis is enabled (using "nullAn‐
710 not", above), this option defines locations where to find exter‐
711 nal annotations to support annotation-based null analysis. The
712 value of this options is a list of directories or zip files.
713 Entries are separated by the platform path separator. The spe‐
714 cial name CLASSPATH will cause lookup of external annotations
715 from the classpath and sourcepath.
716 Helping Options
719 -? -help
722 Display the help message.
723 -v -version
725 Display the build number of the compiler. This is very useful to
726 report a bug.
727 -showversion
729 Display the build number of the compiler and continue. This is
730 very useful to report a bug.
731
734 <http://help.eclipse.org/topic/org.eclipse.jdt.doc.user/tasks/task-
735 using_batch_compiler.htm>
736
738 To report bugs, use <https://bugs.eclipse.org/bugs/enter_bug.cgi?prod‐
739 uct=JDT&component=Core>
740
742 For details on Eclipse committers, see <http://www.eclipse.org/commit‐
743 ters/>
744 10 August 2015 ecj(1)