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 .. versionadded:: 3.12
   9
  10 Find Python interpreter, compiler and development environment (include
  11 directories and libraries).
  12
  13 .. versionadded:: 3.19
  14   When a version is requested, it can be specified as a simple value or as a
  15   range. For a detailed description of version range usage and capabilities,
  16   refer to the :command:`find_package` command.
  17
  18 The following components are supported:
  19
  20 * ``Interpreter``: search for Python interpreter.
  21 * ``Compiler``: search for Python compiler. Only offered by IronPython.
  22 * ``Development``: search for development artifacts (include directories and
  23   libraries).
  24
  25   .. versionadded:: 3.18
  26     This component includes two sub-components which can be specified
  27     independently:
  28
  29     * ``Development.Module``: search for artifacts for Python module
  30       developments.
  31     * ``Development.Embed``: search for artifacts for Python embedding
  32       developments.
  33
  34 * ``NumPy``: search for NumPy include directories.
  35
  36 .. versionadded:: 3.14
  37   Added the ``NumPy`` component.
  38
  39 If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed.
  40
  41 If component ``Development`` is specified, it implies sub-components
  42 ``Development.Module`` and ``Development.Embed``.
  43
  44 To ensure consistent versions between components ``Interpreter``, ``Compiler``,
  45 ``Development`` (or one of its sub-components) and ``NumPy``, specify all
  46 components at the same time::
  47
  48   find_package (Python COMPONENTS Interpreter Development)
  49
  50 This module looks preferably for version 3 of Python. If not found, version 2
  51 is searched.
  52 To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
  53 :module:`FindPython2` modules rather than this one.
  54
  55 .. note::
  56
  57   If components ``Interpreter`` and ``Development`` (or one of its
  58   sub-components) are both specified, this module search only for interpreter
  59   with same platform architecture as the one defined by ``CMake``
  60   configuration. This constraint does not apply if only ``Interpreter``
  61   component is specified.
  62
  63 Imported Targets
  64 ^^^^^^^^^^^^^^^^
  65
  66 This module defines the following :ref:`Imported Targets <Imported Targets>`:
  67
  68 .. versionchanged:: 3.14
  69   :ref:`Imported Targets <Imported Targets>` are only created when
  70   :prop_gbl:`CMAKE_ROLE` is ``PROJECT``.
  71
  72 ``Python::Interpreter``
  73   Python interpreter. Target defined if component ``Interpreter`` is found.
  74 ``Python::Compiler``
  75   Python compiler. Target defined if component ``Compiler`` is found.
  76
  77 ``Python::Module``
  78   .. versionadded:: 3.15
  79
  80   Python library for Python module. Target defined if component
  81   ``Development.Module`` is found.
  82
  83 ``Python::Python``
  84   Python library for Python embedding. Target defined if component
  85   ``Development.Embed`` is found.
  86
  87 ``Python::NumPy``
  88   .. versionadded:: 3.14
  89
  90   NumPy Python library. Target defined if component ``NumPy`` is found.
  91
  92 Result Variables
  93 ^^^^^^^^^^^^^^^^
  94
  95 This module will set the following variables in your project
  96 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
  97
  98 ``Python_FOUND``
  99   System has the Python requested components.
 100 ``Python_Interpreter_FOUND``
 101   System has the Python interpreter.
 102 ``Python_EXECUTABLE``
 103   Path to the Python interpreter.
 104 ``Python_INTERPRETER_ID``
 105   A short string unique to the interpreter. Possible values include:
 106     * Python
 107     * ActivePython
 108     * Anaconda
 109     * Canopy
 110     * IronPython
 111     * PyPy
 112 ``Python_STDLIB``
 113   Standard platform independent installation directory.
 114
 115   Information returned by
 116   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``
 117   or else ``sysconfig.get_path('stdlib')``.
 118 ``Python_STDARCH``
 119   Standard platform dependent installation directory.
 120
 121   Information returned by
 122   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``
 123   or else ``sysconfig.get_path('platstdlib')``.
 124 ``Python_SITELIB``
 125   Third-party platform independent installation directory.
 126
 127   Information returned by
 128   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``
 129   or else ``sysconfig.get_path('purelib')``.
 130 ``Python_SITEARCH``
 131   Third-party platform dependent installation directory.
 132
 133   Information returned by
 134   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``
 135   or else ``sysconfig.get_path('platlib')``.
 136
 137 ``Python_SOABI``
 138   .. versionadded:: 3.17
 139
 140   Extension suffix for modules.
 141
 142   Information returned by
 143   ``distutils.sysconfig.get_config_var('SOABI')`` or computed from
 144   ``distutils.sysconfig.get_config_var('EXT_SUFFIX')`` or
 145   ``python-config --extension-suffix``. If package ``distutils.sysconfig`` is
 146   not available, ``sysconfig.get_config_var('SOABI')`` or
 147   ``sysconfig.get_config_var('EXT_SUFFIX')`` are used.
 148
 149 ``Python_Compiler_FOUND``
 150   System has the Python compiler.
 151 ``Python_COMPILER``
 152   Path to the Python compiler. Only offered by IronPython.
 153 ``Python_COMPILER_ID``
 154   A short string unique to the compiler. Possible values include:
 155     * IronPython
 156
 157 ``Python_DOTNET_LAUNCHER``
 158   .. versionadded:: 3.18
 159
 160   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 161
 162 ``Python_Development_FOUND``
 163   System has the Python development artifacts.
 164
 165 ``Python_Development.Module_FOUND``
 166   .. versionadded:: 3.18
 167
 168   System has the Python development artifacts for Python module.
 169
 170 ``Python_Development.Embed_FOUND``
 171   .. versionadded:: 3.18
 172
 173   System has the Python development artifacts for Python embedding.
 174
 175 ``Python_INCLUDE_DIRS``
 176
 177   The Python include directories.
 178
 179 ``Python_LINK_OPTIONS``
 180   .. versionadded:: 3.19
 181
 182   The Python link options. Some configurations require specific link options
 183   for a correct build and execution.
 184
 185 ``Python_LIBRARIES``
 186   The Python libraries.
 187 ``Python_LIBRARY_DIRS``
 188   The Python library directories.
 189 ``Python_RUNTIME_LIBRARY_DIRS``
 190   The Python runtime library directories.
 191 ``Python_VERSION``
 192   Python version.
 193 ``Python_VERSION_MAJOR``
 194   Python major version.
 195 ``Python_VERSION_MINOR``
 196   Python minor version.
 197 ``Python_VERSION_PATCH``
 198   Python patch version.
 199
 200 ``Python_PyPy_VERSION``
 201   .. versionadded:: 3.18
 202
 203   Python PyPy version.
 204
 205 ``Python_NumPy_FOUND``
 206   .. versionadded:: 3.14
 207
 208   System has the NumPy.
 209
 210 ``Python_NumPy_INCLUDE_DIRS``
 211   .. versionadded:: 3.14
 212
 213   The NumPy include directories.
 214
 215 ``Python_NumPy_VERSION``
 216   .. versionadded:: 3.14
 217
 218   The NumPy version.
 219
 220 Hints
 221 ^^^^^
 222
 223 ``Python_ROOT_DIR``
 224   Define the root directory of a Python installation.
 225
 226 ``Python_USE_STATIC_LIBS``
 227   * If not defined, search for shared libraries and static libraries in that
 228     order.
 229   * If set to TRUE, search **only** for static libraries.
 230   * If set to FALSE, search **only** for shared libraries.
 231
 232   .. note::
 233
 234     This hint will be ignored on ``Windows`` because static libraries are not
 235     available on this platform.
 236
 237 ``Python_FIND_ABI``
 238   .. versionadded:: 3.16
 239
 240   This variable defines which ABIs, as defined in :pep:`3149`, should be
 241   searched.
 242
 243   .. note::
 244
 245     This hint will be honored only when searched for ``Python`` version 3.
 246
 247   .. note::
 248
 249     If ``Python_FIND_ABI`` is not defined, any ABI will be searched.
 250
 251   The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
 252   ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
 253   Each element can be set to one of the following:
 254
 255   * ``ON``: Corresponding flag is selected.
 256   * ``OFF``: Corresponding flag is not selected.
 257   * ``ANY``: The two possibilities (``ON`` and ``OFF``) will be searched.
 258
 259   From this 3-tuple, various ABIs will be searched starting from the most
 260   specialized to the most general. Moreover, ``debug`` versions will be
 261   searched **after** ``non-debug`` ones.
 262
 263   For example, if we have::
 264
 265     set (Python_FIND_ABI "ON" "ANY" "ANY")
 266
 267   The following flags combinations will be appended, in that order, to the
 268   artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
 269
 270   And to search any possible ABIs::
 271
 272     set (Python_FIND_ABI "ANY" "ANY" "ANY")
 273
 274   The following combinations, in that order, will be used: ``mu``, ``m``,
 275   ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
 276
 277   .. note::
 278
 279     This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
 280     when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
 281     `python.org <https://www.python.org/>`_ will be found only if value for
 282     each flag is ``OFF`` or ``ANY``.
 283
 284 ``Python_FIND_STRATEGY``
 285   .. versionadded:: 3.15
 286
 287   This variable defines how lookup will be done.
 288   The ``Python_FIND_STRATEGY`` variable can be set to one of the following:
 289
 290   * ``VERSION``: Try to find the most recent version in all specified
 291     locations.
 292     This is the default if policy :policy:`CMP0094` is undefined or set to
 293     ``OLD``.
 294   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 295     constraints is founded.
 296     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 297
 298 ``Python_FIND_REGISTRY``
 299   .. versionadded:: 3.13
 300
 301   On Windows the ``Python_FIND_REGISTRY`` variable determine the order
 302   of preference between registry and environment variables.
 303   the ``Python_FIND_REGISTRY`` variable can be set to one of the following:
 304
 305   * ``FIRST``: Try to use registry before environment variables.
 306     This is the default.
 307   * ``LAST``: Try to use registry after environment variables.
 308   * ``NEVER``: Never try to use registry.
 309
 310 ``Python_FIND_FRAMEWORK``
 311   .. versionadded:: 3.15
 312
 313   On macOS the ``Python_FIND_FRAMEWORK`` variable determine the order of
 314   preference between Apple-style and unix-style package components.
 315   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 316   variable.
 317
 318   .. note::
 319
 320     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 321
 322   If ``Python_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 323   variable will be used, if any.
 324
 325 ``Python_FIND_VIRTUALENV``
 326   .. versionadded:: 3.15
 327
 328   This variable defines the handling of virtual environments managed by
 329   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 330   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 331   takes precedence over ``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 332   variables.  The ``Python_FIND_VIRTUALENV`` variable can be set to one of the
 333   following:
 334
 335   * ``FIRST``: The virtual environment is used before any other standard
 336     paths to look-up for the interpreter. This is the default.
 337   * ``ONLY``: Only the virtual environment is used to look-up for the
 338     interpreter.
 339   * ``STANDARD``: The virtual environment is not used to look-up for the
 340     interpreter but environment variable ``PATH`` is always considered.
 341     In this case, variable ``Python_FIND_REGISTRY`` (Windows) or
 342     ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 343     ``NEVER`` to select preferably the interpreter from the virtual
 344     environment.
 345
 346   .. versionadded:: 3.17
 347     Added support for ``conda`` environments.
 348
 349   .. note::
 350
 351     If the component ``Development`` is requested, it is **strongly**
 352     recommended to also include the component ``Interpreter`` to get expected
 353     result.
 354
 355 ``Python_FIND_IMPLEMENTATIONS``
 356   .. versionadded:: 3.18
 357
 358   This variable defines, in an ordered list, the different implementations
 359   which will be searched. The ``Python_FIND_IMPLEMENTATIONS`` variable can
 360   hold the following values:
 361
 362   * ``CPython``: this is the standard implementation. Various products, like
 363     ``Anaconda`` or ``ActivePython``, rely on this implementation.
 364   * ``IronPython``: This implementation use the ``CSharp`` language for
 365     ``.NET Framework`` on top of the `Dynamic Language Runtime` (``DLR``).
 366     See `IronPython <https://ironpython.net>`_.
 367   * ``PyPy``: This implementation use ``RPython`` language and
 368     ``RPython translation toolchain`` to produce the python interpreter.
 369     See `PyPy <https://www.pypy.org>`_.
 370
 371   The default value is:
 372
 373   * Windows platform: ``CPython``, ``IronPython``
 374   * Other platforms: ``CPython``
 375
 376   .. note::
 377
 378     This hint has the lowest priority of all hints, so even if, for example,
 379     you specify ``IronPython`` first and ``CPython`` in second, a python
 380     product based on ``CPython`` can be selected because, for example with
 381     ``Python_FIND_STRATEGY=LOCATION``, each location will be search first for
 382     ``IronPython`` and second for ``CPython``.
 383
 384   .. note::
 385
 386     When ``IronPython`` is specified, on platforms other than ``Windows``, the
 387     ``.Net`` interpreter (i.e. ``mono`` command) is expected to be available
 388     through the ``PATH`` variable.
 389
 390 ``Python_FIND_UNVERSIONED_NAMES``
 391   .. versionadded:: 3.20
 392
 393   This variable defines how the generic names will be searched. Currently, it
 394   only applies to the generic names of the interpreter, namely, ``python3`` or
 395   ``python2`` and ``python``.
 396   The ``Python_FIND_UNVERSIONED_NAMES`` variable can be set to one of the
 397   following values:
 398
 399   * ``FIRST``: The generic names are searched before the more specialized ones
 400     (such as ``python2.5`` for example).
 401   * ``LAST``: The generic names are searched after the more specialized ones.
 402     This is the default.
 403   * ``NEVER``: The generic name are not searched at all.
 404
 405 Artifacts Specification
 406 ^^^^^^^^^^^^^^^^^^^^^^^
 407
 408 .. versionadded:: 3.16
 409
 410 To solve special cases, it is possible to specify directly the artifacts by
 411 setting the following variables:
 412
 413 ``Python_EXECUTABLE``
 414   The path to the interpreter.
 415
 416 ``Python_COMPILER``
 417   The path to the compiler.
 418
 419 ``Python_DOTNET_LAUNCHER``
 420   .. versionadded:: 3.18
 421
 422   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 423
 424 ``Python_LIBRARY``
 425   The path to the library. It will be used to compute the
 426   variables ``Python_LIBRARIES``, ``Python_LIBRARY_DIRS`` and
 427   ``Python_RUNTIME_LIBRARY_DIRS``.
 428
 429 ``Python_INCLUDE_DIR``
 430   The path to the directory of the ``Python`` headers. It will be used to
 431   compute the variable ``Python_INCLUDE_DIRS``.
 432
 433 ``Python_NumPy_INCLUDE_DIR``
 434   The path to the directory of the ``NumPy`` headers. It will be used to
 435   compute the variable ``Python_NumPy_INCLUDE_DIRS``.
 436
 437 .. note::
 438
 439   All paths must be absolute. Any artifact specified with a relative path
 440   will be ignored.
 441
 442 .. note::
 443
 444   When an artifact is specified, all ``HINTS`` will be ignored and no search
 445   will be performed for this artifact.
 446
 447   If more than one artifact is specified, it is the user's responsibility to
 448   ensure the consistency of the various artifacts.
 449
 450 By default, this module supports multiple calls in different directories of a
 451 project with different version/component requirements while providing correct
 452 and consistent results for each call. To support this behavior, ``CMake`` cache
 453 is not used in the traditional way which can be problematic for interactive
 454 specification. So, to enable also interactive specification, module behavior
 455 can be controlled with the following variable:
 456
 457 ``Python_ARTIFACTS_INTERACTIVE``
 458   .. versionadded:: 3.18
 459
 460   Selects the behavior of the module. This is a boolean variable:
 461
 462   * If set to ``TRUE``: Create CMake cache entries for the above artifact
 463     specification variables so that users can edit them interactively.
 464     This disables support for multiple version/component requirements.
 465   * If set to ``FALSE`` or undefined: Enable multiple version/component
 466     requirements.
 467
 468 Commands
 469 ^^^^^^^^
 470
 471 This module defines the command ``Python_add_library`` (when
 472 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 473 :command:`add_library` and adds a dependency to target ``Python::Python`` or,
 474 when library type is ``MODULE``, to target ``Python::Module`` and takes care of
 475 Python module naming rules::
 476
 477   Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
 478                       <source1> [<source2> ...])
 479
 480 If the library type is not specified, ``MODULE`` is assumed.
 481
 482 .. versionadded:: 3.17
 483   For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
 484   module suffix will include the ``Python_SOABI`` value, if any.
 485 #]=======================================================================]
 486
 487
 488 cmake_policy(PUSH)
 489 # numbers and boolean constants
 490 cmake_policy (SET CMP0012 NEW)
 491
 492
 493 set (_PYTHON_PREFIX Python)
 494 unset (_Python_REQUIRED_VERSION_MAJOR)
 495 unset (_Python_REQUIRED_VERSIONS)
 496
 497 if (Python_FIND_VERSION_RANGE)
 498   # compute list of major versions
 499   foreach (_Python_MAJOR IN ITEMS 3 2)
 500     if (_Python_MAJOR VERSION_GREATER_EQUAL Python_FIND_VERSION_MIN_MAJOR
 501         AND ((Python_FIND_VERSION_RANGE_MAX STREQUAL "INCLUDE" AND _Python_MAJOR VERSION_LESS_EQUAL Python_FIND_VERSION_MAX)
 502         OR (Python_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE" AND _Python_MAJOR VERSION_LESS Python_FIND_VERSION_MAX)))
 503       list (APPEND _Python_REQUIRED_VERSIONS ${_Python_MAJOR})
 504     endif()
 505   endforeach()
 506   list (LENGTH _Python_REQUIRED_VERSIONS _Python_VERSION_COUNT)
 507   if (_Python_VERSION_COUNT EQUAL 0)
 508     unset (_Python_REQUIRED_VERSIONS)
 509   elseif (_Python_VERSION_COUNT EQUAL 1)
 510     set (_Python_REQUIRED_VERSION_MAJOR ${_Python_REQUIRED_VERSIONS})
 511   endif()
 512 elseif (DEFINED Python_FIND_VERSION)
 513   set (_Python_REQUIRED_VERSION_MAJOR ${Python_FIND_VERSION_MAJOR})
 514 else()
 515   set (_Python_REQUIRED_VERSIONS 3 2)
 516 endif()
 517
 518 if (_Python_REQUIRED_VERSION_MAJOR)
 519   include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 520 elseif (_Python_REQUIRED_VERSIONS)
 521   # iterate over versions in quiet and NOT required modes to avoid multiple
 522   # "Found" messages and prematurally failure.
 523   set (_Python_QUIETLY ${Python_FIND_QUIETLY})
 524   set (_Python_REQUIRED ${Python_FIND_REQUIRED})
 525   set (Python_FIND_QUIETLY TRUE)
 526   set (Python_FIND_REQUIRED FALSE)
 527
 528   set (_Python_REQUIRED_VERSION_LAST 2)
 529
 530   unset (_Python_INPUT_VARS)
 531   foreach (_Python_ITEM IN ITEMS Python_EXECUTABLE Python_COMPILER Python_LIBRARY
 532                                  Python_INCLUDE_DIR Python_NumPy_INCLUDE_DIR)
 533     if (NOT DEFINED ${_Python_ITEM})
 534       list (APPEND _Python_INPUT_VARS ${_Python_ITEM})
 535     endif()
 536   endforeach()
 537
 538   foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
 539     set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
 540     include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 541     if (Python_FOUND OR
 542         _Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
 543       break()
 544     endif()
 545     # clean-up INPUT variables not set by the user
 546     foreach (_Python_ITEM IN LISTS _Python_INPUT_VARS)
 547       unset (${_Python_ITEM})
 548     endforeach()
 549     # clean-up some CACHE variables to ensure look-up restart from scratch
 550     foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
 551       unset (${_Python_ITEM} CACHE)
 552     endforeach()
 553   endforeach()
 554
 555   unset (Python_FIND_VERSION)
 556
 557   set (Python_FIND_QUIETLY ${_Python_QUIETLY})
 558   set (Python_FIND_REQUIRED ${_Python_REQUIRED})
 559   if (Python_FIND_REQUIRED OR NOT Python_FIND_QUIETLY)
 560     # call again validation command to get "Found" or error message
 561     find_package_handle_standard_args (Python HANDLE_COMPONENTS HANDLE_VERSION_RANGE
 562                                               REQUIRED_VARS ${_Python_REQUIRED_VARS}
 563                                               VERSION_VAR Python_VERSION)
 564   endif()
 565 else()
 566   # supported versions not in the specified range. Call final check
 567   if (NOT Python_FIND_COMPONENTS)
 568     set (Python_FIND_COMPONENTS Interpreter)
 569     set (Python_FIND_REQUIRED_Interpreter TRUE)
 570   endif()
 571
 572   include (${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)
 573   find_package_handle_standard_args (Python HANDLE_COMPONENTS HANDLE_VERSION_RANGE
 574                                             VERSION_VAR Python_VERSION
 575                                             REASON_FAILURE_MESSAGE "Version range specified \"${Python_FIND_VERSION_RANGE}\" does not include supported versions")
 576 endif()
 577
 578 if (COMMAND __Python_add_library)
 579   macro (Python_add_library)
 580     __Python_add_library (Python ${ARGV})
 581   endmacro()
 582 endif()
 583
 584 unset (_PYTHON_PREFIX)
 585
 586 cmake_policy(POP)