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 Find Python 2 interpreter, compiler and development environment (include
   9 directories and libraries).
  10
  11 The following components are supported:
  12
  13 * ``Interpreter``: search for Python 2 interpreter
  14 * ``Compiler``: search for Python 2 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 (Python2 COMPONENTS Interpreter Development)
  25
  26 This module looks only for version 2 of Python. This module can be used
  27 concurrently with :module:`FindPython3` module to use both Python versions.
  28
  29 The :module:`FindPython` module can be used if Python version does not matter
  30 for you.
  31
  32 .. note::
  33
  34   If components ``Interpreter`` and ``Development`` are both specified, this
  35   module search only for interpreter with same platform architecture as the one
  36   defined by ``CMake`` configuration. This contraint does not apply if only
  37   ``Interpreter`` component is specified.
  38
  39 Imported Targets
  40 ^^^^^^^^^^^^^^^^
  41
  42 This module defines the following :ref:`Imported Targets <Imported Targets>`
  43 (when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):
  44
  45 ``Python2::Interpreter``
  46   Python 2 interpreter. Target defined if component ``Interpreter`` is found.
  47 ``Python2::Compiler``
  48   Python 2 compiler. Target defined if component ``Compiler`` is found.
  49 ``Python2::Python``
  50   Python 2 library for Python embedding. Target defined if component
  51   ``Development`` is found.
  52 ``Python2::Module``
  53   Python 2 library for Python module. Target defined if component
  54   ``Development`` is found.
  55 ``Python2::NumPy``
  56   NumPy library for Python 2. Target defined if component ``NumPy`` is found.
  57
  58 Result Variables
  59 ^^^^^^^^^^^^^^^^
  60
  61 This module will set the following variables in your project
  62 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
  63
  64 ``Python2_FOUND``
  65   System has the Python 2 requested components.
  66 ``Python2_Interpreter_FOUND``
  67   System has the Python 2 interpreter.
  68 ``Python2_EXECUTABLE``
  69   Path to the Python 2 interpreter.
  70 ``Python2_INTERPRETER_ID``
  71   A short string unique to the interpreter. Possible values include:
  72     * Python
  73     * ActivePython
  74     * Anaconda
  75     * Canopy
  76     * IronPython
  77 ``Python2_STDLIB``
  78   Standard platform independent installation directory.
  79
  80   Information returned by
  81   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
  82 ``Python2_STDARCH``
  83   Standard platform dependent installation directory.
  84
  85   Information returned by
  86   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
  87 ``Python2_SITELIB``
  88   Third-party platform independent installation directory.
  89
  90   Information returned by
  91   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
  92 ``Python2_SITEARCH``
  93   Third-party platform dependent installation directory.
  94
  95   Information returned by
  96   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
  97 ``Python2_Compiler_FOUND``
  98   System has the Python 2 compiler.
  99 ``Python2_COMPILER``
 100   Path to the Python 2 compiler. Only offered by IronPython.
 101 ``Python2_COMPILER_ID``
 102   A short string unique to the compiler. Possible values include:
 103     * IronPython
 104 ``Python2_Development_FOUND``
 105   System has the Python 2 development artifacts.
 106 ``Python2_INCLUDE_DIRS``
 107   The Python 2 include directories.
 108 ``Python2_LIBRARIES``
 109   The Python 2 libraries.
 110 ``Python2_LIBRARY_DIRS``
 111   The Python 2 library directories.
 112 ``Python2_RUNTIME_LIBRARY_DIRS``
 113   The Python 2 runtime library directories.
 114 ``Python2_VERSION``
 115   Python 2 version.
 116 ``Python2_VERSION_MAJOR``
 117   Python 2 major version.
 118 ``Python2_VERSION_MINOR``
 119   Python 2 minor version.
 120 ``Python2_VERSION_PATCH``
 121   Python 2 patch version.
 122 ``Python2_NumPy_FOUND``
 123   System has the NumPy.
 124 ``Python2_NumPy_INCLUDE_DIRS``
 125   The NumPy include directries.
 126 ``Python2_NumPy_VERSION``
 127   The NumPy version.
 128
 129 Hints
 130 ^^^^^
 131
 132 ``Python2_ROOT_DIR``
 133   Define the root directory of a Python 2 installation.
 134
 135 ``Python2_USE_STATIC_LIBS``
 136   * If not defined, search for shared libraries and static libraries in that
 137     order.
 138   * If set to TRUE, search **only** for static libraries.
 139   * If set to FALSE, search **only** for shared libraries.
 140
 141 ``Python2_FIND_STRATEGY``
 142   This variable defines how lookup will be done.
 143   The ``Python2_FIND_STRATEGY`` variable can be set to one of the following:
 144
 145   * ``VERSION``: Try to find the most recent version in all specified
 146     locations.
 147     This is the default if policy :policy:`CMP0094` is undefined or set to
 148     ``OLD``.
 149   * ``LOCATION``: Stops lookup as soon as a version satisfying version
 150     constraints is founded.
 151     This is the default if policy :policy:`CMP0094` is set to ``NEW``.
 152
 153 ``Python2_FIND_REGISTRY``
 154   On Windows the ``Python2_FIND_REGISTRY`` variable determine the order
 155   of preference between registry and environment variables.
 156   the ``Python2_FIND_REGISTRY`` variable can be set to one of the following:
 157
 158   * ``FIRST``: Try to use registry before environment variables.
 159     This is the default.
 160   * ``LAST``: Try to use registry after environment variables.
 161   * ``NEVER``: Never try to use registry.
 162
 163 ``Python2_FIND_FRAMEWORK``
 164   On macOS the ``Python2_FIND_FRAMEWORK`` variable determine the order of
 165   preference between Apple-style and unix-style package components.
 166   This variable can take same values as :variable:`CMAKE_FIND_FRAMEWORK`
 167   variable.
 168
 169   .. note::
 170
 171     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 172
 173   If ``Python2_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
 174   variable will be used, if any.
 175
 176 ``Python2_FIND_VIRTUALENV``
 177   This variable defines the handling of virtual environments managed by
 178   ``virtualenv`` or ``conda``. It is meaningful only when a virtual environment
 179   is active (i.e. the ``activate`` script has been evaluated). In this case, it
 180   takes precedence over ``Python2_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK``
 181   variables.  The ``Python2_FIND_VIRTUALENV`` variable can be set to one of the
 182   following:
 183
 184   * ``FIRST``: The virtual environment is used before any other standard
 185     paths to look-up for the interpreter. This is the default.
 186   * ``ONLY``: Only the virtual environment is used to look-up for the
 187     interpreter.
 188   * ``STANDARD``: The virtual environment is not used to look-up for the
 189     interpreter. In this case, variable ``Python2_FIND_REGISTRY`` (Windows)
 190     or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
 191     ``NEVER`` to select preferably the interpreter from the virtual
 192     environment.
 193
 194   .. note::
 195
 196     If the component ``Development`` is requested, it is **strongly**
 197     recommended to also include the component ``Interpreter`` to get expected
 198     result.
 199
 200 Artifacts Specification
 201 ^^^^^^^^^^^^^^^^^^^^^^^
 202
 203 To solve special cases, it is possible to specify directly the artifacts by
 204 setting the following variables:
 205
 206 ``Python2_EXECUTABLE``
 207   The path to the interpreter.
 208
 209 ``Python2_COMPILER``
 210   The path to the compiler.
 211
 212 ``Python2_LIBRARY``
 213   The path to the library. It will be used to compute the
 214   variables ``Python2_LIBRARIES``, ``Python2_LIBRAY_DIRS`` and
 215   ``Python2_RUNTIME_LIBRARY_DIRS``.
 216
 217 ``Python2_INCLUDE_DIR``
 218   The path to the directory of the ``Python`` headers. It will be used to
 219   compute the variable ``Python2_INCLUDE_DIRS``.
 220
 221 ``Python2_NumPy_INCLUDE_DIR``
 222   The path to the directory of the ``NumPy`` headers. It will be used to
 223   compute the variable ``Python2_NumPy_INCLUDE_DIRS``.
 224
 225 .. note::
 226
 227   All paths must be absolute. Any artifact specified with a relative path
 228   will be ignored.
 229
 230 .. note::
 231
 232   When an artifact is specified, all ``HINTS`` will be ignored and no search
 233   will be performed for this artifact.
 234
 235   If more than one artifact is specified, it is the user's responsability to
 236   ensure the consistency of the various artifacts.
 237
 238 Commands
 239 ^^^^^^^^
 240
 241 This module defines the command ``Python2_add_library`` (when
 242 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 243 :command:`add_library` and adds a dependency to target ``Python2::Python`` or,
 244 when library type is ``MODULE``, to target ``Python2::Module`` and takes care
 245 of Python module naming rules::
 246
 247   Python2_add_library (<name> [STATIC | SHARED | MODULE]
 248                        <source1> [<source2> ...])
 249
 250 If library type is not specified, ``MODULE`` is assumed.
 251 #]=======================================================================]
 252
 253
 254 set (_PYTHON_PREFIX Python2)
 255
 256 set (_Python2_REQUIRED_VERSION_MAJOR 2)
 257
 258 include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 259
 260 if (COMMAND __Python2_add_library)
 261   macro (Python2_add_library)
 262     __Python2_add_library (Python2 ${ARGV})
 263   endmacro()
 264 endif()
 265
 266 unset (_PYTHON_PREFIX)