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: 5FindPython3 6----------- 7 8.. versionadded:: 3.12 9 10Find Python 3 interpreter, compiler and development environment (include 11directories 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 18The 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 39If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed. 40 41If component ``Development`` is specified, it implies sub-components 42``Development.Module`` and ``Development.Embed``. 43 44To ensure consistent versions between components ``Interpreter``, ``Compiler``, 45``Development`` (or one of its sub-components) and ``NumPy``, specify all 46components at the same time:: 47 48 find_package (Python3 COMPONENTS Interpreter Development) 49 50This module looks only for version 3 of Python. This module can be used 51concurrently with :module:`FindPython2` module to use both Python versions. 52 53The :module:`FindPython` module can be used if Python version does not matter 54for 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 64Imported Targets 65^^^^^^^^^^^^^^^^ 66 67This 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 93Result Variables 94^^^^^^^^^^^^^^^^ 95 96This 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 222Hints 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 403Artifacts Specification 404^^^^^^^^^^^^^^^^^^^^^^^ 405 406.. versionadded:: 3.16 407 408To solve special cases, it is possible to specify directly the artifacts by 409setting 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 448By default, this module supports multiple calls in different directories of a 449project with different version/component requirements while providing correct 450and consistent results for each call. To support this behavior, ``CMake`` cache 451is not used in the traditional way which can be problematic for interactive 452specification. So, to enable also interactive specification, module behavior 453can 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 466Commands 467^^^^^^^^ 468 469This 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, 472when library type is ``MODULE``, to target ``Python3::Module`` and takes care 473of Python module naming rules:: 474 475 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]] 476 <source1> [<source2> ...]) 477 478If 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 486set (_PYTHON_PREFIX Python3) 487 488set (_Python3_REQUIRED_VERSION_MAJOR 3) 489 490include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake) 491 492if (COMMAND __Python3_add_library) 493 macro (Python3_add_library) 494 __Python3_add_library (Python3 ${ARGV}) 495 endmacro() 496endif() 497 498unset (_PYTHON_PREFIX) 499