Modules/FindPython.cmake

   1 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2 # file Copyright.txt or https://cmake.org/licensing for details.
   3
   4 #[=======================================================================[.rst:
   5 FindPython
   6 ----------
   7
   8 Find Python interpreter, compiler and development environment (include
   9 directories and libraries).
  10
  11 The following components are supported:
  12
  13 * ``Interpreter``: search for Python interpreter.
  14 * ``Compiler``: search for Python compiler. Only offered by IronPython.
  15 * ``Development``: search for development artifacts (include directories and
  16   libraries).
  17 * ``NumPy``: search for NumPy include directories.
  18
  19 If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed.
  20
  21 To ensure consistent versions between components ``Interpreter``, ``Compiler``,
  22 ``Development`` and ``NumPy``, specify all components at the same time::
  23
  24   find_package (Python COMPONENTS Interpreter Development)
  25
  26 This module looks preferably for version 3 of Python. If not found, version 2
  27 is searched.
  28 To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
  29 :module:`FindPython2` modules rather than this one.
  30
  31 .. note::
  32
  33   If components ``Interpreter`` and ``Development`` are both specified, this
  34   module search only for interpreter with same platform architecture as the one
  35   defined by ``CMake`` configuration. This contraint does not apply if only
  36   ``Interpreter`` component is specified.
  37
  38 Imported Targets
  39 ^^^^^^^^^^^^^^^^
  40
  41 This module defines the following :ref:`Imported Targets <Imported Targets>`
  42 (when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):
  43
  44 ``Python::Interpreter``
  45   Python interpreter. Target defined if component ``Interpreter`` is found.
  46 ``Python::Compiler``
  47   Python compiler. Target defined if component ``Compiler`` is found.
  48 ``Python::Python``
  49   Python library for Python embedding. Target defined if component
  50   ``Development`` is found.
  51 ``Python::Module``
  52   Python library for Python module. Target defined if component ``Development``
  53   is found.
  54 ``Python::NumPy``
  55   NumPy Python library. Target defined if component ``NumPy`` is found.
  56
  57 Result Variables
  58 ^^^^^^^^^^^^^^^^
  59
  60 This module will set the following variables in your project
  61 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
  62
  63 ``Python_FOUND``
  64   System has the Python requested components.
  65 ``Python_Interpreter_FOUND``
  66   System has the Python interpreter.
  67 ``Python_EXECUTABLE``
  68   Path to the Python interpreter.
  69 ``Python_INTERPRETER_ID``
  70   A short string unique to the interpreter. Possible values include:
  71     * Python
  72     * ActivePython
  73     * Anaconda
  74     * Canopy
  75     * IronPython
  76 ``Python_STDLIB``
  77   Standard platform independent installation directory.
  78
  79   Information returned by
  80   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
  81 ``Python_STDARCH``
  82   Standard platform dependent installation directory.
  83
  84   Information returned by
  85   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
  86 ``Python_SITELIB``
  87   Third-party platform independent installation directory.
  88
  89   Information returned by
  90   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
  91 ``Python_SITEARCH``
  92   Third-party platform dependent installation directory.
  93
  94   Information returned by
  95   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
  96 ``Python_SOABI``
  97   Extension suffix for modules.
  98
  99   Information returned by
 100   ``distutils.sysconfig.get_config_flag('SOABI')`` or computed from
 101   ``distutils.sysconfig.get_config_flag('EXT_SUFFIX')`` or
 102   ``python-config --extension-suffix``.
 103 ``Python_Compiler_FOUND``
 104   System has the Python compiler.
 105 ``Python_COMPILER``
 106   Path to the Python compiler. Only offered by IronPython.
 107 ``Python_COMPILER_ID``
 108   A short string unique to the compiler. Possible values include:
 109     * IronPython
 110 ``Python_Development_FOUND``
 111   System has the Python development artifacts.
 112 ``Python_INCLUDE_DIRS``
 113   The Python include directories.
 114 ``Python_LIBRARIES``
 115   The Python libraries.
 116 ``Python_LIBRARY_DIRS``
 117   The Python library directories.
 118 ``Python_RUNTIME_LIBRARY_DIRS``
 119   The Python runtime library directories.
 120 ``Python_VERSION``
 121   Python version.
 122 ``Python_VERSION_MAJOR``
 123   Python major version.
 124 ``Python_VERSION_MINOR``
 125   Python minor version.
 126 ``Python_VERSION_PATCH``
 127   Python patch version.
 128 ``Python_NumPy_FOUND``
 129   System has the NumPy.
 130 ``Python_NumPy_INCLUDE_DIRS``
 131   The NumPy include directries.
 132 ``Python_NumPy_VERSION``
 133   The NumPy version.
 134
 135 Hints
 136 ^^^^^
 137
 138 ``Python_ROOT_DIR``
 139   Define the root directory of a Python installation.
 140
 141 ``Python_USE_STATIC_LIBS``
 142   * If not defined, search for shared libraries and static libraries in that
 143     order.
 144   * If set to TRUE, search **only** for static libraries.
 145   * If set to FALSE, search **only** for shared libraries.
 146
 147 ``Python_FIND_ABI``
 148   This variable defines which ABIs, as defined in
 149   `PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.
 150
 151   .. note::
 152
 153     This hint will be honored only when searched for ``Python`` version 3.
 154
 155   .. note::
 156
 157     If ``Python_FIND_ABI`` is not defined, any ABI will be searched.
 158
 159   The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
 160   ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
 161   Each element can be set to one of the following:
 162
 163   * ``ON``: Corresponding flag is selected.
 164   * ``OFF``: Corresponding flag is not selected.
 165   * ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.
 166
 167   From this 3-tuple, various ABIs will be searched starting from the most
 168   specialized to the most general. Moreover, ``debug`` versions will be
 169   searched **after** ``non-debug`` ones.
 170
 171   For example, if we have::
 172
 173     set (Python_FIND_ABI "ON" "ANY" "ANY")
 174
 175   The following flags combinations will be appended, in that order, to the
 176   artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
 177
 178   And to search any possible ABIs::
 179
 180     set (Python_FIND_ABI "ANY" "ANY" "ANY")
 181
 182   The following combinations, in that order, will be used: ``mu``, ``m``,
 183   ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
 184
 185   .. note::
 186
 187     This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
 188     when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
 189     `python.org <https://www.python.org/>`_ will be found only if value for
 190     each flag is ``OFF`` or ``ANY``.
 191
 192 ``Python_FIND_STRATEGY``
 193   This variable defines how lookup will be done.
 194   The ``Python_FIND_STRATEGY`` variable can be set to one of the following:
 195
 196   * ``VERSION``: Try to find the most recent version in all specified
 197     locations.
 198     This is the default if policy :policy:`CMP0094` is undefined or set to
 199     ``OLD``.
 200   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 201     constraints is founded.
 202     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 203
 204 ``Python_FIND_REGISTRY``
 205   On Windows the ``Python_FIND_REGISTRY`` variable determine the order
 206   of preference between registry and environment variables.
 207   the ``Python_FIND_REGISTRY`` variable can be set to one of the following:
 208
 209   * ``FIRST``: Try to use registry before environment variables.
 210     This is the default.
 211   * ``LAST``: Try to use registry after environment variables.
 212   * ``NEVER``: Never try to use registry.
 213
 214 ``Python_FIND_FRAMEWORK``
 215   On macOS the ``Python_FIND_FRAMEWORK`` variable determine the order of
 216   preference between Apple-style and unix-style package components.
 217   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 218   variable.
 219
 220   .. note::
 221
 222     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 223
 224   If ``Python_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 225   variable will be used, if any.
 226
 227 ``Python_FIND_VIRTUALENV``
 228   This variable defines the handling of virtual environments managed by
 229   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 230   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 231   takes precedence over ``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 232   variables.  The ``Python_FIND_VIRTUALENV`` variable can be set to one of the
 233   following:
 234
 235   * ``FIRST``: The virtual environment is used before any other standard
 236     paths to look-up for the interpreter. This is the default.
 237   * ``ONLY``: Only the virtual environment is used to look-up for the
 238     interpreter.
 239   * ``STANDARD``: The virtual environment is not used to look-up for the
 240     interpreter. In this case, variable ``Python_FIND_REGISTRY`` (Windows)
 241     or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 242     ``NEVER`` to select preferably the interpreter from the virtual
 243     environment.
 244
 245   .. note::
 246
 247     If the component ``Development`` is requested, it is **strongly**
 248     recommended to also include the component ``Interpreter`` to get expected
 249     result.
 250
 251 Artifacts Specification
 252 ^^^^^^^^^^^^^^^^^^^^^^^
 253
 254 To solve special cases, it is possible to specify directly the artifacts by
 255 setting the following variables:
 256
 257 ``Python_EXECUTABLE``
 258   The path to the interpreter.
 259
 260 ``Python_COMPILER``
 261   The path to the compiler.
 262
 263 ``Python_LIBRARY``
 264   The path to the library. It will be used to compute the
 265   variables ``Python_LIBRARIES``, ``Python_LIBRAY_DIRS`` and
 266   ``Python_RUNTIME_LIBRARY_DIRS``.
 267
 268 ``Python_INCLUDE_DIR``
 269   The path to the directory of the ``Python`` headers. It will be used to
 270   compute the variable ``Python_INCLUDE_DIRS``.
 271
 272 ``Python_NumPy_INCLUDE_DIR``
 273   The path to the directory of the ``NumPy`` headers. It will be used to
 274   compute the variable ``Python_NumPy_INCLUDE_DIRS``.
 275
 276 .. note::
 277
 278   All paths must be absolute. Any artifact specified with a relative path
 279   will be ignored.
 280
 281 .. note::
 282
 283   When an artifact is specified, all ``HINTS`` will be ignored and no search
 284   will be performed for this artifact.
 285
 286   If more than one artifact is specified, it is the user's responsability to
 287   ensure the consistency of the various artifacts.
 288
 289 Commands
 290 ^^^^^^^^
 291
 292 This module defines the command ``Python_add_library`` (when
 293 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 294 :command:`add_library` and adds a dependency to target ``Python::Python`` or,
 295 when library type is ``MODULE``, to target ``Python::Module`` and takes care of
 296 Python module naming rules::
 297
 298   Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
 299                       <source1> [<source2> ...])
 300
 301 If the library type is not specified, ``MODULE`` is assumed.
 302
 303 For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
 304 module suffix will include the ``Python_SOABI`` value, if any.
 305 #]=======================================================================]
 306
 307
 308 set (_PYTHON_PREFIX Python)
 309
 310 if (DEFINED Python_FIND_VERSION)
 311   set (_Python_REQUIRED_VERSION_MAJOR ${Python_FIND_VERSION_MAJOR})
 312
 313   include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 314 else()
 315   # iterate over versions in quiet and NOT required modes to avoid multiple
 316   # "Found" messages and prematurally failure.
 317   set (_Python_QUIETLY ${Python_FIND_QUIETLY})
 318   set (_Python_REQUIRED ${Python_FIND_REQUIRED})
 319   set (Python_FIND_QUIETLY TRUE)
 320   set (Python_FIND_REQUIRED FALSE)
 321
 322   set (_Python_REQUIRED_VERSIONS 3 2)
 323   set (_Python_REQUIRED_VERSION_LAST 2)
 324
 325   unset (_Python_INPUT_VARS)
 326   foreach (_Python_ITEM IN ITEMS Python_EXECUTABLE Python_COMPILER Python_LIBRARY
 327                                  Python_INCLUDE_DIR Python_NumPy_INCLUDE_DIR)
 328     if (NOT DEFINED ${_Python_ITEM})
 329       list (APPEND _Python_INPUT_VARS ${_Python_ITEM})
 330     endif()
 331   endforeach()
 332
 333   foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
 334     set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
 335     include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 336     if (Python_FOUND OR
 337         _Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
 338       break()
 339     endif()
 340     # clean-up INPUT variables not set by the user
 341     foreach (_Python_ITEM IN LISTS _Python_INPUT_VARS)
 342       unset (${_Python_ITEM})
 343     endforeach()
 344     # clean-up some CACHE variables to ensure look-up restart from scratch
 345     foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
 346       unset (${_Python_ITEM} CACHE)
 347     endforeach()
 348   endforeach()
 349
 350   unset (Python_FIND_VERSION)
 351
 352   set (Python_FIND_QUIETLY ${_Python_QUIETLY})
 353   set (Python_FIND_REQUIRED ${_Python_REQUIRED})
 354   if (Python_FIND_REQUIRED OR NOT Python_FIND_QUIETLY)
 355     # call again validation command to get "Found" or error message
 356     find_package_handle_standard_args (Python HANDLE_COMPONENTS
 357                                               REQUIRED_VARS ${_Python_REQUIRED_VARS}
 358                                               VERSION_VAR Python_VERSION)
 359   endif()
 360 endif()
 361
 362 if (COMMAND __Python_add_library)
 363   macro (Python_add_library)
 364     __Python_add_library (Python ${ARGV})
 365   endmacro()
 366 endif()
 367
 368 unset (_PYTHON_PREFIX)