minor FAQ edits, referenced cppimport project
diff --git a/docs/compiling.rst b/docs/compiling.rst
new file mode 100644
index 0000000..5f4d098
--- /dev/null
+++ b/docs/compiling.rst
@@ -0,0 +1,171 @@
+Build systems
+#############
+
+Building with setuptools
+========================
+
+For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
+has kindly provided an example project which shows how to set up everything,
+including automatic generation of documentation using Sphinx. Please refer to
+the [pbtest]_ repository.
+
+.. [pbtest] https://github.com/pybind/pbtest
+
+Building with cppimport
+========================
+
+ cppimport is a small Python import hook that determines whether there is a C++
+ source file whose name matches the requested module. If there is, the file is
+ compiled as a Python extension using pybind11 and placed in the same folder as
+ the C++ source file. Python is then able to find the module and load it.
+
+.. [cppimport] https://github.com/tbenthompson/cppimport
+
+.. _cmake:
+
+Building with CMake
+===================
+
+For C++ codebases that already have an existing CMake-based build system, the
+following snippet should be a good starting point to create bindings across
+platforms. It assumes that the code is located in a file named
+:file:`example.cpp`, and that the pybind11 repository is located in a
+subdirectory named :file:`pybind11`.
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 2.8)
+
+ project(example)
+
+ # Add a CMake parameter for choosing a desired Python version
+ set(EXAMPLE_PYTHON_VERSION "" CACHE STRING
+ "Python version to use for compiling the example library")
+
+ include(CheckCXXCompilerFlag)
+
+ # Set a default build configuration if none is specified.
+ # 'MinSizeRel' produces the smallest binaries
+ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+ message(STATUS "Setting build type to 'MinSizeRel' as none was specified.")
+ set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE)
+ set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release"
+ "MinSizeRel" "RelWithDebInfo")
+ endif()
+ string(TOUPPER "${CMAKE_BUILD_TYPE}" U_CMAKE_BUILD_TYPE)
+
+ # Try to autodetect Python (can be overridden manually if needed)
+ set(Python_ADDITIONAL_VERSIONS 3.4 3.5 3.6 3.7)
+ if (NOT ${EXAMPLE_PYTHON_VERSION} STREQUAL "")
+ find_package(PythonLibs ${EXAMPLE_PYTHON_VERSION} EXACT)
+ if (NOT PYTHONLIBS_FOUND)
+ find_package(PythonLibs ${EXAMPLE_PYTHON_VERSION} REQUIRED)
+ endif()
+ else()
+ find_package(PythonLibs REQUIRED)
+ endif()
+
+ # The above sometimes returns version numbers like "3.4.3+";
+ # the "+" must be removed for the next lines to work
+ string(REPLACE "+" "" PYTHONLIBS_VERSION_STRING "+${PYTHONLIBS_VERSION_STRING}")
+
+ # Uncomment the following line if you will also require a matching Python interpreter
+ # find_package(PythonInterp ${PYTHONLIBS_VERSION_STRING} EXACT REQUIRED)
+
+ if (CMAKE_CXX_COMPILER_ID MATCHES "Clang" OR CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+ CHECK_CXX_COMPILER_FLAG("-std=c++14" HAS_CPP14_FLAG)
+ CHECK_CXX_COMPILER_FLAG("-std=c++11" HAS_CPP11_FLAG)
+
+ if (HAS_CPP14_FLAG)
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++14")
+ elseif (HAS_CPP11_FLAG)
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+ else()
+ message(FATAL_ERROR "Unsupported compiler -- at least C++11 support is needed!")
+ endif()
+
+ # Enable link time optimization and set the default symbol
+ # visibility to hidden (very important to obtain small binaries)
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ # Default symbol visibility
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=hidden")
+
+ # Check for Link Time Optimization support
+ CHECK_CXX_COMPILER_FLAG("-flto" HAS_LTO_FLAG)
+ if (HAS_LTO_FLAG)
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -flto")
+ endif()
+ endif()
+ endif()
+
+ # Include path for Python header files
+ include_directories(${PYTHON_INCLUDE_DIR})
+
+ # Include path for pybind11 header files -- this may need to be
+ # changed depending on your setup
+ include_directories(${PROJECT_SOURCE_DIR}/pybind11/include)
+
+ # Create the binding library
+ add_library(example SHARED
+ example.cpp
+ # ... extra files go here ...
+ )
+
+ # Don't add a 'lib' prefix to the shared library
+ set_target_properties(example PROPERTIES PREFIX "")
+
+ if (WIN32)
+ if (MSVC)
+ # /MP enables multithreaded builds (relevant when there are many files), /bigobj is
+ # needed for bigger binding projects due to the limit to 64k addressable sections
+ set_property(TARGET example APPEND PROPERTY COMPILE_OPTIONS /MP /bigobj)
+ # Enforce size-based optimization and link time code generation on MSVC
+ # (~30% smaller binaries in experiments); do nothing in debug mode.
+ set_property(TARGET example APPEND PROPERTY COMPILE_OPTIONS
+ "$<$<CONFIG:Release>:/Os>" "$<$<CONFIG:Release>:/GL>"
+ "$<$<CONFIG:MinSizeRel>:/Os>" "$<$<CONFIG:MinSizeRel>:/GL>"
+ "$<$<CONFIG:RelWithDebInfo>:/Os>" "$<$<CONFIG:RelWithDebInfo>:/GL>"
+ )
+ set_property(TARGET example APPEND_STRING PROPERTY LINK_FLAGS_RELEASE "/LTCG ")
+ set_property(TARGET example APPEND_STRING PROPERTY LINK_FLAGS_MINSIZEREL "/LTCG ")
+ set_property(TARGET example APPEND_STRING PROPERTY LINK_FLAGS_RELWITHDEBINFO "/LTCG ")
+ endif()
+
+ # .PYD file extension on Windows
+ set_target_properties(example PROPERTIES SUFFIX ".pyd")
+
+ # Link against the Python shared library
+ target_link_libraries(example ${PYTHON_LIBRARY})
+ elseif (UNIX)
+ # It's quite common to have multiple copies of the same Python version
+ # installed on one's system. E.g.: one copy from the OS and another copy
+ # that's statically linked into an application like Blender or Maya.
+ # If we link our plugin library against the OS Python here and import it
+ # into Blender or Maya later on, this will cause segfaults when multiple
+ # conflicting Python instances are active at the same time (even when they
+ # are of the same version).
+
+ # Windows is not affected by this issue since it handles DLL imports
+ # differently. The solution for Linux and Mac OS is simple: we just don't
+ # link against the Python library. The resulting shared library will have
+ # missing symbols, but that's perfectly fine -- they will be resolved at
+ # import time.
+
+ # .SO file extension on Linux/Mac OS
+ set_target_properties(example PROPERTIES SUFFIX ".so")
+
+ # Strip unnecessary sections of the binary on Linux/Mac OS
+ if(APPLE)
+ set_target_properties(example PROPERTIES MACOSX_RPATH ".")
+ set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup ")
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ add_custom_command(TARGET example POST_BUILD
+ COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so)
+ endif()
+ else()
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ add_custom_command(TARGET example POST_BUILD
+ COMMAND strip ${PROJECT_BINARY_DIR}/example.so)
+ endif()
+ endif()
+ endif()