{"id":15569448,"url":"https://github.com/johnthagen/clang-blueprint","last_synced_at":"2025-09-07T02:11:27.703Z","repository":{"id":41319646,"uuid":"131409640","full_name":"johnthagen/clang-blueprint","owner":"johnthagen","description":":european_castle: Example C++11 CMake project that incorporates awesome Clang tooling :dragon:","archived":false,"fork":false,"pushed_at":"2020-04-04T12:43:33.000Z","size":787,"stargazers_count":106,"open_issues_count":1,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-20T13:59:30.460Z","etag":null,"topics":["address-sanitizer","clang","clang-format","clang-static-analyzer","clang-tidy","clang-tooling","cmake","coverage-report","cpp","cpp11","cppcheck","doxygen"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnthagen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-28T12:57:39.000Z","updated_at":"2024-10-22T21:53:50.000Z","dependencies_parsed_at":"2022-08-26T08:40:54.024Z","dependency_job_id":null,"html_url":"https://github.com/johnthagen/clang-blueprint","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnthagen%2Fclang-blueprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnthagen%2Fclang-blueprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnthagen%2Fclang-blueprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnthagen%2Fclang-blueprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnthagen","download_url":"https://codeload.github.com/johnthagen/clang-blueprint/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233077318,"owners_count":18621511,"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":["address-sanitizer","clang","clang-format","clang-static-analyzer","clang-tidy","clang-tooling","cmake","coverage-report","cpp","cpp11","cppcheck","doxygen"],"created_at":"2024-10-02T17:29:04.384Z","updated_at":"2025-01-09T02:05:31.900Z","avatar_url":"https://github.com/johnthagen.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clang-blueprint\n\n\u003c!-- Doxygen Table of Contents --\u003e\n[TOC]\n\n| Build Status |                                                                                |\n|--------------|--------------------------------------------------------------------------------|\n| Travis       | [![Travis Build Status][travis-build-status-svg]][travis-build-status]         |\n\nExample C++11 [CMake](https://cmake.org/)  project that incorporates awesome \n[Clang](https://clang.llvm.org/) tooling, such as sanitizers, a code formatter, and code coverage\nreporting.\n\nThis repository is designed to be used as an example of how to set up a C++ project to use\nClang tooling as well as be a template that can be copied and modified. Care has been taken to \nfollow established C++ conventions whenever possible. \n\nFor more information about Clang, see the \n[awesome-clang](https://github.com/ingve/awesome-clang) repository.\n\nFor C++ coding guidelines, see the \n[C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines).\n\n## Requirements\n\n### Ubuntu 18.04 LTS\n\nInstall required packages.\n\n\u003e On Ubuntu 16.04 LTS, omit the `clang-tools` package, which is included in the `clang` package on Ubuntu 16.04 LTS.\n\n```bash\n$ sudo apt install gcc g++ clang clang-tidy clang-tools clang-format cmake cppcheck doxygen graphviz\n```\n\n### macOS\n\nInstall [Homebrew](https://brew.sh/)\n\nInstall required packages\n\n```\n$ brew install llvm clang-format cmake cppcheck doxygen graphviz\n```\n\nThe `llvm` formula is not installed into the user's `PATH` by default because it shadows\ntools such as `clang` that Apple provide. In order to use `clang-tidy` and LLVM code\ncoverage tools, we need those in the `PATH` when `cmake` runs.\n\n```bash\n$ echo 'export PATH=\"/usr/local/opt/llvm/bin:$PATH\"' \u003e\u003e ~/.bash_profile\n```\n\n### CentOS 7\n\nFirst install the [EPEL](https://fedoraproject.org/wiki/EPEL) repository.\n\n```bash\n$ sudo yum install epel-release\n```\n\nNext install the [SCL](https://wiki.centos.org/AdditionalResources/Repositories/SCL) repository.\n\n```bash\n$ sudo yum install centos-release-scl\n```\n\nInstall required packages\n\n```bash\n$ sudo yum install gcc gcc-c++ llvm-toolset-7 llvm-toolset-7-clang-tools-extra cmake3 cppcheck doxygen graphviz\n```\n\n## Build\n\nAppend `-DCMAKE_BUILD_TYPE=Release` or `-DCMAKE_BUILD_TYPE=Debug` to the `cmake` command\narguments to specify release or debug builds.\n\n### GCC\n\n```bash\n$ cd build\n$ cmake ..\n$ make\n```\n\n### Clang\n\n**Note: On CentOS 7, replace the `cmake` command with \n`scl enable llvm-toolset-7 'cmake3 -DCMAKE_CXX_COMPILER=clang++ ..'`.**\n\n```bash\n$ cd build\n$ cmake -DCMAKE_CXX_COMPILER=clang++ ..\n$ make\n```\n\n### Treat warnings as errors\n\nUse `-DWERROR=On` option to treat compile warnings as errors.\n\n```bash\n$ cd build\n$ cmake -DWERROR=On ..\n$ make\n/home/user/GitHub/clang-blueprint/src/danger/bad_examples.cpp:13:18: error: array index\n      3 is past the end of the array (which contains 2 elements)\n      [-Werror,-Warray-bounds]\n    std::cout \u003c\u003c a[3];\n                 ^ ~\n...\n```\n\n## Run\n\nFirst, perform a build as described in the **Build** section, then run the following\ncommands in the `build` directory.\n\n### Application\n\n```bash\n$ ./clang-blueprint\n```\n\n### Unit tests\n\nUnit tests are written using the [Catch2](https://github.com/catchorg/Catch2/) unit testing\nframework.\n\n```bash\n$ ./unit_test\n```\n\n## Build Docs\n\nDocumentation is built using [Doxygen](http://www.doxygen.org/). To configure how the docs are \nbuilt, modify [`docs/Doxyfile`](docs/Doxyfile).\n\n```bash\n$ cd docs\n$ doxygen\n$ firefox html/index.html\n```\n\n![Doxygen Documentation](./docs/images/doxygen.png)\n\n## Clang Tools\n\n**Note: On CentOS 7 for all of the following Clang tool instructions, replace the `cmake` \ncommand with `scl enable llvm-toolset-7 'cmake3 \u003cOPTIONS\u003e ..'`.**\n\n### Clang Static Analyzer\n\nThe [Clang Static Analyzer](https://clang-analyzer.llvm.org/) finds bugs in C/C++ programs\nat compile time.\n\n**Note: Not available on CentOS 7.**\n\n```bash\n$ cd build\n# On Ubuntu 18.04, use the specific scan-build-6.0 command.\n$ scan-build cmake ..\n$ scan-build make\n...\nscan-build: 2 bugs found.\nscan-build: Run 'scan-view /var/folders/...' to examine bug reports.\n\n# Run the scan-view command printed in the build output to view the report.\n# On Ubuntu 18.04, use the specific scan-view-6.0 command.\n$ scan-view /var/folders/...\n```\n\n![Clang Static Analyzer Report](docs/images/clang_static_analyzer_1.png)\n\n![Clang Static Analyzer Report](docs/images/clang_static_analyzer_2.png)\n\n### Clang-Tidy\n\n[Clang-Tidy](http://clang.llvm.org/extra/clang-tidy/) is configured using the \n[`.clang-tidy`](.clang-tidy) configuration file. Modify this file to control which checks should \nbe run and configure parameters for certain checks.\n\nFor real projects, you'll likely want to modify this configuration file and disable certain\nchecks you feel are too pedantic or don't match your project needs.\n\n```bash\n$ cd build\n$ cmake ..\n$ make clang-tidy\nScanning dependencies of target clang-tidy\n95 warnings generated.\n7477 warnings generated.\n/home/user/GitHub/clang-blueprint/src/main.cpp:10:28: warning: \n    parameter 'argc' is unused [misc-unused-parameters]\nint32_t main(const int32_t argc, const char* argv[]) {\n                           ^~~~~\n                            /*argc*/\n/home/user/GitHub/clang-blueprint/src/main.\n...\n```\n\n### AddressSanitizer\n\n[AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) is a fast memory error\ndetector. It consists of a compiler instrumentation module and a run-time library.\nThe tool can detect the following types of bugs:\n\n- Out-of-bounds accesses to heap, stack and globals\n- Use-after-free\n- Use-after-return\n- Use-after-scope\n- Double-free, invalid free\n- Memory leaks\n\nIt is similar in functionality to Valgrind, but runs much faster and is able to catch a\nwider variety of bugs.\n\n```bash\n$ cd build\n$ cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=clang++ -DADDRESS_SANITIZER=On ..\n$ make\n$ ./unit_test\n==25797==ERROR: AddressSanitizer: heap-use-after-free on address 0x61400000024c at \npc 0x000000616ecf bp 0x7ffd7aab4b30 sp 0x7ffd7aab4b28\n...\n```\n\n### UndefinedBehaviourSanitizer\n\nThe [UndefinedBehaviourSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)\nmodifies the program at compile-time to catch various kinds of undefined behavior during \nprogram execution, for example:\n\n- Using misaligned or null pointer\n- Signed integer overflow\n- Conversion to, from, or between floating-point types which would overflow the destination\n\n```bash\n$ cd build\n$ cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=clang++ -DUNDEFINED_SANITIZER=On ..\n$ make\n$ ./unit_test\n/home/user/GitHub/clang-blueprint/test/danger/test_bad_examples.cpp:17:7: \nruntime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'\n...\n```\n\n### Clang Code Coverage\n\n[Clang source-based code coverage](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html)\nprovides metrics on which lines are covered by tests.\n\n```bash\n$ cd build\n$ cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=clang++ -DCLANG_CODE_COVERAGE=On ..\n$ make\n$ ./unit_test\n\n# On Ubuntu 18.04, use the specific llvm-profdata-6.0 command.\n$ llvm-profdata merge -sparse default.profraw -o default.profdata\n# On Ubuntu 18.04, use the specific llvm-cov-6.0 command.\n$ llvm-cov show -format=html -o coverage ./unit_test -instr-profile=default.profdata\n\n# View the coverage report.\n$ firefox coverage/index.html\n```\n\n![Coverage Report](./docs/images/coverage_report.png)\n\n### Clang-Format\n\n[Clang-Format](https://clang.llvm.org/docs/ClangFormat.html) is a tool that can automically\nformat your source code accordiing to a specific style guide, saving developers time. It is \nconfigured using the [`.clang-format`](.clang-format) configuration file. Modify this file to\ncontrol how source files should be formatted.\n\nTo demonstrate `clang-format` in action, first modify a line from [`src/main.cpp`](src/main.cpp)\n\n```cpp\n    return EXIT_SUCCESS;\n```\n\nTo\n\n```cpp\n    return           EXIT_SUCCESS;\n```\n\nNext, run `clang-format` on the project.\n\n```bash\n$ cd build\n$ cmake ..\n$ make clang-format\n```\n\n[`src/main.cpp`](src/main.cpp) will be reformatted properly to\n\n```cpp\n    return EXIT_SUCCESS;\n```\n\n## Cppcheck\n\n[Cppcheck](http://cppcheck.sourceforge.net/) is a static analysis tool for C/C++ code. To run \non the project\n\n```bash\n$ cd build\n$ cmake ..\n$ make cppcheck\n[/home/user/GitHub/clang-blueprint/src/main.cpp:14]: (error) Array 'a[2]' accessed at index 3, \n    which is out of bounds.\n...\n```\n\n\u003c!-- Badges --\u003e\n[travis-build-status]: https://travis-ci.com/johnthagen/clang-blueprint\n[travis-build-status-svg]: https://travis-ci.com/johnthagen/clang-blueprint.svg?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnthagen%2Fclang-blueprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnthagen%2Fclang-blueprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnthagen%2Fclang-blueprint/lists"}