OCLint

Using oclint

When you invoke OCLint, it normally does rule loading, compilation, analysis, and report generation. The options allow you to change the behavior of each step to certain ways that meet your requirement.

See all supported options in OCLint 0.6 by typing oclint -help:

USAGE: oclint [options] <source0> [... <sourceN>]

OPTIONS:
  -R=<directory>              - Add directory to rule loading path
  -fatal-assembler-warnings   - Consider warnings as error
  -help                       - Display available options (-help-hidden for more)
  -max-priority-1=<threshold> - The max allowed number of priority 1 violations
  -max-priority-2=<threshold> - The max allowed number of priority 2 violations
  -max-priority-3=<threshold> - The max allowed number of priority 3 violations
  -o=<path>                   - Write output to <path>
  -p=<string>                 - Build path
  -rc=<paramemter>=<value>    - Override the default baheviour of rules
  -stats                      - Enable statistics output from program
  Choose report type:
    -text                     - Plain text report
    -html                     - HTML formatted report
  -version                    - Display the version of this program

-p <build-path> is used to read a compile command database.

    For example, it can be a CMake build directory in which a file named
    compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
    CMake option to get this output). When no build path is specified,
    a search for compile_commands.json will be attempted through all
    parent paths of the first input file . See:
    http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
    example of setting up Clang Tooling on a source tree.

<source0> ... specify the paths of source files. These paths are
    looked up in the compile command database. If the path of a file is
    absolute, it needs to point into CMake's source tree. If the path is
    relative, the current working directory needs to be in the CMake
    source tree and the file must be in a subdirectory of the current
    working directory. "./" prefixes in the relative files will be
    automatically removed, but the rest of a relative path must be a
    suffix of a path in the compile command database.

For more information, please visit http://oclint.org

Rule Loading Options

-R <directory>
Rule loading path can be changed by using -R option. Multiple rule loading paths can be specified to load rules from more than one directories. By default, OCLint searches $(/path/to/bin/oclint)/../lib/oclint/rules for the dyanmic libraries that contain rules.
-rc <paramemter>=<value>
Certain rules have threshold to decide whether to emit violations. These thresholds can be changed by -rc option with a key-value pair.

More detail on changing the behavior in rules loading process during runtime can be found in customizing rules page.

Compilation Options

OCLint needs to know the specific compiler options for the sources that are being inspected. There are two alternatives, specifying the compiler options or using compile commands database.

Giving Compiler Options

Compiler options can be given directly to OCLint for compilation process. It’s straight forward that, after all OCLint options and sources, append -- separator followed by all compiler options:

oclint [oclint options] <source0> [... <sourceN>] -- [compiler options]

For example, if you are compiling a file named by following command:

clang -x objective-c -arch armv7 -std=gnu99 -fobjc-arc -O0 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS6.0.sdk -g -I./Pods/Headers -c RPActivityIndicatorManager.m

(Wow, it’s longer than expectation.)

Then when you analyze this code, your OCLint command will be:

oclint [oclint options] RPActivityIndicatorManager.m -- -x objective-c -arch armv7 -std=gnu99 -fobjc-arc -O0 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS6.0.sdk -g -I./Pods/Headers -c

Compile Commands Database

-p <build-path>
Choose the build directory in which a file named compile_commands.json exists. When no build path is specified, a search for compile_commands.json will be attempted through all parent paths of the first input file.

OCLint requires this compilation database to understand specific build options for each file. Currently it supports compile_commands.json file. See oclint-json-compilation-database for detail. If you are working with Xcode, oclint-xcodebuild can generate the required compile_database.json file for you with your little help.

Inspection Options

Of course, specify all the source files you want to inspect. Multiple files can be analyzed with one invocation.

Report Options

-o <path>
Instead of piping output to console, -o will redirect the report to the <path> you specified.
-text
Use plain text report, this is the default
-html
Use HTML report for better readability

See customizing reports for detail.

Exit Status Options

-max-priority-1 <threshold>
The max allowed number of priority 1 violations
-max-priority-2 <threshold>
The max allowed number of priority 2 violations
-max-priority-3 <threshold>
The max allowed number of priority 3 violations

This option helps in continuous integration and other build systems. When the number of violations in one of these priorities is larger than the maximum tolerance, OCLint will return with an exit status code other than 0 (code zero means normal termination) to notify a high volume of violations. By default, less than 20 priority 3 violations are allowed, 10 violations is maximum for priority 2, and no priority 1 violation can be tolerated. Too many violations result in bad code quality, if that happens, OCLint return with an exit code of 3.

OCLint returns with one of the four exit codes below

  • 0 - SUCCESS
  • 1 - RULE_NOT_FOUND
  • 2 - ERROR_WHILE_PROCESSING
  • 3 - VIOLATIONS_EXCEED_THRESHOLD

Other Options

-version
Show version information about OCLint, LLVM and some environment variables.