index.rst

ament_lint_auto

The package simplifies using multiple linters as part of the CMake tests. It reduces the amount of CMake code to a bare minimum.

CMakeLists.txt:

# this must happen before the invocation of ament_package()
if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  ament_lint_auto_find_test_dependencies()
endif()

The set of linters to be used is then only specified in the package manifest as test dependencies.

package.xml:

<test_depend>ament_lint_auto</test_depend>

<!-- add test dependencies on any linter, e.g. -->
<test_depend>ament_cmake_clang_format</test_depend>
<test_depend>ament_cmake_cppcheck</test_depend>
<test_depend>ament_cmake_pycodestyle</test_depend>

Since recursive dependencies are also being used a single test dependency is sufficient to test with a set of common linters.

package.xml:

<test_depend>ament_lint_auto</test_depend>

<!-- this recursively depends on a set of common linters -->
<test_depend>ament_lint_common</test_depend>

The documentation of the package ament_cmake_test provides more information on testing in CMake ament packages.

How to exclude files with ament_lint_auto?

Linter hooks shall conform to the ament_lint_auto convention of excluding files specified in the CMake list variable AMENT_LINT_AUTO_FILE_EXCLUDE. As such, the CMake snippet from above can be modified to exclude files across all linters with one addition.

CMakeLists.txt:

# this must happen before the invocation of ament_package()
if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  set(AMENT_LINT_AUTO_FILE_EXCLUDE /path/to/ignored_file ...)
  ament_lint_auto_find_test_dependencies()
endif()

For a more specific example, this excludes all python files matching a pattern using globbing. Multiple expressions can be combined on multiple lines. It might be a good idea to issue a warning to developers that linting is disabled if you plan to enable it at some point.

file(GLOB_RECURSE AMENT_LINT_AUTO_FILE_EXCLUDE
  # Exclude all the python files in src directory
  src/*.py
  # Exclude all the c++ implementation files in test directory
  test/*.cpp
)
message(AUTHOR_WARNING
    "Ament lint auto tests are disabled on the following: "
    ${AMENT_LINT_AUTO_FILE_EXCLUDE}
)