Modules/FindPython.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 FindPython
   6 ----------
   7
   8 Find Python interpreter, compiler and development environment (include
   9 directories and libraries).
  10
  11 The following components are supported:
  12
  13 * ``Interpreter``: search for Python interpreter.
  14 * ``Compiler``: search for Python compiler. Only offered by IronPython.
  15 * ``Development``: search for development artifacts (include directories and
  16   libraries).
  17 * ``NumPy``: search for NumPy include directories.
  18
  19 If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed.
  20
  21 To ensure consistent versions between components ``Interpreter``, ``Compiler``,
  22 ``Development`` and ``NumPy``, specify all components at the same time::
  23
  24   find_package (Python COMPONENTS Interpreter Development)
  25
  26 This module looks preferably for version 3 of Python. If not found, version 2
  27 is searched.
  28 To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
  29 :module:`FindPython2` modules rather than this one.
  30
  31 .. note::
  32
  33   If components ``Interpreter`` and ``Development`` are both specified, this
  34   module search only for interpreter with same platform architecture as the one
  35   defined by ``CMake`` configuration. This contraint does not apply if only
  36   ``Interpreter`` component is specified.
  37
  38 Imported Targets
  39 ^^^^^^^^^^^^^^^^
  40
  41 This module defines the following :ref:`Imported Targets <Imported Targets>`
  42 (when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):
  43
  44 ``Python::Interpreter``
  45   Python interpreter. Target defined if component ``Interpreter`` is found.
  46 ``Python::Compiler``
  47   Python compiler. Target defined if component ``Compiler`` is found.
  48 ``Python::Python``
  49   Python library for Python embedding. Target defined if component
  50   ``Development`` is found.
  51 ``Python::Module``
  52   Python library for Python module. Target defined if component ``Development``
  53   is found.
  54 ``Python::NumPy``
  55   NumPy Python library. Target defined if component ``NumPy`` is found.
  56
  57 Result Variables
  58 ^^^^^^^^^^^^^^^^
  59
  60 This module will set the following variables in your project
  61 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
  62
  63 ``Python_FOUND``
  64   System has the Python requested components.
  65 ``Python_Interpreter_FOUND``
  66   System has the Python interpreter.
  67 ``Python_EXECUTABLE``
  68   Path to the Python interpreter.
  69 ``Python_INTERPRETER_ID``
  70   A short string unique to the interpreter. Possible values include:
  71     * Python
  72     * ActivePython
  73     * Anaconda
  74     * Canopy
  75     * IronPython
  76 ``Python_STDLIB``
  77   Standard platform independent installation directory.
  78
  79   Information returned by
  80   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
  81 ``Python_STDARCH``
  82   Standard platform dependent installation directory.
  83
  84   Information returned by
  85   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
  86 ``Python_SITELIB``
  87   Third-party platform independent installation directory.
  88
  89   Information returned by
  90   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
  91 ``Python_SITEARCH``
  92   Third-party platform dependent installation directory.
  93
  94   Information returned by
  95   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
  96 ``Python_SOABI``
  97   Extension suffix for modules.
  98
  99   Information returned by
 100   ``distutils.sysconfig.get_config_flag('SOABI')`` or computed from
 101   ``distutils.sysconfig.get_config_flag('EXT_SUFFIX')`` or
 102   ``python-config --extension-suffix``.
 103 ``Python_Compiler_FOUND``
 104   System has the Python compiler.
 105 ``Python_COMPILER``
 106   Path to the Python compiler. Only offered by IronPython.
 107 ``Python_COMPILER_ID``
 108   A short string unique to the compiler. Possible values include:
 109     * IronPython
 110 ``Python_Development_FOUND``
 111   System has the Python development artifacts.
 112 ``Python_INCLUDE_DIRS``
 113   The Python include directories.
 114 ``Python_LIBRARIES``
 115   The Python libraries.
 116 ``Python_LIBRARY_DIRS``
 117   The Python library directories.
 118 ``Python_RUNTIME_LIBRARY_DIRS``
 119   The Python runtime library directories.
 120 ``Python_VERSION``
 121   Python version.
 122 ``Python_VERSION_MAJOR``
 123   Python major version.
 124 ``Python_VERSION_MINOR``
 125   Python minor version.
 126 ``Python_VERSION_PATCH``
 127   Python patch version.
 128 ``Python_NumPy_FOUND``
 129   System has the NumPy.
 130 ``Python_NumPy_INCLUDE_DIRS``
 131   The NumPy include directries.
 132 ``Python_NumPy_VERSION``
 133   The NumPy version.
 134
 135 Hints
 136 ^^^^^
 137
 138 ``Python_ROOT_DIR``
 139   Define the root directory of a Python installation.
 140
 141 ``Python_USE_STATIC_LIBS``
 142   * If not defined, search for shared libraries and static libraries in that
 143     order.
 144   * If set to TRUE, search **only** for static libraries.
 145   * If set to FALSE, search **only** for shared libraries.
 146
 147 ``Python_FIND_ABI``
 148   This variable defines which ABIs, as defined in
 149   `PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.
 150
 151   .. note::
 152
 153     This hint will be honored only when searched for ``Python`` version 3.
 154
 155   .. note::
 156
 157     If ``Python_FIND_ABI`` is not defined, any ABI will be searched.
 158
 159   The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
 160   ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
 161   Each element can be set to one of the following:
 162
 163   * ``ON``: Corresponding flag is selected.
 164   * ``OFF``: Corresponding flag is not selected.
 165   * ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.
 166
 167   From this 3-tuple, various ABIs will be searched starting from the most
 168   specialized to the most general. Moreover, ``debug`` versions will be
 169   searched **after** ``non-debug`` ones.
 170
 171   For example, if we have::
 172
 173     set (Python_FIND_ABI "ON" "ANY" "ANY")
 174
 175   The following flags combinations will be appended, in that order, to the
 176   artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
 177
 178   And to search any possible ABIs::
 179
 180     set (Python_FIND_ABI "ANY" "ANY" "ANY")
 181
 182   The following combinations, in that order, will be used: ``mu``, ``m``,
 183   ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
 184
 185   .. note::
 186
 187     This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
 188     when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
 189     `python.org <https://www.python.org/>`_ will be found only if value for
 190     each flag is ``OFF`` or ``ANY``.
 191
 192 ``Python_FIND_STRATEGY``
 193   This variable defines how lookup will be done.
 194   The ``Python_FIND_STRATEGY`` variable can be set to empty or one of the
 195   following:
 196
 197   * ``VERSION``: Try to find the most recent version in all specified
 198     locations.
 199     This is the default if policy :policy:`CMP0094` is undefined or set to
 200     ``OLD``.
 201   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 202     constraints is founded.
 203     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 204
 205 ``Python_FIND_REGISTRY``
 206   On Windows the ``Python_FIND_REGISTRY`` variable determine the order
 207   of preference between registry and environment variables.
 208   the ``Python_FIND_REGISTRY`` variable can be set to empty or one of the
 209   following:
 210
 211   * ``FIRST``: Try to use registry before environment variables.
 212     This is the default.
 213   * ``LAST``: Try to use registry after environment variables.
 214   * ``NEVER``: Never try to use registry.
 215
 216 ``Python_FIND_FRAMEWORK``
 217   On macOS the ``Python_FIND_FRAMEWORK`` variable determine the order of
 218   preference between Apple-style and unix-style package components.
 219   This variable can be set to empty or take same values as
 220   :variable:`CMAKE_FIND_FRAMEWORK` variable.
 221
 222   .. note::
 223
 224     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 225
 226   If ``Python_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 227   variable will be used, if any.
 228
 229 ``Python_FIND_VIRTUALENV``
 230   This variable defines the handling of virtual environments managed by
 231   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 232   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 233   takes precedence over ``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 234   variables.  The ``Python_FIND_VIRTUALENV`` variable can be set to empty or
 235   one of the following:
 236
 237   * ``FIRST``: The virtual environment is used before any other standard
 238     paths to look-up for the interpreter. This is the default.
 239   * ``ONLY``: Only the virtual environment is used to look-up for the
 240     interpreter.
 241   * ``STANDARD``: The virtual environment is not used to look-up for the
 242     interpreter. In this case, variable ``Python_FIND_REGISTRY`` (Windows)
 243     or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 244     ``NEVER`` to select preferably the interpreter from the virtual
 245     environment.
 246
 247   .. note::
 248
 249     If the component ``Development`` is requested, it is **strongly**
 250     recommended to also include the component ``Interpreter`` to get expected
 251     result.
 252
 253 Artifacts Specification
 254 ^^^^^^^^^^^^^^^^^^^^^^^
 255
 256 To solve special cases, it is possible to specify directly the artifacts by
 257 setting the following variables:
 258
 259 ``Python_EXECUTABLE``
 260   The path to the interpreter.
 261
 262 ``Python_COMPILER``
 263   The path to the compiler.
 264
 265 ``Python_LIBRARY``
 266   The path to the library. It will be used to compute the
 267   variables ``Python_LIBRARIES``, ``Python_LIBRAY_DIRS`` and
 268   ``Python_RUNTIME_LIBRARY_DIRS``.
 269
 270 ``Python_INCLUDE_DIR``
 271   The path to the directory of the ``Python`` headers. It will be used to
 272   compute the variable ``Python_INCLUDE_DIRS``.
 273
 274 ``Python_NumPy_INCLUDE_DIR``
 275   The path to the directory of the ``NumPy`` headers. It will be used to
 276   compute the variable ``Python_NumPy_INCLUDE_DIRS``.
 277
 278 .. note::
 279
 280   All paths must be absolute. Any artifact specified with a relative path
 281   will be ignored.
 282
 283 .. note::
 284
 285   When an artifact is specified, all ``HINTS`` will be ignored and no search
 286   will be performed for this artifact.
 287
 288   If more than one artifact is specified, it is the user's responsability to
 289   ensure the consistency of the various artifacts.
 290
 291 Commands
 292 ^^^^^^^^
 293
 294 This module defines the command ``Python_add_library`` (when
 295 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 296 :command:`add_library` and adds a dependency to target ``Python::Python`` or,
 297 when library type is ``MODULE``, to target ``Python::Module`` and takes care of
 298 Python module naming rules::
 299
 300   Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
 301                       <source1> [<source2> ...])
 302
 303 If the library type is not specified, ``MODULE`` is assumed.
 304
 305 For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
 306 module suffix will include the ``Python_SOABI`` value, if any.
 307 #]=======================================================================]
 308
 309
 310 set (_PYTHON_PREFIX Python)
 311
 312 if (DEFINED Python_FIND_VERSION)
 313   set (_Python_REQUIRED_VERSION_MAJOR ${Python_FIND_VERSION_MAJOR})
 314
 315   include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 316 else()
 317   # iterate over versions in quiet and NOT required modes to avoid multiple
 318   # "Found" messages and prematurally failure.
 319   set (_Python_QUIETLY ${Python_FIND_QUIETLY})
 320   set (_Python_REQUIRED ${Python_FIND_REQUIRED})
 321   set (Python_FIND_QUIETLY TRUE)
 322   set (Python_FIND_REQUIRED FALSE)
 323
 324   set (_Python_REQUIRED_VERSIONS 3 2)
 325   set (_Python_REQUIRED_VERSION_LAST 2)
 326
 327   unset (_Python_INPUT_VARS)
 328   foreach (_Python_ITEM IN ITEMS Python_EXECUTABLE Python_COMPILER Python_LIBRARY
 329                                  Python_INCLUDE_DIR Python_NumPy_INCLUDE_DIR)
 330     if (NOT DEFINED ${_Python_ITEM})
 331       list (APPEND _Python_INPUT_VARS ${_Python_ITEM})
 332     endif()
 333   endforeach()
 334
 335   foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
 336     set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
 337     include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 338     if (Python_FOUND OR
 339         _Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
 340       break()
 341     endif()
 342     # clean-up INPUT variables not set by the user
 343     foreach (_Python_ITEM IN LISTS _Python_INPUT_VARS)
 344       unset (${_Python_ITEM})
 345     endforeach()
 346     # clean-up some CACHE variables to ensure look-up restart from scratch
 347     foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
 348       unset (${_Python_ITEM} CACHE)
 349     endforeach()
 350   endforeach()
 351
 352   unset (Python_FIND_VERSION)
 353
 354   set (Python_FIND_QUIETLY ${_Python_QUIETLY})
 355   set (Python_FIND_REQUIRED ${_Python_REQUIRED})
 356   if (Python_FIND_REQUIRED OR NOT Python_FIND_QUIETLY)
 357     # call again validation command to get "Found" or error message
 358     find_package_handle_standard_args (Python HANDLE_COMPONENTS
 359                                               REQUIRED_VARS ${_Python_REQUIRED_VARS}
 360                                               VERSION_VAR Python_VERSION)
 361   endif()
 362 endif()
 363
 364 if (COMMAND __Python_add_library)
 365   macro (Python_add_library)
 366     __Python_add_library (Python ${ARGV})
 367   endmacro()
 368 endif()
 369
 370 unset (_PYTHON_PREFIX)