Split pybind11 into headers and cpp files to speedup compilation

TODO For now, only pybind11.h and options.h have been split. If maintainers
feel that this is going in the right direction, I will update this commit
to split all files.

As discussed at #2322, the split
is opt-in, and has been observed to speed up the compilation of the gem5
project by around 40% from 25 minutes to 15 minutes.

If the PYBIND11_DECLARATIONS_ONLY is not defined, then the .cpp files are
included in the .h files, and everything works header-only as was the case
before this commit.

If PYBIND11_DECLARATIONS_ONLY=1, then only declarations are made visible
from, the header files, and the user must the user must compile the
pybind11 .cpp files, also using PYBIND11_DECLARATIONS_ONLY=1, into objects
and add link those into the final link. This commit also updates CMakeLists
to automate building those object files.

This commit has been tested as follows.

First, the original build and pytest (without PYBIND11_DECLARATIONS_ONLY)
work as before:

mkdir build
cmake ..
make -j `nproc`
make pytest

TODO: if this commit gets traction, I will try to add a test for the
PYBIND11_DECLARATIONS_ONLY version too, otherwise it will likely break.
I'd just re-run the entire pybind with PYBIND11_DECLARATIONS_ONLY as well
every time.

The commit has also been tested with the following minimal manual example:

class_test.cpp

```

struct ClassTest {
    ClassTest(const std::string &name) : name(name) {}
    void setName(const std::string &name_) { name = name_; }
    const std::string &getName() const { return name; }
    std::string name;
};

struct ClassTestDerived : ClassTest {
    ClassTestDerived(const std::string &name, const std::string &name2) :
        ClassTest(name), name2(name2) {}
    std::string getName2() { return name + name2 + "2"; }
    std::string name2;
};

namespace py = pybind11;

PYBIND11_MODULE(class_test, m) {
    m.doc() = "pybind11 example plugin";
    py::class_<ClassTest>(m, "ClassTest")
        .def(py::init<const std::string &>())
        .def("setName", &ClassTest::setName)
        .def("getName", &ClassTest::getName)
        .def_readwrite("name", &ClassTest::name);
    py::class_<ClassTestDerived, ClassTest>(m, "ClassTestDerived")
        .def(py::init<const std::string &, const std::string &>())
        .def("getName2", &ClassTestDerived::getName2)
        .def_readwrite("name", &ClassTestDerived::name);
}
```

class_test_main.py

```

import class_test

my_class_test = class_test.ClassTest('abc');
assert(my_class_test.getName() == 'abc')
my_class_test.setName('012')
assert(my_class_test.name == '012')

my_class_test_derived = class_test.ClassTestDerived('abc', 'def');
assert(my_class_test_derived.getName2() == 'abcdef2')
```

without PYBIND11_DECLARATIONS_ONLY (`python3-config --cflags`) is opened up
and hacked to point to the custom pybind11 source:

```
g++ \
  -save-temps \
  -I/usr/include/python3.8 \
  -I/home/ciro/git/pybind11/include \
  -Wno-unused-result \
  -Wsign-compare \
  -g \
  -fdebug-prefix-map=/build/python3.8-fKk4GY/python3.8-3.8.2=. \
  -specs=/usr/share/dpkg/no-pie-compile.specs \
  -fstack-protector \
  -Wformat \
  -Werror=format-security  \
  -DNDEBUG \
  -g \
  -fwrapv \
  -O3 \
  -Wall \
  -shared \
  -std=c++11 \
  -fPIC class_test.cpp \
  -o class_test`python3-config --extension-suffix` \
  `python3-config --libs` \
;
./class_test_main.py
```

with PYBIND11_DECLARATIONS_ONLY:

```
g++ \
  -DPYBIND11_DECLARATIONS_ONLY=1 \
  -save-temps \
  -I/usr/include/python3.8 \
  -I/home/ciro/git/pybind11/include \
  -Wno-unused-result \
  -Wsign-compare \
  -g \
  -fdebug-prefix-map=/build/python3.8-fKk4GY/python3.8-3.8.2=. \
  -specs=/usr/share/dpkg/no-pie-compile.specs \
  -fstack-protector \
  -Wformat \
  -Werror=format-security  \
  -DNDEBUG \
  -g \
  -fwrapv \
  -O3 \
  -Wall \
  -shared \
  -std=c++11 \
  -fPIC class_test.cpp \
  /home/ciro/git/pybind11/build/libpybind11.a \
  -o class_test`python3-config --extension-suffix` \
  `python3-config --libs` \
;
./class_test_main.py
```

Author: cirosantilli2

CMakeLists.txt

@@ -269,3 +269,12 @@ if(NOT PYBIND11_MASTER_PROJECT)
       "${PYBIND11_INCLUDE_DIR}"
       CACHE INTERNAL "Directory where pybind11 headers are located")
 endif()
+
+find_package (Python3 COMPONENTS Development)
+include_directories(${Python3_INCLUDE_DIRS})
+add_definitions(-DPYBIND11_DECLARATIONS_ONLY=1)
+file(GLOB SOURCES ${CMAKE_SOURCE_DIR}/include/pybind11/*.cpp)
+# Produce libpybind11.a, which contains position independent object files.
+# that may be used to create a shared library.
+add_library(pybind11 STATIC ${SOURCES})
+set_property(TARGET pybind11 PROPERTY POSITION_INDEPENDENT_CODE ON)

include/pybind11/attr.h

@@ -119,7 +119,7 @@ enum op_id : int;
 enum op_type : int;
 struct undefined_t;
 template <op_id id, op_type ot, typename L = undefined_t, typename R = undefined_t> struct op_;
-inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret);
+void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret);
 
 /// Internal data structure which holds metadata about a keyword argument
 struct argument_record {

include/pybind11/cast.h

@@ -89,7 +89,7 @@ class loader_life_support {
 // Gets the cache entry for the given type, creating it if necessary.  The return value is the pair
 // returned by emplace, i.e. an iterator for the entry and a bool set to `true` if the entry was
 // just created.
-inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type);
+std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type);
 
 // Populates a just-created cache entry.
 PYBIND11_NOINLINE inline void all_type_info_populate(PyTypeObject *t, std::vector<type_info *> &bases) {
@@ -481,7 +481,7 @@ inline PyThreadState *get_thread_state_unchecked() {
 }
 
 // Forward declarations
-inline void keep_alive_impl(handle nurse, handle patient);
+void keep_alive_impl(handle nurse, handle patient);
 inline PyObject *make_new_instance(PyTypeObject *type);
 
 class type_caster_generic {

include/pybind11/detail/common.h

@@ -83,7 +83,27 @@
 #if defined(_MSC_VER)
 #  define PYBIND11_NOINLINE __declspec(noinline)
 #else
-#  define PYBIND11_NOINLINE __attribute__ ((noinline))
+#  if PYBIND11_DECLARATIONS_ONLY
+#    define PYBIND11_NOINLINE __attribute__ ((noinline))
+#  else
+// Otherwise GCC 9 would emit warnings for functions that are marked both
+// inline and noinline if we weren't enabling:
+// #pragma GCC diagnostic ignored "-Wattributes"
+// as is currently done in Pybind11. This way we remove reliance on this
+// disabled warning.
+#    define PYBIND11_NOINLINE
+#  endif
+#endif
+
+// Must be used in every .cpp function definition:
+// - on header-only mode, functions must be marked as inline
+//   to prevent multiple definitions
+// - on non-header-only mode, functions must not be marked as inline
+//   so that the symbols will be visible from other objects
+#if PYBIND11_DECLARATIONS_ONLY
+#  define PYBIND11_INLINE
+#else
+#  define PYBIND11_INLINE inline
 #endif
 
 #if defined(PYBIND11_CPP14)

include/pybind11/options.cpp

@@ -0,0 +1,23 @@
+#include "options.h"
+
+PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
+
+PYBIND11_INLINE options::options() : previous_state(global_state()) {}
+
+PYBIND11_INLINE options::~options() {
+    global_state() = previous_state;
+}
+
+PYBIND11_INLINE options& options::disable_user_defined_docstrings() & { global_state().show_user_defined_docstrings = false; return *this; }
+
+PYBIND11_INLINE options& options::enable_user_defined_docstrings() & { global_state().show_user_defined_docstrings = true; return *this; }
+
+PYBIND11_INLINE options& options::disable_function_signatures() & { global_state().show_function_signatures = false; return *this; }
+
+PYBIND11_INLINE options& options::enable_function_signatures() & { global_state().show_function_signatures = true; return *this; }
+
+PYBIND11_INLINE bool options::show_user_defined_docstrings() { return global_state().show_user_defined_docstrings; }
+
+PYBIND11_INLINE bool options::show_function_signatures() { return global_state().show_function_signatures; }
+
+PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)

include/pybind11/options.h

@@ -17,32 +17,30 @@ class options {
 public:
 
     // Default RAII constructor, which leaves settings as they currently are.
-    options() : previous_state(global_state()) {}
+    options();
 
     // Class is non-copyable.
     options(const options&) = delete;
     options& operator=(const options&) = delete;
 
     // Destructor, which restores settings that were in effect before.
-    ~options() {
-        global_state() = previous_state;
-    }
+    ~options();
 
     // Setter methods (affect the global state):
 
-    options& disable_user_defined_docstrings() & { global_state().show_user_defined_docstrings = false; return *this; }
+    options& disable_user_defined_docstrings() &;
 
-    options& enable_user_defined_docstrings() & { global_state().show_user_defined_docstrings = true; return *this; }
+    options& enable_user_defined_docstrings() &;
 
-    options& disable_function_signatures() & { global_state().show_function_signatures = false; return *this; }
+    options& disable_function_signatures() &;
 
-    options& enable_function_signatures() & { global_state().show_function_signatures = true; return *this; }
+    options& enable_function_signatures() &;
 
     // Getter methods (return the global state):
 
-    static bool show_user_defined_docstrings() { return global_state().show_user_defined_docstrings; }
+    static bool show_user_defined_docstrings();
 
-    static bool show_function_signatures() { return global_state().show_function_signatures; }
+    static bool show_function_signatures();
 
     // This type is not meant to be allocated on the heap.
     void* operator new(size_t) = delete;
@@ -63,3 +61,7 @@ class options {
 };
 
 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
+
+#if !PYBIND11_DECLARATIONS_ONLY
+#include "options.cpp"
+#endif