-
Notifications
You must be signed in to change notification settings - Fork 348
/
external-tools.tex
1492 lines (1213 loc) · 56.1 KB
/
external-tools.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\htmlhr
\chapterAndLabel{Integration with external tools}{external-tools}
This chapter discusses how to run a checker from the command line, from a
build system, or from an IDE\@. You can skip to the appropriate section:
% Keep this list up to date with the sections of this chapter and with a
% copy of the list in file introduction.tex .
\begin{itemize}
\item Android (Section~\ref{android})
\item Android Gradle Plugin (Section~\ref{android-gradle})
\item Ant (Section~\ref{ant-task})
\item Buck (Section~\ref{buck})
\item Command line, via Checker Framework javac wrapper (Section~\ref{javac-wrapper})
\item Command line, via JDK javac (Section~\ref{javac})
\item Eclipse (Section~\ref{eclipse})
\item Gradle (Section~\ref{gradle})
\item IntelliJ IDEA (Section~\ref{intellij})
\item javac Diagnostics Wrapper (Section~\ref{javac-diagnostics-wrapper})
\item Lombok (Section~\ref{lombok})
\item Maven (Section~\ref{maven})
\item NetBeans (Section~\ref{netbeans})
\item sbt (Section~\ref{sbt})
\item tIDE (Section~\ref{tide})
\end{itemize}
If your build system or IDE is not listed above, you should customize how
it runs the javac command on your behalf. See your build system or IDE
documentation to learn how to
customize it, adapting the instructions for javac in Section~\ref{javac}.
If you make another tool support running a checker, please
inform us via the
\href{https://groups.google.com/forum/#!forum/checker-framework-discuss}{mailing
list} or
\href{https://github.com/typetools/checker-framework/issues}{issue tracker} so
we can add it to this manual.
All examples in this chapter are in the public domain, with no copyright nor
licensing restrictions.
\sectionAndLabel{Android}{android}
When creating an Android app, you may wish to use \<checker-qual-android>
whenever this document mentions \<checker-qual>. This can lead to smaller
dex files (smaller distributed apps).
The \<checker-qual-android> artifact is identical to the \<checker-qual>
artifact, except that in \<checker-qual-android> annotations have classfile
retention. The default Android Gradle plugin retains types annotated with
runtime-retention annotations in the main dex, but strips out class-retention
annotations.
\sectionAndLabel{Android Studio and the Android Gradle Plugin}{android-gradle}
Android Studio 3.0 and later, and Android Gradle Plugin 3.0.0 and later, support type
annotations. (See
\url{https://developer.android.com/studio/write/java8-support}
for more details.) This section explains how to configure your Android
project to use the Checker Framework. All the changes should be made to
the module's \<build.gradle> file --- not the project's \<build.gradle> file.
Different changes are required for JDK 8
(Section~\ref{android-jdk8}) and for JDK 9+ (Section~\ref{android-jdk11}).
\subsectionAndLabel{JDK 8}{android-jdk8}
This section shows what changes to make if you are using JDK 8.
\begin{enumerate}
\item In your module's \<build.gradle> file, set the source and target
compatibility to \<JavaVersion.VERSION\_1\_8>:
\begin{Verbatim}
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
\end{Verbatim}
\item Add a build variant for running checkers:
\begin{Verbatim}
android {
...
buildTypes {
...
checkTypes {
javaCompileOptions.annotationProcessorOptions.
classNames.add("org.checkerframework.checker.nullness.NullnessChecker")
// You can pass options like so:
// javaCompileOptions.annotationProcessorOptions.arguments.put("warns", "")
}
}
}
\end{Verbatim}
\item Add a dependency configuration for the Java 9 compiler:
\begin{mysmall}
\begin{Verbatim}
configurations {
errorproneJavac {
description = 'Java 9 compiler; required to run the Checker Framework under JDK 8.'
}
}
\end{Verbatim}
\end{mysmall}
\item Declare the Checker Framework dependencies:
\begin{mysmall}
\begin{Verbatim}
dependencies {
... existing dependencies...
ext.checkerFrameworkVersion = '3.34.0'
implementation "org.checkerframework:checker-qual-android:${checkerFrameworkVersion}"
// or if you use no annotations in source code the above line could be
// compileOnly "org.checkerframework:checker-qual-android:${checkerFrameworkVersion}"
annotationProcessor "org.checkerframework:checker:${checkerFrameworkVersion}"
errorproneJavac 'com.google.errorprone:javac:9+181-r4173-1'
}
\end{Verbatim}
\end{mysmall}
\item Direct all tasks of type \<JavaCompile> used by the \<checkTypes>
build variant to use the Error Prone compiler:
\begin{mysmall}
\begin{Verbatim}
gradle.projectsEvaluated {
tasks.withType(JavaCompile).all { compile ->
if (compile.name.contains("CheckTypes")) {
options.fork = true
options.forkOptions.jvmArgs += ["-Xbootclasspath/p:${configurations.errorproneJavac.asPath}".toString()]
}
}
}
\end{Verbatim}
\end{mysmall}
\item To run the checkers, build using the \<checkTypes> variant:
\begin{Verbatim}
gradlew assembleCheckTypes
\end{Verbatim}
\end{enumerate}
\subsectionAndLabel{JDK 11+}{android-jdk11}
This section shows what changes to make if you are using JDK 11 or later.
% We have tested them with JDK 11.
\begin{enumerate}
\item In your module's \<build.gradle> file, set the source and target
compatibility to \<JavaVersion.VERSION\_1\_8>:
\begin{Verbatim}
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
\end{Verbatim}
\item Add a build variant for running checkers:
\begin{Verbatim}
android {
...
buildTypes {
...
checkTypes {
javaCompileOptions.annotationProcessorOptions.
classNames.add("org.checkerframework.checker.nullness.NullnessChecker")
// You can pass options like so:
// javaCompileOptions.annotationProcessorOptions.arguments.put("warns", "")
}
}
}
\end{Verbatim}
\item Declare the Checker Framework dependencies:
\begin{mysmall}
\begin{Verbatim}
dependencies {
... existing dependencies...
ext.checkerFrameworkVersion = '3.34.0'
implementation "org.checkerframework:checker-qual-android:${checkerFrameworkVersion}"
// or if you use no annotations in source code the above line could be
// compileOnly "org.checkerframework:checker-qual-android:${checkerFrameworkVersion}"
annotationProcessor "org.checkerframework:checker:${checkerFrameworkVersion}"
}
\end{Verbatim}
\end{mysmall}
\item To run the checkers, build using the \<checkTypes> variant:
\begin{Verbatim}
gradlew assembleCheckTypes
\end{Verbatim}
\end{enumerate}
\sectionAndLabel{Ant task}{ant-task}
If you use the \href{https://ant.apache.org/}{Ant} build tool to compile
your software, then you can add an Ant task that runs a checker. We assume
that your Ant file already contains a compilation target that uses the
\code{javac} task, and that the \<CHECKERFRAMEWORK> environment variable is set.
\begin{enumerate}
\item
Set the \code{cfJavac} property:
%BEGIN LATEX
\begin{smaller}
%END LATEX
\begin{Verbatim}
<property environment="env"/>
<property name="checkerframework" value="${env.CHECKERFRAMEWORK}" />
<condition property="cfJavac" value="javac.bat" else="javac">
<os family="windows" />
</condition>
<presetdef name="cf.javac">
<javac fork="yes" executable="${checkerframework}/checker/bin/${cfJavac}" >
<compilerarg value="-version"/>
<compilerarg value="-implicit:class"/>
</javac>
</presetdef>
\end{Verbatim}
%BEGIN LATEX
\end{smaller}
%END LATEX
\item \textbf{Duplicate} the compilation target, then \textbf{modify} it slightly as
indicated in this example:
%BEGIN LATEX
\begin{smaller}
%END LATEX
\begin{Verbatim}
<target name="check-nullness"
description="Check for null pointer dereferences"
depends="clean,...">
<!-- use cf.javac instead of javac -->
<cf.javac ... >
<compilerarg line="-processor org.checkerframework.checker.nullness.NullnessChecker"/>
<!-- optional, to not check uses of library methods:
<compilerarg value="-AskipUses=^(java\.awt\.|javax\.swing\.)"/>
-->
<compilerarg line="-Xmaxerrs 10000"/>
...
</cf.javac>
</target>
\end{Verbatim}
%BEGIN LATEX
\end{smaller}
%END LATEX
Fill in each ellipsis (\ldots) from the original compilation target.
However, do not copy any \<fork=> setting from the original \code{<javac>}
task invocation.
If your original compilation target set the bootclasspath, then you cannot
use the javac wrapper script as the above instructions do. You should edit
your Ant buildfile to make invocations similar to those described in
Section~\ref{javac}, but accommodating your bootclasspath.
In the example, the target is named \code{check-nullness}, but you can
name it whatever you like.
\end{enumerate}
\subsectionAndLabel{Explanation}{ant-task-explanation}
This section explains each part of the Ant task.
\begin{enumerate}
\item Definition of \code{cf.javac}:
The \code{fork} field of the \code{javac} task
ensures that an external \code{javac} program is called. Otherwise, Ant will run
\code{javac} via a Java method call, and there is no guarantee that it will get
correct version of \code{javac}.
The \code{-version} compiler argument is just for debugging; you may omit
it.
The \code{-implicit:class} compiler argument causes annotation processing
to be performed on implicitly compiled files. (An implicitly compiled file
is one that was not specified on the command line, but for which the source
code is newer than the \code{.class} file.) This is the default, but
supplying the argument explicitly suppresses a compiler warning.
%% -Awarns was removed above without removing it here.
% The \code{-Awarns} compiler argument is optional, and causes the checker to
% treat errors as warnings so that compilation does not fail even if
% pluggable type-checking fails; see Section~\ref{checker-options}.
\item The \code{check-nullness} target:
The target assumes the existence of a \code{clean} target that removes all
\code{.class} files. That is necessary because Ant's \code{javac} target
doesn't re-compile \code{.java} files for which a \code{.class} file
already exists.
The \code{-processor ...} compiler argument indicates which checker to
run. You can supply additional arguments to the checker as well.
\end{enumerate}
\sectionAndLabel{Buck}{buck}
Buck is a build system maintained by Facebook.
Buck has support for annotation processors, but that support is
undocumented because the Buck maintainers may change the syntax in the
future and they don't wish to ever change anything that is documented.
You can learn more about Buck and annotation processors at these URLs:
{\codesize\url{https://stackoverflow.com/questions/32915721/documentation-for-annotation-processors-buck}},
{\codesize\url{https://github.com/facebook/buck/issues/85}}.
In order to use Checker Framework with Buck on \textbf{JDK 8}, you first need
to place the Error Prone JDK 9 compiler in Buck's bootclasspath
(further explanation in Section~\ref{javac-jdk8}). To do so,
follow the instructions on this page: \\
{\codesize\url{https://github.com/uber/okbuck/wiki/Using-Error-Prone-with-Buck-and-OkBuck#using-error-prone-javac-on-jdk-8}} \\
You only need to follow the instructions to use Error Prone javac on
that page, not the instructions to enable Error Prone.
Here is an example \<BUCK> build
file showing how to enable the Checker Framework:
\begin{Verbatim}
prebuilt_jar(
name = 'checker-framework',
binary_jar = 'checker-3.34.0.jar',
visibility = [ 'PUBLIC' ]
)
prebuilt_jar(
name = 'checker-qual',
binary_jar = 'checker-qual-3.34.0.jar',
visibility = [ 'PUBLIC' ]
)
java_library (
name = 'hello',
srcs = glob(['src/main/java/**/*.java']),
java_version = '1.8',
provided_deps = [ ':checker-framework', ':checker-qual' ],
# To add annotation processing
annotation_processors = [ 'org.checkerframework.checker.units.UnitsChecker' ],
annotation_processor_deps = [ ':checker-framework', ':checker-qual' ],
)
\end{Verbatim}
\subsectionAndLabel{Troubleshooting}{buck-troubleshooting}
Use \<--verbose 8> to see diagnostic output including a command line that
ought to be equivalent to Buck's use of an in-process Java compiler.
For example, you might run
\begin{Verbatim}
./buck clean
./buck fetch //...
./buck build --verbose 8 //app:main
\end{Verbatim}
However, the command lines that buck prints with \<-v 8> is \emph{not} what
Buck actually executes. Buck's invocation of the Checker Framework may
produce errors that cannot be reproduced from the command line. This is
because Buck uses
\href{https://github.com/facebook/buck/blob/main/src/com/facebook/buck/jvm/java/Jsr199Javac.java}{in-process
compilation}, potentially multi-threaded, and because Buck may use
\href{https://github.com/facebook/buck/blob/main/src/com/facebook/buck/util/ClassLoaderCache.java}{multiple
classloaders} that are cached.
You can force Buck to run an external javac, thus behaving exactly like the
command line that its diagnostics print. Use the configuration flag \<-c
tools.javac=\emph{path-to-javac}>, for example:
\begin{Verbatim}
./buck clean && ./buck fetch //... && ./buck build //app:main -c tools.javac=$(which javac)
\end{Verbatim}
\sectionAndLabel{Command line, via Checker Framework javac wrapper}{javac-wrapper}
\label{javac-installation} % for backward compatibility, added 10/2/2019
To perform pluggable type-checking from the command line, run the \<javac>
command that ships with the Checker Framework. This is called the
``Checker Framework compiler'' or the ``Checker Framework \<javac> wrapper''.
It is exactly the same as the OpenJDK
\<javac> compiler, with one small difference: it includes the Checker
Framework jar file on its classpath.
You cannot use the \<javac> wrapper if you wish to set the bootclasspath.
There are three ways to use the Checker Framework compiler from the command
line. You can use any
one of them. However, if you are using the Windows command shell, you must
use the last one.
% Is the last one required for Cygwin, as well as for the Windows command shell?
Adjust the pathnames if you have installed the Checker Framework somewhere
other than \<\${HOME}/checker-framework-3.34.0/>.
\begin{itemize}
\item
Option 1:
Add directory
\code{.../checker-framework-3.34.0/checker/bin} to your path, \emph{before} any other
directory that contains a \<javac> executable.
If you are
using the bash shell, a way to do this is to add the following to your
\verb|~/.profile| (or alternately \verb|~/.bash_profile| or \verb|~/.bashrc|) file:
\begin{Verbatim}
export CHECKERFRAMEWORK=${HOME}/checker-framework-3.34.0
export PATH=${CHECKERFRAMEWORK}/checker/bin:${PATH}
\end{Verbatim}
After editing the file, log out and back in to ensure that the environment variable
setting takes effect.
\item
\begin{sloppypar}
Option 2:
Whenever this document tells you to run \code{javac},
instead run \code{\$CHECKERFRAMEWORK/checker/bin/javac}.
\end{sloppypar}
You can simplify this by introducing an alias \<javacheck>. Then,
whenever this document tells you to run \code{javac}, instead run
\<javacheck>. Here is the syntax for your
\verb|~/.bashrc|, \verb|~/.profile|, or \verb|~/.bash_profile|
file:
% No Windows example because this doesn't work under Windows.
\begin{Verbatim}
export CHECKERFRAMEWORK=${HOME}/checker-framework-3.34.0
alias javacheck='$CHECKERFRAMEWORK/checker/bin/javac'
\end{Verbatim}
After editing the file, log out and back in to ensure that the environment variable
setting and alias take effect.
\item
Option 3:
Whenever this document tells you to run \code{javac}, instead
run \<checker.jar> via \<java> (not \<javac>) as in:
\begin{Verbatim}
java -jar "$CHECKERFRAMEWORK/checker/dist/checker.jar" -cp "myclasspath" -processor nullness MyFile.java
\end{Verbatim}
You can simplify the above command by introducing an alias
\<javacheck>. Then, whenever this document tells you to run
\code{javac}, instead run \<javacheck>. For example:
\begin{Verbatim}
# Unix
export CHECKERFRAMEWORK=${HOME}/checker-framework-3.34.0
alias javacheck='java -jar "$CHECKERFRAMEWORK/checker/dist/checker.jar"'
# Windows
set CHECKERFRAMEWORK = C:\Program Files\checker-framework-3.34.0\
doskey javacheck=java -jar "%CHECKERFRAMEWORK%\checker\dist\checker.jar" $*
\end{Verbatim}
(Explanation for advanced users:
More generally, anywhere that you would use \<javac.jar>, you can substitute
\<\$CHECKERFRAMEWORK/checker/dist/checker.jar>;
the result is to use the Checker
Framework compiler instead of the regular \<javac>.)
\end{itemize}
%% Does this work? Text elsewhere in the manual imples that it does not.
% \item
% \begin{sloppypar}
% In order to use the updated compiler when you type \code{javac}, add the
% directory \<C:\ttbs{}Program Files\ttbs{}checker-framework\ttbs{}checkers\ttbs{}binary> to the
% beginning of your path variable. Also set a \code{CHECKERFRAMEWORK} variable.
% \end{sloppypar}
%
% % Instructions stolen from http://www.webreference.com/js/tips/020429.html
%
% To set an environment variable, you have two options: make the change
% temporarily or permanently.
% \begin{itemize}
% \item
% To make the change \textbf{temporarily}, type at the command shell prompt:
%
% \begin{alltt}
% path = \emph{newdir};%PATH%
% \end{alltt}
%
% For example:
%
% \begin{Verbatim}
% set CHECKERFRAMEWORK = C:\Program Files\checker-framework
% path = %CHECKERFRAMEWORK%\checker\bin;%PATH%
% \end{Verbatim}
%
% This is a temporary change that endures until the window is closed, and you
% must re-do it every time you start a new command shell.
%
% \item
% To make the change \textbf{permanently},
% Right-click the \<My Computer> icon and
% select \<Properties>. Select the \<Advanced> tab and click the
% \<Environment Variables> button. You can set the variable as a ``System
% Variable'' (visible to all users) or as a ``User Variable'' (visible to
% just this user). Both work; the instructions below show how to set as a
% ``System Variable''.
% In the \<System Variables> pane, select
% \<Path> from the list and click \<Edit>. In the \<Edit System Variable>
% dialog box, move the cursor to the beginning of the string in the
% \<Variable Value> field and type the full directory name (not using the
% \verb|%CHECKERFRAMEWORK%| environment variable) followed by a
% semicolon (\<;>).
%
% % This is for the benefit of the Ant task.
% Similarly, set the \code{CHECKERFRAMEWORK} variable.
%
% This is a permanent change that only needs to be done once ever.
% \end{itemize}
\sectionAndLabel{Command line, via JDK javac}{javac}
This section explains how to use the Checker Framework with the OpenJDK or
OracleJDK \<javac>, rather than with the \<javac> wrapper script described in
Section~\ref{javac-wrapper}.
This
section assumes you have downloaded the Checker Framework release zip and set
the environment variable \<CHECKERFRAMEWORK> to point to the unzipped directory.
Alternately, you can get all of the jars mentioned in this section from Maven Central:
\begin{itemize}
\item \<javac.jar>: \url{https://search.maven.org/artifact/com.google.errorprone/javac/9%2B181-r4173-1/jar}
\item \<checker-qual.jar>: \url{https://repo1.maven.org/maven2/org/checkerframework/checker-qual/3.34.0/checker-qual-3.34.0.jar}
\item \<checker-util.jar>: \url{https://repo1.maven.org/maven2/org/checkerframework/checker-util/3.34.0/checker-util-3.34.0.jar}
\item \<checker.jar>: \url{https://repo1.maven.org/maven2/org/checkerframework/checker/3.34.0/checker-3.34.0-all.jar}
\end{itemize}
Different arguments to \<javac> are required for JDK 8
(Section~\ref{javac-jdk8}) and for JDK 9+ (Section~\ref{javac-jdk11}).
\subsectionAndLabel{JDK 8}{javac-jdk8}
This section shows what arguments to pass to the OpenJDK or OracleJDK
\<javac> (\emph{not} the \<javac> wrapper script of
Section~\ref{javac-wrapper}) to run the Checker
Framework, if you are using JDK 8.
\begin{Verbatim}
javac \
-J-Xbootclasspath/p:$CHECKERFRAMEWORK/checker/dist/javac.jar \
-cp $CHECKERFRAMEWORK/checker/dist/checker-qual.jar \
-processorpath $CHECKERFRAMEWORK/checker/dist/checker.jar \
-processor org.checkerframework.checker.nullness.NullnessChecker \
-source 8 -target 8
\end{Verbatim}
Below is an explanation of each argument.
\begin{enumerate}
\item \<-J-Xbootclasspath/p:\$CHECKERFRAMEWORK/checker/dist/javac.jar>:
even when running under JDK 8, a Java 9+ compiler (either the Error Prone
compiler or the OpenJDK Java compiler (version 9 or later) must be on the JVM bootclasspath.
The \<-J> indicates that this is a JVM argument rather than a compiler
argument.
The following exception is thrown if this argument is missing:
\begin{Verbatim}
error: SourceChecker.typeProcessingStart: unexpected Throwable (NoSuchMethodError);
message: com.sun.tools.javac.code.Type.stripMetadata()Lcom/sun/tools/javac/code/Type;
\end{Verbatim}
If you are compiling your own checker, the following exception is thrown if this argument is missing:
\begin{Verbatim}
java.lang.NoSuchFieldError: ANNOTATION_PROCESSOR_MODULE_PATH
\end{Verbatim}
\item \<-cp \$CHECKERFRAMEWORK/checker/dist/checker-qual.jar>: \<checker-qual.jar>
must be on the compilation classpath.
\item \<-processorpath \$CHECKERFRAMEWORK/checker/dist/checker.jar>:
\<checker.jar> must be on the processor path. Using this option means that the processor path, not
the classpath, will be searched for annotation processors
and for classes that they load.
\item \<-processor org.checkerframework.checker.nullness.NullnessChecker>:
Choose which checker to run by passing its fully qualified name as a processor.
(Note, using this option means that javac will not search for annotation
processors, but rather will run only those specified here.)
\item \<-source 8 -target 8>: Because the build is using
a Java 9 compiler, these options ensure that the
source code is Java 8 and that Java 8 bytecode is created.
\end{enumerate}
\subsectionAndLabel{JDK 11+}{javac-jdk11}
This section shows what arguments to pass to the OpenJDK or OracleJDK
\<javac> (\emph{not} the \<javac> wrapper script of
Section~\ref{javac-wrapper}) to run the Checker
Framework, if you are using JDK 9 or later. These
instructions should work on JDK 9 or later, but we only test with supported
versions of Java: JDK 11, JDK 17, and JDK 20.
\subsubsectionAndLabel{Non-modularized code}{javac-jdk11-non-modularized}
To compile non-modularized code:
% Keep list of --add-opens and --add-exports in sync with the "maven" and "SBT" sections,
% the method CheckerMain#getExecArguments, checker-framework/build.gradle in compilerArgsForRunningCFs,
% and in the checker-framework-gradle-plugin, CheckerFrameworkPlugin#applyToProject
\begin{Verbatim}
javac \
-J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \
-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED \
-processorpath $CHECKERFRAMEWORK/checker/dist/checker.jar \
-cp $CHECKERFRAMEWORK/checker/dist/checker-qual.jar \
-processor org.checkerframework.checker.nullness.NullnessChecker
\end{Verbatim}
The arguments are explained above, except for two of them:
\begin{enumerate}
\item \<-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED> which
opens the \<jdk.compiler/com.sun.tools.java.comp> package. This is
required because the Checker Framework reflectively accesses private members of this package.
\item \<-J--add-exports=...=ALL-UNNAMED> which exports the listed packages. This is
required with JDK 17+ because the Checker Framework accesses non-exported members of these packages.
(These are also required with JDK 11 if \<--illegal-access> is set to \<deny>.)
\end{enumerate}
If this option is missing, \<javac> may issue one of the below warnings:
\begin{Verbatim}
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.checkerframework.javacutil.Resolver
(file:$CHECKERFRAMEWORK/checker/dist/checker.jar) to method com.sun.tools.javac.comp.Resolve.findMethod(...)
WARNING: Please consider reporting this to the maintainers of org.checkerframework.javacutil.Resolver
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
\end{Verbatim}
\begin{Verbatim}
java.lang.IllegalAccessError: class org.checkerframework.javacutil.AbstractTypeProcessor
(in unnamed module ...) cannot access class com.sun.tools.javac.processing.JavacProcessingEnvironment
(in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.processing
to unnamed module ...
\end{Verbatim}
\subsubsectionAndLabel{Modularized code}{javac-jdk11-modularized}
To compile a module, first add \<requires
org.checkerframework.checker.qual;> to your \<module-info.java>. The Checker
Framework inserts inferred annotations into bytecode even if none appear in source code,
so you must do this even if you write no annotations in your code.
\begin{Verbatim}
javac \
-J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
-J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \
-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED \
-processorpath $CHECKERFRAMEWORK/checker/dist/checker.jar \
--module-path $CHECKERFRAMEWORK/checker/dist/checker-qual.jar \
-processor org.checkerframework.checker.nullness.NullnessChecker
\end{Verbatim}
\<checker-qual.jar> must be on the module path rather than the class path, but
do not put \<checker.jar> on the processor module path as it is not
modularized.
\sectionAndLabel{Eclipse}{eclipse}
% Eclipse supports type annotations.
% Eclipse does not directly support running the Checker Framework,
% nor is Eclipse necessary for running the Checker Framework.
You
need to run the Checker Framework via a build tool (Ant, Gradle, Maven, etc.), rather
than by supplying the \<-processor> command-line option to the \<ejc>
compiler, which is also known as \<eclipsec>.
The reason is that the Checker Framework is built upon \<javac>,
and \<ejc> represents the Java program differently. (If both \<javac> and \<ejc>
implemented JSR 198~\cite{JSR198}, then it would be possible to build
an annotation processor that works with both compilers.)
There is no dedicated Eclipse plug-in for running the Checker Framework,
but it's still easy to run the Checker Framework. First, create a
target/task in your build system to run the Checker Framework. Then, run
the target/task from Eclipse. Section~\ref{eclipse-ant} gives details for
Ant, but other build systems are similar.
\subsectionAndLabel{Using an Ant task}{eclipse-ant}
Add an Ant target as described in Section~\ref{ant-task}. You can
run the Ant target by executing the following steps
(instructions copied from
{\codesize\url{https://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2FgettingStarted%2Fqs-84_run_ant.htm}}):
\begin{enumerate}
\item
Select \code{build.xml} in one of the navigation views and choose
{\bf Run As $>$ Ant Build...} from its context menu.
\item
A launch configuration dialog is opened on a launch configuration
for this Ant buildfile.
\item
In the {\bf Targets} tab, select the new ant task (e.g., check-interning).
\item
Click {\bf Run}.
\item
The Ant buildfile is run, and the output is sent to the Console view.
\end{enumerate}
\subsectionAndLabel{Troubleshooting Eclipse}{eclipse-troubleshooting}
Eclipse issues an ``Unhandled Token in @SuppressWarnings'' warning if you
write a \<@SuppressWarnings> annotation containing a string that Eclipse does not
know about. Unfortunately, Eclipse
\href{https://bugs.eclipse.org/bugs/show_bug.cgi?id=122475}{hard-codes}
this list.
To eliminate the warnings:
disable all ``Unhandled Token in @SuppressWarnings'' warnings in Eclipse.
Look under the menu headings
``Java $\rightarrow$ Compiler $\rightarrow$ Errors/Warnings $\rightarrow$
Annotations $\rightarrow$ Unhandled Token in '@SuppressWarnings',''
and set it to ignore.
\sectionAndLabel{Gradle}{gradle}
To run a checker
on a project that uses the \href{https://gradle.org/}{Gradle} build system,
use the
\ahreforurl{https://github.com/kelloggm/checkerframework-gradle-plugin}{Checker
Framework Gradle plugin}. Its documentation explains how to use it.
\sectionAndLabel{IntelliJ IDEA}{intellij}
% The following method has been tested with IntelliJ IDEA 2019.1.1.
This section tells you how to make IntelliJ IDEA automatically run a
checker on every compile for Java projects and/or modules.
If your project uses a build tool (Ant, Gradle, Maven, etc.), \emph{do not}
use the instructions in this section.
Follow the instructions for that build tool instead (they are in
a different section of this chapter). To compile your project, run the
build tool (possibly from within IntelliJ IDEA, possibly not).
\subsectionAndLabel{Running a checker on every IntelliJ compilation}{intellij-every-compilation}
If your project does not use a build tool, use the following instructions
to run a checker within IntelliJ IDEA on every compile:
\begin{enumerate}
\item Change the project SDK to 11 or later, as explained at
\url{https://www.jetbrains.com/help/idea/sdk.html#change-project-sdk}.
\item Make sure the language level for your project is 8 or higher, as explained at
\url{https://www.jetbrains.com/help/idea/project-page.html}.
\item Create and configure an annotation profile, following the instructions at \url{https://www.jetbrains.com/help/idea/annotation-processors-support.html}.
When configuring the profile:
\begin{enumerate}
\item Add \<.../checker-framework/checker/dist/checker.jar> to the processor path.
\item Add checkers to be run during compilation by writing the
fully-qualified name of the checker in the ``Processor FQ Name''
section. An example of a fully-qualified checker name is
``org.checkerframework.checker.nullness.NullnessChecker''.
\end{enumerate}
\item Add \<.../checker-framework/checker/dist/checker-qual.jar>, as a dependency to all
modules you wish to type check. (They should all have been associated with
the annotation profile above.)
Instructions appear at
\url{https://www.jetbrains.com/help/idea/creating-and-managing-projects.html}.
\end{enumerate}
Now, when you compile your code, the checker will be run.
It is necessary to manually inform the IDE via a plugin if an annotation
system adds any dependencies beyond those that normally exist in Java.
For information about the extension points, see
\url{https://youtrack.jetbrains.com/issue/IDEA-159286}.
\subsectionAndLabel{Running a checker on every IntelliJ change or save}{intellij-every-save}
To make IntelliJ compile on every change or save,
follow the instructions at
\url{https://www.jetbrains.com/help/idea/compiling-applications.html#auto-build}.
You can also configure IntelliJ to automatically save (and thus
automatically compile) your work periodically. Instructions appear at
\url{https://www.jetbrains.com/help/idea/system-settings.html#sync}.
\sectionAndLabel{javac diagnostics wrapper}{javac-diagnostics-wrapper}
The \href{https://github.com/eisopux/javac-diagnostics-wrapper}{javac
diagnostics wrapper} project can post-process the javac
diagnostics output into other formats, such as
the LSP (Language Server Protocol) JSON style.
\sectionAndLabel{Lombok}{lombok}
Project Lombok (\url{https://projectlombok.org/}) is a library that
generates getter, setter, and builder methods, among other features.
For example, if you declare
a field:
\begin{Verbatim}
@Getter @Setter
private @Regex String role;
\end{Verbatim}
\noindent
then Lombok will generate getter and setter methods:
\begin{Verbatim}
public @Regex String getRole() { return role; }
public void setRole(@Regex String role) { this.role = role; }
\end{Verbatim}
\subsectionAndLabel{Annotations on generated code}{lombok-copying-annotations}
As illustrated in the example above, Lombok copies type annotations from fields
to generated methods, when the user writes Lombok's \<@Getter>, \<@Setter>,
and \<@Builder> annotations. Lombok does so only for certain type
annotations (including all annotations in the Checker Framework
distribution); see variable \<BASE\_COPYABLE\_ANNOTATIONS> in file
\href{https://github.com/projectlombok/lombok/blob/master/src/core/lombok/core/handlers/HandlerUtil.java}{\<HandlerUtil.java>}.
To make Lombok copy other type annotations from fields to generated code,
add those type annotations to the \<lombok.copyableAnnotations>
configuration key in your \<lombok.config> file. For example:
\begin{Verbatim}
lombok.copyableAnnotations += my.checker.qual.MyTypeAnnotation
\end{Verbatim}
Directory \<docs/examples/lombok> contains an example Gradle project that
augments the configuration key.
% Alternatives:
% * It would be better if Lombok automatically copied all type annotations.
% Unfortunately, there is no way for Lombok to know whether an annotation
% is a type annotation, at the (early) point in the javac pipeline where
% Lombok runs.
% TODO: write a simple tool that generates a lombok.config file for a particular
% project, with all type annotations used in the project.
\subsectionAndLabel{Type-checking code with Lombok annotations}{lombok-typechecking}
If you run the Checker Framework and Lombok in the same \<javac>
invocation, the Checker Framework cannot type-check a class that contains
Lombok annotations. The way that Lombok changes the class prevents the
Checker Framework from seeing any of the class. (The Checker Framework
works fine on classes that do not contain Lombok annotations, including if
they call Lombok-generated code.)
Therefore, you must run the Checker Framework in a postpass after the
\<javac> that runs Lombok has completed. Use the
\href{https://projectlombok.org/features/delombok}{Delombok} tool
(distributed with Lombok) to generate Java source code, then run the
Checker Framework on that. The
\href{https://github.com/kelloggm/checkerframework-gradle-plugin}{Checker
Framework Gradle plugin} does this for you automatically.
\subsectionAndLabel{Maven Projects using Lombok}{lombok-maven}
\href{http://anthonywhitford.com/lombok.maven/lombok-maven-plugin/}{Lombok Maven Plugin}
can be used to delombok source code for Maven projects. The
\href{http://anthonywhitford.com/lombok.maven/lombok-maven-plugin/faq.html#alt-src-setup}
{Lombok Maven Plugin FAQ} discusses how to configure the plugin when code
using Lombok is mixed with standard Java code. Once the Lombok Maven plugin
is configured correctly, the Checker Framework Maven configuration can be added
independently.
\sectionAndLabel{Maven}{maven}
If you use the \href{https://maven.apache.org/}{Maven} tool,
then you can enable Checker Framework checkers by following the
instructions below.
See the directory \code{docs/examples/MavenExample/} for examples of the use of
Maven build files.
This example can be used to verify that
Maven is correctly downloading the Checker Framework from the
\href{https://search.maven.org/search?q=org.checkerframework}{Maven
Central Repository} and executing it.
Please note that the \<-AoutputArgsToFile> command-line option
(see Section~\ref{creating-debugging-options-output-args}) and shorthands for built-in checkers
(see Section~\ref{shorthand-for-checkers}) are not available when
following these instructions. Both these features are available only when a checker is
launched via \<checker.jar> such as when \code{\$CHECKERFRAMEWORK/checker/bin/javac}
is run. The instructions in this section
bypass \<checker.jar> and cause the compiler to run a
checker as an annotation processor directly.
Debugging your Maven configuration can be tricky because of a
\ahreforurl{https://issues.apache.org/jira/browse/MCOMPILER-434}{bug in
maven-compiler-plugin versions before 3.10.1}: Maven does not report
annotation processor exceptions, even when
the \<-X> command-line argument is passed.
\begin{enumerate}
\item Declare a dependency on the Checker Framework artifacts from
Maven Central. Find the
existing \code{<dependencies>} section (not within
\code{<dependencyManagement>}, but somewhere else) and add the following new
\code{<dependency>} items:
\begin{alltt}
<dependencies>
... existing <dependency> items ...
<!-- Annotations from the Checker Framework: nullness, interning, locking, ... -->
<dependency>
<groupId>org.checkerframework</groupId>
<artifactId>checker-qual</artifactId>
<version>\ReleaseVersion{}</version>
</dependency>
</dependencies>
\end{alltt}
Periodically update to the most recent version, to obtain the
latest bug fixes and new features:
\begin{Verbatim}
mvn versions:use-latest-versions -Dincludes="org.checkerframework:*"
\end{Verbatim}
\item If using JDK 8, use a Maven property to hold the location of the
Error Prone \<javac.jar>.
To set the value of these properties automatically, you will use the Maven Dependency plugin.
Add a dependency:
\begin{alltt}