vibhatha commented on a change in pull request #12085: URL: https://github.com/apache/arrow/pull/12085#discussion_r779590500
########## File path: docs/source/developers/cpp/development.rst ########## @@ -92,32 +92,51 @@ Address Sanitizer and Undefined Behavior Sanitizer to check for various patterns of misbehaviour such as memory leaks. In addition, the codebase is subjected to a number of code style and code cleanliness checks. -In order to have a passing CI build, your modified git branch must pass the +In order to have a passing CI build, your modified Git branch must pass the following checks: * C++ builds with the project's active version of ``clang`` without compiler warnings with ``-DBUILD_WARNING_LEVEL=CHECKIN``. Note that there are classes of warnings (such as ``-Wdocumentation``, see more on this below) that are not caught by ``gcc``. +* Passes various C++ (and others) style checks, checked with the ``lint`` + subcommand to :ref:`Archery <archery>`. This can also be fixed locally + by running ``archery lint --cpplint --clang-format --clang-tidy --fix``. * CMake files pass style checks, can be fixed by running ``archery lint --cmake-format --fix``. This requires Python 3 and `cmake_format <https://github.com/cheshirekow/cmake_format>`_ (note: - this currently does not work on Windows) -* Passes various C++ (and others) style checks, checked with the ``lint`` - subcommand to :ref:`Archery <archery>`. This can also be fixed locally - by running ``archery lint --cpplint --fix``. + this currently does not work on Windows). In order to account for variations in the behavior of ``clang-format`` between major versions of LLVM, we pin the version of ``clang-format`` -used. You can confirm the current pinned version by finding -the ``CLANG_TOOLS`` variable value in `.env -<https://github.com/apache/arrow/blob/master/.env>`_. +used. You can confirm the current pinned version by finding the +``CLANG_TOOLS`` variable value in `.env +<https://github.com/apache/arrow/blob/master/.env>`_. Note that the version +must match exactly; a newer version will not work. LLVM can be installed +through a system package manager or a package manager like Conda or +Homebrew, or binaries can be directly downloaded for various platforms from +the `LLVM website <https://releases.llvm.org/>`_. + +For convenience, C++ style checks can run via a build, in addition to +Archery. To do so, build one or more of the targets ``format`` (for +clang-format), ``lint_cpp_cli``, ``lint`` (for cpplint), or +``clang-tidy``. For example:: + + $ cmake -GNinja ../cpp ... + $ ninja format lint clang-tidy lint_cpp_cli Depending on how you installed clang-format, the build system may not be able -to find it. You can provide an explicit path to your LLVM installation (or the -root path for the clang tools) with the environment variable -`$CLANG_TOOLS_PATH` or by passing ``-DClangTools_PATH=$PATH_TO_CLANG_TOOLS`` when -invoking CMake. +to find it. In that case, invoking CMake will show errors like the following:: + + -- clang-format 12 not found + +Or if the wrong version is installed:: + + -- clang-format found, but version did not match "^clang-format version 12" + +You can provide an explicit path to the directory containing the clang-format +executable and others with the environment variable ``$CLANG_TOOLS_PATH``, or +by passing ``-DClangTools_PATH=$PATH_TO_CLANG_TOOLS`` when invoking CMake. Review comment: @lidavidm may be we can put an example usage, if somebody used llvm (since Arrow docs also mention about using llvm tools), the path for ClangTools must point to that. May be this is so trivial and it doesn't need mentioning. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: github-unsubscr...@arrow.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
