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
8Find Python 3 interpreter, compiler and development environment (include
9directories and libraries).
10
11Three components are supported:
12
13* ``Interpreter``: search for Python 3 interpreter
14* ``Compiler``: search for Python 3 compiler. Only offered by IronPython.
15* ``Development``: search for development artifacts (include directories and
16  libraries)
17* ``NumPy``: search for NumPy include directories.
18
19If no ``COMPONENTS`` is specified, ``Interpreter`` is assumed.
20
21To ensure consistent versions between components ``Interpreter``, ``Compiler``,
22``Development`` and ``NumPy``, specify all components at the same time::
23
24  find_package (Python3 COMPONENTS Interpreter Development)
25
26This module looks only for version 3 of Python. This module can be used
27concurrently with :module:`FindPython2` module to use both Python versions.
28
29The :module:`FindPython` module can be used if Python version does not matter
30for 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
39Imported Targets
40^^^^^^^^^^^^^^^^
41
42This module defines the following :ref:`Imported Targets <Imported Targets>`
43(when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):
44
45``Python3::Interpreter``
46  Python 3 interpreter. Target defined if component ``Interpreter`` is found.
47``Python3::Compiler``
48  Python 3 compiler. Target defined if component ``Compiler`` is found.
49``Python3::Python``
50  Python 3 library for Python embedding. Target defined if component
51  ``Development`` is found.
52``Python3::Module``
53  Python 3 library for Python module. Target defined if component
54  ``Development`` is found.
55``Python3::NumPy``
56  NumPy library for Python 3. Target defined if component ``NumPy`` is found.
57
58Result Variables
59^^^^^^^^^^^^^^^^
60
61This module will set the following variables in your project
62(see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
63
64``Python3_FOUND``
65  System has the Python 3 requested components.
66``Python3_Interpreter_FOUND``
67  System has the Python 3 interpreter.
68``Python3_EXECUTABLE``
69  Path to the Python 3 interpreter.
70``Python3_INTERPRETER_ID``
71  A short string unique to the interpreter. Possible values include:
72    * Python
73    * ActivePython
74    * Anaconda
75    * Canopy
76    * IronPython
77``Python3_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``Python3_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``Python3_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``Python3_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``Python3_Compiler_FOUND``
98  System has the Python 3 compiler.
99``Python3_COMPILER``
100  Path to the Python 3 compiler. Only offered by IronPython.
101``Python3_COMPILER_ID``
102  A short string unique to the compiler. Possible values include:
103    * IronPython
104``Python3_Development_FOUND``
105  System has the Python 3 development artifacts.
106``Python3_INCLUDE_DIRS``
107  The Python 3 include directories.
108``Python3_LIBRARIES``
109  The Python 3 libraries.
110``Python3_LIBRARY_DIRS``
111  The Python 3 library directories.
112``Python3_RUNTIME_LIBRARY_DIRS``
113  The Python 3 runtime library directories.
114``Python3_VERSION``
115  Python 3 version.
116``Python3_VERSION_MAJOR``
117  Python 3 major version.
118``Python3_VERSION_MINOR``
119  Python 3 minor version.
120``Python3_VERSION_PATCH``
121  Python 3 patch version.
122``Python3_NumPy_FOUND``
123  System has the NumPy.
124``Python3_NumPy_INCLUDE_DIRS``
125  The NumPy include directries.
126``Python3_NumPy_VERSION``
127  The NumPy version.
128
129Hints
130^^^^^
131
132``Python3_ROOT_DIR``
133  Define the root directory of a Python 3 installation.
134
135``Python3_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``Python3_FIND_STRATEGY``
142  This variable defines how lookup will be done.
143  The ``Python3_FIND_STRATEGY`` variable can be set to empty or one of the
144  following:
145
146  * ``VERSION``: Try to find the most recent version in all specified
147    locations.
148    This is the default if policy :policy:`CMP0094` is undefined or set to
149    ``OLD``.
150  * ``LOCATION``: Stops lookup as soon as a version satisfying version
151    constraints is founded.
152    This is the default if policy :policy:`CMP0094` is set to ``NEW``.
153
154``Python3_FIND_REGISTRY``
155  On Windows the ``Python3_FIND_REGISTRY`` variable determine the order
156  of preference between registry and environment variables.
157  The ``Python3_FIND_REGISTRY`` variable can be set to empty or one of the
158  following:
159
160  * ``FIRST``: Try to use registry before environment variables.
161    This is the default.
162  * ``LAST``: Try to use registry after environment variables.
163  * ``NEVER``: Never try to use registry.
164
165``Python3_FIND_FRAMEWORK``
166  On macOS the ``Python3_FIND_FRAMEWORK`` variable determine the order of
167  preference between Apple-style and unix-style package components.
168  This variable can be set to empty or take same values as
169  :variable:`CMAKE_FIND_FRAMEWORK` variable.
170
171  .. note::
172
173    Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
174
175  If ``Python3_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
176  variable will be used, if any.
177
178``Python3_FIND_VIRTUALENV``
179  This variable defines the handling of virtual environments. It is meaningfull
180  only when a virtual environment is active (i.e. the ``activate`` script has
181  been evaluated). In this case, it takes precedence over
182  ``Python3_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
183  The ``Python3_FIND_VIRTUALENV`` variable can be set to empty or one of the
184  following:
185
186  * ``FIRST``: The virtual environment is used before any other standard
187    paths to look-up for the interpreter. This is the default.
188  * ``ONLY``: Only the virtual environment is used to look-up for the
189    interpreter.
190  * ``STANDARD``: The virtual environment is not used to look-up for the
191    interpreter. In this case, variable ``Python3_FIND_REGISTRY`` (Windows)
192    or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
193    ``NEVER`` to select preferably the interpreter from the virtual
194    environment.
195
196Commands
197^^^^^^^^
198
199This module defines the command ``Python_add_library`` (when
200:prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
201:command:`add_library` and adds a dependency to target ``Python3::Python`` or,
202when library type is ``MODULE``, to target ``Python3::Module`` and takes care
203of Python module naming rules::
204
205  Python3_add_library (my_module MODULE src1.cpp)
206
207If library type is not specified, ``MODULE`` is assumed.
208#]=======================================================================]
209
210
211set (_PYTHON_PREFIX Python3)
212
213set (_Python3_REQUIRED_VERSION_MAJOR 3)
214
215include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
216
217if (COMMAND __Python3_add_library)
218  macro (Python3_add_library)
219    __Python3_add_library (Python3 ${ARGV})
220  endmacro()
221endif()
222
223unset (_PYTHON_PREFIX)
224