Commit ac0af663 authored by Baptiste Esteban's avatar Baptiste Esteban
Browse files

Start documentation update

parent ad348e3e
Pipeline #27348 passed with stages
in 28 minutes and 5 seconds
Python Module
=============
.. warning:: This module is under development.
.. warning:: This module is under development. The features explained in the following sections are only available in the ``next`` branch of the project repository
and in the ``unstable`` Conan's channel.
.. toctree::
python/first_step.rst
......
First steps
===========
Introduction
============
The Pylene library makes possible to expose its features in Python. To this aim, it provides two components :
* The ``Pylene-numpy`` library, which converts Pylene images into Numpy arrays.
* The ``pylena`` module, which binds some Pylene algorithms in Python.
For instance, the ``pylena`` module is under development and is currently empty. However, it is possible to create
a Python module using `Pybind11 <https://pybind11.readthedocs.io>`_ and the ``Pylene-numpy`` library. This is described in the next section.
Installation
------------
^^^^^^^^^^^^
.. important:: For now, only the ``pylena_numpy`` library is available. It makes possible to write Python packages using the ``Pylene`` library. In the future,
the ``pylena`` module will be developped, making the ``Pylene`` algorithms available in Python and easily usable.
Before continuing, it is advised to read this section about the Pylene installation.
Using Conan
^^^^^^^^^^^
This subsection describe how to get the ``Pylene-numpy`` library. Two methods are explained :
.. code-block:: console
* Getting ``Pylene-numpy`` using Conan to use it in a project.
* Building the ``Pylene-numpy`` library from sources.
In any cases, on Linux, make sure to get the Pylene library using the ``Position Independent Code`` compiler option
since Python modules on Linux are dynamic libraries. On Windows, the standard installation steps will install the Python
components.
Using Conan (preferred)
-----------------------
When writing a `conanfile` to get the `Pylene` library, some ``options`` have to be added to get the Python components.
Bellow is an exemple of a `conanfile.txt`, where the `fPIC` option has been added for Pylene.
$ conan install pylene/head@lrde/stable -o pylene:fPIC=True -o pylene:python=True
.. code-block:: text
For developpers (Build from source)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[generators]
cmake_find_package
[requires]
pylene/head@lrde/unstable
[options]
pylene:fPIC=True # Or pylene:shared=True
Building Pylene using CMake
---------------------------
People willing to build the Pylene library, such as Pylene's developpers, should execute the following command
to build the Python components.
.. code-block:: console
$ git clone https://gitlab.lrde.epita.fr/olena/pylene.git
$ cd pylene
$ mkdir build && cd build
$ conan install .. --build missing
$ cmake .. -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DPYLENE_BUILD_PYTHON=ON
$ make pylena_numpy
\ No newline at end of file
$ conan install .. -o pylene:fPIC=True
$ cmake .. -DPYLENE_BUILD_PYTHON=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON
$ make -j4
As explained above, the `fPIC` option has been added to the Conan install command. Futhermore, two CMake's options
are added:
* ``-DPYLENE_BUILD_PYTHON=ON`` to enable the build process of the Python components.
* ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` to compile using the `fPIC` flags of the compiler.
If CMake is runned with ``-DPYLENE_BUILD_PYTHON=ON`` but not with ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON``, a warning will be shown during the build system generation
but it will not prevent the build process to run. So during the build process, a linker error should be raised for the building of the ``pylena`` module.
\ No newline at end of file
if (NOT CMAKE_POSITION_INDEPENDENT_CODE)
message(WARNING "Building the Python components without POSITION_INDEPENDENT_CODE enabled. \
Build should fail during the linking part of the compilation of the pylena module.")
endif()
find_package(fmt 6.0 REQUIRED)
add_library(Pylene-numpy)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment