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   find_package (Python2 COMPONENTS Interpreter Development)
  49
  50 This module looks only for version 2 of Python. This module can be used
  51 concurrently with :module:`FindPython3` 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 ``Python2::Interpreter``
  74   Python 2 interpreter. Target defined if component ``Interpreter`` is found.
  75 ``Python2::Compiler``
  76   Python 2 compiler. Target defined if component ``Compiler`` is found.
  77 ``Python2::Module``
  78   .. versionadded:: 3.15
  79
  80   Python 2 library for Python module. Target defined if component
  81   ``Development.Module`` is found.
  82
  83 ``Python2::Python``
  84   Python 2 library for Python embedding. Target defined if component
  85   ``Development.Embed`` is found.
  86
  87 ``Python2::NumPy``
  88   .. versionadded:: 3.14
  89
  90   NumPy library for Python 2. 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 ``Python2_FOUND``
  99   System has the Python 2 requested components.
 100 ``Python2_Interpreter_FOUND``
 101   System has the Python 2 interpreter.
 102 ``Python2_EXECUTABLE``
 103   Path to the Python 2 interpreter.
 104 ``Python2_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 ``Python2_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 ``Python2_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 ``Python2_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 ``Python2_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 ``Python2_Compiler_FOUND``
 137   System has the Python 2 compiler.
 138 ``Python2_COMPILER``
 139   Path to the Python 2 compiler. Only offered by IronPython.
 140 ``Python2_COMPILER_ID``
 141   A short string unique to the compiler. Possible values include:
 142     * IronPython
 143
 144 ``Python2_DOTNET_LAUNCHER``
 145   .. versionadded:: 3.18
 146
 147   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 148
 149 ``Python2_Development_FOUND``
 150   System has the Python 2 development artifacts.
 151
 152 ``Python2_Development.Module_FOUND``
 153   .. versionadded:: 3.18
 154
 155   System has the Python 2 development artifacts for Python module.
 156
 157 ``Python2_Development.Embed_FOUND``
 158   .. versionadded:: 3.18
 159
 160   System has the Python 2 development artifacts for Python embedding.
 161
 162 ``Python2_INCLUDE_DIRS``
 163   The Python 2 include directories.
 164
 165 ``Python2_LINK_OPTIONS``
 166   .. versionadded:: 3.19
 167
 168   The Python 2 link options. Some configurations require specific link options
 169   for a correct build and execution.
 170
 171 ``Python2_LIBRARIES``
 172   The Python 2 libraries.
 173 ``Python2_LIBRARY_DIRS``
 174   The Python 2 library directories.
 175 ``Python2_RUNTIME_LIBRARY_DIRS``
 176   The Python 2 runtime library directories.
 177 ``Python2_VERSION``
 178   Python 2 version.
 179 ``Python2_VERSION_MAJOR``
 180   Python 2 major version.
 181 ``Python2_VERSION_MINOR``
 182   Python 2 minor version.
 183 ``Python2_VERSION_PATCH``
 184   Python 2 patch version.
 185
 186 ``Python2_PyPy_VERSION``
 187   .. versionadded:: 3.18
 188
 189   Python 2 PyPy version.
 190
 191 ``Python2_NumPy_FOUND``
 192   .. versionadded:: 3.14
 193
 194   System has the NumPy.
 195
 196 ``Python2_NumPy_INCLUDE_DIRS``
 197   .. versionadded:: 3.14
 198
 199   The NumPy include directories.
 200
 201 ``Python2_NumPy_VERSION``
 202   .. versionadded:: 3.14
 203
 204   The NumPy version.
 205
 206 Hints
 207 ^^^^^
 208
 209 ``Python2_ROOT_DIR``
 210   Define the root directory of a Python 2 installation.
 211
 212 ``Python2_USE_STATIC_LIBS``
 213   * If not defined, search for shared libraries and static libraries in that
 214     order.
 215   * If set to TRUE, search **only** for static libraries.
 216   * If set to FALSE, search **only** for shared libraries.
 217
 218   .. note::
 219
 220     This hint will be ignored on ``Windows`` because static libraries are not
 221     available on this platform.
 222
 223 ``Python2_FIND_STRATEGY``
 224   .. versionadded:: 3.15
 225
 226   This variable defines how lookup will be done.
 227   The ``Python2_FIND_STRATEGY`` variable can be set to one of the following:
 228
 229   * ``VERSION``: Try to find the most recent version in all specified
 230     locations.
 231     This is the default if policy :policy:`CMP0094` is undefined or set to
 232     ``OLD``.
 233   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 234     constraints is founded.
 235     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 236
 237 ``Python2_FIND_REGISTRY``
 238   .. versionadded:: 3.13
 239
 240   On Windows the ``Python2_FIND_REGISTRY`` variable determine the order
 241   of preference between registry and environment variables.
 242   the ``Python2_FIND_REGISTRY`` variable can be set to one of the following:
 243
 244   * ``FIRST``: Try to use registry before environment variables.
 245     This is the default.
 246   * ``LAST``: Try to use registry after environment variables.
 247   * ``NEVER``: Never try to use registry.
 248
 249 ``Python2_FIND_FRAMEWORK``
 250   .. versionadded:: 3.15
 251
 252   On macOS the ``Python2_FIND_FRAMEWORK`` variable determine the order of
 253   preference between Apple-style and unix-style package components.
 254   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 255   variable.
 256
 257   .. note::
 258
 259     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 260
 261   If ``Python2_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 262   variable will be used, if any.
 263
 264 ``Python2_FIND_VIRTUALENV``
 265   .. versionadded:: 3.15
 266
 267   This variable defines the handling of virtual environments managed by
 268   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 269   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 270   takes precedence over ``Python2_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 271   variables.  The ``Python2_FIND_VIRTUALENV`` variable can be set to one of the
 272   following:
 273
 274   * ``FIRST``: The virtual environment is used before any other standard
 275     paths to look-up for the interpreter. This is the default.
 276   * ``ONLY``: Only the virtual environment is used to look-up for the
 277     interpreter.
 278   * ``STANDARD``: The virtual environment is not used to look-up for the
 279     interpreter but environment variable ``PATH`` is always considered.
 280     In this case, variable ``Python2_FIND_REGISTRY`` (Windows) or
 281     ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 282     ``NEVER`` to select preferably the interpreter from the virtual
 283     environment.
 284
 285   .. versionadded:: 3.17
 286     Added support for ``conda`` environments.
 287
 288   .. note::
 289
 290     If the component ``Development`` is requested, it is **strongly**
 291     recommended to also include the component ``Interpreter`` to get expected
 292     result.
 293
 294 ``Python2_FIND_IMPLEMENTATIONS``
 295   .. versionadded:: 3.18
 296
 297   This variable defines, in an ordered list, the different implementations
 298   which will be searched. The ``Python2_FIND_IMPLEMENTATIONS`` variable can
 299   hold the following values:
 300
 301   * ``CPython``: this is the standard implementation. Various products, like
 302     ``Anaconda`` or ``ActivePython``, rely on this implementation.
 303   * ``IronPython``: This implementation use the ``CSharp`` language for
 304     ``.NET Framework`` on top of the `Dynamic Language Runtime` (``DLR``).
 305     See `IronPython <http://ironpython.net>`_.
 306   * ``PyPy``: This implementation use ``RPython`` language and
 307     ``RPython translation toolchain`` to produce the python interpreter.
 308     See `PyPy <https://www.pypy.org>`_.
 309
 310   The default value is:
 311
 312   * Windows platform: ``CPython``, ``IronPython``
 313   * Other platforms: ``CPython``
 314
 315   .. note::
 316
 317     This hint has the lowest priority of all hints, so even if, for example,
 318     you specify ``IronPython`` first and ``CPython`` in second, a python
 319     product based on ``CPython`` can be selected because, for example with
 320     ``Python2_FIND_STRATEGY=LOCATION``, each location will be search first for
 321     ``IronPython`` and second for ``CPython``.
 322
 323   .. note::
 324
 325     When ``IronPython`` is specified, on platforms other than ``Windows``, the
 326     ``.Net`` interpreter (i.e. ``mono`` command) is expected to be available
 327     through the ``PATH`` variable.
 328
 329 ``Python2_FIND_UNVERSIONED_NAMES``
 330   .. versionadded:: 3.20
 331
 332   This variable defines how the generic names will be searched. Currently, it
 333   only applies to the generic names of the interpreter, namely, ``python2`` and
 334   ``python``.
 335   The ``Python2_FIND_UNVERSIONED_NAMES`` variable can be set to one of the
 336   following values:
 337
 338   * ``FIRST``: The generic names are searched before the more specialized ones
 339     (such as ``python2.5`` for example).
 340   * ``LAST``: The generic names are searched after the more specialized ones.
 341     This is the default.
 342   * ``NEVER``: The generic name are not searched at all.
 343
 344 Artifacts Specification
 345 ^^^^^^^^^^^^^^^^^^^^^^^
 346
 347 .. versionadded:: 3.16
 348
 349 To solve special cases, it is possible to specify directly the artifacts by
 350 setting the following variables:
 351
 352 ``Python2_EXECUTABLE``
 353   The path to the interpreter.
 354
 355 ``Python2_COMPILER``
 356   The path to the compiler.
 357
 358 ``Python2_DOTNET_LAUNCHER``
 359   .. versionadded:: 3.18
 360
 361   The ``.Net`` interpreter. Only used by ``IronPython`` implementation.
 362
 363 ``Python2_LIBRARY``
 364   The path to the library. It will be used to compute the
 365   variables ``Python2_LIBRARIES``, ``Python2_LIBRARY_DIRS`` and
 366   ``Python2_RUNTIME_LIBRARY_DIRS``.
 367
 368 ``Python2_INCLUDE_DIR``
 369   The path to the directory of the ``Python`` headers. It will be used to
 370   compute the variable ``Python2_INCLUDE_DIRS``.
 371
 372 ``Python2_NumPy_INCLUDE_DIR``
 373   The path to the directory of the ``NumPy`` headers. It will be used to
 374   compute the variable ``Python2_NumPy_INCLUDE_DIRS``.
 375
 376 .. note::
 377
 378   All paths must be absolute. Any artifact specified with a relative path
 379   will be ignored.
 380
 381 .. note::
 382
 383   When an artifact is specified, all ``HINTS`` will be ignored and no search
 384   will be performed for this artifact.
 385
 386   If more than one artifact is specified, it is the user's responsibility to
 387   ensure the consistency of the various artifacts.
 388
 389 By default, this module supports multiple calls in different directories of a
 390 project with different version/component requirements while providing correct
 391 and consistent results for each call. To support this behavior, ``CMake`` cache
 392 is not used in the traditional way which can be problematic for interactive
 393 specification. So, to enable also interactive specification, module behavior
 394 can be controlled with the following variable:
 395
 396 ``Python2_ARTIFACTS_INTERACTIVE``
 397   .. versionadded:: 3.18
 398
 399   Selects the behavior of the module. This is a boolean variable:
 400
 401   * If set to ``TRUE``: Create CMake cache entries for the above artifact
 402     specification variables so that users can edit them interactively.
 403     This disables support for multiple version/component requirements.
 404   * If set to ``FALSE`` or undefined: Enable multiple version/component
 405     requirements.
 406
 407 Commands
 408 ^^^^^^^^
 409
 410 This module defines the command ``Python2_add_library`` (when
 411 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 412 :command:`add_library` and adds a dependency to target ``Python2::Python`` or,
 413 when library type is ``MODULE``, to target ``Python2::Module`` and takes care
 414 of Python module naming rules::
 415
 416   Python2_add_library (<name> [STATIC | SHARED | MODULE]
 417                        <source1> [<source2> ...])
 418
 419 If library type is not specified, ``MODULE`` is assumed.
 420 #]=======================================================================]
 421
 422
 423 set (_PYTHON_PREFIX Python2)
 424
 425 set (_Python2_REQUIRED_VERSION_MAJOR 2)
 426
 427 include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 428
 429 if (COMMAND __Python2_add_library)
 430   macro (Python2_add_library)
 431     __Python2_add_library (Python2 ${ARGV})
 432   endmacro()
 433 endif()
 434
 435 unset (_PYTHON_PREFIX)