文章结构：
- 1. 什么是 OCLint
- 2. OCLint 安装
- 2.1. Homebrew 安装
- 2.2. 下载并设置下载目录为环境变量
- 2.3. 下载并拷贝至系统环境变量中
- 3. OCLint 工具的组成
- 4. OCLint 的使用
- 4.1. OCLint 结合 xcodebuild 的使用
- 4.1.1. 清理工程（可选）
- 4.1.2. 编译工程，输出编译报告
- 4.1.3. 输出分析结果
- 4.2. 使用 OCLint 分析 Xcode 工程
- 4.1. OCLint 结合 xcodebuild 的使用
- 5. OCLint 与持续集成
- 6. 遇到的问题
- 6.1. PCH 错误
- 6.2. oclint: error: violations exceed threshold
- 7. 引用文档
1. 什么是 OCLint
OCLint 是针对于 C,C++,Objective-C 代码的静态分析工具，目的是提高软件质量并且减少代码中存在的潜在问题，OCLint 旨于分析以下潜在问题：
- 可能出现的 bug：if/else/try/catch 等条件语句空的声明
- 未使用的代码： 未使用的局部变量以及参数
- 复杂的代码逻辑：高循环复杂度、NP 复杂度（懵）、 高 NCSS（懵）
- 冗余代码：冗余的条件表达式以及无效的括号
- 代码嗅觉：方法代码行过长或者参数过多
- 不好的代码习惯：颠倒的逻辑和参数的错误分配
- ...
静态代码分析工具是侦测编译器不可见的潜在缺陷的关键技术。OCLint 具有以下先进的代码检验特性：
- 依靠源码的抽象语法树来提高分析的精确度以及效率，误报率低
- 动态规则
- 灵活可扩展的配置，确保用户可以自定义分析行为
- 命令行式的调用使持续集成成为可能
2. OCLint 安装
下载 OCLint
2.1. Homebrew 安装
确保你已经安装了 Homebrew
$ brew install oclint
近些天使用 Homebrew 安装 OCLint 经常失败，遂放弃了这种安装方式。
2.2. 下载并设置下载目录为环境变量
添加以下代码到命令行启动文件中，默认启动文件是 .bashrc 或 .bash_profile ，安装 oh-my-zsh 后是 .zshrc 文件。
$ OCLINT_HOME=path-to-oclint-release
$ export PATH=$OCLINT_HOME/bin:$PATH
解释：path-to-oclint-release是 OCLint 安装包的路径
使用以下命令判断是否添加环境变量成功
echo $PATH
2.3. 下载并拷贝至系统环境变量中
也可以直接将 OCLint 的可执行文件拷贝至系统文件夹 /usr/local/bin。可以注意到 /usr/local/bin 也在 PATH 中。
cd oclint
cp bin/oclint* /usr/local/bin/
cp -rp lib/* /usr/local/lib/
3. OCLint 工具的组成
OCLint 工具集由一下三部分组成
- oclint
- oclint-json-compilation-database
- oclint-xcodebuild
具体的使用手册还是建议大家去阅读他们的官方文档，其功能可以简单概括为：
-
oclint是 OCLint 工具集最主要的指令，主要作用是规则加载、编译分析选项以及生成分析报告 -
oclint-json-compilation-database的作用是在 JSON Compilation Database format 类型的编译文件compile_commands.json中提取必要的信息。 -
oclint-xcodebuild用于将xcodebuild生成的 log 文件xcodebuild.log转换为JSON Compilation Database format类型
可以使用时序图来概括我们使用这几个指令的场景：
4. OCLint 的使用
4.1. OCLint 结合 xcodebuild 的使用
xcodebuild 命令用来编译 Xcode 工程，xcodebuild 可以编译 Xcode 工程里面的一个或多个 target，也可以用来编译 Xcode workspace 或者 Xcode project 中的任意一个 scheme。
OCLint 结合 xcodebuild 的使用主要分为一下几个步骤
- 使用 xcodebuild clean 清理工程(可选)
- 使用 xcodebuild build 编译工程 并且使用 xcpretty 输出编译文件
- 使用 oclint-json-compilation-database 输出分析结果
4.1.1. 清理工程（可选）
假设一个源文件已经使用 xcodebuild 编译过了，并且没有被修改，那么下次编译的时候改源文件不参与编译，也就是说生成的 compile_commands.json 文件里面是不含有该源文件的内容的。如果你希望该源文件每次都编译，可以使用 xcodebuild clean 指令来清理编译缓存。
然而 clean 过后，编译过程会变得相当漫长，这种现象在大项目中表现最为明显。所以说如果你的项目文件没改动，工程的编译选项也未修改。使用上次的 xcodebuild 和 compile_commands.json 进行分析也是可取的。这里是否可以得出增量编译的条件下，项目中未变动代码的部分是不会出现在新的编译报告中的。
4.1.2. 编译工程，输出编译报告
使用 xcodebuild 命令编译工程，例如使用一下命令编译 OCLintDemo.xcworkspace 下的 OCLintDemo scheme。
xcodebuild -workspace OCLintDemo.xcworkspace \
-scheme OCLintDemo \
-configuration Debug \
-sdks iphonesimulator10.3 \
build
此时就有两种方式生成 compile_commands.json。
方式一：使用 tee 指令获取输出结果为 xcodebuild.log ，使用 oclint-xcodebuild 将 xcodebuild.log 输出为 compile_commands.json 文件
xcodebuild -workspace OCLintDemo.xcworkspace \
-scheme OCLintDemo \
-configuration Debug \
-sdks iphonesimulator10.3 \
build | tee xcodebuild.log
oclint-xcodebuild
方式二：使用 xcpretty 直接将编译结果输出为 compile_commands.json
xcodebuild -workspace OCLintDemo.xcworkspace \
-scheme OCLintDemo \
-configuration Debug \
-sdks iphonesimulator10.3 \
build | xcpretty -r json-compilation-database -o compile_commands.json
推荐使用 xcpretty 的方式生成 json-compilation-database 类型的编译报告。
4.1.3. 输出分析结果
使用 oclint-json-compilation-database 指令来解析 json-compilation-database 类型的编译报告。
$ oclint-json-compilation-database --help
usage: oclint-json-compilation-database [-h] [-v] [-debug] [-i INCLUDES]
[-e EXCLUDES]
[oclint_args [oclint_args ...]]
OCLint for JSON Compilation Database (compile_commands.json)
positional arguments:
oclint_args arguments that are passed to OCLint invocation
optional arguments:
-h, --help show this help message and exit
-v show invocation command with arguments
-debug, --debug invoke OCLint in debug mode
-i INCLUDES, -include INCLUDES, --include INCLUDES
extract files matching pattern
-e EXCLUDES, -exclude EXCLUDES, --exclude EXCLUDES
remove files matching pattern
从引导上来看，oclint-json-compilation-database 可以通过 -e 选项来忽略对制定路径文件的分析，对于使用 Cocoapods 来管理依赖的工程，我们往往会忽略 Pods 文件夹。
oclint-json-compilation-database -e Pods -- xxxx
通常使用 -- 来分割 oclint-json-compilation-database 的参数与 oclint_args。oclint_args 就是 oclint 命令的参数，接下来我们来看看 oclint 指令支持的参数。
$ oclint --help
USAGE: oclint [options] [... ]
OPTIONS:
OCLint options:
-R= - Add directory to rule loading path
-allow-duplicated-violations - Allow duplicated violations in the OCLint report
-disable-rule= - Disable rules
-enable-clang-static-analyzer - Enable Clang Static Analyzer, and integrate results into OCLint report
-enable-global-analysis - Compile every source, and analyze across global contexts (depends on number of source files, could results in high memory load)
-extra-arg= - Additional argument to append to the compiler command line
-extra-arg-before= - Additional argument to prepend to the compiler command line
-list-enabled-rules - List enabled rules
-max-priority-1= - The max allowed number of priority 1 violations
-max-priority-2= - The max allowed number of priority 2 violations
-max-priority-3= - The max allowed number of priority 3 violations
-no-analytics - Disable the anonymous analytics
-o= - Write output to
-p= - Build path
-rc== - Override the default behavior of rules
-report-type= - Change output report type
-rule= - Explicitly pick rules
Generic Options:
-help - Display available options (-help-hidden for more)
-help-list - Display list of available options (-help-list-hidden for more)
-version - Display the version of this program
-p 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.
... 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
如果想最终输出一个 HTML 类型的分析报告，一个完整的 oclint-json-compile-database 指令应该这么写
$ oclint-json-compilation-database -e Pods -- -o=report.html
4.2. 使用 OCLint 分析 Xcode 工程
Using OCLint with Xcode
5. OCLint 与持续集成
6. 遇到的问题
6.1. PCH 错误
Compiler Errors: (please be aware that these errors will prevent OCLint from analyzing this source code) :0:0: input is not a PCH file: '/xxx/PrefixHeader.pch.pch' :0:0: file '/xxx/PrefixHeader.pch.pch' is not a valid precompiled PCH file :0:0: input is not a PCH file: '/xxx/PrefixHeader.pch.pch' :0:0: file '/xxx/PrefixHeader.pch.pch' is not a valid precompiled PCH file OCLint Report Summary: TotalFiles=0 FilesWithViolations=0 P1=0 P2=0 P3=0 [OCLint (http://oclint.org) v0.12]
没找到问题原因，目前只知道将编译选项 Precompile prefix header 设置为 NO 可以解决问题。
6.2. oclint: error: violations exceed threshold
运行 oclint-json-compilation-databse 以下错误
$ oclint-json-compilation-database -e Pods -- -o=report.html
oclint: error: violations exceed threshold
P1=0[0] P2=1637[10] P3=53904[20]
出现这个的原因是项目中的 issue 超过了限制，使用以下 option 来约定最大的 issue 阈值。
-max-priority-1=9999 -max-priority-2=9999 -max-priority-3=9999
7. 引用文档
OCLint Documentation
Using OCLint with xcodebuild
Using OCLint with Xcode
oclint-json-compilation-database
json-compilation-database