├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Developer.Lx 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # FauxPas_document_translation 2 | 3 | #### 原文：[http://fauxpasapp.com/docs](http://fauxpasapp.com/docs) 4 | #### 翻译：[DeveloperLx](http://weibo.com/DeveloperLx) 5 | 6 | # 文档 7 | --- 8 | # 目录 9 | > #### 检查一个Xcode项目 10 | > 选择执行哪些规则 11 | > #### 使用命令行接口（CLI） 12 | > #### 配置 13 | > 项目特定的配置文件 14 | 15 | > 配置建议 16 | > #### 过滤诊断 17 | > #### 制止诊断（Suppressing Diagnostics） 18 | > 在代码中制止诊断 19 | 20 | > 在指定的文件或目录制止诊断 21 | 22 | > 从检查中排除指定的文件、目录或Xcode组 23 | > #### 启动FauxPas的快捷方式 24 | > 在FaxuPas图形界面工具（GUI）中快速地打开活跃的Xcode项目 25 | 26 | > 在Xcode build过程中执行检查 27 | 28 | > 在Xcode中手动调用FauxPas 29 | > #### 使用定制的脚本处理诊断 30 | > 发布（Emitting）机器可读的输出 31 | 32 | > 机器可读的输出的结构 33 | 34 | > 处理机器可读的输出 35 | > #### 处理故障 36 | > 当使用Xcode编译我的项目时，FauxPas给出了一些我不理解的编译错误 37 | 38 | > FauxPas没有成功地检查项目 39 | 40 | > 我安装了多个版本的Xcode；怎样确保FauxPas使用了我想用的那一个 41 | 42 | --- 43 | ## 检查一个Xcode项目 44 | > FauxPas执行检查在**Xcode项目**中的**单个target**上，使用单个的**项目配置**。在最简化的情况下，项目必须被指定————如果没有被指定的话，FauxPas就会选择一个默认的target和build配置。 45 | 46 | ### 选择哪些规则去执行 47 | > 可以通过标签或单独地选择规则。单独的规则也可以被排除。排除的动作将被最后实施，所以如果你排除了一个因选择标签而选择的规则，这条规则将不会被执行。 48 | 49 | #### 图形界面工具： 50 | * 在规则选择视图中，通过点击它们的名称来选择标签（规则将通过它们的标签被选择，然后显示一个勾的标记在它们的左边，替换单独地选择勾选框） 51 | * 选择单独的规则 - 勾选紧挨着它们的框 52 | * 排除单独的规则 - 通过右击（或command+点击）列表中的一个规则，选择（排除规则） 53 | 54 | #### 命令行： 55 | * 使用 -g/--ruleTags 来选择有指定标签的全部的规则 56 | * 使用 -r/--rules 来选择单独的规则 57 | * 使用 --excludedRules 来排除单独的规则 58 | 59 | > **建议：尽可能地通过标签来选择规则和避免选择单独的规则。然后排除任何你不想要的规则。当FauxPas更新时在你已选的标签下有了新的规则，这个新规则就会被自动地选中。** 60 | 61 | > 在命令行中，你也可以使用--onlyRules参数来仅仅执行指定的规则，这会覆盖全部的其它的规则选择选项。当你的项目有一个指定的配置文件（带有规则和标签选择及规则排除），而你又想临时地覆盖掉时，上述操作是非常方便的。 62 | 63 | ## 使用命令行接口 64 | > 为了通过命令行使用FauxPas，你必须首先安装fauxpas命令： 65 | * 图形用户界面：从应用菜单中选择 FauxPas > Install CLI Tools... 菜单项。 66 | * 命令行：执行命令： 67 | 68 | ``` 69 | /Applications/FauxPas.app/Contents/Resources/install-cli-tools 70 | ``` 71 | 72 | > 这将安装fauxpas命令到/usr/local/bin，当然你也可以移动它到其它你希望的地方。 73 | 74 | > 在终端执行 fauxpas help，可以查看命令行接口的文档。 75 | 76 | ## 配置 77 | > FauxPas可以通过下列方式进行配置： 78 | 79 | * 命令行参数（如果你使用命令行接口） 80 | * 图形界面工具 81 | * 配置文件 82 | 83 | > 配置文件可以使用JSON来编写。查看一个完整的示例配置文件，可以在终端执行执行 fauxpas exampleConfig（**注意这要求命令行接口工具必须被安装**）。 84 | > 当使用命令行接口时，可以通过 -c/--configFile 参数选取配置文件。 85 | 86 | ### 项目指定配置文件 87 | > 引用一个项目指定的配置文件，可以通过添加它到一个在项目根目录下（与.xcodeproj目录所在在的相同目录），名为FauxPasConfig的目录下，它的扩展名为.fauxpas.json. 这个文件也可以存在在其它地方，只要它的扩展名如同上述，并且你的Xcode项目包含一个指向它的引用。 88 | 89 | > 如果有多个配置文件在FauxPasConfig目录下，则默认使用名为main.fauxpas.json的那个。 90 | 91 | > 项目指定的配置文件将被自动选取，无论在命令行接口或在图形界面工具的调用时。 92 | 93 | ### 配置建议 94 | > 很多FauxPas的配置选项会影响它检查你的项目的时间。对于大多数Xcode项目，默认是一个尝试有利于平衡速度和兼容性的配置；对于你特定的项目，为了提高检查速度，调整一些选项，也是OK的。 95 | 96 | > 这里有一些可以帮助你检查项目速度更快的建议： 97 | 98 | * 避免选择workspace和scheme。假如你想检查的项目可以被独立地build（也就是说不用作为一个workspace的一部分来build），请设置**“Xcode workspace to build project with”**和**“Xcode scheme to build project with”**选项不被选中。 99 | * 避免执行完全build（full builds）。如果**“Build project before checking”**选项关闭，FauxPas可以更快地开始坚持你的项目。有时这个选项是必须被打开的（例如如果项目在build过程中会生成头文件），但是对于大多数项目可以安全地关闭这个选项。 100 | * 仅仅处理指定target的PCHs。如果**“Process only target precompiled headers”**选项是打开的，FauxPas可以更快地开始坚持你的项目。有时这个选项必须被关闭，但是对于大多数项目，它是可以安全地被打开的。 101 | * 选择仅仅一个架构（architecture）。如果你的项目通常是在多个中央处理器架构（CPU architectures）上build的，你可以通过限制FauxPas引发的build，去调用仅仅一个架构，来提升FauxPas的速度。你可以通过在**“Additional xcodebuild arguments to use”**选项上添加一个ARCHS build设置的值（例如ARCHS=armv7）来实现。 102 | 103 | ## 过滤诊断 104 | > 在图形界面工具中，“Diagnostics”视图有一个文本输入框，它允许你输入一些过滤器来只展示相应匹配过滤器的诊断。 105 | 106 | > 你可以添加多个过滤器，它们将一个接一个地被全部执行。 107 | 108 | > 支持下列过滤器： 109 | 110 | * 文件：仅展示匹配文件的诊断。可能会用到通配符\*。例如：file=foo.m 或 file=\*ViewController.m 111 | * 规则：仅展示匹配规则的诊断。例如：rule=Dot syntax usage 112 | * 效果（Impact）：仅展示指定效果（Functionality, Maintainability, Style）的诊断。例如：impact=Functionality 113 | * 靠谱程度（Confidence）：仅展示指定靠谱程度(Absolute, High, Medium, Low)的诊断。例如：confidence=High 114 | * 严重程度：仅展示指定严重程度(Error, Warning, Concern)的诊断。例如：severity=Error 115 | 116 | ## 制止诊断 117 | > 如果通过一个特定的规则，你没有得到任何有用的诊断，或者不同意这条规则的基本前提，只需从被执行的规则中排除这条即可。 118 | 119 | ### 在代码中制止诊断 120 | > 如果你想保持一个规则打开，但在你代码中一个特定区域中制止它的诊断，你可以使用定义在头文件FauxPasAnnotations.h中的宏来解决。 121 | 122 | > 要添加上述的头文件到你的项目中，按下面的做： 123 | 124 | * 运行FauxPas图形界面工具 125 | * 打开你的工程 126 | * 选择 Project > Add Annotations Header… 菜单项 127 | > 关于怎样使用那些宏，更多的说明包含在自身这个头文件之中。 128 | 129 | ### 在特定的文件或目录中制止诊断 130 | > 在FauxPas中，每条规则都有一个名叫“Regexes for ignored file paths”的选项。这个选项可以被用来制止在这条规则下，全部的匹配它指定的正则表达式的文件路径。 131 | 132 | ### 从检查中排除指定的文件、目录或Xcode组 133 | > 如果你想从被FauxPas检查的地方，排除匹配特定样式的文件，你可以使用下列选项： 134 | 135 | * 排除文件的正则表达式：[--fileExclusionRegexes] 136 | * 排除文件的前缀：[--fileExclusionPrefixes] 137 | * 排除的Xcode组：[--fileExclusionXcodeGroups] 138 | 139 | > 注意这些选项不仅仅在匹配的文件中制止诊断：它们完全从检查开始就已被排除。 140 | 141 | ## 启动FauxPas的快捷方式 142 | ### 在FauxPas图形界面工具中快速打开活动的Xcode项目 143 | > 在FauxPas图形界面工具中，你可以使用open命令打开一个指定的Xcode项目。 144 | 145 | > 使用一个简短的AppleScript片段来从Xcode中获取当前活动的项目的路径： 146 | 147 | ``` 148 | open -a FauxPas "`osascript -e 'tell application \"Xcode\" to return path of active project document'`" 149 | 150 | ``` 151 | 152 | > 你可以为此使用一个协助应用（像是Keyboard Maestro, FastScripts或Spark）来指定一个全局的热键。 153 | 154 | ### 在Xcode build期间执行检查 155 | > FauxPas可以在Xcode的build phase中被执行。你可以在Xcode图形界面工具中看到它产生的诊断结果，并且轻松地跳转到相应的文件位置中。这个方法也允许FauxPas打断build，通过返回一个非零的退出状态（by returning a nonzero exit status）（--minErrorStatusSeverity这个选项可以被用来控制FauxPas返回错误退出状态的条件）。 156 | 157 | * 确保你的FauxPas命令行接口已安装 158 | * 在Xcode你的项目中，为你期望检查的target创建一个新的“Run Script” build phase 159 | * 添加下列内容作为脚本： 160 | 161 | ``` 162 | [[ ${FAUXPAS_SKIP} == 1 ]] && exit 0 163 | 164 | FAUXPAS_PATH="/usr/local/bin/fauxpas" 165 | if [[ -f "${FAUXPAS_PATH}" ]]; then 166 | "${FAUXPAS_PATH}" check-xcode 167 | else 168 | echo "warning: Faux Pas was not found at '${FAUXPAS_PATH}'" 169 | fi 170 | ``` 171 | 172 | > 有了这个脚本之后，FauxPas检查将在build过程中被执行，除非FAUXPAS_SKIP这个build设置被赋值为1。 173 | 174 | ### 在Xcode中手动调用FauxPas 175 | > 要想在Xcode中手动运行FauxPas: 176 | 177 | * 确保你的FauxPas命令行接口已安装 178 | * 创建一个新的名为“Faux Pas”的Aggregate target到你的项目中 179 | * 给“Faux Pas”这个target创建一个名为“Run Faux Pas”的新的“Run Script” build phase 180 | * 添加下列内容作为其脚本，用你项目实际的名称替代PROJECT_NAME： 181 | 182 | ``` 183 | /usr/local/bin/fauxpas -o xcode check "PROJECT_NAME.xcodeproj" 184 | ``` 185 | 186 | > 现在你可以通过build “Faux Pas”scheme 来调用FauxPas。 187 | 188 | ## 使用定制的脚本处理诊断 189 | > 如果你想编写自己的脚本来处理FauxPas给出的诊断，你必须首先让它产生机器可读的输出。 190 | 191 | ### 给出机器可读的输出 192 | > 在命令行接口中，--outputFormat (或 -o) 参数允许你指定诊断的标准输出的格式。可选的值如下： 193 | 194 | * human —— 人类可读的输出（缺省） 195 | * json —— json输出 196 | * plist —— 属性列表输出（当前这个输出作为一个XML列表） 197 | * xcode —— 能够被Xcode理解的，基于行的输出。当你使用 check-xcode 命令时，它是默认的选项，它可以让Xcode以错误和警告的形式来展示诊断。 198 | 199 | > 在图形界面工具中，你可以在诊断视图中，按Export Diagnostics…按钮，以上述任意格式来保存诊断到一个文件中。 200 | 201 | ### 机器可读的输出的结构 202 | > 对于全部机器可读的格式，它的实际诊断的结构都是相同的————仅仅是序列化输出的变量（serialization format varies）不同（仅存在的例外，是由于属性列表域中没有“null”的值，因此这些域只是简化给出）。 203 | 204 | > 根对象有下列域： 205 | 206 | * fauxPasVersion —— FauxPas用来生成输出的版本 207 | * timeStamp —— 当给出输出时的一个unix时间戳 208 | * projectPath —— .xcodeproj目录的文件系统路径（filesystem path） 209 | * projectName —— 被检查的Xcode项目的名称 210 | * targetName —— 在Xcode项目中被检查的target 211 | * targetBundleVersion —— 被检查target的Info.plist中，CFBundleVersion的值 212 | * buildConfigurationName —— Xcode使用的build配置的名称 213 | * projectIconBase64PNG —— 项目的64位编码的PNG的图标（展示在FauxPas图形界面工具上）（120✖️120像素） 214 | * versionControlSystemName —— 项目用到的版本控制系统的名称 215 | * versionControlRevision —— 当前版本控制系统的版本标识（当前仅支持Git） 216 | * diagnostics —— 一个诊断对象的数组 217 | 218 | > 诊断对象有下列域： 219 | 220 | * ruleShortName —— 给出诊断的规则的简短的名称 221 | * ruleName —— 给出诊断的规则的全称 222 | * ruleDescription —— 给出诊断的规则的全部描述 223 | * ruleWarning —— 对于一些规则，关联到产生的诊断的人类可读的警告 224 | * info —— 对于诊断的人类可读的信息 225 | * html —— 一个包含上述所有键的字典，且带有HTML格式的值 226 | * identifier —— 被每条规则选择的一个任意的值，通常用来指出诊断指向的那部分数据（例如： Missing Translation 这个规则，将指出可能缺失的字符串资源的键） 227 | * file —— 诊断指向的文件的全路径 228 | * context —— 诊断指向的那段代码的parent代码标记（a “parent” code symbol） 的名称或标记（例如：一个函数，方法或类） 229 | * extent —— 诊断指向的文件的位置的标记 230 | 231 | ``` 232 | start和end，都有下列的结构 233 | line —— 行号 234 | byteColumn —— 每行以字节为单位的列 235 | byteOffset —— 以字节为单位的相对于文件开头的偏移量 236 | utf16Column —— 每行以UTF-16为单位的列 237 | utf16Offset —— 以UTF-16为单位的相对于文件开头的偏移量 238 | ``` 239 | * fileSnippet —— 诊断指向文件的段的内容 240 | * impact —— 这个诊断描述的问题的基本影响（Impact），应当是（functionality, maintainability or style） 241 | * severity —— 诊断的严重程度（一个[0-10]的整数值，较高的值表明较高的严重程度。3是“concern”，5是“warning”，9是“error”。） 242 | * severityDescription —— 对于severity的文字描述 243 | * confidence —— 我们认为的这个诊断的靠谱程度（一个[0-10]的整数值，较高的值表明较高的靠谱程度） 244 | * confidenceDescription —— 对于confidence的文字描述 245 | 246 | ### 处理机器可读的输出 247 | > 你当然可以用任何你认为合适的方法来处理诊断，但是这里有一个建议：使用 jq 来给出JSON格式的输出。 248 | 249 | > 这里有一个例子，打印出项目中可能未被使用的资源文件的列表： 250 | ``` 251 | $ fauxpas --onlyRules UnusedResource -o json check MyProject.xcodeproj 252 | | jq --raw-output '.diagnostics[] | .file' 253 | /Users/username/myproject/unused1.jpg 254 | /Users/username/myproject/unused2.xml 255 | ``` 256 | 257 | ## 处理故障 258 | ### 当使用Xcode编译我的项目时，FauxPas给出了一些我不理解的编译错误 259 | > FauxPas使用了一个相对于Xcode些许不同的Clang编译器的版本（这是不得已而为之的：尽管LLVM/Clang是开源的，但苹果有它自己闭源的fork）。 260 | 261 | ##### 比较Clang的版本 262 | > 执行下列命令来查看你安装的Xcode使用的Clang的版本： 263 | 264 | ``` 265 | xcrun clang -dM -E -x c /dev/null | grep __VERSION__ 266 | ``` 267 | 268 | > 执行下列命令来查看你安装的FauxPas使用的Clang的版本： 269 | 270 | ``` 271 | fauxpas -v version | grep Clang 272 | ``` 273 | 274 | > 注意：然而苹果为它的Clang fork使用它自己版本号的方案，这造成了比较的不同。这个资源可以提供帮助[https://gist.github.com/yamaya/2924292.](https://gist.github.com/yamaya/2924292.) 275 | 276 | ##### 制止编译器警告 277 | > 如果你在项目中使用-Weverything警告标记，请尝试移除它（这个标记打开在Clang中的全部警告，甚至新的、错误的、试验性的都有）。如果你不想在你的项目配置中关掉这个标记，但就是想为FauxPas关掉它，你可以添加-Wno-everything这个值到“Additional compiler arguments to use”(--extraCompilerArgs)这个配置选项中。 278 | 279 | > 如果你只是想对于FauxPas关掉全部的编译警告（但对于只在你的项目中时却不关掉），添加-w标记到“Additional compiler arguments to use”(--extraCompilerArgs)这个配置选项中。 280 | 281 | ### FauxPas没有成功地检查我的项目 282 | > 请确认FauxPas对你的项目使用了正确的xcodebuild参数。如果你打开了--verbose选项，FauxPas将打印被用到log输出中的xcodebuild参数。 283 | 284 | > 为了确定正确地build你的项目需要什么xcodebuild参数，你可以在终端cd到你.xcodeproj目录所在的目录，然后尝试在这里执行xcodebuild（开始时，使用和FauxPas相同的参数） 285 | 286 | ##### 生成源码的项目 287 | > 如果你的项目在build过程中生成或修改源文件（例如：头文件），你必须打开“Build project before checking” (--fullBuild)选项。如果正确地解释（interpreting）你项目的源码需要依赖在build过程中生成的其它东西（例如：一个依赖的项目），你也需要进行同样的操作。 288 | 289 | ##### 项目使用一个workspace来编译 290 | > 如果你的项目通常使用Xcode Workspace来build，并且无法作为一个独立的项目来build，你就必须指定--workspace和--scheme选项。 291 | 292 | > 当你在图形界面工具中，打开一个没有关联的配置文件的项目，就会展示一个配置帮助表（configuration help sheet），让你来轻松地选择workspace和scheme。 293 | 294 | ### 我安装了多个版本的Xcode；我怎样确保FauxPas使用了我想用的那一个 295 | > FauxPas使用xcrun来寻找它需要的全部Xcode开发者工具（例如xcodebuild）。如果你打开了--verbose选项，FauxPas将在你检查项目时打印这些路径到log中。 296 | 297 | > 你可以使用xcode-select程序来改变你的系统使用哪个Xcode。 298 | 299 | ``` 300 | xcode-select -switch /Applications/Xcode.app 301 | ``` 302 | 303 | > 如果你不想让这个改变全局化，你可以在执行FauxPas前设置 DEVELOPER_DIR 环境变量。 304 | 305 | ``` 306 | DEVELOPER_DIR="/Applications/Xcode.app" fauxpas 307 | ``` 308 | --------------------------------------------------------------------------------