1、OCLint是什么
OCLint 是基于LLVM/Clang（前端编译）而开发的代码静态分析工具，是针对于 C,C++,Objective-C 代码的静态分析工具，目的是提高软件质量并且减少代码中存在的潜在问题。官方文档：https://oclint-docs.readthedocs.io/en/stable/
2、OCLint安装
推荐使用 Homebrew安装：brew install oclint
3、OCLint工作流程`
OCLint流程.png
4、OCLint指令`
4.1、OCLint有三个指令：oclint，oclint-json-compilation-database，oclint-xcodebuild。
- oclint：核心指令，通过这个指令可以指定加载验证规则、编译代码、分析代码和生成报告。
- oclint-json-compilation-database：从编译好的compile_commands.json文件中读取配置信息并执行oclint。
- oclint-xcodebuild：通过这个指令可以从 Xcode 的 xcodebuild.log 文件导出编译选项并保存成 JSON Compilation Database 格式。然后把保存到 compile_commands.json 文件中(OCLint team好久不维护了，采用xcpretty替换)。
4.2、oclint指令的使用：
- -R <目录>：指定规则加载的目录。可以是多个目录，用空格隔开，默认情况下会搜索
$(oclint 可执行文件目录)/../lib/oclint/rules。 - -disable-rule <规则名> 通过规则名使某些验证规则失效。
- -rc <参数>=<值> 修改某些阈值。
4.2.1、下面是一个简单的示例，表示从/path/to/rules加载规则，然后使 GotoStatement这个验证规则失效。
oclint -R /path/to/rules -disable-rule GotoStatement
4.2.2、然后来看一下阈值，下面是 OCLint 里面一些常见的阈值：
| 名称 | 描述 | 默认值 |
|---|---|---|
| CYCLOMATIC_COMPLEXITY | 循环嵌套数限制 | 10 |
| LONG_CLASS | 类行数限制 | 1000 |
| LONG_LINE | 每行的字符限制 | 100 |
| LONG_METHOD | 方法行数限制 | 50 |
| LONG_VARIABLE_NAME | 参数名字符限制 | 20 |
| MAXIMUM_IF_LENGTH | if 的行数限制 | 15 |
| MINIMUM_CASES_IN_SWITCH | switch case 的最小数目 | 3 |
| NPATH_COMPLEXITY | 通过该方法的非循环执行路径数量限制 | 200 |
| NCSS_METHOD | 连续未注释行数限制 | 30 |
| NESTED_BLOCK_DEPTH | block 嵌套层数限制 | 5 |
| SHORT_VARIABLE_NAME | 变量名的最小字符数限制 | 3 |
| TOO_MANY_FIELDS | 类成员限制 | 20 |
| TOO_MANY_METHODS | 类方法数限制 | 30 |
| TOO_MANY_PARAMETERS | 参数个数限制 | 10 |
4.2.3、生成报告选项
-
-o <目录>：指定报告的输出目标。
-
-report-type <类型名>：指定报告输出的类型。默认是普通文本。
报告输出的类型有如下几种：
-
Plain Text Report(text)
-
HTML Report(html)
-
XML Report(xml)
-
JSON Reporter (json)
-
PMD Reporter (pmd)：这种类型主要提供给 CI 系统使用，在 CI 系统的展示会更友好。
-
Xcode Reporter (xcode)：主要提供给 Xcode 内查看。
同样，我们也可以把这个配置加入到 .oclint 文件中：
report-type: htmloutput: oclint.html
4.2.4、退出状态选项
-
-max-priority-1 <阈值>
-
-max-priority-2 <阈值>
-
-max-priority-3 <阈值>
首先我们来看一下 OCLint 会返回的 5 种退出 Code：
-
0 - SUCCESS：成功。
-
1 - RULE_NOT_FOUND：没有找到验证规则。
-
2 - REPORTER_NOT_FOUND：没有指定报告输出地址。
-
3 - ERROR_WHILE_PROCESSING：验证过程中出错。
-
4 - ERROR_WHILE_REPORTING：生成报告时出错。
-
5 - VIOLATIONS_EXCEED_THRESHOLD：违反规则的次数超出阈值。
然后我们来看一下各个优先级默认的阈值：优先级 3 的阈值为 20；优先级 2 的阈值为 10；优先级 1 的阈值为 0。如果超过了其中任意一个阈值，就表示你的代码质量是不达标的，然后 OCLint 会返回 VIOLATIONS_EXCEED_THRESHOLD。
4.2.5、全局分析选项
- -enable-global-analysis
开启这个选项可以得到更准确的分析结果，但是相对耗时比较长，一般不采用。
4.2.5、Clang 静态分析选项
- -enable-clang-static-analyzer
如果开启这个选项，OCLint 会 hook Clang 的编译过程，然后收集编译信息然后添加到报告中。需要注意的是：这也会增加分析的时间。
4.2.6、Debug 选项
- -debug
开启这个选项会给出更详细的信息。但是这个选项只有在 OCLint 的 debug 标示开启的时候才有效。
4.3、oclint-json-compilation-database指令的使用
4.3.1、过滤选项
-
-i INCLUDES
-
-e EXCLUDES
这两个选项是指在 compile_commands.json 文件中配置的基础上添加一些文件/目录来执行 oclint，或者让一些文件/目录不执行 oclint。
比如，我们一般不对第三方库执行 oclint ，这个时候可以用下面的指令来把 Pods 目录排除：
<pre class="line-numbers language-ruby" style="margin: 0px; padding: 0px; font-family: ConfluenceInstalledFont, monospace;">
oclint-json-compilation-database -e Pods</pre>
4.3.2、oclint的选项
可以通过 --的方式在指令的最后 oclint 选项。比如：
oclint-json-compilation-database -e Pods -- -o=report.html
在最后添加了一个 oclint 的 -o 选项，表示将报告输出到当前目录的 report.html 文件中。
4.3.3、调试选项
-
-v：通过这个选项可以输出最终执行的 oclint 指令。
-
-debug：开启这个选项会给出更详细的信息。但是同样这个选项只有在 OCLint 的 debug 标示开启的时候才有效。
4.4、oclint-xcodebuild
这个命令是给使用 Xcode 的用户提供的。主要用于分析 xcodebuild.log 文件，然后快速生成 compile_commands.json 文件。该指令已经不委会了，改用 xcpretty。
4.4.1、安装xcpretty
其实只需要执行下面指令即可:
gem install xcpretty
4.4.2、使用xcpretty生成compile_commands.json文件
通过下面的指令即可生成 compile_commands.json文件：
xcodebuild [flags] | xcpretty -r json-compilation-database -o compile_commands.json
如果想保存 xcodebuild.log，可以换成下面的指令：
xcodebuild [flags] | tee xcodebuild.log | xcpretty -r json-compilation-database -o compile_commands.json
然后就可以执行 oclint-json-compilation-database来进行验证了。
4.4.3、使用xcbuild生成compile_commands.json文件
使用如下指令即可生成 compile_commands.json文件
xcbuild [flags] | xcpretty -r json-compilation-database -o compile_commands.json
事实上xcbuild和xcodebuild的指令是完全兼容的。
5、jenkins接入
5.1、编写oclint脚本
OCLint大概的执行流程：
- Clean工程
- Clang编译工程生成xcodebuild.log
- xcpretty转化log为json文件：xcpretty -r json-compilation-database -o compile_commands.json
- oclint-json-compilation-database根据设置的规则分析生成报告
脚本如下：
#!/bin/bash -il
source ~/.bashrc
myworkspace=xxx.xcworkspace
myscheme=xxx
# clean cache
rm -rf ~/Library/Developer/Xcode/DerivedData/;
rm compile_commands.json;
rm oclint_result.xml;
# clean -- build -- OCLint analyse
echo 'start analyse';
xcodebuild -workspace $myworkspace -scheme $myscheme clean&&
xcodebuild -workspace $myworkspace -scheme $myscheme \
-configuration Debug GCC_PRECOMPILE_PREFIX_HEADER=YES CLANG_ENABLE_MODULE_DEBUGGING=NO COMPILER_INDEX_STORE_ENABLE=NO \
-destination 'platform=iOS Simulator,name=iPhone X' \
| xcpretty -r json-compilation-database -o compile_commands.json&&
oclint-json-compilation-database -e Pods -e node_modules -- \
-report-type pmd \
-rc LONG_LINE=300 \
-rc LONG_METHOD=200 \
-rc LONG_VARIABLE_NAME=40 \
-rc LONG_CLASS=3000 \
-max-priority-1=1000 \
-max-priority-2=1000 \
-max-priority-3=2000 \
-disable-rule=UnusedMethodParameter \
-disable-rule=AvoidPrivateStaticMembers \
-disable-rule=ShortVariableName \
-allow-duplicated-violations=false >> oclint_result.xml; \
echo 'end analyse';
# echo result
if [ -f ./oclint_result.xml ];
then echo 'done';
else echo 'failed';
fi
5.2、脚本分析
- -e
需要忽略分析的文件，这些文件的警告不会出现在报告中 - -rc
需要覆盖的规则的阀值，这里可以自定义项目的阀值，默认阀值 - -enable-rule
支持的规则，默认是oclint提供的都支持，可以组合-disable-rule来过滤掉一些规则
规则列表 - -disable-rule
需要忽略的规则，根据项目需求设置 - -report-type
分析的报告的类型，支持[text、html、xml、json、pmd]，差异可见对应Sample；
一般会选择可读性好的html或者pmd；这里我们选取pmd类型，用于结合PMD analysis生成PMD warnings，能比较友好的在Jenkins的看板中展示出来。
5.3、执行分析
打开终端，cd到oclint.sh所在的目录，执行
chmod 777 oclint.sh && ./oclint.sh
最终在同级目录下会生成compile_commands.json和oclint_result.xml
-
compile_commands.json -- xcpretty将原始的xcodebuild.log转为json格式的json-compilation-database -
oclint_result.xml--oclint生成的分析报告
5.4、集成到Jenkin
5.4.1、添加一个执行shell的流程，将执行分析的脚本执行
执行shell.png
5.4.2、构建完成生成pmd报告,需要在Jenkins插件管理中安装PMD，推荐使用“Warnings Next Generation Plugin”
报告分析.png
5.4.3、扫描结果展示
6、遇到的问题：
问题1：oclint: error: cannot open report output file xxxxxxx
解决方案：使用 >> 命令 替代 -o 命令，例如：
使用 ">> oclint_result.html" 代替 '-o oclint_result.html'，比如：
oclint-json-compilation-database -e Pods -e React
-- -report-type html
-rc LONG_LINE=200
-rc LONG_VARIABLE_NAME=30
-disable-rule ShortVariableName
-max-priority-1=100000
-max-priority-2=100000
-max-priority-3=100000 >> oclint_result.html
问题2：oclint: error: compilation contains multiple jobs
解决方法：
第一步：在podfile文件中添加
post_install do |pi|
pi.pods_project.targets.each do |t|
t.build_configurations.each do |config|
config.build_settings['COMPILER_INDEX_STORE_ENABLE'] = "NO"
end
end
end
第二步：修改工程
修改工程.png
7、其他&思考
1、问题默认优先级只有三个等级，似乎无法轻易修改，自定义规则时也只能在三个等级中选一个。
2、其他代码扫描工具是否能覆盖更多场景，是否有更智能的检测？比如判定编码可能导致内存泄露。
3、OCLint默认规则中对代码编写格式的要求机会没有，例如方法名、变量名驼峰写法，括号和换行的要求，空格的使用等
4、当前版本（OCLint version 21.03）共72条规则，部门内部的开发规范的大部分规则无法覆盖。
5、作为功能更加全面，支持语言更多的coverity，是否在objective-c扫描上表现更加出色？
网友评论