Package: clant
ClantClant (CLAng liNT) is a fast and easy to use wrapper script for checking C and
C++ code with the clang-based toolsclang-tidyandinclude-what-you-use.Though these tools are helpful, they can be tricky to configure correctly.  For
example, checks in headers can be mistakenly skipped, mixing C and C++ code can
be a hassle, and the interface and output of the bundled wrapper scripts are
inconsistent.Clant aims to handle all of these details and provide a simple interface for
running these tools on a project with nice output.  Tools are run in parallel
for maximum speed, and output is printed in the standard make and GCC format
supported by most editors.ExampleUsing Clant looks something like this:$ cd /mylib
$ clant
clant: Entering directory `/mylib/build'
clant: Loading compilation database `compile_commands.json'
../include/mylib/mylib.h:1:1: note: includes are correct
../src/mylib.c:239:1: error: function 'run' has a definition with different parameter names [readability-inconsistent-declaration-parameter-name,-warnings-as-errors]
run(Thing* result);
^
../src/mylib.c:576:1: note: the definition seen here
run(Thing* out)
^
../src/rerex.c:239:1: note: differing parameters are named here: ('result'), in definition: ('out')
run(Something* result);
^              ~~~~~~
               out

../test/test_something.c:26:1: error: remove this line
#include <stdlib.h>
../test/test_something.c:1:1: note: code is tidy
clant: Leaving directory `/mylib/build/build'InstallationClant is a Python script that can simply be run anywhere, installation is not
necessary.It can, however, be installed withpip:pip install clantInstallation from the source directory is also possible:cd path_to_clant_source
pip install .UsageIdeally, you can simply run clant from your project directory:cd path_to_my_project
clantClant will assume that a build exists in thebuildsubdirectory, and look forcompile_commands.jsonthere.  To use a different build directory, pass it as
a parameter:clant releaseBy default, the number of threads supported by the CPU will be used.  To use a
different number of threads, use the-joption:clant -j 4Individual tools can be disabled for faster runs or to suppress warnings while
working on issues:clant --no-tidy
clant --no-iwyuChecking HeadersClant attempts to run tools in a way that automatically includes appropriate
headers in checks, but this may miss headers that are not included in the
build, or that are not inside the project directory.  Additional headers can be
checked by providing include directories with the--includeoption.
This will run checks on all the headers in that directory, recursively:clant --include includeInclude Mapping FilesMapping filesare supported by include-what-you-use to specify include file
mappings for third-party libraries or other things that the tool does not
automatically understand.  Additional mapping files can be given with the--mappingoption:clant --mapping /path/to/somelibrary.imp
clant --mapping someotherlibrary.impIf they are not absolute paths, mapping files will be searched for first in the
project directory, then in the system include-what-you-use directory (relative
to the binary, typically/usr/share/include-what-you-use).Excluding FilesSometimes, certain files can't be realistically changed to reach the same level
of cleanliness as the rest of the project, for example generated or third-party
code.  Such files can be excluded by providing a regular expression with the--excludeoption:clant --exclude '.*generated.*\.c'WarningsWarnings are configured using the standard.clang-tidymechanism.  The
simplest approach is to simply add a single.clang-tidyfile to the project
root, and enable or suppress any warnings there.To be more fine-grained, for example to specify stricter warnings for headers
than implementations, separate files can be used.  The.clang-tidyfile in
the closest parent directory to the source being checked will be used.  Note,
however, thatclang-tidydoes not check headers on their own by default, and
that included headers will be checked using the settings for that compilation
(including the language), not the.clang-tidyfile associated with the
header.This can be especially tricky for projects that contain both C and C++.  To get
around this problem, unless the--no-auto-headersoption is given, Clant
automatically includes headers of the matching language based on their
extension, which overrides theHeaderFilterRegexoption in the.clang-tidyfile.  This prevents C++ warnings from being produced for C headers, or
vice-versa.  For C sources with extension.c, any included.hfiles within
the project are checked.  For C++ sources with extension.cppor.cc, any
included.hh,.hpp, or.ippfiles within the project are checked.The extra headers given with the--includeoption are always checked on their
own, avoiding these issues.  Since there is no associated command in the
compilation database for headers, Clant combines all of the include paths given
to any compile command to run tools on these headers.Using from PythonClant is also installed as a Python package calledclant, which contains a
single module, also calledclant.The command-line utility is implemented inclant.main(), which takes no
arguments since they are read fromsys.argv.That is a simple wrapper forclant.run(), which takes parameters that loosely
correspond with command line parameters, but using lists for multiple values
and more appropriate names.  Onlybuild_diris required.  For example:fromclantimportclantclant.run(auto_headers=True,build_dir="build",exclude_patterns=[".*gen.*"],iwyu=False,jobs=4,mapping_files=["qt5_11.imp"],tidy=True,verbose=False)Configuration FileA configuration can be included in a project by adding a.clant.jsonfile in
the project root directory.  This file must be a JSON object, where the keys
correspond to the keyword parameters ofclant.run()described above.The one exception is theversionkey, which must be present, and represents
the version of Clant the configuration file is for.  Currently, this is only
used to print a warning if the configuration is newer, but it may be used in
the future to handle any potential compatibility issues.For example, this configuration uses all of the supported keys:{"auto_headers":true,"build_dir":"release","exclude_patterns":[".*gen.*"],"iwyu":false,"jobs":4,"mapping_files":["qt5_11.imp"],"tidy":true,"verbose":false,"version":"1.0.0"}If command line parameters are also given, then values from the configuration
file will override them, except for lists, which will be added.AssumptionsAside from some of the defaults described above, Clant is a somewhat
opinionated tool that assumes a few things for ease of use:clang-tidyandinclude-what-you-useare installed, that is, these
commands are available in thePATH.The build directory is an immediate child of the project directory.The build directory contains a validJSON Compilation Databasenamedcompile_commands.json.For the auto headers feature:C sources have extension.c, C headers have extension.h.C++ sources have extension.cppor.cc, C++ headers have extension.hpp,.hh, or.ipp.For checking extra headers:Headers can be "compiled" by including every-Igiven to every compile
command, so there are no conflicting header names.Feel free to submit a patch if any of these are problematic for you.-- David Robillardd@drobilla.net