2 This module provides helpers for C++11+ projects using pybind11.
6 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions are met:
11 1. Redistributions of source code must retain the above copyright notice, this
12 list of conditions and the following disclaimer.
14 2. Redistributions in binary form must reproduce the above copyright notice,
15 this list of conditions and the following disclaimer in the documentation
16 and/or other materials provided with the distribution.
18 3. Neither the name of the copyright holder nor the names of its contributors
19 may be used to endorse or promote products derived from this software
20 without specific prior written permission.
22 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
23 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
24 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 from __future__
import annotations
51 from functools
import lru_cache
52 from pathlib
import Path
66 from setuptools
import Extension
as _Extension
67 from setuptools.command.build_ext
import build_ext
as _build_ext
69 from distutils.command.build_ext
import (
70 build_ext
as _build_ext,
72 from distutils.extension
import Extension
as _Extension
74 import distutils.ccompiler
75 import distutils.errors
77 WIN = sys.platform.startswith(
"win32")
and "mingw" not in sysconfig.get_platform()
78 MACOS = sys.platform.startswith(
"darwin")
79 STD_TMPL =
"/std:c++{}" if WIN
else "-std=c++{}"
91 Build a C++11+ Extension module with pybind11. This automatically adds the
92 recommended flags when you init the extension and assumes C++ sources - you
93 can further modify the options yourself.
95 The customizations are:
97 * ``/EHsc`` and ``/bigobj`` on Windows
98 * ``stdlib=libc++`` on macOS
99 * ``visibility=hidden`` and ``-g0`` on Unix
101 Finally, you can set ``cxx_std`` via constructor or afterwards to enable
102 flags for C++ std, and a few extra helper flags related to the C++ standard
103 level. It is _highly_ recommended you either set this, or use the provided
104 ``build_ext``, which will search for the highest supported extension for
105 you if the ``cxx_std`` property is not set. Do not set the ``cxx_std``
106 property more than once, as flags are added when you set it. Set the
107 property to None to disable the addition of C++ standard flags.
109 If you want to add pybind11 headers manually, for example for an exact
110 git checkout, then set ``include_pybind11=False``.
117 self.extra_compile_args[:0] = flags
120 self.extra_link_args[:0] = flags
122 def __init__(self, *args: Any, **kwargs: Any) ->
None:
124 cxx_std = kwargs.pop(
"cxx_std", 0)
126 if "language" not in kwargs:
127 kwargs[
"language"] =
"c++"
129 include_pybind11 = kwargs.pop(
"include_pybind11",
True)
139 pyinc = pybind11.get_include()
141 if pyinc
not in self.include_dirs:
142 self.include_dirs.append(pyinc)
143 except ModuleNotFoundError:
150 cflags += [
"/EHsc",
"/bigobj"]
152 cflags += [
"-fvisibility=hidden"]
153 env_cflags = os.environ.get(
"CFLAGS",
"")
154 env_cppflags = os.environ.get(
"CPPFLAGS",
"")
155 c_cpp_flags = shlex.split(env_cflags) + shlex.split(env_cppflags)
156 if not any(opt.startswith(
"-g")
for opt
in c_cpp_flags):
163 The CXX standard level. If set, will add the required flags. If left at
164 0, it will trigger an automatic search when pybind11's build_ext is
165 used. If None, will have no effect. Besides just the flags, this may
166 add a macos-min 10.9 or 10.14 flag if MACOSX_DEPLOYMENT_TARGET is
175 "You cannot safely change the cxx_level after setting it!", stacklevel=2
180 if WIN
and level == 11:
188 cflags = [STD_TMPL.format(level)]
191 if MACOS
and "MACOSX_DEPLOYMENT_TARGET" not in os.environ:
197 current_macos =
tuple(
int(x)
for x
in platform.mac_ver()[0].
split(
".")[:2])
198 desired_macos = (10, 9)
if level < 17
else (10, 14)
199 macos_string =
".".join(
str(x)
for x
in min(current_macos, desired_macos))
200 macosx_min = f
"-mmacosx-version-min={macos_string}"
201 cflags += [macosx_min]
202 ldflags += [macosx_min]
209 tmp_chdir_lock = threading.Lock()
212 @contextlib.contextmanager
214 "Prepare and enter a temporary directory, cleanup when done"
220 tmpdir = tempfile.mkdtemp()
225 shutil.rmtree(tmpdir)
231 Return the flag if a flag name is supported on the
232 specified compiler, otherwise None (can be used as a boolean).
233 If multiple flags are passed, return the first that matches.
237 fname = Path(
"flagcheck.cpp")
239 fname.write_text(
"int main (int, char **) { return 0; }", encoding=
"utf-8")
242 compiler.compile([
str(fname)], extra_postargs=[flag])
243 except distutils.errors.CompileError:
249 cpp_flag_cache =
None
255 Return the max supported C++ std level (17, 14, or 11). Returns latest on Windows.
261 levels = [17, 14, 11]
264 if has_flag(compiler, STD_TMPL.format(level)):
267 msg =
"Unsupported compiler -- at least C++11 support is needed!"
268 raise RuntimeError(msg)
273 Customized build_ext that allows an auto-search for the highest supported
274 C++ level for Pybind11Extension. This is only needed for the auto-search
275 for now, and is completely optional otherwise.
280 Build extensions, injecting C++ std for Pybind11Extension if needed.
283 for ext
in self.extensions:
284 if hasattr(ext,
"_cxx_level")
and ext._cxx_level == 0:
291 paths: Iterable[str], package_dir: dict[str, str] |
None =
None
292 ) -> list[Pybind11Extension]:
294 Generate Pybind11Extensions from source files directly located in a Python
297 ``package_dir`` behaves as in ``setuptools.setup``. If unset, the Python
298 package root parent is determined as the first parent directory that does
299 not contain an ``__init__.py`` file.
303 if package_dir
is None:
305 parent, _ = os.path.split(path)
306 while os.path.exists(os.path.join(parent,
"__init__.py")):
307 parent, _ = os.path.split(parent)
308 relname, _ = os.path.splitext(os.path.relpath(path, parent))
309 qualified_name = relname.replace(os.path.sep,
".")
314 for prefix, parent
in package_dir.items():
315 if path.startswith(parent):
316 relname, _ = os.path.splitext(os.path.relpath(path, parent))
317 qualified_name = relname.replace(os.path.sep,
".")
319 qualified_name = prefix +
"." + qualified_name
324 f
"path {path} is not a child of any of the directories listed "
325 f
"in 'package_dir' ({package_dir})"
327 raise ValueError(msg)
334 This will recompile only if the source file changes. It does not check
335 header files, so a more advanced function or Ccache is better if you have
336 editable header files in your package.
338 return os.stat(obj).st_mtime < os.stat(src).st_mtime
343 This is the safest but slowest choice (and is the default) - will always
349 S = TypeVar(
"S", bound=
"ParallelCompile")
351 CCompilerMethod = Callable[
353 distutils.ccompiler.CCompiler,
356 Optional[List[Union[Tuple[str], Tuple[str, Optional[str]]]]],
374 Make a parallel compile function. Inspired by
375 numpy.distutils.ccompiler.CCompiler.compile and cppimport.
377 This takes several arguments that allow you to customize the compile
381 Set an environment variable to control the compilation threads, like
384 0 will automatically multithread, or 1 will only multithread if the
387 The limit for automatic multithreading if non-zero
389 A function of (obj, src) that returns True when recompile is needed. No
390 effect in isolated mode; use ccache instead, see
391 https://github.com/matplotlib/matplotlib/issues/1507/
395 ParallelCompile("NPY_NUM_BUILD_JOBS").install()
399 with ParallelCompile("NPY_NUM_BUILD_JOBS"):
402 By default, this assumes all files need to be recompiled. A smarter
403 function can be provided via needs_recompile. If the output has not yet
404 been generated, the compile will always run, and this function is not
408 __slots__ = (
"envvar",
"default",
"max",
"_old",
"needs_recompile")
412 envvar: str |
None =
None,
415 needs_recompile: Callable[[str, str], bool] = no_recompile,
421 self._old: list[CCompilerMethod] = []
425 Builds a function object usable as distutils.ccompiler.CCompiler.compile.
428 def compile_function(
429 compiler: distutils.ccompiler.CCompiler,
431 output_dir: str |
None =
None,
432 macros: list[tuple[str] | tuple[str, str |
None]] |
None =
None,
433 include_dirs: list[str] |
None =
None,
435 extra_preargs: list[str] |
None =
None,
436 extra_postargs: list[str] |
None =
None,
437 depends: list[str] |
None =
None,
440 macros, objects, extra_postargs, pp_opts, build = compiler._setup_compile(
441 output_dir, macros, include_dirs, sources, depends, extra_postargs
443 cc_args = compiler._get_cc_args(pp_opts, debug, extra_preargs)
449 if self.
envvar is not None:
452 def _single_compile(obj: Any) ->
None:
454 src, ext = build[obj]
459 compiler._compile(obj, src, ext, cc_args, extra_postargs, pp_opts)
464 import multiprocessing.synchronize
465 from multiprocessing.pool
import ThreadPool
471 threads = multiprocessing.cpu_count()
472 threads = self.
max if self.
max and self.
max < threads
else threads
473 except NotImplementedError:
478 for _
in pool.imap_unordered(_single_compile, objects):
486 return compile_function
490 Installs the compile function into distutils.ccompiler.CCompiler.compile.
492 distutils.ccompiler.CCompiler.compile = self.
function()
496 self._old.append(distutils.ccompiler.CCompiler.compile)
500 distutils.ccompiler.CCompiler.compile = self._old.pop()