This page documents several ways of running Infer, that you can adapt to your own project.
- Make sure your project is clean when you first run Infer on it (with
make clean, or
gradle clean, or ...).
- When running Infer several times in a row, either clean your project as in
step 1 in-between Infer runs, or add
- These steps are not needed if you are not using an incremental build system,
for instance if you are analyzing single files with
infer run -- javac Hello.java.
- After a successful Infer run, you can explore Infer's reports in more details
infer-explorefrom the same directory.
The two phases of an Infer run
Regardless of the input language (Java, Objective-C, or C), there are two main phases in an Infer run:
1. The capture phase
Compilation commands are captured by Infer to translate the files to be analyzed into Infer's own internal intermediate language.
This translation is similar to compilation, so Infer takes information from the
compilation process to perform its own translation. This is why we call infer
with a compilation command:
infer run -- javac File.java or
infer run -- clang -c file.c. What happens is that the files get compiled as
usual, and they also get translated by Infer to be analyzed in the second phase.
In particular, if no file gets compiled, also no file will be analyzed.
Infer stores the intermediate files in the results directory which by default is
created in the folder where the
infer command is invoked, and is called
infer-out/. You can change the name of the results directory with the option
infer run -o /tmp/out -- javac Test.java
You can run just the capture phase using the
capture subcommand instead of the
infer capture -- javac Test.java
2. The analysis phase
In this phase, the files in
infer-out/ are analyzed by Infer. Infer analyzes
each function and method separately. If Infer encounters an error when analyzing
a method or function, it stops there for that method or function, but will
continue the analysis of other methods and functions. So, a possible workflow
would be to run Infer on your code, fix the errors generated, and run it again
to find possibly more errors or to check that all the errors have been fixed.
The errors will be displayed in the standard output and also in a file
infer-out/report.txt. We filter the bugs and show the ones that are most
likely to be real.
Global (default) and differential workflows
By default, running Infer will delete the previous
infer-out/ directory if it
exists. This leads to a default workflow where the entire project is analyzed
every time. Passing
-r) to Infer prevents it from deleting
infer-out/, leading to a differential workflow.
There are exceptions to this. In particular, you can run only one of the phases
above. For instance,
infer run -- javac Hello.java is equivalent to running
these two commands:
infer capture -- javac Hello.javainfer analyze
Notice that the second command does not erase
infer-out/, as the files it
needs to analyze live there!
You can learn more about the subcommands supported by Infer by running
infer capture --help, or more generally
infer <subcommand> --help.
Let us highlight when you may need global and differential workflows.
The global workflow is well suited to running Infer on all the files in a
project, e.g., for a Gradle-based project that compiles using the
infer run -- gradle build
In general, running Infer on your project is as simple as running
infer run -- <your build command here> where the build command is the one you
would normally use to compile your source code.
To start a fresh analysis and be sure to analyze all the files in your project,
you have to clean the build products, for instance with
make clean for a
gradle clean for Gradle, etc.
Software projects such as mobile apps use incremental build systems, where code evolves as a sequence of code changes. For these projects, it can often make sense to analyze only the current changes in the project, instead of analyzing the whole project every time. It is possible to analyze only what's changed using Infer's reactive mode.
Infer should first be run on a clean version of the project, to capture all the compilation commands in its capture phase.
For instance, for a project compiled using Gradle,
gradle cleaninfer capture -- gradle build
Note that the above command does not perform an expensive analysis, but captures all the compilation commands and stores the results in Infer's internal format.
Next, if you change some files in your project, for instance in response to an Infer report, or as part of normal development, you can either clean and reanalyze the entire project (as in the global workflow above), or else tell Infer that you are interested in the effects of the code change. The second option can be significantly faster, as only a subset of the project needs to be analyzed: the modified files/procedures and their dependencies.
edit some/File.java# make some changes to some/File.javainfer run --reactive -- gradle build
Note that you can run Infer with the
--reactive flag the first time around as
To control the granularity of the changes to be analyzed, it is possible to tell
Infer to combine several changes into one before the analysis. This is done with
edit some/File1.java# make some changes to some/File1.javainfer run --reactive -- gradle buildedit some/File2.java# make some changes to some/File2.javainfer run --reactive --continue -- gradle build
After the first invocation, Infer will analyze the results of the first change.
After the second invocation, Infer will analyze the results of both changes. If
--continue option were omitted, it would only analyze the results of the
Finally, it is always possible to perform an analysis of the current changes in isolation:
infer run --reactive --continue -- analyze
The list of build systems supported by Infer is detailed in the next section.
Exploring Infer reports
You can get more information about the reports generated by Infer by running
infer-explore in the same directory. For instance
infer run -- gradle buildinfer-explore
This tool allows you to see error traces leading to each bug reported by Infer,
which can be helpful in tracking down the precise cause of each bug. See the
infer-explore --help for more information.