From 24ddf4b3f13e264369b2f09060306e6eae9b68a5 Mon Sep 17 00:00:00 2001 From: Dean Moldovan Date: Fri, 27 May 2016 00:11:52 +0200 Subject: [PATCH] Update CMake build documentation --- docs/compiling.rst | 150 +++++---------------------------------------- 1 file changed, 16 insertions(+), 134 deletions(-) diff --git a/docs/compiling.rst b/docs/compiling.rst index 5f4d0983..5800694a 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -26,146 +26,28 @@ Building with cppimport 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`. +For C++ codebases that have an existing CMake-based build system, a Python +extension module can be created with just a few lines of code: .. code-block:: cmake - cmake_minimum_required(VERSION 2.8) - + cmake_minimum_required(VERSION 2.8.12) 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") + add_subdirectory(pybind11) + pybind11_add_module(example example.cpp) - include(CheckCXXCompilerFlag) +This assumes that the pybind11 repository is located in a subdirectory named +:file:`pybind11` and that the code is located in a file named :file:`example.cpp`. +The CMake command ``add_subdirectory`` will import a function with the signature +``pybind11_add_module( source1 [source2 ...])``. It will take care of all +the details needed to build a Python extension module on any platform. - # 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) +The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION`` +variable before adding the pybind11 subdirectory. Alternatively, an exact Python +installation can be specified by setting ``PYTHON_EXECUTABLE``. - # 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() +A working sample project, including a way to invoke CMake from :file:`setup.py` for +PyPI integration, can be found in the [cmake_example]_ repository. - # 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 - "$<$:/Os>" "$<$:/GL>" - "$<$:/Os>" "$<$:/GL>" - "$<$:/Os>" "$<$:/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() +.. [cmake_example] https://github.com/dean0x7d/pybind11_cmake_example