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 里面一些常见的阈值：

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: html
• output: 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扫描上表现更加出色？