make bolder docs warning about recc flags not in cmake interface lib. fix up gitignore for add_subdir build.

Author: loriab

.gitignore

@@ -33,4 +33,5 @@ MANIFEST
 /cmake/
 .cache/
 sosize-*.txt
-share/cmake/pybind11/pybind11*cmake
+pybind11Config*.cmake
+pybind11Targets.cmake

docs/compiling.rst

@@ -84,11 +84,7 @@ variables to guide Python and C++ standard detection should be set
 and libraries as needed, and C++ compile definitions attached. This
 target is suitable for linking to an independently constructed (through
 ``add_library``, not ``pybind11_add_module``) target in the consuming
-project. Note that this target has only build *requirements* attached
-and is missing the several build *recommendations* supplied by
-``pybind11_add_module`` (see :ref:`faq <faq:symhidden>` for discussion
-of desirability).
-A working example can be found at [test_installed_target]_ .
+project. A working example can be found at [test_installed_target]_ .
 
 .. code-block:: cmake
 
@@ -102,5 +98,20 @@ A working example can be found at [test_installed_target]_ .
     set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
                                              SUFFIX "${PYTHON_MODULE_EXTENSION}")
 
+..warning:
+
+    Since pybind11 is a metatemplate library, it is crucial that certain
+    compiler flags are provided to ensure high quality code generation. In
+    contrast to the ``pybind11_add_module()`` command, the CMake interface
+    library only provides the *minimal* set of parameters to ensure that the
+    code using pybind11 compiles, but it does **not** pass these extra compiler
+    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
+    explanation on why these are needed.
+
 .. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt