README

PHP-specific Plugin for clang's static analyzer

About clang:
  Clang /ˈklæŋ/ is a compiler front end for the C, C++, Objective-C and
  Objective-C++ programming languages. It uses LLVM as its back end and has
  been part of its releases since LLVM 2.6.
  http://en.wikipedia.org/wiki/Clang

About clang's static analyzer:
  The Clang Static Analyzer is a source code analysis tool that finds bugs
  in C, C++, and Objective-C programs.
  http://clang-analyzer.llvm.org/

About this project:
  PHP uses a family of variadic functions like zend_parse_parameters(), or
  zpp in short, to retrieve arguements from PHP userland into C variables.
  Due to the variadic nature ofthis funtion the compiler can't check the
  type of the C variable. This plugin enriches the Clang Static Analyzer
  with a capaility to check it.

Requirements:
  Clang >= 3.4
  CMAKE >= 2.8 (optional, might work with earlir versions)

  On debian based systems you can obtain the newer Clang binaries using the
  instructions from http://llvm.org/apt/

Installing with cmake:
  With cmake cross platform builds can be achieved. An example command
  sequence to build on Ubuntu:

  aptitude install clang llvm-dev libclang-dev
  cmake -G"Unix Makefiles" -DCLANG_INCLUDE_DIRS:STRING=/usr/include/clang/3.4/ \
           -DLLVM_CONFIG_EXECUTABLE:STRING=/usr/bin/llvm-config-3.4
  make

  Note the explicit Clang version, that might change for your particular
  system. Or even it could be ommited when the minimal required Clang version
  is in the path.

  On Windows it'll work similar way, though note that LLVM has Visual Studio
  2012 as requirement. Therefore you'll need cmake >= 2.8 and the generator
  name there is "Visual Studio 11". Depending on required Clang version, you
  might need to build Clang yourself. For that case some useful doc can be
  found under http://clang.llvm.org/get_started.html

Usage:
  To check a simple file one has to load the plugin and activate the checker
  this might look like this:
   $ clang -cc1 \
           -fcolor-diagnostics \
           -analyze \
           -analyzer-checker=php.ZPPChecker \
           -load /path/to/PHPChecker.so \
	   -analyzer-config php-zpp-version=PHP5 \
           source_fileto_check.c
  Note: The -cc1 frontend doesn't include system headers and such by default.
  For more than simple test files this might not be useful. A call like
   $ clang -Xclang -fcolor-diagnostics \
           -Xclang -analyze \
           -Xclang -analyzer-checker=php.ZPPChecker5 \
           -Xclang -load=/path/to/PHPChecker.so \
	   -Xclang -analyzer-config -Xclang php-zpp-version=PHP5 \
           source_fileto_check.c
  might be more helpful. This frontend behaves like gcc, clang-specific
  options have to be prefixed with -Xclang. See clang documentation for
  details.

  For testing a complete build including a HTML report Clang Analyzer provides
  a set of helper scripts. PHP can be compiled using them in such a manner:
   $ scan-build --use-analyzer=/path/to/bin/clang \
                ./configure --enable-php-features-as-usual
   $ scan-build --use-analyzer=/path/to/bin/clang \
                -load-plugin /path/to/PHPChecker.so \
                -enable-checker php.ZPPChecker5 \
                make
  So first we configure PHP, using the wrapper script ensures to setup the proper
  compiler but we don't want to run all checks during configure phase. After that
  we enable all tests.
  Unfortunately scan-build doesn't allow passing extra options (-analyzer-config)
  The version can also be choosen by setting the PHP_ZPP_CHECKER_VERSION
  environment variable accordingly.

Licensing:
  Currently University of Illinois Open Source License is being used. Eventually
  the code might be relicensed under PHP License 3.01 at a later stage.