[docs] Added a document describing how to build python bindings.

2019-12-05 15:39:03 +03:00 · 2019-12-05 15:39:03 +03:00 · 8028d3a00c
commit 8028d3a00c
parent 1c102789d4
1 changed files with 133 additions and 0 deletions
--- a/docs/building_pybindings.txt
+++ b/docs/building_pybindings.txt
@ -0,0 +1,133 @@
+Some of the project's librariers (traffic, search, kml and others) come
+with python bindings, i.e. have some of their functions exposed to be
+callable from the python programming language. The version of python
+is not enforced, so some libraries may be using python 2 and some may
+be using python 3.
+
+This document describes how to build these python bindings.
+
+
+Installing Boost.Python
+-----------------------
+
+The MAPS.ME project comes with its own version of Boost (https://www.boost.org/)
+in a submodule. While most of the project uses boost in the header-only mode,
+you will need to build the Boost.Python library to link against if you need
+python bindings.
+
+Once you've run
+
+  $ git submodule update --init --recursive
+
+and
+
+  $ ./configure.sh
+
+from omim's root directory, you'll have the Boost headers installed but the
+python library will not be built by default, so we'll need to build it
+manually. (The less clean alternative is to
+link against the version of library installed in your system in case you have
+a system installation of Boost. This is not recommended.)
+
+The official instruction for Boost 1.68 is here: https://www.boost.org/doc/libs/1_68_0/libs/python/doc/html/building/configuring_boost_build.html.
+
+Here is a recap.
+
+Write the paths to your python binary, headers and libraries in a .jam-file.
+We will edit the auto-generated file omim/3party/boost/project-config.jam
+which omim's configure.sh should have generated by now.
+Unfortunately, Boost's bootstrap.sh (called from omim's configures.sh) that generates
+this file is not sufficiently versatile to allow us provide the necessary paths
+at the ./configure.sh stage.
+
+Example for a macOS installation:
+
+    $ pwd
+
+    /omim/3party/boost
+
+    $ cat >>project-config.jam <<EOF
+
+using python
+  : 3.7
+  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/bin/python3
+  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/Headers
+  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/lib
+  ;
+EOF
+
+    $ ./b2 --with-python python=3.7
+
+Boost.Build does not work well with duplicating "using python" rules for the same
+version so if you've made a mistake, manually edit the file instead of appending
+a version with corrected paths.
+
+(On some systems you may need to call
+    $ ./b2 --with-python python=3.7 cxxflags="-fPIC"
+instead)
+
+The syntax is
+    using python : <version> : <python binary> : <path to python headers> : <path to python libraries> ;
+
+Newlines are allowed, semicolon is required.
+If there are several versions of Boost.Python that you want to build,
+they can all be added to the same .jam-file with this "using python" directive.
+
+To remove the python libraries, execute the script that installed them with the
+additional "--clean" flag:
+
+    $ ./b2 --with-python --clean
+
+Or you can remove them manually:
+
+   $ pwd
+
+    /omim/3party/boost
+
+   $ rm -r bin.v2 stage
+
+
+
+Building pybindings
+-------------------
+
+Now you're ready to build omim's CMake targets that link against Boost.Python:
+
+    $ pwd
+
+    /omim
+
+    $ mkdir ../build-omim
+    $ cd ../build-omim
+    $ cmake ../omim \
+       -DPYBINDINGS=ON \
+       -DPYBINDINGS_VERSION=9.5.0 \
+       -DPYTHON_VERSION=3.7.5 \
+
+    (make sure that the version match what you've provided in the .jam file
+     when building the Boost.Python lib)
+
+    $ make -j4 pysearch
+
+If the above invocation of CMake fails to find the correct
+python installation on your system, you may need to help it:
+
+     $ cmake ../omim \
+         -DPYBINDINGS=ON \
+         -DPYBINDINGS_VERSION=9.5.0 \
+         -DPYTHON_VERSION=3.7.5 \
+         -DPYTHON_EXECUTABLE=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/bin/python3 \
+         -DPYTHON_INCLUDE_DIRS=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/Headers \
+         -DPYTHON_LIBRARY=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/lib/libpython3.7m.dylib \
+
+
+Test your newly built target:
+
+    $ MWM_RESOURCES_DIR=../omim/data \
+      MWM_WRITABLE_DIR=..omim/data \
+      PYTHONPATH=. \
+      ../omim/search/pysearch/run_search_engine.py \
+
+
+Do not forget to clean CMake's caches (by purging the build/ directory, for example)
+if something goes wrong during the CMake stage.