Difference between revisions of "Add linters to a project"

Revision as of 15:49, 9 November 2016

To add Phabricator linters to a project (specifically, clang-format-linter):

Install clang-format-linter locally

A custom local install of the clang-format-linker can be easily done as such:

# On an Apertis image:
apt-get install arcanist-clang-format-linter
# Or on a non-Apertis image (alternatively, packages for clang-format-linter might be available for your distribution):
<change to the path where you want to put the linter, e.g. ~/source>
git clone https://github.com/pwithnall/morefas-phabricator.git clang-format-linter
arc set-config load "[ \"$(pwd)/clang-format-linter\" ]"

# Check the installation: 
arc linters  # should list ‘clang-format’ as ‘configured’

We are using a custom clone of the original clang-format-linter which adds support for splitting the diff into chunks and adds some more help.

Make sure clang-format is recent

Again, this should be done on each developer’s machine.

Install clang-format 3.7 or later, and make sure that running "clang-format" results in running that version. For instance, in Debian unstable as of January 2016 it's called clang-format-3.7, so you might add ~/bin to your PATH and make a symbolic link:

ln -s /usr/bin/clang-format-3.7 ~/bin/clang-format

Update .arcconfig

Update the .arcconfig file for the project (in git) to add the linter configuration and load the clang-format-linter arcanist extension:

"lint.engine": "ArcanistConfigurationDrivenLintEngine"

Add a .clang-format file

clang-format accepts its format options from a hidden file, defined in YAML format. Create .clang-format and commit it to git:

# See https://wiki.apertis.org/Guidelines/Coding_conventions#Code_formatting
BasedOnStyle: GNU
AlwaysBreakAfterDefinitionReturnType: All
BreakBeforeBinaryOperators: None
BinPackParameters: false
SpaceAfterCStyleCast: true

These are the current recommended formatting options from the coding conventions, but may change in future as clang-format evolves or corner cases in the configuration are found and fixed.

Add a .arclint file

To enable the linters to be used with arc lint (and hence with arc diff and git-phab attach), add a .arclint file to the project and commit it to git. This example file contains XML, Python and C linters. Note that you should adjust the include path for the clang-format-default linter to include the source directories in your project, while excluding any generated C or H files.

{
  "linters": {
    "clang-format-default": {
      "type": "clang-format",
      "version": ">=3.7.0",
      "include": "(^(src|tests|canterbury)/.*\\.(c|h)$)"
    },
    "pep8-default": {
      "type": "pep8",
      "flags": ["--ignore=E402"],
      "include": "(\\.py$)"
    },
    "xml-default": {
      "type": "xml",
      "include": "(\\.xml$)"
    }
  }
}

We ignore PEP8 error E402 because the recommended copyright headers, editor modelines and encoding lines push the first import statement below the recommended line number according to PEP8.