README.md
1# sanitizers-cmake
2
3 [](https://github.com/arsenm/sanitizers-cmake/issues)
4[](LICENSE)
5
6CMake module to enable sanitizers for binary targets.
7
8
9## Include into your project
10
11To use [FindSanitizers.cmake](cmake/FindSanitizers.cmake), simply add this repository as git submodule into your own repository
12```Shell
13mkdir externals
14git submodule add git://github.com/arsenm/sanitizers-cmake.git externals/sanitizers-cmake
15```
16and adding ```externals/sanitizers-cmake/cmake``` to your ```CMAKE_MODULE_PATH```
17```CMake
18set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/externals/sanitizers-cmake/cmake" ${CMAKE_MODULE_PATH})
19```
20
21If you don't use git or dislike submodules you can copy the files in [cmake directory](cmake) into your repository. *Be careful and keep updates in mind!*
22
23Now you can simply run ```find_package``` in your CMake files:
24```CMake
25find_package(Sanitizers)
26```
27
28
29## Usage
30
31You can enable the sanitizers with ``SANITIZE_ADDRESS``, ``SANITIZE_MEMORY``, ``SANITIZE_THREAD`` or ``SANITIZE_UNDEFINED`` options in your CMake configuration. You can do this by passing e.g. ``-DSANITIZE_ADDRESS=On`` on your command line or with your graphical interface.
32
33If sanitizers are supported by your compiler, the specified targets will be build with sanitizer support. If your compiler has no sanitizing capabilities (I asume intel compiler doesn't) you'll get a warning but CMake will continue processing and sanitizing will simply just be ignored.
34
35#### Compiler issues
36
37Different compilers may be using different implementations for sanitizers. If you'll try to sanitize targets with C and Fortran code but don't use gcc & gfortran but clang & gfortran, this will cause linking problems. To avoid this, such problems will be detected and sanitizing will be disabled for these targets.
38
39Even C only targets may cause problems in certain situations. Some problems have been seen with AddressSanitizer for preloading or dynamic linking. In such cases you may try the ``SANITIZE_LINK_STATIC`` to link sanitizers for gcc static.
40
41
42
43## Build targets with sanitizer support
44
45To enable sanitizer support you simply have to add ``add_sanitizers(<TARGET>)`` after defining your target. To provide a sanitizer blacklist file you can use the ``sanitizer_add_blacklist_file(<FILE>)`` function:
46```CMake
47find_package(Sanitizers)
48
49sanitizer_add_blacklist_file("blacklist.txt")
50
51add_executable(some_exe foo.c bar.c)
52add_sanitizers(some_exe)
53
54add_library(some_lib foo.c bar.c)
55add_sanitizers(some_lib)
56```
57
58## Run your application
59
60The sanitizers check your program, while it's running. In some situations (e.g. LD_PRELOAD your target) it might be required to preload the used AddressSanitizer library first. In this case you may use the ``asan-wrapper`` script defined in ``ASan_WRAPPER`` variable to execute your application with ``${ASan_WRAPPER} myexe arg1 ...``.
61
62
63## Contribute
64
65Anyone is welcome to contribute. Simply fork this repository, make your changes **in an own branch** and create a pull-request for your change. Please do only one change per pull-request.
66
67You found a bug? Please fill out an [issue](https://github.com/arsenm/sanitizers-cmake/issues) and include any data to reproduce the bug.
68
69
70#### Contributors
71
72* [Matt Arsenault](https://github.com/arsenm)
73* [Alexander Haase](https://github.com/alehaa)
74
){kind=link}
){kind=link}