{"id":20956469,"url":"https://github.com/bluebrain/hpc-coding-conventions","last_synced_at":"2025-05-14T05:31:47.143Z","repository":{"id":36092214,"uuid":"166150136","full_name":"BlueBrain/hpc-coding-conventions","owner":"BlueBrain","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-17T12:46:03.000Z","size":323,"stargazers_count":8,"open_issues_count":11,"forks_count":6,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-02T13:22:40.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueBrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null}},"created_at":"2019-01-17T02:57:12.000Z","updated_at":"2024-10-01T16:38:37.000Z","dependencies_parsed_at":"2024-03-04T18:08:20.080Z","dependency_job_id":null,"html_url":"https://github.com/BlueBrain/hpc-coding-conventions","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fhpc-coding-conventions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fhpc-coding-conventions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fhpc-coding-conventions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fhpc-coding-conventions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueBrain","download_url":"https://codeload.github.com/BlueBrain/hpc-coding-conventions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076977,"owners_count":22010630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T01:26:07.222Z","updated_at":"2025-05-14T05:31:46.643Z","avatar_url":"https://github.com/BlueBrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlueBrain HPC Team C++ Development Guidelines\n\nThis document describes both C++ development guidelines adopted by\nHPC team, and the tools and processes required to\nensure they are properly followed over time.\n\n## Documentation\n\nDevelopment Guidelines are split in the following sections:\n* [Tooling](./cpp/Tooling.md)\n* [Development Lifecycle](./cpp/DevelopmentLifecycle.md)\n* [Code Formatting](./cpp/formatting/README.md)\n* [Naming Conventions](./cpp/NamingConventions.md)\n* [Code Documentation](./cpp/Documentation.md)\n* Best Practices\n* Python bindings\n\n## Status\n\nThis project in currently under development, and shall not provide the features\nits documentation pretends. Here is a raw summary of the status:\n\n| Feature               | Definition         | Documentation      | Integration         | Adoption (\u003e10 proj) |\n| --------------------- | ------------------ | ------------------ | ------------------  | ------------------- |\n| ClangFormat           | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  | WIP                 |\n| ClangTidy             | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  | WIP                 |\n| Naming Conventions    | :heavy_check_mark: | :heavy_check_mark: | :no_entry_sign: N/A | :no_entry_sign: N/A |\n| Writing Documentation | :heavy_check_mark: | :heavy_check_mark: |                     |                     |\n| Project template      | WIP                |                    |                     |                     |\n| Good Practices        |                    |                    |                     |                     |\n| Memory Check          |                    |                    |                     |                     |\n| UT Code Coverage      |                    |                    |                     |                     |\n\n## CMake Project\n\nThis directory provides a CMake project that allows one to use the tools and the processes\ndescribed in this document. This project requires CMake version 3.10 or higher.\n\n### Requirements\n\nThis CMake project expects for the following utilities to be available:\n* [Python 3.5 or higher](https://python.org)\n* [ClangFormat 9](https://releases.llvm.org/9.0.0/tools/clang/docs/ClangFormat.html)\n* [ClangTidy 7](https://releases.llvm.org/7.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html)\n* [cmake-format](https://github.com/cheshirekow/cmake_format) Python package version 0.6\n* [pre-commit](https://pre-commit.com/) Python package\n* [git](https://git-scm.com/) version control system 2.17 or higher.\n\nOptionally, it will also look for:\n* [valgrind](http://valgrind.org/) memory checker\n* code coverage utilities like gcov, lcov, or gcov\n\n### Installation\n\nYou can import this CMake project into your Git repository using a git submodule:\n```\ngit submodule add https://github.com/BlueBrain/hpc-coding-conventions.git\ngit submodule update --init --recursive\n```\n\nNote: if your project already has a `cmake` sub-directory, it is recommended to create the\nsubmodule in this directory instead of top-level.\n\nThen simply add the following line in the top `CMakeLists.txt`, after your project\ndeclaration:\n```\nproject(mylib CXX)\n# [...]\nadd_subdirectory(hpc-coding-conventions/cpp)\n```\n\nAfter cloning or updating this git submodule, run CMake to take benefits of the latest changes.\nThis will setup or update git [pre-commit](https://pre-commit.com) hooks of this repository.\n\nCMake variables defined by this project are prefixed by `${PROJECT_NAME}` by default.\nThe CMake variable `CODING_CONV_PREFIX` allows to specify another prefix. It must be defined\nbefore including this CMake project, for instance:\n```cmake\nproject(mylib CXX)\n# [...]\nset(CODING_CONV_PREFIX Foo)\nadd_subdirectory(hpc-coding-conventions/cpp)\n```\n\n### Usage\n\n#### Code Formatting\n\nCreate file `.bbp-project.yaml` at the root of your project and enable the formatting tools,\nyou want to enable, for instance:\n\n```yaml\ntools:\n  ClangFormat:\n    enable: True\n  CMakeFormat:\n    enable: True\n```\n\nYou can then use the `bin/format` utility.\n\n#### Version deduction\n\n`bin/format` relies on `PATH` environment variable to locate the proper tools.\nYou can override the default required versions specified in `bbp-project.yaml`:\n\n```yaml\ntools:\n  ClangFormat:\n    enable: True\n    version: ~=15.0.0\n```\n\nIt is also possible to override the path to a tool in the YAML config file:\n```yaml\ntools:\n  CMakeFormat:\n    path: /path/to/bin/cmake-format\n```\n\n##### Usage\n\n* To format the entire codebase: `/path/to/hpc-coding-conventions/bin/format`\n* To check the formatting: `/path/to/hpc-coding-conventions/bin/format -n`\n* To format the CMake files only: `/path/to/hpc-coding-conventions/bin/format --lang CMake`\n* To check the formatting of C++ files in a specific locations:\n    `/path/to/hpc-coding-conventions/bin/format -n --lang c++ src/path1/ /src/path2/foo.cpp`\n\n\n##### Advanced configuration\n\nYou can override the default file filters of a tool, for instance:\n\n```yaml\ntools:\n  ClangFormat:\n    include:\n      match: \u0026cpp_patterns\n      - src/steps/.*\\.((h)|(cpp)|(hpp))\n      - test/unit/.*\\.((h)|(cpp)|(hpp))\n    path: /foo/bin/clang-format\n  ClangTidy:\n    include:\n      match: *cpp_patterns\n```\n\n##### Custom ClangFormat configuration\n\nThese coding conventions come with a predefined configuration of ClangFormat that\nis by default copied in the top directory of the project.\n\nIt is recommended to not add this `.clang-format` to git so that it is fully\ndriven by this project. It will get updated along with the evolution of these\nguidelines. Thus it is recommended to inform git to ignore this file by adding\nit to the top `.gitignore`.\n\nA project can however override the predefined configuration of ClangFormat\nin two ways:\n1. Create a `.clang-format.changes` containing only the required modifications.\n1. Add `.clang-format` to the git repository. This project will never try\nto modify it.\n\n##### Custom CMakeFormat configuration\n\nLike ClangFormat, these coding conventions already provide a CMakeFormat\nconfiguration that the user can customize with a file named\n`.cmake-format.changes.yaml` placed at the project's root directory.\nThis file can be used to specify the signature of owned CMake functions\nand macros, for instance:\n\n```yaml\nadditional_commands:\n  add_mpi_test:\n    kwargs:\n      NAME: 1\n      NUM_PROCS: 1\n      COMMAND: '*'\n```\n\nwill allow CMakeFormat to properly format functions calls like below:\n\n```cmake\nadd_mpi_test(\n  NAME OpSplitOmega_h_2D\n  NUM_PROCS 2\n  COMMAND $\u003cTARGET_FILE:OpSplitOmega_h\u003e --num-iterations 100 square.msh)\n```\n\n##### Continuous Integration\n\nDefine `${PROJECT}_TEST_FORMATTING:BOOL` CMake variable to enforce formatting during\nthe `test` make target.\n\n#### Static Analysis\n\nTo activate static analysis of C++ files with clang-tidy within CMake, enable\nthe CMake variable `${PROJECT}_STATIC_ANALYSIS` where `${PROJECT}` is the name\ngiven to the CMake `project` function.\nFor instance, given a project `foo`:\n`cmake -DFoo_STATIC_ANALYSIS:BOOL=ON \u003cpath\u003e`\nWhenever a C++ file is compiled by CMake, clang-tidy will be called.\n\nYou can also use utility: `bin/clang-tidy`\n\n##### Usage\n\nThis will provide a `clang-tidy` *make* target that will perform static analysis\nof all C++ files. Target fails as soon as one defect is detected among the files.\n\nIt will also activate static analysis report during the compilation phase.\n\n##### Advanced configuration\n\nThe following CMake cache variables can be used to customize the static analysis\nof the code:\n\n* `${PROJECT}_ClangTidy_DEPENDENCIES`: list of CMake targets to build before\n  check C/C++ code. Default value is `\"\"`\n\nThese variables are meant to be overridden inside your CMake project.\nThey are CMake _CACHE_ variables whose value must be forced\n**before including this CMake project**.\n\n##### Custom ClangTidy configuration\n\nThese coding conventions come with a `.clang-tidy` file providing a predefined\nlist of ClangTidy checks. By default, this file is copied in the top directory\nof the project.\n\nIt is recommended to not add this `.clang-tidy` to git so that it is fully\ndriven by this project. It will get updated along with the evolution of these\nguidelines. Thus it is recommended to inform git to ignore this file by adding\nit to the top `.gitignore`.\n\nA project can however override the predefined configuration of ClangFormat\nin two ways:\n1. Create a `.clang-tidy.changes` containing only the required modifications.\n1. Add `.clang-tidy` to the git repository. This project will never try\nto modify it.\n\n#### Pre-Commit utility\n\nEnable CMake option `${PROJECT}_GIT_HOOKS` to enable automatic checks\nbefore committing or pushing with git. the git operation will fail if\none of the registered checks fails.\n\nThe following checks are available:\n* `check-clang-format`: check C++ formatting\n* `check-cmake-format`: check CMake formatting\n* `clang-tidy`: execute static-analysis\n* `courtesy-msg`: print a courtesy message to the console.\n  This check never fails. The default message is a reminder to test and\n  format the changes when pushing a contribution with git.\n  A project can overwrite the message displayed by adding the CMake template\n  named `.git-push-message.cmake.in` at the root of the project directory.\n\nTo enable these checks, use CMake variables `${PROJECT}_GIT_COMMIT_HOOKS` and\n`${PROJECT}_GIT_PUSH_HOOKS` to specify which checks should be executed for\neach specific git operation. For instance:\n\n`cmake -Dfoo_GIT_COMMIT_HOOKS=clang-tidy \\\n       -Dfoo_GIT_PUSH_HOOKS=check-clang-format,courtesy-msg \u003cpath\u003e`\n\nThis feature requires the `pre-commit` utility.\n\n#### Bob\n\n`bob.cmake` is a CMake utility file part of hpc-coding-conventions that provides\na set of convenient macros and functions used to:\n* specify your project options and dependencies\n* specify the proper compilation flags\n* install the proper CMake export flags so that your project can be\n  loaded by another project with the `find_package` CMake function.\n\n##### Compilation flags\n\nBy default, CMake relies on the `CMAKE_BUILD_TYPE` variable to set the proper\ncompilation flags. Because _bob_ is now taking care of it, you must configure\nyour project with `CMAKE_BUILD_TYPE` empty.\n\n_bob_ sets the compilation flags according to a set of CMake variables:\n* `${PROJECT_NAME}_CXX_OPTIMIZE:BOOL`: Compile C++ with optimization (default is ON)\n* `${PROJECT_NAME}_CXX_SYMBOLS:BOOL`: Compile C++ with debug symbols (default is ON)\n* `${PROJECT_NAME}_CXX_WARNINGS:BOOL`: Compile C++ with warnings\" (default is ON)\n* `${PROJECT_NAME}_EXTRA_CXX_FLAGS:STRING`: Additional C++ compilation flags\n* `${PROJECT_NAME}_CXX_FLAGS:STRING`: bypass variables above and use the specified\n  compilation flags. `CMAKE_BUILD_TYPE` is ignored.\n* `${PROJECT_NAME}_NORMAL_CXX_FLAGS:BOOL`: Allow `CMAKE_CXX_FLAGS` to follow _normal_ CMake behavior\n  and bypass all variables above.\n\nDefault `CMAKE_CXX_FLAGS` variable value is taken into account.\n\n##### Integration\n\nThe top-level CMakelists.txt of your project may look like:\n\n```cmake\ncmake_minimum_required(VERSION 3.10)\nproject(HelloWorld VERSION 1.0.0 LANGUAGES CXX)\nadd_subdirectory(hpc-coding-conventions/cpp)\n\nbob_begin_package()\nbob_begin_cxx_flags()\nbob_cxx17_flags()\n# specify custom compilation flags\nfind_package(OpenMP)\nif(OpenMP_FOUND)\n  set(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}\")\n  set(CMAKE_C_FLAGS \"${CMAKE_C_FLAGS} ${OpenMP_C_FLAGS}\")\n  set(CMAKE_FLAGS \"${CMAKE_FLAGS} ${OpenMP_FLAGS}\")\nelse()\n  message(WARNING \"OpenMP support is disabled because it could not be found.\")\nendif()\nbob_end_cxx_flags()\n\n# specify your targets:\nadd_library(...)\nadd_executable(...)\n\nbob_end_package()\n```\n\n#### Embedded third parties\n\nExternal libraries required to build or test your C++ project can be either\ndirectly added to the git repository or as a git submodule. The standard\nroot location for this kind of files is the `3rdparty/` directory but can be\noverriden with the `${PROJECT_NAME}_3RDPARTY_DIR` CMake variable.\n\nAdding single-file/header-only C++ libraries directly to the git repository\nof your project is acceptable in general, like catch2 or the JSON library\nof Niels Lohmann for instance.\n\nMore significant dependencies should be considered as pure external\ndependencies. But it can also be very convenient to have them as git\nsubmodules, and be able to switch between the two.\n\nThis project provides helper functions to deal with these dependencies:\n\n###### cpp_cc_git_submodule\n\n````cmake\n#\n# cpp_cc_git_submodule(source_dir\n#                      [DISABLED]\n#                      SUBDIR path\n#                      [BUILD] [\u003carguments\u003e]\n#                      [PACKAGE] [\u003carguments\u003e]\n#                      GIT_ARGS [\u003carguments\u003e])\n#\n# Add a CMake option in the cache to control whether the\n# submodule is used or not (default ON). The option is named after the source\n# directory passed in first argument, for instance:\n#   cpp_cc_git_submodule(src/eigen)\n# adds the following CMake cached option:\n#  ${PROJECT_NAME}_3RDPARTY_USE_SRC_EIGEN:BOOL=ON\n#\n# If enabled, then the submodule is fetched if missing in the working copy.\n#\n# If the DISABLED argument is provided, then the default value for the CMake\n# option is OFF.\n#\n# If the BUILD argument is provided then the directory is added to the build\n# through the add_subdirectory CMake function. Arguments following the BUILD\n# arguments are passed to the add_subdirectory function call.\n#\n# The optional SUBDIR argument is used by the BUILD argument to determine\n# the path to the directory added to the build. The path specified is relative\n# to the path to the git submodule.\n#\n# If the PACKAGE argument is provided and the CMake option to determine whether\n# the git submodule should be used or not is FALSE, then a call to the find_package\n# function is made with the arguments specified to the PACKAGE option.\n#\n# Default options passed to the `git submodule update` command are\n# `--init --recursive --depth 1` to perform a shallow clone of the submodule.\n# If the GIT_ARGS argument is provided, then its value supersedes the default options.\n#\n````\n\n\n## Contributing\n\nShould you want to contribute to the naming conventions,\nplease refer to the dedicated [contributing document](./cpp/formatting/CONTRIBUTING.md) first.\n\n\n## Funding \u0026 Acknowledgment\n\nThe development of this software was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government's ETH Board of the Swiss Federal Institutes of Technology.\n\nCopyright © 2019-2022 Blue Brain Project/EPFL\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fhpc-coding-conventions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluebrain%2Fhpc-coding-conventions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fhpc-coding-conventions/lists"}