README

For a short installation guide, see the INSTALL file.

For examples on how to use this tool, see HOWTO.

== Introducing LLCov ==

=== What is LLCov? ===

LLCov is a C/C++ code instrumentation tool that can be used to measure block coverage.
Unlike the popular GCOV coverage tool for GCC, LLCov instruments each basic block in 
the code with a call to an external function (provided by an arbitrary runtime library). 
In addition, the instrumentation can be limited to parts of the code (e.g. individual 
files, functions or blocks) to improve performance and focus on the relevant code parts.
LLCov is based on LLVM and integrates into the Clang C/C++ compiler.

=== Why would I need this? ===

There are several scenarios where LLCov could aid the development process while GCOV 
would not be suitable for the purpose:

* Instrument only code that is not covered by tests: Almost all projects have one or 
  more test suites that cover a certain amount of the code base. Adding an 
  instrumentation to the "untested" code can be helpful for automatic testing tools 
  to detect when such a part of the code is executed.
* Instrument only code changed by a patch: Whenever a patch is submitted, only the 
  code that is changed by the patch could be instrumented, to see if it is covered 
  by the test suites and to what extent. Only instrumenting the patched part should 
  provide a great performance boost.
* Use coverage information while the program is running (as a "feedback"), e.g. in a 
  fuzzer: If the fuzzer knows that it just covered a piece of code that should be 
  tested more extensively, it can focus further on that part. This kind of feedback 
  can also be used to adjust probabilities in the fuzzer automatically to provide a 
  better balance between different branches during testing.
* Get coverage information via alternative ways: The runtime library of LLCov can 
  easily be replaced/extended, e.g. to send all coverage information over a network 
  link. Wouldn't it be nice to get coverage information from a mobile/embedded device 
  directly over the network?