From 6d94e8de984ad4b47503b9c612e764bd9a81b826 Mon Sep 17 00:00:00 2001 From: Victor Popov Date: Mon, 6 Apr 2020 18:07:33 +0300 Subject: [PATCH] [docs] adjust pybindings build docs to new build system --- docs/building_pybindings.txt | 163 +++++++++++++---------------------- 1 file changed, 59 insertions(+), 104 deletions(-) diff --git a/docs/building_pybindings.txt b/docs/building_pybindings.txt index 43c974cb67..171ab81f91 100644 --- a/docs/building_pybindings.txt +++ b/docs/building_pybindings.txt @@ -7,121 +7,76 @@ be using python 3. This document describes how to build these python bindings. -Installing Boost.Python ------------------------ - +Preparing source tree +--------------------- 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. +in a submodule. You have to recursively update submodules before you start +building anything. -Once you've run +Ensure you have ran: $ 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. - -We will append the python config to the end of project-config.jam. -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. - -Example for a macOS installation: - - $ pwd - - /omim/3party/boost - - $ cat >>project-config.jam < : : : ; - -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. - -If you want to remove the python libraries, you'll have to do it by manually removing -the build directory. (b2 provides a "--clean" flag which seems to be broken) - - $ pwd - - /omim/3party/boost - - $ rm -r build-python37 +Building single pybinding module +-------------------------------- +Find a correspoding module's setup.py. +Current list of available modules and setup's: -Building pybindings -------------------- +- generator/mwm_diff/pymwm_diff/setup.py +- generator/pygen/setup.py +- kml/pykmlib/setup.py +- local_ads/pylocal_ads/setup.py +- search/pysearch/setup.py +- tracking/pytracking/setup.py +- traffic/pytraffic/setup.py -Now you're ready to build omim's CMake targets that link against Boost.Python. +Run chosen setup.py with Python you want to build binding for. +Examples: -Do not forget to clean CMake's caches (by purging the build/ directory, for example) -if something goes wrong during the CMake stage. + $ python kml/pykmlib/setup.py build install + $ python3.6 generator/mwm_diff/pymwm_diff/setup.py bdist_wheel - $ 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_DIR=/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 +During build, our setup.py will configure and build boost_python library for +needed Python version, configure omim, and build needed binding. -Test your newly built target: +Building all pybindings modules +------------------------------- +Run generic pyhelpers/setup.py with needed Python. This will invoke build (or +other actions) for all pybindings. - $ MWM_RESOURCES_DIR=../omim/data \ - MWM_WRITABLE_DIR=..omim/data \ - PYTHONPATH=. \ - ../omim/search/pysearch/run_search_engine.py + +Supported actions and options +----------------------------- +Please refer to setuptools/distutils documentation for description of all +available commands. +Main commands are: + build + install + bdist_wheel + +Notable option for build command: + + --omim-builddir [path to omim builddir] + +It should be used to store build dir somewhere outside source tree. If not +specified, everything will be build in directory `build` from current +directory. + +Complete wheels generation example: + $ python3.7 pyhelpers/setup.py build --omim-builddir ../omim-build/ bdist_wheel + +This will create wheels for all pybindings in `../omim-build/pybindings-dist/`. + + +Pip installation +---------------- + +One can install pybinding straight from source: + + $ pip install git+https://github.com/mapsme/omim.git@master#egg=pykmlib&subdirectory=kml/pykmlib + +But this can be a long wait, it is better to use already compiled .whl +distribution.