pybind11_add_module(): OPT_SIZE target
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 36381eb..461002e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -11,6 +11,12 @@
See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
+* ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that
+ switches the binding target to size-based optimization regardless global
+ CMake build type (except in debug mode, where optimizations remain disabled).
+ This reduces binary size quite substantially (~25%).
+ `#2463 <https://github.com/pybind/pybind11/pull/2463>`_
+
* Keyword-only argument supported in Python 2 or 3 with ``py::kw_only()``.
`#2100 <https://github.com/pybind/pybind11/pull/2100>`_
diff --git a/docs/compiling.rst b/docs/compiling.rst
index 72b0c1e..ca4dc75 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -62,7 +62,7 @@
.. code-block:: cmake
pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL]
- [NO_EXTRAS] [THIN_LTO] source1 [source2 ...])
+ [NO_EXTRAS] [THIN_LTO] [OPT_SIZE] source1 [source2 ...])
This function behaves very much like CMake's builtin ``add_library`` (in fact,
it's a wrapper function around that command). It will add a library target
@@ -96,6 +96,19 @@
``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` is set (either ON or OFF), then that
will be respected instead of the built-in flag search.
+The ``OPT_SIZE`` flag enables size-based optimization equivalent to the
+standard ``/Os`` or ``-Os`` compiler flags and the ``MinSizeRel`` build type,
+which avoid optimizations that that can substantially increase the size of the
+resulting binary. This flag is particularly useful in projects that are split
+into performance-critical parts and associated bindings. In this case, we can
+compile the project in release mode (and hence, optimize performance globally),
+and specify ``OPT_SIZE`` for the binding target, where size might be the main
+concern as performance is often less critical here. A ~25% size reduction has
+been observed in practice. This flag only changes the optimization behavior at
+a per-target level and takes precedence over the global CMake build type
+(``Release``, ``RelWithDebInfo``) except for ``Debug`` builds, where
+optimizations remain disabled.
+
.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html
Configuration variables
@@ -245,6 +258,9 @@
``pybind11::windows_extras``
``/bigobj`` and ``/mp`` for MSVC.
+ ``pybind11::opt_size``
+ ``/Os`` for MSVC, ``-Os`` for other compilers. Does nothing for debug builds.
+
Two helper functions are also provided:
``pybind11_strip(target)``