From 4f5410511ac900ce89b5b727f38ab4fcec9eb1e7 Mon Sep 17 00:00:00 2001
From: Alexander Haase <ahaase@alexhaase.de>
Date: Tue, 14 Jun 2016 01:39:30 +0200
Subject: [PATCH] Updated README file.

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index dee9ef6..4c8f580 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,73 @@
-sanitizers-cmake
-================
+# CMake-sanitizers
 
-CMake modules to help use sanitizers
+ [![](https://img.shields.io/github/issues-raw/RWTH-ELP/CMake-sanitizers.svg?style=flat-square)](https://github.com/RWTH-ELP/CMake-sanitizers/issues)
+[![MIT](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+
+CMake module to enable sanitizers for binary targets.
+
+
+## Include into your project
+
+To use [FindSanitizers.cmake](cmake/FindSanitizers.cmake), simply add this repository as git submodule into your own repository
+```Shell
+mkdir externals
+git submodule add git://github.com/RWTH-ELP/CMake-sanitizers.git externals/CMake-sanitizers
+```
+and adding ```externals/cmake-sanitizers/cmake``` to your ```CMAKE_MODULE_PATH```
+```CMake
+set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/externals/cmake-sanitizers/cmake" ${CMAKE_MODULE_PATH})
+```
+
+If 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!*
+
+Now you can simply run ```find_package``` in your CMake files:
+```CMake
+find_package(Sanitizers)
+```
+
+
+## Usage
+
+You 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.
+
+If 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.
+
+#### Compiler issues
+
+Different 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.
+
+Even 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.
+
+
+
+## Build targets with sanitizer support
+
+To 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 ``add_sanitizer_blacklist(<FILE>)`` function:
+```CMake
+find_package(Sanitizers)
+
+add_sanitizer_blacklist("blacklist.txt")
+
+add_executable(some_exe foo.c bar.c)
+add_sanitizers(some_exe)
+
+add_library(some_lib foo.c bar.c)
+add_sanitizers(some_lib)
+```
+
+## Run your application
+
+The 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 ...``.
+
+
+## Contribute
+
+Anyone 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.
+
+You found a bug? Please fill out an [issue](https://github.com/RWTH-ELP/CMake-sanitizers/issues) and include any data to reproduce the bug.
+
+
+#### Contributors
+
+* [Matt Arsenault](https://github.com/arsenm)
+* [Alexander Haase](https://github.com/alehaa)