From 81f66a4e66214b8fc9a62947805bef53949ad162 Mon Sep 17 00:00:00 2001 From: john bowen Date: Thu, 12 Dec 2024 18:05:41 -0800 Subject: [PATCH] tweak docs --- docs/sphinx/dev_guide/contributing.rst | 64 ++++++++++++++++---------- 1 file changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/sphinx/dev_guide/contributing.rst b/docs/sphinx/dev_guide/contributing.rst index 9bf84052e6..72ad393ffa 100644 --- a/docs/sphinx/dev_guide/contributing.rst +++ b/docs/sphinx/dev_guide/contributing.rst @@ -196,38 +196,52 @@ likely the develop branch. ----------------------------------- Style ----------------------------------- -RAJA enforces style within the src and include directories using clang-format, +RAJA enforces style within the ``src`` and ``include`` directories using clang-format, major version 14. Formatting will be enforced on pull requests through CI, and it is up to the contributor to guarantee that their code is in compliance with the -clang-format settings specified within .clang-format. To make this easy, +clang-format settings specified within ``.clang-format``. To make this easy, RAJA has provided two options for applying clang-format: +* The CMake build target ``style`` + * If a ``clang-format`` executable with major version 14 is available in the ``PATH`` + when running CMake, RAJA's build system should find that executable and set + the CMake variable ``CLANGFORMAT_EXECUTABLE`` to that executable's path. + * If an invalid version exists in the ``PATH``, or no ``clang-format`` version is + specified in the path, the ``CLANGFORMAT_EXECUTABLE`` variable must be set by the + user in order to properly configure the make `style` target. This can be done by + passing ``-DCLANGFORMAT_EXECUTABLE=`` to ``cmake`` during + build configuration. + * If an invalid version of ``clang-format`` is supplied, the following error will be + emitted at build config time: -#. The CMake build target `style` - * If a clang-format executable with major version 14 is available in the PATH - when running CMake, RAJA's build system should find that executable and set - CLANGFORMAT_EXECUTABLE to that executable's path. - * If an invalid version exists in the PATH, or no clang-format version is - specified in the path, the CLANGFORMAT_EXECUTABLE variable must be set by the - user in order to properly configure the make `style` target. This can be done by - passing `-DCLANGFORMAT_EXECUTABLE=` to `cmake` during - build configuration. - * If an invalid version of `clang-format` is supplied, the following error will be - emitted at build config time: - `` blt_add_clangformat_target: clang-format '14'' is required, found .`` - `` Disabling 'style' build target.`` - * If no `CLANGFORMAT_EXECUTABLE` is supplied, `cmake` will print the warning - ``Failed to locate CMakeFormat executable``. + .. code-block:: bash + + blt_add_clangformat_target: clang-format '14' is required, found . + Disabling 'style' build target. + + + * If no ``CLANGFORMAT_EXECUTABLE`` is supplied, ``cmake`` will print the warning + ``Failed to locate CMakeFormat executable``. -#. Git hooks - * Run `scripts/setup-hooks.sh`. This script will install a `pre-commit` git hook - script that applies clang-format to any changes staged with git. If a clang-format - executable with major version 14 is available in the PATH, this executable will be used. - If not, the user must set the environment variable `RAJA_CLANG_FORMAT` to a valid - clang-format executable. If the script cannot find a valid clang-format installation - from either the PATH or from the environment variable `RAJA_CLANG_FORMAT`, the - script will print a warning and exit, allowing the commit to continue. +* Git hooks + + * Follow these steps to setup githooks, from the root directory of RAJA + + .. code-block:: bash + + # Only necessary if clang-format 14 is not in the $PATH variable. + # This line can also be placed in .zshrc + $ export RAJA_CLANG_FORMAT= + $ scripts/setup-hooks.sh + + * The ``scripts/setup-hooks.sh`` script will install a ``pre-commit`` git hook + script that applies clang-format to any changes staged with git. If a ``clang-format`` + executable with major version 14 is available in the ``PATH``, this executable will be used. + If not, the user must set the environment variable ``RAJA_CLANG_FORMAT`` to a valid + clang-format executable. If the script cannot find a valid clang-format installation + from either the ``PATH`` or from the environment variable ``RAJA_CLANG_FORMAT``, the + script will print a warning and exit, allowing the commit to continue. .. _prfromfork-label: