Faux Pas performs its checks on a single Target of an Xcode project, using a single Build Configuration. At a minimum, the project must be specified — Faux Pas can select a default target and build configuration if they are left unspecified.
Rules can be selected by their tags, or individually. Individual rules can also be excluded. Exclusions are applied last, so that if you exclude a rule that has a tag you have selected, the rule will not be applied.
-g / --ruleTags to select all rules that have the specified tags-r / --rules to select individual rules--excludedRules to exclude individual rulesRecommendation: Select rules by tags as much as possible, and avoid selecting individual rules if you can. Then exclude any rules you don’t want. This way new rules added in updated versions of this app will be selected automatically if they are tagged with tags you have selected.
In the command line, you can also use the --onlyRules argument to run only specific rules, overriding all the other rule selection options. This is handy when your project has a configuration file with rule tag selections and/or rule exclusions that you would like to temporarily override.
In order to use Faux Pas from the command line, you must first install the fauxpas command:
Command-Line: Run the command:
/Applications/FauxPas.app/Contents/Resources/install-cli-tools
This will install the fauxpas command in /usr/local/bin but you can of course move it elsewhere if you wish.
To see the command-line interface documentation, run fauxpas help in the terminal.
Faux Pas can be configured via:
Configuration files may be written in JSON. To see a full example configuration file, run fauxpas exampleConfig in the terminal (note that this requires the CLI tools to be installed).
When using the command-line interface, a configuration file may be selected using the -c / --configFile argument.
A project-specific configuration file may be used by adding it into a folder named FauxPasConfig in the project root folder (the same folder where the .xcodeproj folder resides) with the file extension .fauxpas.json. The file may also reside elsewhere, as long as the file extension is the above and the Xcode project contains a reference to it.
If there are multiple configuration files in the FauxPasConfig folder, the default is the one named main.fauxpas.json.
Project-specific configuration files will be automatically picked up, for both CLI and GUI invocations of the application.
Many Faux Pas configuration options affect how long it takes for it to check your project. The default configuration is an attempt at a good balance between speed and compatibility with most Xcode projects, but it’s a good idea to adjust the options a bit in order to improve checking speed for your particular project.
Here are some suggestions that help Faux Pas check your project faster:
ARCHS build setting in the “Additional xcodebuild arguments to use” option — for example ARCHS=armv7.The “Diagnostics” view in the GUI has a text field that allows entering filters that limit the displayed diagnostics to ones matching the given filters.
You can add multiple filters, in which case they all will be applied one after the other.
The following filters are supported:
* may be used. For example: file=foo.m or file=*ViewController.mrule=Dot syntax usageFunctionality, Maintainability, Style). For example: impact=FunctionalityAbsolute, High, Medium, Low). For example: confidence=HighError, Warning, Concern). For example: severity=ErrorIf you don’t find any of the diagnostics emitted by a particular rule useful (or disagree with the basic premise of the rule,) simply exclude that rule from being applied.
If you want to keep a rule enabled, but suppress diagnostics in specific sections of your code, you can use the macros defined in the FauxPasAnnotations.h header for that.
To add that header to your project, do this:
Further instructions on how to use the macros are included in the header file itself.
Each rule in Faux Pas has an option called “Regexes for ignored file paths”. This option can be used to suppress diagnostics from that rule in all file paths that match any of the specified regular expressions.
If you want to exclude files that match specific patterns from being checked by Faux Pas, you can use the following options:
[--fileExclusionRegexes][--fileExclusionPrefixes][--fileExclusionXcodeGroups]Note that these options don’t just suppress diagnostics from matching files: they entirely exclude them from being checked.
You can use the open command to open a specific Xcode project in the Faux Pas GUI. Combine this with a short AppleScript snippet to get the currently active project path from Xcode:
open -a FauxPas "`osascript -e 'tell application \"Xcode\" to return path of active project document'`"
You can use a helper application (like Keyboard Maestro, FastScripts, or Spark) to assign a global hotkey for this.
Faux Pas can be executed in an Xcode build phase. This allows you to see the diagnostics it produces in the Xcode GUI, and easily jump to the relevant file positions. This method also allows Faux Pas to “break the build” by returning a nonzero exit status (the --minErrorStatusSeverity option can be used to control the conditions in which Faux Pas returns an error exit status).
Add the following as the contents of the script:
[[ ${FAUXPAS_SKIP} == 1 ]] && exit 0
FAUXPAS_PATH="/usr/local/bin/fauxpas"
if [[ -f "${FAUXPAS_PATH}" ]]; then
"${FAUXPAS_PATH}" check-xcode
else
echo "warning: Faux Pas was not found at '${FAUXPAS_PATH}'"
fi
With this script, Faux Pas will be run during the build unless the FAUXPAS_SKIP build setting is given the value 1.
To manually run Faux Pas from within Xcode:
Add the following as the contents of the script, substituting the actual name of your project for PROJECT_NAME:
/usr/local/bin/fauxpas -o xcode check "PROJECT_NAME.xcodeproj"
You can now invoke Faux Pas by building the “Faux Pas” scheme.
If you want to write your own custom scripts to process the diagnostics emitted by Faux Pas, you must first make it produce machine-readable output.
The --outputFormat (or -o) argument in the CLI allows you to specify the format in which diagnostics are written into the standard output stream. The possible values for this are:
human — Human-readable output (default)json — JSON outputplist — Property list output (currently this outputs an XML property list)xcode — Line-based output, as understood by Xcode. This is used by default when you use the check-xcode command, to get Xcode to display the diagnostics as errors and warnings.In the GUI, you can press the Export Diagnostics… button in the diagnostics view to save the diagnostics into a file in any of the above formats.
For all of the machine-readable formats, the actual structure of the diagnostic objects is the same — only the serialization format varies (the only exception to this is the fact that property list fields may not have “null” values, so such fields are simply omitted there.)
The root object has the following fields:
fauxPasVersion — The version of Faux Pas used to produce the outputtimeStamp — A unix timestamp for the time when the output was producedprojectPath — The filesystem path to the .xcodeproj folderprojectName — The name of the checked Xcode projecttargetName — The name of the checked target in the Xcode projecttargetBundleVersion — The CFBundleVersion value from the checked target’s Info.plistbuildConfigurationName — The name of the Xcode build configuration usedprojectIconBase64PNG — The project icon (as displayed in the Faux Pas GUI) as a base64-encoded PNG (120 by 120 pixels)versionControlSystemName — The name of the version control system used by the projectversionControlRevision — The current version control system revision identifier (Currently only supported for Git)diagnostics — An array of diagnostic objectsThe diagnostic objects have the following fields:
ruleShortName — The short name of the rule that emitted this diagnosticruleName — The full name of the rule that emitted this diagnosticruleDescription — The full description of the rule that emitted this diagnosticruleWarning - For some rules, an human-readable warning related to the produced diagnostics.info — Human-readable information about the diagnostichtml — A dictionary containing all of the above keys, with HTML-formatted values.identifier — An arbitrary value chosen by each rule, usually to specify a relevant piece of data that the diagnostic refers to (e.g. the Missing Translation rule will specify here the string resource key that seems to be missing.)file — The full path to the file that this diagnostic refers tocontext — The name/signature of a “parent” code symbol of the section of code this diagnostic refers to (e.g. a function or method, or a class)extent — Position markers for the section of file this diagnostic refers to
start and end, both with the following structure:
line — The line numberbyteColumn — The column of line, in bytesbyteOffset — The offset from the beginning of the file, in bytesutf16Column — The column of line, in UTF-16 unitsutf16Offset — The offset from the beginning of the file, in UTF-16 unitsfileSnippet — The contents of the section of file this diagnostic refers toimpact — What the primary “impact” of the problem described by this diagnostic is considered to be (functionality, maintainability or style)severity — How “severe” this diagnostic is considered to be (an integer [0-10] inclusive, higher values indicate higher severity. 3 is “concern”, 5 is “warning”, and 9 is “error”.)severityDescription — A textual description of severityconfidence — How confident we are that this diagnostic is not a false positive (an integer [0-10] inclusive, higher values indicate higher confidence)confidenceDescription — A textual description of confidenceYou may of course process the diagnostics data in any way you deem fit, but here is one suggestion: use jq with the JSON output format.
Here is an example that prints out a list of resource files that are potentially unused in the project:
$ fauxpas --onlyRules UnusedResource -o json check MyProject.xcodeproj \
| jq --raw-output '.diagnostics[] | .file'
/Users/username/myproject/unused1.jpg
/Users/username/myproject/unused2.xml
Faux Pas uses a slightly different version of the Clang compiler than Xcode does (this is by necessity: although LLVM/Clang is open source, Apple has its own closed-source fork of it).
Run the following to see the version of Clang your Xcode installation is using:
xcrun clang -dM -E -x c /dev/null | grep __VERSION__
And the following to see the version of Clang your Faux Pas installation is using:
fauxpas -v version | grep Clang
Note, however, that Apple uses its own version number scheme for its Clang fork, which makes comparisons difficult. The following resource can help with this: https://gist.github.com/yamaya/2924292.
If you are using the -Weverything warning flag in your project, try removing it (this flag enables all warnings in Clang, even the new, buggy/experimental ones). If you don’t want to disable this flag in your project configuration, but do want to disable it for Faux Pas, you can add -Wno-everything to the value of the “Additional compiler arguments to use” (--extraCompilerArgs) configuration option.
If you just want to disable all compiler warnings for Faux Pas (but not your project), add the flag -w to the “Additional compiler arguments to use” (--extraCompilerArgs) configuration option.
Please ensure that Faux Pas is using the correct xcodebuild arguments for your project. If you enable the --verbose option, Faux Pas will print the xcodebuild arguments it uses into the log output.
In order to determine what xcodebuild arguments are needed to correctly build your project, you can cd to the folder that contains your .xcodeproj in Terminal.app, and try running xcodebuild there (to begin with, using the same arguments as Faux Pas.)
If your project generates or modifies source files (e.g. headers) during a build, you must enable the “Build project before checking” (--fullBuild) option. The same applies if correctly interpreting your project’s source code depends on something else that is generate during the build (for example, a dependent project).
If your project is normally built using an Xcode Workspace, and cannot be built as an independent project, you must specify the --workspace and --scheme options.
When you open a project that does not have an associated configuration file in the GUI, a configuration help sheet will be shown that lets you easily select the workspace and scheme to use.
Faux Pas uses xcrun to find all the Xcode developer tools that it needs (e.g. xcodebuild). If you enable the --verbose option, Faux Pas will print these paths into the log when you check a project.
You can use the xcode-select program to change which Xcode your system uses.
xcode-select -switch /Applications/Xcode.app
If you don’t want to make this change globally, you can set the DEVELOPER_DIR environment variable before executing Faux Pas.
DEVELOPER_DIR="/Applications/Xcode.app" fauxpas <arguments...>