Use "PYCONFIG_*_DIR" variables to simplify configure/install of 'pyconfig.h'
Change PY_*_VERSION variables to PY_*_VERSION to match CMake convention.

If used, this will also allow macro "write_basic_package_version_file"
to work out of the box.

See http://www.cmake.org/cmake/help/v2.8.10/cmake.html#command:find_package
Introduce variables INCLUDE_{BUILD, INSTALL}_DIR

*_BUILD_DIR variable are always absolute paths
*_INSTALL_DIR variables are always relative paths

Keeping this convention make writing of install rules and output paths
easier and less confusing.
Export targets from both the installed and build tree

For reference, see http://www.cmake.org/Wiki/CMake/Tutorials/Exporting_and_Importing_Targets
Introduce BIN_{BUILD, INSTALL}_DIR variables

*_BUILD_DIR variable are always absolute paths
*_INSTALL_DIR variables are always relative paths

Keeping this convention make writing of install rules and output paths
easier and less confusing.
Introduce variable EXTENSION_{BUILD, INSTALL}_DIR

*_BUILD_DIR variable are always absolute paths
*_INSTALL_DIR variables are always relative paths

Keeping this convention make writing of install rules and output paths
easier and less confusing.
Add generation of PythonConfig.cmake

For both install and build tree, the files:

  PythonConfig.cmake
  PythonConfigVersion.cmake
  PythonTargets.cmake

will be configured into:

   <prefix>/share/<libpython>/

It means the following option have to be passed when build a project
depending on python:

   -DPython_DIR:PATH=/path/to/<prefix>/share/<libpython>/

Since CMake 2.8.8, there is convenient module named "CMakePackageConfigHelpers"
that provided the helper macros "configure_package_config_file" and
"write_basic_package_version_file" allowing to easily configure
relocatable packages.
See http://www.cmake.org/cmake/help/v2.8.8/cmake.html#module:CMakePackageConfigHelpers

To avoid upgrading the minimum requirement version of CMake, the
generation of 'PythonConfig.cmake' is done only if possible. To display
message with the macro are not available, a convenient
macro named "check_cmake_command_exists" has also been added.

To allow find_package to work with both a build and install tree, the macro
"configure_package_config_file" is called twice with different value for
the variable:

  CONFIG_DIR_CONFIG
  INCLUDE_DIR_CONFIG
  PYTHON_CONFIG_CODE

The config variables (except PYTHON_CONFIG_CODE) are set using either
the *_BUILD_* or the *_INSTALL_* variables.

The PYTHON_CONFIG_CODE variable allows to inject some CMake code
in the configured PythonConfig.cmake files.

More specifically, for the case of the build tree, not all public headers
are available within INCLUDE_BUILD_DIR. For that reason, using PYTHON_CONFIG_CODE
the variable PYTHON_INCLUDE_DIR is updated with PYCONFIG_BUILD_DIR.

Finally, the PythonConfigVersion file is automatically generated with the
help of "write_basic_package_version_file" and is identical for both the
build and the install tree.

On Linux, I was able to successfully build a simple python module against
both trees. See corresponding CMakeLists.txt was:

cmake_minimum_required(VERSION 2.8.10)
project(example)

find_package(Python REQUIRED CONFIG)
include_directories(${PYTHON_INCLUDE_DIRS})

add_library(example MODULE examplemodule.cxx)
target_link_libraries(example ${PYTHON_LIBRARIES})
set_target_properties(example PROPERTIES PREFIX "")

Questions:

  - Does it make sens to configure the file in <prefix>/share/<libpython>
also for the build tree?  This has the advantages of keeping the build
directory uncluttered but it "less" conventional.

Todo:

  - Teach PythonConfig how to understand COMPONENTS. The list of COMPONENTS
that could be specified are the different python extension.

  - Provide a backward compatible interface for FindPythonLibs.cmake
and FindPythonInterp.cmake. It means existing code would have to simply
append a NO_MODULE or CONFIG option to their existing find_package
statement.

  - Configuration of pkg-config files
Merge branch 'add-package-config-file' into next

* add-package-config-file:
  Add generation of PythonConfig.cmake
  Introduce variable EXTENSION_{BUILD, INSTALL}_DIR
  Introduce BIN_{BUILD, INSTALL}_DIR variables
  Export targets from both the installed and build tree
  Introduce variables INCLUDE_{BUILD, INSTALL}_DIR
  Change PY_*_VERSION variables to PY_*_VERSION to match CMake convention.
  Use "PYCONFIG_*_DIR" variables to simplify configure/install of 'pyconfig.h'