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