Add explanation to README.md

Author: Felix Widmaier

README.md

@@ -1,19 +1,66 @@
-Using Boost::Python with cmake
-==============================
+Using Boost::Python with catkin
+===============================
 
-The official boost documentation uses boosts own build tool `bjam`. To integrate it into a catkin build, I have to use
-cmake, though.
-This page looks like a very nice and detailed tutorial: https://www.preney.ca/paul/archives/107
+This is a minimal example of how to use Boost::Python in a catkin package.
+As there is little helpful documentation about this topic on the internet, I try to summarize
+all necessary steps here.
 
-Maybe even better:
-https://github.com/ethz-asl/Schweizer-Messer/wiki/Adding-boost::python-exports-to-your-ROS-package
+First you need some C++ code. `src/mycpplib.cpp` contains a simple hello world function that is
+made available for Python using Boost::Python. (see documentation of Boost::Python for more
+details on how to use it).
 
-Form http://wiki.ros.org/catkin/CMakeLists.txt:
-7.2 Custom output directory
-While the default output directory for executables and libraries is usual set to a reasonable
-value it must be customized in certain cases. I.e. a library containing Python bindings must be
-placed in a different folder to be importable in Python:
+To compile it and make it available for python, some configuration in the CMakeLists.txt has to
+be done:
 
-    set_target_properties(python_module_library PROPERTIES
-      LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
-    )
+
+Configure cmake
+---------------
+
+ 1. You need Boost::Python and the path to the python include dirs:
+        find_package(Boost REQUIRED COMPONENTS python)
+        find_package(PythonLibs REQUIRED) # sets ${PYTHON_INCLUDE_DIRS}
+    Make sure to add them to the include directories:
+        include_directories(
+          ${catkin_INCLUDE_DIRS}
+          ${Boost_INCLUDE_DIRS}
+          ${PYTHON_INCLUDE_DIRS}
+        )
+ 2. uncomment `catkin_python_setup()`. This will set up the destination path of the python
+    module. You also need a basic _setup.py_ in the packages root directory.
+ 3. add a library:
+        add_library(mycpplib SHARED
+          src/mycpplib.cpp
+        )
+        target_link_libraries(mycpplib
+          ${catkin_LIBRARIES}
+          ${Boost_LIBRARIES}
+        )
+        # change output directory, so python can find the module
+        set_target_properties(mycpplib PROPERTIES
+          LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
+        )
+    The last command is important because it will change the destination of the compiled library
+    from `/catkin_ws/devel/lib/` to `/catkin_ws/devel/lib/python2.7/dist-packages/` so it can be
+    found by python.
+    Also don't forget the `SHARED` in `add_library`.
+
+
+Use the module
+--------------
+
+After you compiled the package, you should be able to use the wrapped module in Python:
+
+        import boostpy_test.libmycpplib as cpp
+        cpp.hello()
+
+
+References
+----------
+
+Some references that were helpful for me in one or the other way:
+
+ * Boost::Python documentation: http://www.boost.org/doc/libs/1_57_0/libs/python/doc/index.html
+ * Using Boost::Python with cmake: https://www.preney.ca/paul/archives/107
+ * https://github.com/ethz-asl/Schweizer-Messer/wiki/Adding-boost::python-exports-to-your-ROS-package
+ * http://wiki.ros.org/catkin/CMakeLists.txt, Section 7.2 (the `set_target_properties` command
+   comes from there)

src/mycpplib.cpp

@@ -9,8 +9,8 @@ void hello()
 }
 
 
-
-BOOST_PYTHON_MODULE(libmycpplib) // name has to match with the name in CMakeLists `add_library` + prefix 'lib'
+// name has to match with the name in CMakeLists `add_library` + prefix 'lib'
+BOOST_PYTHON_MODULE(libmycpplib)
 {
    using namespace boost::python;
    def("hello", hello);