Modules/FindPython2.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 FindPython2
   6 -----------
   7
   8 .. versionadded:: 3.12
   9
  10 Find Python 2 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 2 interpreter
  21 * ``Compiler``: search for Python 2 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 2 module
  30       developments.
  31     * ``Development.Embed``: search for artifacts for Python 2 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 .. code-block:: cmake
  49
  50   find_package (Python2 COMPONENTS Interpreter Development)
  51
  52 This module looks only for version 2 of Python. This module can be used
  53 concurrently with :module:`FindPython3` module to use both Python versions.
  54
  55 The :module:`FindPython` module can be used if Python version does not matter
  56 for you.
  57
  58 .. note::
  59
  60   If components ``Interpreter`` and ``Development`` (or one of its
  61   sub-components) are both specified, this module search only for interpreter
  62   with same platform architecture as the one defined by CMake
  63   configuration. This constraint does not apply if only ``Interpreter``
  64   component is specified.
  65
  66 Imported Targets
  67 ^^^^^^^^^^^^^^^^
  68
  69 This module defines the following :ref:`Imported Targets <Imported Targets>`:
  70
  71 .. versionchanged:: 3.14
  72   :ref:`Imported Targets <Imported Targets>` are only created when
  73   :prop_gbl:`CMAKE_ROLE` is ``PROJECT``.
  74
  75 ``Python2::Interpreter``
  76   Python 2 interpreter. This target is defined only if the ``Interpreter``
  77   component is found.
  78 ``Python2::InterpreterDebug``
  79   .. versionadded:: 3.30
  80
  81   Python 2 debug interpreter. This target is defined only if the
  82   ``Interpreter`` component is found and the ``Python2_EXECUTABLE_DEBUG``
  83   variable is defined. The target is only defined on the ``Windows`` platform.
  84
  85 ``Python2::InterpreterMultiConfig``
  86   .. versionadded:: 3.30
  87
  88   Python 2 interpreter. The release or debug version of the interpreter will be
  89   used, based on the context (platform, configuration).
  90   This target is defined only if the ``Interpreter`` component is found
  91
  92 ``Python2::Compiler``
  93   Python 2 compiler. This target is defined only if the ``Compiler`` component
  94   is found.
  95 ``Python2::Module``
  96   .. versionadded:: 3.15
  97
  98   Python 2 library for Python module. Target defined if component
  99   ``Development.Module`` is found.
 100
 101 ``Python2::Python``
 102   Python 2 library for Python embedding. Target defined if component
 103   ``Development.Embed`` is found.
 104
 105 ``Python2::NumPy``
 106   .. versionadded:: 3.14
 107
 108   NumPy library for Python 2. Target defined if component ``NumPy`` is found.
 109
 110 Result Variables
 111 ^^^^^^^^^^^^^^^^
 112
 113 This module will set the following variables in your project
 114 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
 115
 116 ``Python2_FOUND``
 117   System has the Python 2 requested components.
 118 ``Python2_Interpreter_FOUND``
 119   System has the Python 2 interpreter.
 120 ``Python2_EXECUTABLE``
 121   Path to the Python 2 interpreter.
 122 ``Python2_EXECUTABLE_DEBUG``
 123   .. versionadded:: 3.30
 124
 125   Path to the debug Python 2 interpreter. It is only defined on the ``Windows``
 126   platform.
 127
 128 ``Python2_INTERPRETER``
 129   .. versionadded:: 3.30
 130
 131   Path to the Python 2 interpreter, defined as a
 132   :manual:`generator expression <cmake-generator-expressions(7)>` selecting
 133   the ``Python2_EXECUTABLE`` or ``Python2_EXECUTABLE_DEBUG`` variable based on
 134   the context (platform, configuration).
 135
 136 ``Python2_INTERPRETER_ID``
 137   A short string unique to the interpreter. Possible values include:
 138     * Python
 139     * ActivePython
 140     * Anaconda
 141     * Canopy
 142     * IronPython
 143     * PyPy
 144 ``Python2_STDLIB``
 145   Standard platform independent installation directory.
 146
 147   Information returned by ``sysconfig.get_path('stdlib')`` or else
 148   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
 149 ``Python2_STDARCH``
 150   Standard platform dependent installation directory.
 151
 152   Information returned by ``sysconfig.get_path('platstdlib')`` or else
 153   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
 154 ``Python2_SITELIB``
 155   Third-party platform independent installation directory.
 156
 157   Information returned by ``sysconfig.get_path('purelib')`` or else
 158   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
 159 ``Python2_SITEARCH``
 160   Third-party platform dependent installation directory.
 161
 162   Information returned by ``sysconfig.get_path('platlib')`` or else
 163   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
 164 ``Python2_Compiler_FOUND``
 165   System has the Python 2 compiler.
 166 ``Python2_COMPILER``
 167   Path to the Python 2 compiler. Only offered by IronPython.
 168 ``Python2_COMPILER_ID``
 169   A short string unique to the compiler. Possible values include:
 170     * IronPython
 171
 172 ``Python2_DOTNET_LAUNCHER``
 173   .. versionadded:: 3.18
 174
 175   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 176
 177 ``Python2_Development_FOUND``
 178   System has the Python 2 development artifacts.
 179
 180 ``Python2_Development.Module_FOUND``
 181   .. versionadded:: 3.18
 182
 183   System has the Python 2 development artifacts for Python module.
 184
 185 ``Python2_Development.Embed_FOUND``
 186   .. versionadded:: 3.18
 187
 188   System has the Python 2 development artifacts for Python embedding.
 189
 190 ``Python2_INCLUDE_DIRS``
 191   The Python 2 include directories.
 192
 193 ``Python2_DEBUG_POSTFIX``
 194   .. versionadded:: 3.30
 195
 196   Postfix of debug python module. This variable can be used to define the
 197   :prop_tgt:`DEBUG_POSTFIX` target property.
 198
 199 ``Python2_LINK_OPTIONS``
 200   .. versionadded:: 3.19
 201
 202   The Python 2 link options. Some configurations require specific link options
 203   for a correct build and execution.
 204
 205 ``Python2_LIBRARIES``
 206   The Python 2 libraries.
 207 ``Python2_LIBRARY_DIRS``
 208   The Python 2 library directories.
 209 ``Python2_RUNTIME_LIBRARY_DIRS``
 210   The Python 2 runtime library directories.
 211 ``Python2_VERSION``
 212   Python 2 version.
 213 ``Python2_VERSION_MAJOR``
 214   Python 2 major version.
 215 ``Python2_VERSION_MINOR``
 216   Python 2 minor version.
 217 ``Python2_VERSION_PATCH``
 218   Python 2 patch version.
 219
 220 ``Python2_PyPy_VERSION``
 221   .. versionadded:: 3.18
 222
 223   Python 2 PyPy version.
 224
 225 ``Python2_NumPy_FOUND``
 226   .. versionadded:: 3.14
 227
 228   System has the NumPy.
 229
 230 ``Python2_NumPy_INCLUDE_DIRS``
 231   .. versionadded:: 3.14
 232
 233   The NumPy include directories.
 234
 235 ``Python2_NumPy_VERSION``
 236   .. versionadded:: 3.14
 237
 238   The NumPy version.
 239
 240 Hints
 241 ^^^^^
 242
 243 ``Python2_ROOT_DIR``
 244   Define the root directory of a Python 2 installation.
 245
 246 ``Python2_USE_STATIC_LIBS``
 247   * If not defined, search for shared libraries and static libraries in that
 248     order.
 249   * If set to TRUE, search **only** for static libraries.
 250   * If set to FALSE, search **only** for shared libraries.
 251
 252   .. note::
 253
 254     This hint will be ignored on ``Windows`` because static libraries are not
 255     available on this platform.
 256
 257 ``Python2_FIND_STRATEGY``
 258   .. versionadded:: 3.15
 259
 260   This variable defines how lookup will be done.
 261   The ``Python2_FIND_STRATEGY`` variable can be set to one of the following:
 262
 263   * ``VERSION``: Try to find the most recent version in all specified
 264     locations.
 265     This is the default if policy :policy:`CMP0094` is undefined or set to
 266     ``OLD``.
 267   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 268     constraints is founded.
 269     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 270
 271   See also ``Python2_FIND_UNVERSIONED_NAMES``.
 272
 273 ``Python2_FIND_REGISTRY``
 274   .. versionadded:: 3.13
 275
 276   On Windows the ``Python2_FIND_REGISTRY`` variable determine the order
 277   of preference between registry and environment variables.
 278   the ``Python2_FIND_REGISTRY`` variable can be set to one of the following:
 279
 280   * ``FIRST``: Try to use registry before environment variables.
 281     This is the default.
 282   * ``LAST``: Try to use registry after environment variables.
 283   * ``NEVER``: Never try to use registry.
 284
 285 ``Python2_FIND_FRAMEWORK``
 286   .. versionadded:: 3.15
 287
 288   On macOS the ``Python2_FIND_FRAMEWORK`` variable determine the order of
 289   preference between Apple-style and unix-style package components.
 290   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 291   variable.
 292
 293   .. note::
 294
 295     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 296
 297   If ``Python2_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 298   variable will be used, if any.
 299
 300 ``Python2_FIND_VIRTUALENV``
 301   .. versionadded:: 3.15
 302
 303   This variable defines the handling of virtual environments managed by
 304   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 305   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 306   takes precedence over ``Python2_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 307   variables.  The ``Python2_FIND_VIRTUALENV`` variable can be set to one of the
 308   following:
 309
 310   * ``FIRST``: The virtual environment is used before any other standard
 311     paths to look-up for the interpreter. This is the default.
 312   * ``ONLY``: Only the virtual environment is used to look-up for the
 313     interpreter.
 314   * ``STANDARD``: The virtual environment is not used to look-up for the
 315     interpreter but environment variable ``PATH`` is always considered.
 316     In this case, variable ``Python2_FIND_REGISTRY`` (Windows) or
 317     ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 318     ``NEVER`` to select preferably the interpreter from the virtual
 319     environment.
 320
 321   .. versionadded:: 3.17
 322     Added support for ``conda`` environments.
 323
 324   .. note::
 325
 326     If the component ``Development`` is requested (or one of its
 327     sub-components) and is not found or the wrong artifacts are returned,
 328     including also the component ``Interpreter`` may be helpful.
 329
 330 ``Python2_FIND_IMPLEMENTATIONS``
 331   .. versionadded:: 3.18
 332
 333   This variable defines, in an ordered list, the different implementations
 334   which will be searched. The ``Python2_FIND_IMPLEMENTATIONS`` variable can
 335   hold the following values:
 336
 337   * ``CPython``: this is the standard implementation. Various products, like
 338     ``Anaconda`` or ``ActivePython``, rely on this implementation.
 339   * ``IronPython``: This implementation use the ``CSharp`` language for
 340     ``.NET Framework`` on top of the `Dynamic Language Runtime` (``DLR``).
 341     See `IronPython <https://ironpython.net>`_.
 342   * ``PyPy``: This implementation use ``RPython`` language and
 343     ``RPython translation toolchain`` to produce the python interpreter.
 344     See `PyPy <https://pypy.org>`_.
 345
 346   The default value is:
 347
 348   * Windows platform: ``CPython``, ``IronPython``
 349   * Other platforms: ``CPython``
 350
 351   .. note::
 352
 353     This hint has the lowest priority of all hints, so even if, for example,
 354     you specify ``IronPython`` first and ``CPython`` in second, a python
 355     product based on ``CPython`` can be selected because, for example with
 356     ``Python2_FIND_STRATEGY=LOCATION``, each location will be search first for
 357     ``IronPython`` and second for ``CPython``.
 358
 359   .. note::
 360
 361     When ``IronPython`` is specified, on platforms other than ``Windows``, the
 362     ``.Net`` interpreter (i.e. ``mono`` command) is expected to be available
 363     through the ``PATH`` variable.
 364
 365 ``Python2_FIND_UNVERSIONED_NAMES``
 366   .. versionadded:: 3.20
 367
 368   This variable defines how the generic names will be searched. Currently, it
 369   only applies to the generic names of the interpreter, namely, ``python2`` and
 370   ``python``.
 371   The ``Python2_FIND_UNVERSIONED_NAMES`` variable can be set to one of the
 372   following values:
 373
 374   * ``FIRST``: The generic names are searched before the more specialized ones
 375     (such as ``python2.5`` for example).
 376   * ``LAST``: The generic names are searched after the more specialized ones.
 377     This is the default.
 378   * ``NEVER``: The generic name are not searched at all.
 379
 380   See also ``Python2_FIND_STRATEGY``.
 381
 382 Artifacts Specification
 383 ^^^^^^^^^^^^^^^^^^^^^^^
 384
 385 .. versionadded:: 3.16
 386
 387 To solve special cases, it is possible to specify directly the artifacts by
 388 setting the following variables:
 389
 390 ``Python2_EXECUTABLE``
 391   The path to the interpreter.
 392
 393 ``Python2_COMPILER``
 394   The path to the compiler.
 395
 396 ``Python2_DOTNET_LAUNCHER``
 397   .. versionadded:: 3.18
 398
 399   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 400
 401 ``Python2_LIBRARY``
 402   The path to the library. It will be used to compute the
 403   variables ``Python2_LIBRARIES``, ``Python2_LIBRARY_DIRS`` and
 404   ``Python2_RUNTIME_LIBRARY_DIRS``.
 405
 406 ``Python2_INCLUDE_DIR``
 407   The path to the directory of the ``Python`` headers. It will be used to
 408   compute the variable ``Python2_INCLUDE_DIRS``.
 409
 410 ``Python2_NumPy_INCLUDE_DIR``
 411   The path to the directory of the ``NumPy`` headers. It will be used to
 412   compute the variable ``Python2_NumPy_INCLUDE_DIRS``.
 413
 414 .. note::
 415
 416   All paths must be absolute. Any artifact specified with a relative path
 417   will be ignored.
 418
 419 .. note::
 420
 421   When an artifact is specified, all ``HINTS`` will be ignored and no search
 422   will be performed for this artifact.
 423
 424   If more than one artifact is specified, it is the user's responsibility to
 425   ensure the consistency of the various artifacts.
 426
 427 By default, this module supports multiple calls in different directories of a
 428 project with different version/component requirements while providing correct
 429 and consistent results for each call. To support this behavior, CMake cache
 430 is not used in the traditional way which can be problematic for interactive
 431 specification. So, to enable also interactive specification, module behavior
 432 can be controlled with the following variable:
 433
 434 ``Python2_ARTIFACTS_INTERACTIVE``
 435   .. versionadded:: 3.18
 436
 437   Selects the behavior of the module. This is a boolean variable:
 438
 439   * If set to ``TRUE``: Create CMake cache entries for the above artifact
 440     specification variables so that users can edit them interactively.
 441     This disables support for multiple version/component requirements.
 442   * If set to ``FALSE`` or undefined: Enable multiple version/component
 443     requirements.
 444
 445 ``Python2_ARTIFACTS_PREFIX``
 446   .. versionadded:: 4.0
 447
 448   Define a custom prefix which will be used for the definition of all the
 449   result variables, targets, and commands. By using this variable, this module
 450   supports multiple calls in the same directory with different
 451   version/component requirements.
 452   For example, in case of cross-compilation, development components are needed
 453   but the native python interpreter can also be required:
 454
 455   .. code-block:: cmake
 456
 457     find_package(Python2 COMPONENTS Development)
 458
 459     set(Python2_ARTIFACTS_PREFIX "_HOST")
 460     find_package(Python2 COMPONENTS Interpreter)
 461
 462     # Here Python2_HOST_EXECUTABLE and Python2_HOST::Interpreter artifacts are defined
 463
 464   .. note::
 465
 466     For consistency with standard behavior of modules, the various standard
 467     ``_FOUND`` variables (i.e. without the custom prefix) are also defined by
 468     each call to the :command:`find_package` command.
 469
 470 Commands
 471 ^^^^^^^^
 472
 473 This module defines the command ``Python2_add_library`` (when
 474 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 475 :command:`add_library` and adds a dependency to target ``Python2::Python`` or,
 476 when library type is ``MODULE``, to target ``Python2::Module`` and takes care
 477 of Python module naming rules:
 478
 479 .. code-block:: cmake
 480
 481   Python2_add_library (<name> [STATIC | SHARED | MODULE]
 482                        <source1> [<source2> ...])
 483
 484 If library type is not specified, ``MODULE`` is assumed.
 485
 486 .. versionadded:: 3.30
 487   For ``MODULE`` type, the :prop_tgt:`DEBUG_POSTFIX` target property is
 488   initialized with the value of ``Python2_DEBUG_POSTFIX`` variable if defined.
 489 #]=======================================================================]
 490
 491
 492 set (_PYTHON_BASE Python2)
 493 if(${_PYTHON_BASE}_ARTIFACTS_PREFIX)
 494   set(_PYTHON_PREFIX "${_PYTHON_BASE}${${_PYTHON_BASE}_ARTIFACTS_PREFIX}")
 495 else()
 496   set(_PYTHON_PREFIX "${_PYTHON_BASE}")
 497 endif()
 498
 499 set (_${_PYTHON_PREFIX}_REQUIRED_VERSION_MAJOR 2)
 500
 501 include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 502
 503 if (COMMAND __${_PYTHON_PREFIX}_add_library AND NOT COMMAND ${_PYTHON_PREFIX}_add_library)
 504   cmake_language(EVAL CODE
 505     "macro (${_PYTHON_PREFIX}_add_library)
 506        __${_PYTHON_PREFIX}_add_library (${_PYTHON_PREFIX} \${ARGV})
 507      endmacro()")
 508 endif()
 509
 510 unset (_PYTHON_BASE)
 511 unset (_PYTHON_PREFIX)