Modules/FindPython3.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 FindPython3
   6 -----------
   7
   8 .. versionadded:: 3.12
   9
  10 Find Python 3 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 3 interpreter
  21 * ``Compiler``: search for Python 3 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 3 module
  30       developments.
  31     * ``Development.Embed``: search for artifacts for Python 3 embedding
  32       developments.
  33
  34   .. versionadded:: 3.26
  35
  36     * ``Development.SABIModule``: search for artifacts for Python 3 module
  37       developments using the
  38       `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_.
  39       This component is available only for version ``3.2`` and upper.
  40
  41 * ``NumPy``: search for NumPy include directories.
  42
  43 .. versionadded:: 3.14
  44   Added the ``NumPy`` component.
  45
  46 If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed.
  47
  48 If component ``Development`` is specified, it implies sub-components
  49 ``Development.Module`` and ``Development.Embed``.
  50
  51 To ensure consistent versions between components ``Interpreter``, ``Compiler``,
  52 ``Development`` (or one of its sub-components) and ``NumPy``, specify all
  53 components at the same time::
  54
  55   find_package (Python3 COMPONENTS Interpreter Development)
  56
  57 This module looks only for version 3 of Python. This module can be used
  58 concurrently with :module:`FindPython2` module to use both Python versions.
  59
  60 The :module:`FindPython` module can be used if Python version does not matter
  61 for you.
  62
  63 .. note::
  64
  65   If components ``Interpreter`` and ``Development`` (or one of its
  66   sub-components) are both specified, this module search only for interpreter
  67   with same platform architecture as the one defined by CMake
  68   configuration. This constraint does not apply if only ``Interpreter``
  69   component is specified.
  70
  71 Imported Targets
  72 ^^^^^^^^^^^^^^^^
  73
  74 This module defines the following :ref:`Imported Targets <Imported Targets>`:
  75
  76 .. versionchanged:: 3.14
  77   :ref:`Imported Targets <Imported Targets>` are only created when
  78   :prop_gbl:`CMAKE_ROLE` is ``PROJECT``.
  79
  80 ``Python3::Interpreter``
  81   Python 3 interpreter. Target defined if component ``Interpreter`` is found.
  82 ``Python3::Compiler``
  83   Python 3 compiler. Target defined if component ``Compiler`` is found.
  84
  85 ``Python3::Module``
  86   .. versionadded:: 3.15
  87
  88   Python 3 library for Python module. Target defined if component
  89   ``Development.Module`` is found.
  90
  91 ``Python3::SABIModule``
  92   .. versionadded:: 3.26
  93
  94   Python 3 library for Python module using the Stable Application Binary
  95   Interface. Target defined if component ``Development.SABIModule`` is found.
  96
  97 ``Python3::Python``
  98   Python 3 library for Python embedding. Target defined if component
  99   ``Development.Embed`` is found.
 100
 101 ``Python3::NumPy``
 102   .. versionadded:: 3.14
 103
 104   NumPy library for Python 3. Target defined if component ``NumPy`` is found.
 105
 106 Result Variables
 107 ^^^^^^^^^^^^^^^^
 108
 109 This module will set the following variables in your project
 110 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
 111
 112 ``Python3_FOUND``
 113   System has the Python 3 requested components.
 114 ``Python3_Interpreter_FOUND``
 115   System has the Python 3 interpreter.
 116 ``Python3_EXECUTABLE``
 117   Path to the Python 3 interpreter.
 118 ``Python3_INTERPRETER_ID``
 119   A short string unique to the interpreter. Possible values include:
 120     * Python
 121     * ActivePython
 122     * Anaconda
 123     * Canopy
 124     * IronPython
 125     * PyPy
 126 ``Python3_STDLIB``
 127   Standard platform independent installation directory.
 128
 129   Information returned by ``sysconfig.get_path('stdlib')``.
 130 ``Python3_STDARCH``
 131   Standard platform dependent installation directory.
 132
 133   Information returned by ``sysconfig.get_path('platstdlib')``.
 134 ``Python3_SITELIB``
 135   Third-party platform independent installation directory.
 136
 137   Information returned by ``sysconfig.get_path('purelib')``.
 138 ``Python3_SITEARCH``
 139   Third-party platform dependent installation directory.
 140
 141   Information returned by ``sysconfig.get_path('platlib')``.
 142
 143 ``Python3_SOABI``
 144   .. versionadded:: 3.17
 145
 146   Extension suffix for modules.
 147
 148   Information computed from ``sysconfig.get_config_var('EXT_SUFFIX')`` or
 149   ``sysconfig.get_config_var('SOABI')`` or
 150   ``python3-config --extension-suffix``.
 151
 152 ``Python3_SOSABI``
 153   .. versionadded:: 3.26
 154
 155   Extension suffix for modules using the Stable Application Binary Interface.
 156
 157   Information computed from ``importlib.machinery.EXTENSION_SUFFIXES`` if the
 158   COMPONENT ``Interpreter`` was specified. Otherwise, the extension is ``abi3``
 159   except for ``Windows``, ``MSYS`` and ``CYGWIN`` for which this is an empty
 160   string.
 161
 162 ``Python3_Compiler_FOUND``
 163   System has the Python 3 compiler.
 164 ``Python3_COMPILER``
 165   Path to the Python 3 compiler. Only offered by IronPython.
 166 ``Python3_COMPILER_ID``
 167   A short string unique to the compiler. Possible values include:
 168     * IronPython
 169
 170 ``Python3_DOTNET_LAUNCHER``
 171   .. versionadded:: 3.18
 172
 173   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 174
 175 ``Python3_Development_FOUND``
 176
 177   System has the Python 3 development artifacts.
 178
 179 ``Python3_Development.Module_FOUND``
 180   .. versionadded:: 3.18
 181
 182   System has the Python 3 development artifacts for Python module.
 183
 184 ``Python3_Development.SABIModule_FOUND``
 185   .. versionadded:: 3.26
 186
 187   System has the Python 3 development artifacts for Python module using the
 188   Stable Application Binary Interface.
 189
 190 ``Python3_Development.Embed_FOUND``
 191   .. versionadded:: 3.18
 192
 193   System has the Python 3 development artifacts for Python embedding.
 194
 195 ``Python3_INCLUDE_DIRS``
 196
 197   The Python 3 include directories.
 198
 199 ``Python3_LINK_OPTIONS``
 200   .. versionadded:: 3.19
 201
 202   The Python 3 link options. Some configurations require specific link options
 203   for a correct build and execution.
 204
 205 ``Python3_LIBRARIES``
 206   The Python 3 libraries.
 207 ``Python3_LIBRARY_DIRS``
 208   The Python 3 library directories.
 209 ``Python3_RUNTIME_LIBRARY_DIRS``
 210   The Python 3 runtime library directories.
 211 ``Python3_SABI_LIBRARIES``
 212   .. versionadded:: 3.26
 213
 214   The Python 3 libraries for the Stable Application Binary Interface.
 215 ``Python3_SABI_LIBRARY_DIRS``
 216   .. versionadded:: 3.26
 217
 218   The Python 3 ``SABI`` library directories.
 219 ``Python3_RUNTIME_SABI_LIBRARY_DIRS``
 220   .. versionadded:: 3.26
 221
 222   The Python 3 runtime ``SABI`` library directories.
 223 ``Python3_VERSION``
 224   Python 3 version.
 225 ``Python3_VERSION_MAJOR``
 226   Python 3 major version.
 227 ``Python3_VERSION_MINOR``
 228   Python 3 minor version.
 229 ``Python3_VERSION_PATCH``
 230   Python 3 patch version.
 231
 232 ``Python3_PyPy_VERSION``
 233   .. versionadded:: 3.18
 234
 235   Python 3 PyPy version.
 236
 237 ``Python3_NumPy_FOUND``
 238   .. versionadded:: 3.14
 239
 240   System has the NumPy.
 241
 242 ``Python3_NumPy_INCLUDE_DIRS``
 243   .. versionadded:: 3.14
 244
 245   The NumPy include directories.
 246
 247 ``Python3_NumPy_VERSION``
 248   .. versionadded:: 3.14
 249
 250   The NumPy version.
 251
 252 Hints
 253 ^^^^^
 254
 255 ``Python3_ROOT_DIR``
 256   Define the root directory of a Python 3 installation.
 257
 258 ``Python3_USE_STATIC_LIBS``
 259   * If not defined, search for shared libraries and static libraries in that
 260     order.
 261   * If set to TRUE, search **only** for static libraries.
 262   * If set to FALSE, search **only** for shared libraries.
 263
 264   .. note::
 265
 266     This hint will be ignored on ``Windows`` because static libraries are not
 267     available on this platform.
 268
 269 ``Python3_FIND_ABI``
 270   .. versionadded:: 3.16
 271
 272   This variable defines which ABIs, as defined in :pep:`3149`, should be
 273   searched.
 274
 275   .. note::
 276
 277     If ``Python3_FIND_ABI`` is not defined, any ABI will be searched.
 278
 279   The ``Python3_FIND_ABI`` variable is a 3-tuple specifying, in that order,
 280   ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
 281   Each element can be set to one of the following:
 282
 283   * ``ON``: Corresponding flag is selected.
 284   * ``OFF``: Corresponding flag is not selected.
 285   * ``ANY``: The two possibilities (``ON`` and ``OFF``) will be searched.
 286
 287   From this 3-tuple, various ABIs will be searched starting from the most
 288   specialized to the most general. Moreover, ``debug`` versions will be
 289   searched **after** ``non-debug`` ones.
 290
 291   For example, if we have::
 292
 293     set (Python3_FIND_ABI "ON" "ANY" "ANY")
 294
 295   The following flags combinations will be appended, in that order, to the
 296   artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
 297
 298   And to search any possible ABIs::
 299
 300     set (Python3_FIND_ABI "ANY" "ANY" "ANY")
 301
 302   The following combinations, in that order, will be used: ``mu``, ``m``,
 303   ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
 304
 305   .. note::
 306
 307     This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
 308     when ``Python3_FIND_ABI`` is defined, ``Python`` distributions from
 309     `python.org <https://www.python.org/>`_ will be found only if value for
 310     each flag is ``OFF`` or ``ANY``.
 311
 312 ``Python3_FIND_STRATEGY``
 313   .. versionadded:: 3.15
 314
 315   This variable defines how lookup will be done.
 316   The ``Python3_FIND_STRATEGY`` variable can be set to one of the following:
 317
 318   * ``VERSION``: Try to find the most recent version in all specified
 319     locations.
 320     This is the default if policy :policy:`CMP0094` is undefined or set to
 321     ``OLD``.
 322   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 323     constraints is founded.
 324     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 325
 326   See also ``Python3_FIND_UNVERSIONED_NAMES``.
 327
 328 ``Python3_FIND_REGISTRY``
 329   .. versionadded:: 3.13
 330
 331   On Windows the ``Python3_FIND_REGISTRY`` variable determine the order
 332   of preference between registry and environment variables.
 333   The ``Python3_FIND_REGISTRY`` variable can be set to one of the following:
 334
 335   * ``FIRST``: Try to use registry before environment variables.
 336     This is the default.
 337   * ``LAST``: Try to use registry after environment variables.
 338   * ``NEVER``: Never try to use registry.
 339
 340 ``Python3_FIND_FRAMEWORK``
 341   .. versionadded:: 3.15
 342
 343   On macOS the ``Python3_FIND_FRAMEWORK`` variable determine the order of
 344   preference between Apple-style and unix-style package components.
 345   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 346   variable.
 347
 348   .. note::
 349
 350     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 351
 352   If ``Python3_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 353   variable will be used, if any.
 354
 355 ``Python3_FIND_VIRTUALENV``
 356   .. versionadded:: 3.15
 357
 358   This variable defines the handling of virtual environments managed by
 359   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 360   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 361   takes precedence over ``Python3_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 362   variables.  The ``Python3_FIND_VIRTUALENV`` variable can be set to one of the
 363   following:
 364
 365   * ``FIRST``: The virtual environment is used before any other standard
 366     paths to look-up for the interpreter. This is the default.
 367   * ``ONLY``: Only the virtual environment is used to look-up for the
 368     interpreter.
 369   * ``STANDARD``: The virtual environment is not used to look-up for the
 370     interpreter but environment variable ``PATH`` is always considered.
 371     In this case, variable ``Python3_FIND_REGISTRY`` (Windows) or
 372     ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 373     ``NEVER`` to select preferably the interpreter from the virtual
 374     environment.
 375
 376   .. versionadded:: 3.17
 377     Added support for ``conda`` environments.
 378
 379   .. note::
 380
 381     If the component ``Development`` is requested, it is **strongly**
 382     recommended to also include the component ``Interpreter`` to get expected
 383     result.
 384
 385 ``Python3_FIND_IMPLEMENTATIONS``
 386   .. versionadded:: 3.18
 387
 388   This variable defines, in an ordered list, the different implementations
 389   which will be searched. The ``Python3_FIND_IMPLEMENTATIONS`` variable can
 390   hold the following values:
 391
 392   * ``CPython``: this is the standard implementation. Various products, like
 393     ``Anaconda`` or ``ActivePython``, rely on this implementation.
 394   * ``IronPython``: This implementation use the ``CSharp`` language for
 395     ``.NET Framework`` on top of the `Dynamic Language Runtime` (``DLR``).
 396     See `IronPython <https://ironpython.net>`_.
 397   * ``PyPy``: This implementation use ``RPython`` language and
 398     ``RPython translation toolchain`` to produce the python interpreter.
 399     See `PyPy <https://www.pypy.org>`_.
 400
 401   The default value is:
 402
 403   * Windows platform: ``CPython``, ``IronPython``
 404   * Other platforms: ``CPython``
 405
 406   .. note::
 407
 408     This hint has the lowest priority of all hints, so even if, for example,
 409     you specify ``IronPython`` first and ``CPython`` in second, a python
 410     product based on ``CPython`` can be selected because, for example with
 411     ``Python3_FIND_STRATEGY=LOCATION``, each location will be search first for
 412     ``IronPython`` and second for ``CPython``.
 413
 414   .. note::
 415
 416     When ``IronPython`` is specified, on platforms other than ``Windows``, the
 417     ``.Net`` interpreter (i.e. ``mono`` command) is expected to be available
 418     through the ``PATH`` variable.
 419
 420 ``Python3_FIND_UNVERSIONED_NAMES``
 421   .. versionadded:: 3.20
 422
 423   This variable defines how the generic names will be searched. Currently, it
 424   only applies to the generic names of the interpreter, namely, ``python3`` and
 425   ``python``.
 426   The ``Python3_FIND_UNVERSIONED_NAMES`` variable can be set to one of the
 427   following values:
 428
 429   * ``FIRST``: The generic names are searched before the more specialized ones
 430     (such as ``python3.5`` for example).
 431   * ``LAST``: The generic names are searched after the more specialized ones.
 432     This is the default.
 433   * ``NEVER``: The generic name are not searched at all.
 434
 435   See also ``Python3_FIND_STRATEGY``.
 436
 437 Artifacts Specification
 438 ^^^^^^^^^^^^^^^^^^^^^^^
 439
 440 .. versionadded:: 3.16
 441
 442 To solve special cases, it is possible to specify directly the artifacts by
 443 setting the following variables:
 444
 445 ``Python3_EXECUTABLE``
 446   The path to the interpreter.
 447
 448 ``Python3_COMPILER``
 449   The path to the compiler.
 450
 451 ``Python3_DOTNET_LAUNCHER``
 452   .. versionadded:: 3.18
 453
 454   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 455
 456 ``Python3_LIBRARY``
 457   The path to the library. It will be used to compute the
 458   variables ``Python3_LIBRARIES``, ``Python3_LIBRARY_DIRS`` and
 459   ``Python3_RUNTIME_LIBRARY_DIRS``.
 460
 461 ``Python3_SABI_LIBRARY``
 462   .. versionadded:: 3.26
 463
 464   The path to the library for Stable Application Binary Interface. It will be
 465   used to compute the variables ``Python3_SABI_LIBRARIES``,
 466   ``Python3_SABI_LIBRARY_DIRS`` and ``Python3_RUNTIME_SABI_LIBRARY_DIRS``.
 467
 468 ``Python3_INCLUDE_DIR``
 469   The path to the directory of the ``Python`` headers. It will be used to
 470   compute the variable ``Python3_INCLUDE_DIRS``.
 471
 472 ``Python3_NumPy_INCLUDE_DIR``
 473   The path to the directory of the ``NumPy`` headers. It will be used to
 474   compute the variable ``Python3_NumPy_INCLUDE_DIRS``.
 475
 476 .. note::
 477
 478   All paths must be absolute. Any artifact specified with a relative path
 479   will be ignored.
 480
 481 .. note::
 482
 483   When an artifact is specified, all ``HINTS`` will be ignored and no search
 484   will be performed for this artifact.
 485
 486   If more than one artifact is specified, it is the user's responsibility to
 487   ensure the consistency of the various artifacts.
 488
 489 By default, this module supports multiple calls in different directories of a
 490 project with different version/component requirements while providing correct
 491 and consistent results for each call. To support this behavior, CMake cache
 492 is not used in the traditional way which can be problematic for interactive
 493 specification. So, to enable also interactive specification, module behavior
 494 can be controlled with the following variable:
 495
 496 ``Python3_ARTIFACTS_INTERACTIVE``
 497   .. versionadded:: 3.18
 498
 499   Selects the behavior of the module. This is a boolean variable:
 500
 501   * If set to ``TRUE``: Create CMake cache entries for the above artifact
 502     specification variables so that users can edit them interactively.
 503     This disables support for multiple version/component requirements.
 504   * If set to ``FALSE`` or undefined: Enable multiple version/component
 505     requirements.
 506
 507 Commands
 508 ^^^^^^^^
 509
 510 This module defines the command ``Python3_add_library`` (when
 511 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 512 :command:`add_library` and adds a dependency to target ``Python3::Python`` or,
 513 when library type is ``MODULE``, to target ``Python3::Module`` or
 514 ``Python3::SABIModule`` (when ``USE_SABI`` option is specified) and takes care
 515 of Python module naming rules::
 516
 517   Python3_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
 518                        <source1> [<source2> ...])
 519
 520 If the library type is not specified, ``MODULE`` is assumed.
 521
 522 .. versionadded:: 3.17
 523   For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
 524   module suffix will include the ``Python3_SOABI`` value, if any.
 525
 526 .. versionadded:: 3.26
 527   For ``MODULE`` type, if the option ``USE_SABI`` is specified, the
 528   preprocessor definition ``Py_LIMITED_API`` will be specified, as ``PRIVATE``,
 529   for the target ``<name>`` with the value computed from ``<version>`` argument.
 530   The expected format for ``<version>`` is ``major[.minor]``, where each
 531   component is a numeric value. If ``minor`` component is specified, the
 532   version should be, at least, ``3.2`` which is the version where the
 533   `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_
 534   was introduced. Specifying only major version ``3`` is equivalent to ``3.2``.
 535
 536   When option ``WITH_SOABI`` is also specified,  the module suffix will include
 537   the ``Python3_SOSABI`` value, if any.
 538 #]=======================================================================]
 539
 540
 541 set (_PYTHON_PREFIX Python3)
 542
 543 set (_Python3_REQUIRED_VERSION_MAJOR 3)
 544
 545 include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 546
 547 if (COMMAND __Python3_add_library)
 548   macro (Python3_add_library)
 549     __Python3_add_library (Python3 ${ARGV})
 550   endmacro()
 551 endif()
 552
 553 unset (_PYTHON_PREFIX)