feat: setup.py redesign and helpers

Author: henryiii

.github/workflows/ci.yml

@@ -349,11 +349,13 @@ jobs:
     - name: Install system requirements
       run: apk add doxygen python3-dev
 
-    - name: Ensure pip
-      run: python3 -m ensurepip
+    - name: Ensure and upgrade pip
+      run: |
+        python3 -m ensurepip
+        python3 -m pip -U pip
 
     - name: Install docs & setup requirements
-      run: python3 -m pip install -r docs/requirements.txt pytest setuptools
+      run: python3 -m pip install -r docs/requirements.txt pytest setuptools cmake --prefer-binary
 
     - name: Build docs
       run: python3 -m sphinx -W -b html docs docs/.build

.github/workflows/format.yml

@@ -17,3 +17,5 @@ jobs:
     - uses: actions/checkout@v2
     - uses: actions/setup-python@v2
     - uses: pre-commit/action@v2.0.0
+      with:
+        extra_args: --hook-stage manual

.gitignore

@@ -39,3 +39,5 @@ pybind11Config*.cmake
 pybind11Targets.cmake
 /*env*
 /.vscode
+/pybind11/include/*
+/pybind11/share/*

.pre-commit-config.yaml

@@ -34,6 +34,13 @@ repos:
     types: [file]
     files: (\.cmake|CMakeLists.txt)(.in)?$
 
+- repo: https://github.com/mgedmin/check-manifest
+  rev: "0.42"
+  hooks:
+  - id: check-manifest
+    stages: [manual]
+    additional_dependencies: [cmake, ninja]
+
 - repo: local
   hooks:
   - id: check-style

MANIFEST.in

@@ -1,2 +1,7 @@
 recursive-include include/pybind11 *.h
-include LICENSE README.md .github/CONTRIBUTING.md
+recursive-include pybind11 *.h
+recursive-include pybind11 *.cmake
+recursive-include pybind11 *.py
+recursive-include tools *.cmake
+recursive-include tools *.in
+include CMakeLists.txt LICENSE README.md .github/CONTRIBUTING.md

docs/compiling.rst

@@ -13,6 +13,51 @@ the [python_example]_ repository.
 
 .. [python_example] https://github.com/pybind/python_example
 
+A helper file is provided with pybind11 that can simplify usage with setuptools
+if you have pybind11 installed as a Python package; the file is also standalone,
+if you want to copy it to your package. If use use PEP518's ``pyproject.toml``
+file:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools", "wheel", "pybind11==2.6.0"]
+    build-backend = "setuptools.build_meta"
+
+you can ensure that pybind11 is available during the building of your project
+(pip 10+ required).
+
+An example of a ``setup.py`` using pybind11's helpers:
+
+.. code-block:: python
+
+    from setuptools import setup, Extension
+    from pybind11.setup_helpers import BuildExt
+
+    ext_modules = [
+        Extension(
+            "python_example",
+            sorted(["src/main.cpp"]),
+            language="c++",
+        ),
+    ]
+
+    setup(
+        ...,
+        cmdclass={"build_ext": BuildExt},
+        ext_modules=ext_modules
+    )
+
+
+If you copy ``setup_helpers.py`` into your local project to try to support the
+classic build procedure, then you will need to use the deprecated
+``setup_requires=["pybind11>=2.6.0"]`` keyword argument to setup;
+``setup_helpers`` tries to support this as well.
+
+.. versionchanged:: 2.6
+
+    Added support file.
+
 Building with cppimport
 ========================
 

pybind11/__init__.py

@@ -1,13 +1,12 @@
 # -*- coding: utf-8 -*-
-from ._version import version_info, __version__  # noqa: F401 imported but unused
 
+from ._version import version_info, __version__
+from .commands import get_include, get_cmake_dir
 
-def get_include(user=False):
-    import os
-    d = os.path.dirname(__file__)
-    if os.path.exists(os.path.join(d, "include")):
-        # Package is installed
-        return os.path.join(d, "include")
-    else:
-        # Package is from a source directory
-        return os.path.join(os.path.dirname(d), "include")
+
+__all__ = (
+    "version_info",
+    "__version__",
+    "get_include",
+    "get_cmake_dir",
+)

pybind11/__main__.py

@@ -9,29 +9,34 @@
 
 
 def print_includes():
-    dirs = [sysconfig.get_path('include'),
-            sysconfig.get_path('platinclude'),
-            get_include()]
+    dirs = [
+        sysconfig.get_path("include"),
+        sysconfig.get_path("platinclude"),
+        get_include(),
+    ]
 
     # Make unique but preserve order
     unique_dirs = []
     for d in dirs:
         if d not in unique_dirs:
             unique_dirs.append(d)
 
-    print(' '.join('-I' + d for d in unique_dirs))
+    print(" ".join("-I" + d for d in unique_dirs))
 
 
 def main():
-    parser = argparse.ArgumentParser(prog='python -m pybind11')
-    parser.add_argument('--includes', action='store_true',
-                        help='Include flags for both pybind11 and Python headers.')
+    parser = argparse.ArgumentParser(prog="python -m pybind11")
+    parser.add_argument(
+        "--includes",
+        action="store_true",
+        help="Include flags for both pybind11 and Python headers.",
+    )
     args = parser.parse_args()
     if not sys.argv[1:]:
         parser.print_help()
     if args.includes:
         print_includes()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

pybind11/_version.py

@@ -1,3 +1,4 @@
 # -*- coding: utf-8 -*-
-version_info = (2, 5, 'dev1')
-__version__ = '.'.join(map(str, version_info))
+
+version_info = (2, 6, 0, "dev1")
+__version__ = ".".join(map(str, version_info))

pybind11/commands.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+import os
+
+
+DIR = os.path.abspath(os.path.dirname(__file__))
+
+
+def get_include(user=False):
+    installed_path = os.path.join(DIR, "include")
+    source_path = os.path.join(DIR, "include")
+    return installed_path if os.path.exists(installed_path) else source_path
+
+
+def get_cmake_dir():
+    cmake_installed_path = os.path.join(DIR, "share", "cmake", "pybind11")
+    if os.path.exists(cmake_installed_path):
+        return cmake_installed_path
+    else:
+        raise ImportError(
+            "pybind11 not installed, installation required to access the CMake files"
+        )

pybind11/setup_helpers.py

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+
+"""
+This module provides a way to check to see if flag is available,
+has_flag (built-in to distutils.CCompiler in Python 3.6+), and
+a cpp_flag function, which will compute the highest available
+flag (or if a flag is supported).
+
+LICENSE:
+
+Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import os
+import sys
+import tempfile
+
+import distutils.errors
+from distutils.command.build_ext import build_ext
+
+
+# It is recommended to use PEP 518 builds if using this module. However, this
+# file explicitly supports being copied into a user's project directory
+# standalone, and pulling pybind11 with the deprecated setup_requires feature.
+
+
+class DelayedPybindInclude(object):
+    """
+    Helper class to determine the pybind11 include path The purpose of this
+    class is to postpone importing pybind11 until it is actually installed, so
+    that the ``get_include()`` method can be invoked if pybind11 is loaded via
+    setup_requires.
+    """
+
+    def __str__(self):
+        import pybind11
+
+        return pybind11.get_include()
+
+
+# cf http://bugs.python.org/issue26689
+def has_flag(compiler, flagname):
+    """
+    Return a boolean indicating whether a flag name is supported on the
+    specified compiler.
+    """
+
+    with tempfile.NamedTemporaryFile("w", suffix=".cpp", delete=False) as f:
+        f.write("int main (int argc, char **argv) { return 0; }")
+        fname = f.name
+    try:
+        compiler.compile([fname], extra_postargs=[flagname])
+    except distutils.errors.CompileError:
+        return False
+    finally:
+        try:
+            os.remove(fname)
+        except OSError:
+            pass
+    return True
+
+
+def cpp_flag(compiler, value=None):
+    """
+    Return the ``-std=c++[11/14/17]`` compiler flag.
+    The newer version is preferred over c++11 (when it is available).
+    """
+
+    flags = ["-std=c++17", "-std=c++14", "-std=c++11"]
+
+    if value is not None:
+        mapping = {17: 0, 14: 1, 11: 2}
+        flags = [flags[mapping[value]]]
+
+    for flag in flags:
+        if has_flag(compiler, flag):
+            return flag
+
+    raise RuntimeError("Unsupported compiler -- at least C++11 support is needed!")
+
+
+c_opts = {
+    "msvc": ["/EHsc"],
+    "unix": [],
+}
+
+l_opts = {
+    "msvc": [],
+    "unix": [],
+}
+
+if sys.platform == "darwin":
+    darwin_opts = ["-stdlib=libc++", "-mmacosx-version-min=10.9"]
+    c_opts["unix"] += darwin_opts
+    l_opts["unix"] += darwin_opts
+
+
+class BuildExt(build_ext):
+    """
+    Customized build_ext that can be further customized by users.
+
+    Most use cases can be addressed by adding items to the extensions.
+    However, if you need to customize, try:
+
+        class BuildExt(pybind11.setup_utils.BuildExt):
+            def build_extensions(self):
+                # Do something here, like add things to extensions
+
+            super(BuildExt, self).build_extensions()
+
+    One simple customization point is provided: ``self.cxx_std`` lets
+    you set a C++ standard (None is the default search).
+    """
+
+    def __init__(self, *args, **kwargs):
+        super(BuildExt, self).__init__(*args, **kwargs)
+        self.cxx_std = None
+
+    def build_extensions(self):
+        ct = self.compiler.compiler_type
+        comp_opts = c_opts.get(ct, [])
+        link_opts = l_opts.get(ct, [])
+        if ct == "unix":
+            comp_opts.append(cpp_flag(self.compiler, self.cxx_std))
+            if has_flag(self.compiler, "-fvisibility=hidden"):
+                comp_opts.append("-fvisibility=hidden")
+
+        for ext in self.extensions:
+            ext.extra_compile_args += comp_opts
+            ext.extra_link_args += link_opts
+            ext.include_dirs += [DelayedPybindInclude()]
+
+        super(BuildExt, self).build_extensions()

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "cmake==3.18.0", "ninja"]
+build-backend = "setuptools.build_meta"