From 3879045fb7961c927a8de2e3c55b0c3fe9a3a16a Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Thu, 10 Aug 2017 12:03:29 -0400
Subject: [PATCH 1/6] Force hidden visibility on pybind code

This adds a PYBIND11_NAMESPACE macro that expands to the `pybind11`
namespace with hidden visibility under gcc-type compilers, and otherwise
to the plain `pybind11`.  This then forces hidden visibility on
everything in pybind, solving the visibility issues discussed at end
end of #949.
---
 include/pybind11/attr.h          |  4 ++--
 include/pybind11/buffer_info.h   |  4 ++--
 include/pybind11/cast.h          |  4 ++--
 include/pybind11/chrono.h        |  4 ++--
 include/pybind11/class_support.h |  4 ++--
 include/pybind11/common.h        | 15 +++++++++++++--
 include/pybind11/complex.h       |  4 ++--
 include/pybind11/descr.h         |  4 ++--
 include/pybind11/eigen.h         |  4 ++--
 include/pybind11/embed.h         |  4 ++--
 include/pybind11/eval.h          |  4 ++--
 include/pybind11/functional.h    |  4 ++--
 include/pybind11/numpy.h         |  4 ++--
 include/pybind11/operators.h     |  4 ++--
 include/pybind11/options.h       |  4 ++--
 include/pybind11/pybind11.h      |  4 ++--
 include/pybind11/pytypes.h       |  4 ++--
 include/pybind11/stl.h           |  4 ++--
 include/pybind11/stl_bind.h      |  4 ++--
 include/pybind11/typeid.h        |  4 ++--
 20 files changed, 51 insertions(+), 40 deletions(-)

diff --git a/include/pybind11/attr.h b/include/pybind11/attr.h
index 44a33458da..54760cdbc9 100644
--- a/include/pybind11/attr.h
+++ b/include/pybind11/attr.h
@@ -12,7 +12,7 @@
 
 #include "cast.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 /// \addtogroup annotations
 /// @{
@@ -478,4 +478,4 @@ constexpr bool expected_num_args(size_t nargs, bool has_args, bool has_kwargs) {
 }
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/buffer_info.h b/include/pybind11/buffer_info.h
index 6d1167d212..1f5e3a9531 100644
--- a/include/pybind11/buffer_info.h
+++ b/include/pybind11/buffer_info.h
@@ -11,7 +11,7 @@
 
 #include "common.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 /// Information record describing a Python buffer object
 struct buffer_info {
@@ -105,4 +105,4 @@ template <typename T> struct compare_buffer_info<T, detail::enable_if_t<std::is_
 };
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/cast.h b/include/pybind11/cast.h
index cfd565e59f..41e65cc8b9 100644
--- a/include/pybind11/cast.h
+++ b/include/pybind11/cast.h
@@ -30,7 +30,7 @@
 #include <string_view>
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 // Forward declarations:
 inline PyTypeObject *make_static_property_type();
@@ -2084,4 +2084,4 @@ NAMESPACE_END(detail)
         template<> class type_caster<Type> : public type_caster_base<Type> { }; \
     }}
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/chrono.h b/include/pybind11/chrono.h
index 8a41d08b0c..95ada76e0f 100644
--- a/include/pybind11/chrono.h
+++ b/include/pybind11/chrono.h
@@ -27,7 +27,7 @@
 #define PyDateTime_DELTA_GET_MICROSECONDS(o) (((PyDateTime_Delta*)o)->microseconds)
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 template <typename type> class duration_caster {
@@ -159,4 +159,4 @@ template <typename Rep, typename Period> class type_caster<std::chrono::duration
 };
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/class_support.h b/include/pybind11/class_support.h
index 287412d956..d006a1e5cc 100644
--- a/include/pybind11/class_support.h
+++ b/include/pybind11/class_support.h
@@ -11,7 +11,7 @@
 
 #include "attr.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 inline PyTypeObject *type_incref(PyTypeObject *type) {
@@ -599,4 +599,4 @@ inline PyObject* make_new_python_type(const type_record &rec) {
 }
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/common.h b/include/pybind11/common.h
index dc50b7cfb4..e83a64759f 100644
--- a/include/pybind11/common.h
+++ b/include/pybind11/common.h
@@ -16,6 +16,17 @@
 #  define NAMESPACE_END(name) }
 #endif
 
+// Robust support for some features and loading modules compiled against different pybind versions
+// requires forcing hidden visibility on pybind code, so we enforce this by setting the attribute on
+// the main `pybind11` namespace.
+#if !defined(PYBIND11_NAMESPACE)
+#  ifdef __GNUG__
+#    define PYBIND11_NAMESPACE pybind11 __attribute__((visibility("hidden")))
+#  else
+#    define PYBIND11_NAMESPACE pybind11
+#  endif
+#endif
+
 #if !defined(_MSC_VER) && !defined(__INTEL_COMPILER)
 #  if __cplusplus >= 201402L
 #    define PYBIND11_CPP14
@@ -297,7 +308,7 @@ extern "C" {
     void pybind11_init_##name(pybind11::module &variable)
 
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 using ssize_t = Py_ssize_t;
 using size_t  = std::size_t;
@@ -877,4 +888,4 @@ NAMESPACE_END(detail)
 
 
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/complex.h b/include/pybind11/complex.h
index 7d422e2094..5dac27cc4e 100644
--- a/include/pybind11/complex.h
+++ b/include/pybind11/complex.h
@@ -17,7 +17,7 @@
 #  undef I
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 template <typename T> struct format_descriptor<std::complex<T>, detail::enable_if_t<std::is_floating_point<T>::value>> {
     static constexpr const char c = format_descriptor<T>::c;
@@ -58,4 +58,4 @@ template <typename T> class type_caster<std::complex<T>> {
     PYBIND11_TYPE_CASTER(std::complex<T>, _("complex"));
 };
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/descr.h b/include/pybind11/descr.h
index 23a099cfb6..f6c0a68385 100644
--- a/include/pybind11/descr.h
+++ b/include/pybind11/descr.h
@@ -12,7 +12,7 @@
 
 #include "common.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 /* Concatenate type signatures at compile time using C++14 */
@@ -182,4 +182,4 @@ PYBIND11_NOINLINE inline descr type_descr(descr&& d) { return _("{") + std::move
 #endif
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/eigen.h b/include/pybind11/eigen.h
index fc0705167f..a702bf39eb 100644
--- a/include/pybind11/eigen.h
+++ b/include/pybind11/eigen.h
@@ -35,7 +35,7 @@
 // of matrices seems highly undesirable.
 static_assert(EIGEN_VERSION_AT_LEAST(3,2,7), "Eigen support in pybind11 requires Eigen >= 3.2.7");
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 // Provide a convenience alias for easier pass-by-ref usage with fully dynamic strides:
 using EigenDStride = Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic>;
@@ -601,7 +601,7 @@ struct type_caster<Type, enable_if_t<is_eigen_sparse<Type>::value>> {
 };
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
 
 #if defined(__GNUG__) || defined(__clang__)
 #  pragma GCC diagnostic pop
diff --git a/include/pybind11/embed.h b/include/pybind11/embed.h
index 98bf7690ce..79ad0209c4 100644
--- a/include/pybind11/embed.h
+++ b/include/pybind11/embed.h
@@ -63,7 +63,7 @@
     void pybind11_init_##name(pybind11::module &variable)
 
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 /// Python 2.7/3.x compatible version of `PyImport_AppendInittab` and error checks.
@@ -190,4 +190,4 @@ class scoped_interpreter {
     bool is_valid = true;
 };
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/eval.h b/include/pybind11/eval.h
index 165003b85e..ea85ba1dbe 100644
--- a/include/pybind11/eval.h
+++ b/include/pybind11/eval.h
@@ -13,7 +13,7 @@
 
 #include "pybind11.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 enum eval_mode {
     /// Evaluate a string containing an isolated expression
@@ -114,4 +114,4 @@ object eval_file(str fname, object global = globals(), object local = object())
     return reinterpret_steal<object>(result);
 }
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/functional.h b/include/pybind11/functional.h
index fdb6b330c9..eda14ba583 100644
--- a/include/pybind11/functional.h
+++ b/include/pybind11/functional.h
@@ -12,7 +12,7 @@
 #include "pybind11.h"
 #include <functional>
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 template <typename Return, typename... Args>
@@ -82,4 +82,4 @@ struct type_caster<std::function<Return(Args...)>> {
 };
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/numpy.h b/include/pybind11/numpy.h
index 388e21229e..bb8546cb51 100644
--- a/include/pybind11/numpy.h
+++ b/include/pybind11/numpy.h
@@ -34,7 +34,7 @@
    upon the library user. */
 static_assert(sizeof(ssize_t) == sizeof(Py_intptr_t), "ssize_t != Py_intptr_t");
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 class array; // Forward declaration
 
@@ -1591,7 +1591,7 @@ Helper vectorize(Return (Class::*f)(Args...) const) {
     return Helper(std::mem_fn(f));
 }
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
 
 #if defined(_MSC_VER)
 #pragma warning(pop)
diff --git a/include/pybind11/operators.h b/include/pybind11/operators.h
index 562987b864..11ea24850c 100644
--- a/include/pybind11/operators.h
+++ b/include/pybind11/operators.h
@@ -18,7 +18,7 @@
 #  pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 /// Enumeration with all supported operator types
@@ -160,7 +160,7 @@ NAMESPACE_END(detail)
 
 using detail::self;
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
 
 #if defined(_MSC_VER)
 #  pragma warning(pop)
diff --git a/include/pybind11/options.h b/include/pybind11/options.h
index 3105551ddd..531ec8a81b 100644
--- a/include/pybind11/options.h
+++ b/include/pybind11/options.h
@@ -11,7 +11,7 @@
 
 #include "common.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 class options {
 public:
@@ -62,4 +62,4 @@ class options {
     state previous_state;
 };
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h
index 2e69701656..01c02dc4d1 100644
--- a/include/pybind11/pybind11.h
+++ b/include/pybind11/pybind11.h
@@ -44,7 +44,7 @@
 #include "options.h"
 #include "class_support.h"
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 /// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
 class cpp_function : public function {
@@ -1862,7 +1862,7 @@ template <class T> function get_overload(const T *this_ptr, const char *name) {
 #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
     PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, #fn, fn, __VA_ARGS__)
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
 
 #if defined(_MSC_VER)
 #  pragma warning(pop)
diff --git a/include/pybind11/pytypes.h b/include/pybind11/pytypes.h
index b652b8e992..ba30e84ee4 100644
--- a/include/pybind11/pytypes.h
+++ b/include/pybind11/pytypes.h
@@ -14,7 +14,7 @@
 #include <utility>
 #include <type_traits>
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
 /* A few forward declarations */
 class handle; class object;
@@ -1320,4 +1320,4 @@ template <typename D>
 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }
 
 NAMESPACE_END(detail)
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/stl.h b/include/pybind11/stl.h
index c8c9e90606..ac212bfe23 100644
--- a/include/pybind11/stl.h
+++ b/include/pybind11/stl.h
@@ -46,7 +46,7 @@
 #  define PYBIND11_HAS_VARIANT 1
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 /// Extracts an const lvalue reference or rvalue reference for U based on the type of T (e.g. for
@@ -362,7 +362,7 @@ inline std::ostream &operator<<(std::ostream &os, const handle &obj) {
     return os;
 }
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
 
 #if defined(_MSC_VER)
 #pragma warning(pop)
diff --git a/include/pybind11/stl_bind.h b/include/pybind11/stl_bind.h
index 6263f9926c..d9f5b56d6a 100644
--- a/include/pybind11/stl_bind.h
+++ b/include/pybind11/stl_bind.h
@@ -15,7 +15,7 @@
 #include <algorithm>
 #include <sstream>
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
 /* SFINAE helper class used by 'is_comparable */
@@ -598,4 +598,4 @@ class_<Map, holder_type> bind_map(handle scope, const std::string &name, Args&&.
     return cl;
 }
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/typeid.h b/include/pybind11/typeid.h
index c903fb14cb..9d3ddcd533 100644
--- a/include/pybind11/typeid.h
+++ b/include/pybind11/typeid.h
@@ -16,7 +16,7 @@
 #include <cxxabi.h>
 #endif
 
-NAMESPACE_BEGIN(pybind11)
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 /// Erase all occurrences of a substring
 inline void erase_all(std::string &string, const std::string &search) {
@@ -50,4 +50,4 @@ template <typename T> static std::string type_id() {
     return name;
 }
 
-NAMESPACE_END(pybind11)
+NAMESPACE_END(PYBIND11_NAMESPACE)

From 88ae0c119077a113e9ee5e7215ce0d56a3df699a Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Thu, 10 Aug 2017 12:08:42 -0400
Subject: [PATCH 2/6] Use hidden visibility always; set via cmake property
 rather than compiler flag

This should resolve the issues with default visibility causing problems
under debug compilations.  Moreover using the cmake property makes it
easier for a caller to override if absolutely needed for some reason.
---
 tools/pybind11Tools.cmake | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/tools/pybind11Tools.cmake b/tools/pybind11Tools.cmake
index 86ccd58d3b..63752ead17 100644
--- a/tools/pybind11Tools.cmake
+++ b/tools/pybind11Tools.cmake
@@ -139,6 +139,13 @@ function(pybind11_add_module target_name)
   set_target_properties(${target_name} PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}")
   set_target_properties(${target_name} PROPERTIES SUFFIX "${PYTHON_MODULE_EXTENSION}")
 
+  # -fvisibility=hidden is required to allow multiple modules compiled against
+  # different pybind versions to work properly, and for some features (e.g.
+  # py::module_local).  We force it on everything inside the `pybind11`
+  # namespace; also turning it on for a pybind module compilation here avoids
+  # potential warnings or issues from having mixed hidden/non-hidden types.
+  set_target_properties(${target_name} PROPERTIES CXX_VISIBILITY_PRESET "hidden")
+
   if(WIN32 OR CYGWIN)
     # Link against the Python shared library on Windows
     target_link_libraries(${target_name} PRIVATE ${PYTHON_LIBRARIES})
@@ -175,9 +182,6 @@ function(pybind11_add_module target_name)
   _pybind11_add_lto_flags(${target_name} ${ARG_THIN_LTO})
 
   if (NOT MSVC AND NOT ${CMAKE_BUILD_TYPE} MATCHES Debug)
-    # Set the default symbol visibility to hidden (very important to obtain small binaries)
-    target_compile_options(${target_name} PRIVATE "-fvisibility=hidden")
-
     # Strip unnecessary sections of the binary on Linux/Mac OS
     if(CMAKE_STRIP)
       if(APPLE)

From 368fb7f4398fe2bf3dbd3f3577ce102c8821a0c8 Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Thu, 10 Aug 2017 12:27:33 -0400
Subject: [PATCH 3/6] Update docs to reflect forced hidden visibility

---
 docs/advanced/misc.rst | 20 +++++++-------------
 docs/compiling.rst     | 21 +++++++++++----------
 2 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
index 8751faf671..0c80c50f96 100644
--- a/docs/advanced/misc.rst
+++ b/docs/advanced/misc.rst
@@ -135,22 +135,16 @@ has been executed:
 
 Naturally, both methods will fail when there are cyclic dependencies.
 
-Note that compiling code which has its default symbol visibility set to
-*hidden* (e.g. via the command line flag ``-fvisibility=hidden`` on GCC/Clang) can interfere with the
-ability to access types defined in another extension module. Workarounds
-include changing the global symbol visibility (not recommended, because it will
-lead unnecessarily large binaries) or manually exporting types that are
-accessed by multiple extension modules:
+Note that pybind11 code compiled with hidden-by-default symbol visibility (e.g.
+via the command line flag ``-fvisibility=hidden`` on GCC/Clang), which is
+strongly recommended for pybind11 modules, can interfere with the ability to
+access types defined in another extension module.  Working around this requires
+manually export types that are accessed by multiple extension modules; pybind11
+provides a macro to do just this:
 
 .. code-block:: cpp
 
-    #ifdef _WIN32
-    #  define EXPORT_TYPE __declspec(dllexport)
-    #else
-    #  define EXPORT_TYPE __attribute__ ((visibility("default")))
-    #endif
-
-    class EXPORT_TYPE Dog : public Animal {
+    class PYBIND11_EXPORT Dog : public Animal {
         ...
     };
 
diff --git a/docs/compiling.rst b/docs/compiling.rst
index 91e65df3db..371f231668 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -74,13 +74,15 @@ removes this target from the default build (see CMake docs for details).
 
 Since pybind11 is a template library, ``pybind11_add_module`` adds compiler
 flags to ensure high quality code generation without bloat arising from long
-symbol names and duplication of code in different translation units. The
-additional flags enable LTO (Link Time Optimization), set default visibility
-to *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>`
-for a more detailed explanation. These optimizations are never applied in
-``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even
-in ``Release`` mode. However, this will result in code bloat and is generally
-not recommended.
+symbol names and duplication of code in different translation units. It
+sets default visibility to *hidden*, which is required for some pybind11
+features and functionality when attempting to load multiple pybind11 modules
+compiled under different pybind11 versions.  It also adds additional flags
+enabling LTO (Link Time Optimization) and strip unneeded symbols. See the
+:ref:`FAQ entry <faq:symhidden>` for a more detailed explanation. These
+latter optimizations are never applied in ``Debug`` mode.  If ``NO_EXTRAS`` is
+given, they will always be disabled, even in ``Release`` mode. However, this
+will result in code bloat and is generally not recommended.
 
 As stated above, LTO is enabled by default. Some newer compilers also support
 different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause
@@ -181,9 +183,8 @@ to an independently constructed (through ``add_library``, not
     flags (i.e. this is up to you).
 
     These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
-    and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
-    (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
-    (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
+    and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual
+    Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
     explanation on why these are needed.
 
 Embedding the Python interpreter

From 17c332d3595dfbb8448eb6cdfd6f15cb31dce663 Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Sat, 12 Aug 2017 22:58:49 -0400
Subject: [PATCH 4/6] Add -fvisibility=hidden to interface targets

---
 CMakeLists.txt                | 3 +++
 tools/pybind11Config.cmake.in | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 51a17d9aa5..6d1d964b43 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -91,6 +91,9 @@ if(NOT (CMAKE_VERSION VERSION_LESS 3.0))  # CMake >= 3.0
                                                 $<BUILD_INTERFACE:${PYTHON_INCLUDE_DIRS}>
                                                 $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
   target_compile_options(pybind11 INTERFACE $<BUILD_INTERFACE:${PYBIND11_CPP_STANDARD}>)
+  if(NOT MSVC)
+    target_compile_options(pybind11 INTERFACE $<BUILD_INTERFACE:-fvisibility=hidden>)
+  endif()
 
   add_library(module INTERFACE)
   add_library(pybind11::module ALIAS module)
diff --git a/tools/pybind11Config.cmake.in b/tools/pybind11Config.cmake.in
index 3dd1b2c1ab..4ea7a9cf07 100644
--- a/tools/pybind11Config.cmake.in
+++ b/tools/pybind11Config.cmake.in
@@ -91,6 +91,9 @@ if(NOT TARGET ${PN}::pybind11)
     endif()
 
     set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_COMPILE_OPTIONS "${PYBIND11_CPP_STANDARD}")
+    if(NOT MSVC)
+      set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_COMPILE_OPTIONS "-fvisibility=hidden")
+    endif()
 
     get_property(_iid TARGET ${PN}::pybind11 PROPERTY INTERFACE_INCLUDE_DIRECTORIES)
     get_property(_ill TARGET ${PN}::module PROPERTY INTERFACE_LINK_LIBRARIES)

From 8b9c6c509d0817df193df08e083d7becd7a140d8 Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Sat, 12 Aug 2017 23:04:20 -0400
Subject: [PATCH 5/6] Update docs wrt hidden visibility

---
 docs/advanced/misc.rst |  6 +++---
 docs/compiling.rst     |  2 +-
 docs/faq.rst           | 40 +++++++++++++++++++++++++++++++++++-----
 3 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
index 0c80c50f96..6d8cfc9b8b 100644
--- a/docs/advanced/misc.rst
+++ b/docs/advanced/misc.rst
@@ -137,10 +137,10 @@ Naturally, both methods will fail when there are cyclic dependencies.
 
 Note that pybind11 code compiled with hidden-by-default symbol visibility (e.g.
 via the command line flag ``-fvisibility=hidden`` on GCC/Clang), which is
-strongly recommended for pybind11 modules, can interfere with the ability to
+required proper pybind11 functionality, can interfere with the ability to
 access types defined in another extension module.  Working around this requires
-manually export types that are accessed by multiple extension modules; pybind11
-provides a macro to do just this:
+manually exporting types that are accessed by multiple extension modules;
+pybind11 provides a macro to do just this:
 
 .. code-block:: cpp
 
diff --git a/docs/compiling.rst b/docs/compiling.rst
index 371f231668..90b3829523 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -184,7 +184,7 @@ to an independently constructed (through ``add_library``, not
 
     These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
     and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual
-    Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
+    Studio (``/bigobj``).  The :ref:`FAQ <faq:symhidden>` contains an
     explanation on why these are needed.
 
 Embedding the Python interpreter
diff --git a/docs/faq.rst b/docs/faq.rst
index 072b157292..8f33eb014a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -151,6 +151,33 @@ specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The
 culprit is generally the generation of function signatures at compile time
 using C++14 template metaprogramming.
 
+.. _`faq:hidden_visibility`:
+
+"‘SomeClass’ declared with greater visibility than the type of its field ‘SomeClass::member’ [-Wattributes]"
+============================================================================================================
+
+This error typically indicates that you are compiling without the required
+``-fvisibility`` flag.  pybind11 code internally forces hidden visibility on
+all internal code, but if non-hidden (and thus *exported*) code attempts to
+include a pybind type (for example, ``py::object`` or ``py::list``) you can run
+into this warning.
+
+To avoid it, make sure you are specifying ``-fvisibility=hidden`` when
+compiling pybind code.
+
+As to why ``-fvisibility=hidden`` is necessary, because pybind modules could
+have been compiled under different versions of pybind itself, it is also
+important that the symbols defined in one module do not clash with the
+potentially-incompatible symbols defined in another.  While Python extension
+modules are usually loaded with localized symbols (under POSIX systems
+typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default
+can be changed, but even if it isn't it is not always enough to guarantee
+complete independence of the symbols involved when not using
+``-fvisibility=hidden``.
+
+Additionally, ``-fvisiblity=hidden`` can deliver considerably binary size
+savings.  (See the following section for more details).
+
 
 .. _`faq:symhidden`:
 
@@ -192,11 +219,14 @@ world. So we'll generally only want to export symbols for those functions which
 are actually called from the outside.
 
 This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
-and Clang, which sets the default symbol visibility to *hidden*. It's best to
-do this only for release builds, since the symbol names can be helpful in
-debugging sessions. On Visual Studio, symbols are already hidden by default, so
-nothing needs to be done there. Needless to say, this has a tremendous impact
-on the final binary size of the resulting extension library.
+and Clang, which sets the default symbol visibility to *hidden*, which has a
+tremendous impact on the final binary size of the resulting extension library.
+(On Visual Studio, symbols are already hidden by default, so nothing needs to
+be done there.)
+
+In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids
+potential serious issues when loading multiple modules and is required for
+proper pybind operation.  See the previous FAQ entry for more details.
 
 Another aspect that can require a fair bit of code are function signature
 descriptions. pybind11 automatically generates human-readable function

From 22eae8a38529c8dc36dd93b7cb2c0af9b1bb18c7 Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Sun, 13 Aug 2017 10:43:56 -0400
Subject: [PATCH 6/6] Remove visibility=hidden build/install separation

---
 CMakeLists.txt                | 2 +-
 tools/pybind11Config.cmake.in | 3 ---
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6d1d964b43..842b59fbe9 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -92,7 +92,7 @@ if(NOT (CMAKE_VERSION VERSION_LESS 3.0))  # CMake >= 3.0
                                                 $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
   target_compile_options(pybind11 INTERFACE $<BUILD_INTERFACE:${PYBIND11_CPP_STANDARD}>)
   if(NOT MSVC)
-    target_compile_options(pybind11 INTERFACE $<BUILD_INTERFACE:-fvisibility=hidden>)
+    target_compile_options(pybind11 INTERFACE -fvisibility=hidden)
   endif()
 
   add_library(module INTERFACE)
diff --git a/tools/pybind11Config.cmake.in b/tools/pybind11Config.cmake.in
index 4ea7a9cf07..3dd1b2c1ab 100644
--- a/tools/pybind11Config.cmake.in
+++ b/tools/pybind11Config.cmake.in
@@ -91,9 +91,6 @@ if(NOT TARGET ${PN}::pybind11)
     endif()
 
     set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_COMPILE_OPTIONS "${PYBIND11_CPP_STANDARD}")
-    if(NOT MSVC)
-      set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_COMPILE_OPTIONS "-fvisibility=hidden")
-    endif()
 
     get_property(_iid TARGET ${PN}::pybind11 PROPERTY INTERFACE_INCLUDE_DIRECTORIES)
     get_property(_ill TARGET ${PN}::module PROPERTY INTERFACE_LINK_LIBRARIES)