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.
50 from functools
import lru_cache
51 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 build_ext
as _build_ext
70 from distutils.extension
import Extension
as _Extension
72 import distutils.ccompiler
73 import distutils.errors
75 WIN = sys.platform.startswith(
"win32")
and "mingw" not in sysconfig.get_platform()
76 MACOS = sys.platform.startswith(
"darwin")
77 STD_TMPL =
"/std:c++{}" if WIN
else "-std=c++{}"
89 Build a C++11+ Extension module with pybind11. This automatically adds the
90 recommended flags when you init the extension and assumes C++ sources - you
91 can further modify the options yourself.
93 The customizations are:
95 * ``/EHsc`` and ``/bigobj`` on Windows
96 * ``stdlib=libc++`` on macOS
97 * ``visibility=hidden`` and ``-g0`` on Unix
99 Finally, you can set ``cxx_std`` via constructor or afterwards to enable
100 flags for C++ std, and a few extra helper flags related to the C++ standard
101 level. It is _highly_ recommended you either set this, or use the provided
102 ``build_ext``, which will search for the highest supported extension for
103 you if the ``cxx_std`` property is not set. Do not set the ``cxx_std``
104 property more than once, as flags are added when you set it. Set the
105 property to None to disable the addition of C++ standard flags.
107 If you want to add pybind11 headers manually, for example for an exact
108 git checkout, then set ``include_pybind11=False``.
115 self.extra_compile_args[:0] = flags
118 self.extra_link_args[:0] = flags
120 def __init__(self, *args: Any, **kwargs: Any) ->
None:
122 cxx_std = kwargs.pop(
"cxx_std", 0)
124 if "language" not in kwargs:
125 kwargs[
"language"] =
"c++"
127 include_pybind11 = kwargs.pop(
"include_pybind11",
True)
137 pyinc = pybind11.get_include()
139 if pyinc
not in self.include_dirs:
140 self.include_dirs.append(pyinc)
141 except ModuleNotFoundError:
148 cflags += [
"/EHsc",
"/bigobj"]
150 cflags += [
"-fvisibility=hidden"]
151 env_cflags = os.environ.get(
"CFLAGS",
"")
152 env_cppflags = os.environ.get(
"CPPFLAGS",
"")
153 c_cpp_flags = shlex.split(env_cflags) + shlex.split(env_cppflags)
154 if not any(opt.startswith(
"-g")
for opt
in c_cpp_flags):
161 The CXX standard level. If set, will add the required flags. If left at
162 0, it will trigger an automatic search when pybind11's build_ext is
163 used. If None, will have no effect. Besides just the flags, this may
164 add a macos-min 10.9 or 10.14 flag if MACOSX_DEPLOYMENT_TARGET is
173 "You cannot safely change the cxx_level after setting it!", stacklevel=2
178 if WIN
and level == 11:
186 cflags = [STD_TMPL.format(level)]
189 if MACOS
and "MACOSX_DEPLOYMENT_TARGET" not in os.environ:
195 current_macos =
tuple(
int(x)
for x
in platform.mac_ver()[0].
split(
".")[:2])
196 desired_macos = (10, 9)
if level < 17
else (10, 14)
197 macos_string =
".".join(
str(x)
for x
in min(current_macos, desired_macos))
198 macosx_min = f
"-mmacosx-version-min={macos_string}"
199 cflags += [macosx_min]
200 ldflags += [macosx_min]
207 tmp_chdir_lock = threading.Lock()
210 @contextlib.contextmanager
212 "Prepare and enter a temporary directory, cleanup when done"
218 tmpdir = tempfile.mkdtemp()
223 shutil.rmtree(tmpdir)
229 Return the flag if a flag name is supported on the
230 specified compiler, otherwise None (can be used as a boolean).
231 If multiple flags are passed, return the first that matches.
235 fname = Path(
"flagcheck.cpp")
237 fname.write_text(
"int main (int, char **) { return 0; }", encoding=
"utf-8")
240 compiler.compile([
str(fname)], extra_postargs=[flag])
241 except distutils.errors.CompileError:
247 cpp_flag_cache =
None
253 Return the max supported C++ std level (17, 14, or 11). Returns latest on Windows.
259 levels = [17, 14, 11]
262 if has_flag(compiler, STD_TMPL.format(level)):
265 msg =
"Unsupported compiler -- at least C++11 support is needed!"
266 raise RuntimeError(msg)
271 Customized build_ext that allows an auto-search for the highest supported
272 C++ level for Pybind11Extension. This is only needed for the auto-search
273 for now, and is completely optional otherwise.
278 Build extensions, injecting C++ std for Pybind11Extension if needed.
281 for ext
in self.extensions:
282 if hasattr(ext,
"_cxx_level")
and ext._cxx_level == 0:
289 paths: Iterable[str], package_dir: Optional[Dict[str, str]] =
None
290 ) -> List[Pybind11Extension]:
292 Generate Pybind11Extensions from source files directly located in a Python
295 ``package_dir`` behaves as in ``setuptools.setup``. If unset, the Python
296 package root parent is determined as the first parent directory that does
297 not contain an ``__init__.py`` file.
301 if package_dir
is None:
303 parent, _ = os.path.split(path)
304 while os.path.exists(os.path.join(parent,
"__init__.py")):
305 parent, _ = os.path.split(parent)
306 relname, _ = os.path.splitext(os.path.relpath(path, parent))
307 qualified_name = relname.replace(os.path.sep,
".")
312 for prefix, parent
in package_dir.items():
313 if path.startswith(parent):
314 relname, _ = os.path.splitext(os.path.relpath(path, parent))
315 qualified_name = relname.replace(os.path.sep,
".")
317 qualified_name = prefix +
"." + qualified_name
322 f
"path {path} is not a child of any of the directories listed "
323 f
"in 'package_dir' ({package_dir})"
325 raise ValueError(msg)
332 This will recompile only if the source file changes. It does not check
333 header files, so a more advanced function or Ccache is better if you have
334 editable header files in your package.
336 return os.stat(obj).st_mtime < os.stat(src).st_mtime
341 This is the safest but slowest choice (and is the default) - will always
347 S = TypeVar(
"S", bound=
"ParallelCompile")
349 CCompilerMethod = Callable[
351 distutils.ccompiler.CCompiler,
354 Optional[Union[Tuple[str], Tuple[str, Optional[str]]]],
372 Make a parallel compile function. Inspired by
373 numpy.distutils.ccompiler.CCompiler.compile and cppimport.
375 This takes several arguments that allow you to customize the compile
379 Set an environment variable to control the compilation threads, like
382 0 will automatically multithread, or 1 will only multithread if the
385 The limit for automatic multithreading if non-zero
387 A function of (obj, src) that returns True when recompile is needed. No
388 effect in isolated mode; use ccache instead, see
389 https://github.com/matplotlib/matplotlib/issues/1507/
393 ParallelCompile("NPY_NUM_BUILD_JOBS").install()
397 with ParallelCompile("NPY_NUM_BUILD_JOBS"):
400 By default, this assumes all files need to be recompiled. A smarter
401 function can be provided via needs_recompile. If the output has not yet
402 been generated, the compile will always run, and this function is not
406 __slots__ = (
"envvar",
"default",
"max",
"_old",
"needs_recompile")
410 envvar: Optional[str] =
None,
413 needs_recompile: Callable[[str, str], bool] = no_recompile,
419 self._old: List[CCompilerMethod] = []
423 Builds a function object usable as distutils.ccompiler.CCompiler.compile.
426 def compile_function(
427 compiler: distutils.ccompiler.CCompiler,
429 output_dir: Optional[str] =
None,
430 macros: Optional[Union[Tuple[str], Tuple[str, Optional[str]]]] =
None,
431 include_dirs: Optional[List[str]] =
None,
433 extra_preargs: Optional[List[str]] =
None,
434 extra_postargs: Optional[List[str]] =
None,
435 depends: Optional[List[str]] =
None,
438 macros, objects, extra_postargs, pp_opts, build = compiler._setup_compile(
439 output_dir, macros, include_dirs, sources, depends, extra_postargs
441 cc_args = compiler._get_cc_args(pp_opts, debug, extra_preargs)
447 if self.
envvar is not None:
450 def _single_compile(obj: Any) ->
None:
452 src, ext = build[obj]
457 compiler._compile(obj, src, ext, cc_args, extra_postargs, pp_opts)
462 import multiprocessing.synchronize
463 from multiprocessing.pool
import ThreadPool
469 threads = multiprocessing.cpu_count()
470 threads = self.
max if self.
max and self.
max < threads
else threads
471 except NotImplementedError:
476 for _
in pool.imap_unordered(_single_compile, objects):
484 return compile_function
488 Installs the compile function into distutils.ccompiler.CCompiler.compile.
490 distutils.ccompiler.CCompiler.compile = self.
function()
494 self._old.append(distutils.ccompiler.CCompiler.compile)
498 distutils.ccompiler.CCompiler.compile = self._old.pop()