# PythonExtensions

This module defines CMake functions to build Python extension modules and stand-alone executables.

The following variables are defined:

    PYTHON_PREFIX                     - absolute path to the current Python
                                        distribution's prefix
    PYTHON_SITE_PACKAGES_DIR          - absolute path to the current Python
                                        distribution's site-packages directory
    PYTHON_RELATIVE_SITE_PACKAGES_DIR - path to the current Python
                                        distribution's site-packages directory
                                        relative to its prefix
    PYTHON_SEPARATOR                  - separator string for file path
                                        components.  Equivalent to ``os.sep`` in
                                        Python.
    PYTHON_PATH_SEPARATOR             - separator string for PATH-style
                                        environment variables.  Equivalent to
                                        ``os.pathsep`` in Python.
    PYTHON_EXTENSION_MODULE_SUFFIX    - suffix of the compiled module. For example, on
                                        Linux, based on environment, it could be ``.cpython-35m-x86_64-linux-gnu.so``.

The following functions are defined:

python_extension_module

For libraries meant to be used as Python extension modules, either dynamically loaded or directly linked. Amend the configuration of the library target (created using `add_library`) with additional options needed to build and use the referenced library as a Python extension module.

> python_extension_module(<Target>

>   [LINKED_MODULES_VAR <LinkedModVar>] [FORWARD_DECL_MODULES_VAR <ForwardDeclModVar>] [MODULE_SUFFIX <ModuleSuffix>])

Only extension modules that are configured to be built as MODULE libraries can be runtime-loaded through the standard Python import mechanism. All other modules can only be included in standalone applications that are written to expect their presence. In addition to being linked against the libraries for these modules, such applications must forward declare their entry points and initialize them prior to use. To generate these forward declarations and initializations, see `python_modules_header`.

If `<Target>` does not refer to a target, then it is assumed to refer to an extension module that is not linked at all, but compiled along with other source files directly into an executable. Adding these modules does not cause any library configuration modifications, and they are not added to the list of linked modules. They still must be forward declared and initialized, however, and so are added to the forward declared modules list.

If the associated target is of type `MODULE_LIBRARY`, the LINK_FLAGS target property is used to set symbol visibility and export only the module init function. This applies to GNU and MSVC compilers.

Options:

`LINKED_MODULES_VAR <LinkedModVar>`

  Name of the variable referencing a list of extension modules whose libraries must be linked into the executables of any stand-alone applications that use them. By default, the global property `PY_LINKED_MODULES_LIST` is used.

`FORWARD_DECL_MODULES_VAR <ForwardDeclModVar>`

  Name of the variable referencing a list of extension modules whose entry points must be forward declared and called by any stand-alone applications that use them. By default, the global property `PY_FORWARD_DECL_MODULES_LIST` is used.

`MODULE_SUFFIX <ModuleSuffix>`

  Suffix appended to the python extension module file. The default suffix is retrieved using `sysconfig.get_config_var("SO")"`, if not available, the default is then `.so` on unix and `.pyd` on windows. Setting the variable `PYTHON_EXTENSION_MODULE_SUFFIX` in the caller scope defines the value used for all extensions not having a suffix explicitly specified using `MODULE_SUFFIX` parameter.

python_standalone_executable

  python_standalone_executable(<Target>)

For standalone executables that initialize their own Python runtime (such as when building source files that include one generated by Cython with the –embed option). Amend the configuration of the executable target (created using `add_executable`) with additional options needed to properly build the referenced executable.

python_modules_header

Generate a header file that contains the forward declarations and initialization routines for the given list of Python extension modules. `<Name>` is the logical name for the header file (no file extensions). `<HeaderFilename>` is the actual destination filename for the header file (e.g.: decl_modules.h).

> python_modules_header(<Name> [HeaderFilename]

>   [FORWARD_DECL_MODULES_LIST <ForwardDeclModList>] [HEADER_OUTPUT_VAR <HeaderOutputVar>] [INCLUDE_DIR_OUTPUT_VAR <IncludeDirOutputVar>])

without the extension is used as the logical name. If only `<Name>` is

If only `<Name>` is provided, and it ends in the “.h” extension, then it is assumed to be the `<HeaderFilename>`. The filename of the header file provided, and it does not end in the “.h” extension, then the `<HeaderFilename>` is assumed to `<Name>.h`.

The exact contents of the generated header file depend on the logical `<Name>`. It should be set to a value that corresponds to the target application, or for the case of multiple applications, some identifier that conveyes its purpose. It is featured in the generated multiple inclusion guard as well as the names of the generated initialization routines.

The generated header file includes forward declarations for all listed modules, as well as implementations for the following class of routines:

`int <Name>_<Module>(void)`

  Initializes the python extension module, `<Module>`. Returns an integer handle to the module.

`void <Name>_LoadAllPythonModules(void)`

  Initializes all listed python extension modules.

`void CMakeLoadAllPythonModules(void);`

  Alias for `<Name>_LoadAllPythonModules` whose name does not depend on `<Name>`. This function is excluded during preprocessing if the preprocessing macro `EXCLUDE_LOAD_ALL_FUNCTION` is defined.

`void Py_Initialize_Wrapper();`

  Wrapper arpund `Py_Initialize()` that initializes all listed python extension modules. This function is excluded during preprocessing if the preprocessing macro `EXCLUDE_PY_INIT_WRAPPER` is defined. If this function is generated, then `Py_Initialize()` is redefined to a macro that calls this function.

Options:

`FORWARD_DECL_MODULES_LIST <ForwardDeclModList>`

  List of extension modules for which to generate forward declarations of their entry points and their initializations. By default, the global property `PY_FORWARD_DECL_MODULES_LIST` is used.

`HEADER_OUTPUT_VAR <HeaderOutputVar>`

  Name of the variable to set to the path to the generated header file. By default, `<Name>` is used.

`INCLUDE_DIR_OUTPUT_VAR <IncludeDirOutputVar>`

  Name of the variable to set to the path to the directory containing the generated header file. By default, `<Name>_INCLUDE_DIRS` is used.

Defined variables:

`<HeaderOutputVar>`

  The path to the generated header file

`<IncludeDirOutputVar>`

  Directory containing the generated header file

## Example usage

    find_package(PythonExtensions)
    find_package(Cython)
    find_package(Boost COMPONENTS python)

    # Simple Cython Module -- no executables
    add_cython_target(_module.pyx)
    add_library(_module MODULE ${_module})
    python_extension_module(_module)

    # Mix of Cython-generated code and C++ code using Boost Python
    # Stand-alone executable -- no modules
    include_directories(${Boost_INCLUDE_DIRS})
    add_cython_target(main.pyx CXX EMBED_MAIN)
    add_executable(main boost_python_module.cxx ${main})
    target_link_libraries(main ${Boost_LIBRARIES})
    python_standalone_executable(main)

    # stand-alone executable with three extension modules:
    # one statically linked, one dynamically linked, and one loaded at runtime
    #
    # Freely mixes Cython-generated code, code using Boost-Python, and
    # hand-written code using the CPython API.

    # module1 -- statically linked
    add_cython_target(module1.pyx)
    add_library(module1 STATIC ${module1})
    python_extension_module(module1
                            LINKED_MODULES_VAR linked_module_list
                            FORWARD_DECL_MODULES_VAR fdecl_module_list)

    # module2 -- dynamically linked
    include_directories(${Boost_INCLUDE_DIRS})
    add_library(module2 SHARED boost_module2.cxx)
    target_link_libraries(module2 ${Boost_LIBRARIES})
    python_extension_module(module2
                            LINKED_MODULES_VAR linked_module_list
                            FORWARD_DECL_MODULES_VAR fdecl_module_list)

    # module3 -- loaded at runtime
    add_cython_target(module3a.pyx)
    add_library(module3 MODULE ${module3a} module3b.cxx)
    target_link_libraries(module3 ${Boost_LIBRARIES})
    python_extension_module(module3
                            LINKED_MODULES_VAR linked_module_list
                            FORWARD_DECL_MODULES_VAR fdecl_module_list)

    # application executable -- generated header file + other source files
    python_modules_header(modules
                          FORWARD_DECL_MODULES_LIST ${fdecl_module_list})
    include_directories(${modules_INCLUDE_DIRS})

    add_cython_target(mainA)
    add_cython_target(mainC)
    add_executable(main ${mainA} mainB.cxx ${mainC} mainD.c)

    target_link_libraries(main ${linked_module_list} ${Boost_LIBRARIES})
    python_standalone_executable(main)

The following functions are defined:

add_python_library

Add a library that contains a mix of C, C++, Fortran, Cython, F2PY, Template, and Tempita sources. The required targets are automatically generated to “lower” source files from their high-level representation to a file that the compiler can accept.

> add_python_library(<Name>

>   SOURCES [source1 [source2 …]] [INCLUDE_DIRECTORIES [dir1 [dir2 …]] [LINK_LIBRARIES [lib1 [lib2 …]] [DEPENDS [source1 [source2 …]]])

## Example usage

    find_package(PythonExtensions)

    file(GLOB arpack_sources ARPACK/SRC/*.f ARPACK/UTIL/*.f)

     add_python_library(arpack_scipy
       SOURCES ${arpack_sources}
               ${g77_wrapper_sources}
       INCLUDE_DIRECTORIES ARPACK/SRC
     )

add_python_extension

Add a extension that contains a mix of C, C++, Fortran, Cython, F2PY, Template, and Tempita sources. The required targets are automatically generated to “lower” source files from their high-level representation to a file that the compiler can accept.

> add_python_extension(<Name>

>   SOURCES [source1 [source2 …]] [INCLUDE_DIRECTORIES [dir1 [dir2 …]] [LINK_LIBRARIES [lib1 [lib2 …]] [DEPENDS [source1 [source2 …]]])

## Example usage

    find_package(PythonExtensions)

    file(GLOB arpack_sources ARPACK/SRC/*.f ARPACK/UTIL/*.f)

     add_python_extension(arpack_scipy
       SOURCES ${arpack_sources}
               ${g77_wrapper_sources}
       INCLUDE_DIRECTORIES ARPACK/SRC
     )