Merge pull request #48 from UCBoulder/maint/add-clang-linters

Maint/add clang linters

Author: NateAM

.clang-format

@@ -0,0 +1,18 @@
+BasedOnStyle: "Google"
+
+AlignAfterOpenBracket:               Align
+AlignArrayOfStructures:              Left
+AlignConsecutiveAssignments:         AcrossComments
+AlignConsecutiveDeclarations:        Consecutive
+AlignEscapedNewlines:                true
+AlignOperands:                       Align
+AlignTrailingComments:               true
+AllowShortIfStatementsOnASingleLine: AllIfsAndElse
+ColumnLimit:                         120
+PenaltyBreakOpenParenthesis:         100
+CommentPragmas:                      'TESTARGS'
+TabWidth:                            4
+IndentWidth:                         4
+UseTab:                              Never
+NamespaceIndentation:                All
+PointerAlignment:                    Right

.clang-tidy

@@ -0,0 +1,3 @@
+Checks: "clang-diagnostic-*,clang-analyzer-*,-clang-analyzer-optin.performance.Padding,readability-inconsistent-declaration-parameter-name"
+HeaderFilterRegex: .*
+WarningsAsErrors: "clang-diagnostic-*,clang-analyzer-*,-clang-analyzer-optin.performance.Padding,readability-inconsistent-declaration-parameter-name"

.github/workflows/github-test.yml

@@ -41,9 +41,20 @@ jobs:
         if: ${{ matrix.os == 'ubuntu-latest' }}
         shell: bash -el {0}
         run: gersemi CMakeLists.txt src/ docs/ --check --diff
+      - name: Configure
+        shell: bash -el {0}
+        run: cmake -S . -B build -DTARDIGRADE_HEADER_ONLY=${{ matrix.header_only }} -DTARDIGRADE_ERROR_TOOLS_OPT=${{ matrix.tardigrade_opt }} -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+      - name: clang-tidy Lint
+        if: ${{ matrix.os == 'ubuntu-latest'}}
+        shell: bash -el {0}
+        run: run-clang-tidy -config-file=.clang-tidy -header-filter=*.h -p build -extra-arg="-mno-sse2"
+      - name: clang-format Lint
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.tardigrade_opt == 'OFF' && matrix.header_only == 'ON' }}
+        shell: bash -el {0}
+        run: cmake --build build --target cpp-format-check
       - name: Build
         shell: bash -el {0}
-        run: cmake -S . -B build -DTARDIGRADE_HEADER_ONLY=${{ matrix.header_only }} -DTARDIGRADE_ERROR_TOOLS_OPT=${{ matrix.tardigrade_opt }} && cmake --build build --target all
+        run: cmake --build build --target all
       - name: Test
         shell: bash -el {0}
         run: conda activate test-environment && ctest --test-dir build -V

CMakeLists.txt

@@ -50,6 +50,10 @@ if(${not_conda_test} STREQUAL "true")
     project(${PROJECT_NAME} VERSION ${${PROJECT_NAME}_VERSION} LANGUAGES CXX)
 endif()
 
+if(CMAKE_EXPORT_COMPILE_COMMANDS)
+    set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
+endif()
+
 # Add installation directory variables
 include(GNUInstallDirs)
 
@@ -58,13 +62,21 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -pedantic")
 if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -lrt -O3 -DNDEBUG")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -DNDEBUG")
 endif()
 
 # Enable CTest
 enable_testing()
 
 #================================================================================================= FIND DEPENDENCIES ===
+
+#=============================================================================================== FIND PROGRAMS
+
+find_program(CLANG_FORMAT_EXECUTABLE NAMES clang-format REQUIRED)
+set_property(GLOBAL PROPERTY CLANG_FORMAT_SOURCE_FILES)
+
+#=============================================================================================== ADD PROJECT TARGETS ===
+
 # Find eigen
 find_package(Eigen3 3.3 REQUIRED NO_MODULE)
 include_directories(${EIGEN3_INCLUDE_DIR})
@@ -165,3 +177,25 @@ if(${not_conda_test} STREQUAL "true")
         DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake
     )
 endif()
+
+#================================================================================== SETUP CLANG FORMATTING TARGETS ===
+
+if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+    get_property(CLANG_FORMAT_SOURCE_FILES_VALUE GLOBAL PROPERTY CLANG_FORMAT_SOURCE_FILES)
+
+    add_custom_target(
+        cpp-format-check
+        COMMAND ${CLANG_FORMAT_EXECUTABLE} -style=file --dry-run -Werror ${CLANG_FORMAT_SOURCE_FILES_VALUE}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Check the C++ code format with clang-format"
+    )
+    set_target_properties(cpp-format-check PROPERTIES EXCLUDE_FROM_ALL TRUE)
+
+    add_custom_target(
+        cpp-format
+        COMMAND ${CLANG_FORMAT_EXECUTABLE} -style=file -i ${CLANG_FORMAT_SOURCE_FILES_VALUE}
+        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+        COMMENT "Format the C++ code with clang-format"
+    )
+    set_target_properties(cpp-format PROPERTIES EXCLUDE_FROM_ALL TRUE)
+endif()

README.rst

@@ -11,6 +11,8 @@
 .. _`Sphinx style guide`: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html
 .. _`PEP-8`: https://www.python.org/dev/peps/pep-0008/
 .. _`gersemi`: https://github.com/BlankSpruce/gersemi
+.. _`clang-tidy`: https://clang.llvm.org/extra/clang-tidy/
+.. _`clang-format`: https://clang.llvm.org/docs/ClangFormat.html
 
 .. targets-end-do-not-remove
 
@@ -124,6 +126,8 @@ Build the Conda package
 Contribution Guidelines
 ***********************
 
+.. contribution-start-do-not-remove
+
 Git Commit Message
 ==================
 
@@ -172,41 +176,45 @@ and any automatic fixes may be reviewed and then applied by developers with the
    $ gersemi CMakeLists.txt src/ docs/ --diff
    $ gersemi CMakeLists.txt src/ docs/ --in-place
 
-This project does not yet have a full style guide. Generally, wherever a style can't be inferred from surrounding code
-this project falls back to `PEP-8`_ -like styles. There are two notable exceptions to the notional PEP-8 fall back:
+This project enforces its style using `clang-tidy`_ and `clang-format`_ as configured with the
+`.clang-format` and `.clang-tidy` files in the root directory. The formatting of the project can be
+checked using `clang-tidy`_ by first configuring the project using
 
-1. `Doxygen`_ style docstrings are required for automated, API from source documentation.
-2. This project prefers expansive whitespace surrounding parentheses, braces, and brackets.
+.. code-block:
 
-   * No leading space between a function and the argument list.
-   * One space following an open paranthesis ``(``, brace ``{``, or bracket ``[``
-   * One space leading a close paranthesis ``)``, brace ``}``, or bracket ``]``
+   $ cmake -S . -B build ... -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
 
-An example of the whitespace style:
+where `...` are the other configuration flags specified. After this clang-tidy can be run on the
+full project from the source directory via
 
-.. code-block:: bash
+.. CAUTION::
+    Commit all changes prior to running the clang tidy command. This will edit all source files.
 
-   my_function( arg1, { arg2, arg3 }, arg4 );
+.. code-block:
+
+   $ run-clang-tidy -config-file=.clang-tidy -header-filter=*.h -p build
 
-The following ``sed`` commands may be useful for updating white space, but must
-be used with care. The developer is recommended to use a unique git commit
-between each command with a corresponding review of the changes and a unit test
-run.
+The formatting can be checked using `clang-format`_ by running
 
-* Trailing space for open paren/brace/bracket
+.. code-block:
 
-  .. code-block:: bash
+   $ cmake -S . -B build ...
+   $ cmake --build build --target cpp-format-check
 
-     sed -i 's/\([({[]\)\([^ ]\)/\1 \2/g' <list of files to update>
+which will indicate if the formatting is correct. The c++ files can be re-formatted to match the
+style guidance by running
 
-* Leading space for close paren/brace/bracket
+.. CAUTION::
+    Commit all changes prior to running the format command. This will edit all source files.
 
-  .. code-block:: bash
+.. code-block
 
-     sed -i 's/\([^ ]\)\([)}\]]\)/\1 \2/g' <list of files to update>
+   $ cmake --build build --target cpp-format
 
-* White space between adjacent paren/brace/bracket
+If the style is not constrained by the above, it should be inferred by the surrounding code.
+Wherever a style can't be inferred from surrounding code this project falls back to `PEP-8`_-like
+styles the exceptions to the notional PEP-8 fall back:
 
-  .. code-block:: bash
+1. `Doxygen`_ style docstrings are required for automated, API from source documentation.
 
-     sed -i 's/\([)}\]]\)\([)}\]]\)/\1 \2/g' <list of files to update>
+.. contribution-end-do-not-remove

environment.txt

@@ -1,6 +1,5 @@
 boa
 breathe>=4.30.0
-clang-tools
 cmake>=3.30
 compilers
 cython
@@ -15,7 +14,9 @@ pytest-cov
 pytest-xdist
 python
 python-build  # required to build tardigrade_error_tools from source
-setuptools_scm>=6.2
+setuptools >=77
+setuptools_scm>=8
+clang-tools
 sphinx>=3.0.4
 sphinx_rtd_theme>=0.4.3
 sphinxcontrib-bibtex

recipe/meta.yaml

@@ -25,11 +25,12 @@ requirements:
     - {{ compiler('cxx') }}
     - make
     - cmake >=3.30
+    - clang-tools
     - breathe >=4.3.0
     - doxygen
     - libboost-python-devel >=1.82
-    - setuptools >=62
-    - setuptools_scm >=6.2
+    - setuptools >=77
+    - setuptools_scm >=8
     - sphinx >=3.0.4
     - sphinx_rtd_theme >=0.4.3
     - sphinxcontrib-bibtex
@@ -45,6 +46,7 @@ test:
     - {{ compiler('cxx') }}
     - make
     - cmake >=3.30
+    - clang-tools
     - libboost-python-devel >=1.82
     - doxygen
     - sphinx >=3.0.4

src/cpp/CMakeLists.txt

@@ -12,6 +12,9 @@ install(
 )
 install(FILES ${PROJECT_NAME}.h ${PROJECT_NAME}.cpp DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
+set_property(GLOBAL APPEND PROPERTY CLANG_FORMAT_SOURCE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}.h")
+set_property(GLOBAL APPEND PROPERTY CLANG_FORMAT_SOURCE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}.cpp")
+
 foreach(package ${ADDITIONAL_HEADER_ONLY_LIBRARIES})
     target_include_directories(
         ${package}
@@ -26,4 +29,9 @@ foreach(package ${ADDITIONAL_HEADER_ONLY_LIBRARIES})
         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
     )
     install(FILES ${package}.h ${package}.cpp DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+
+    get_target_property(target_sources ${package} SOURCES)
+    foreach(source ${target_sources})
+        set_property(GLOBAL APPEND PROPERTY CLANG_FORMAT_SOURCE_FILES "${PROJECT_SOURCE_DIR}/${source}")
+    endforeach(source)
 endforeach(package)