|
| 1 | +.. _compiling: |
| 2 | + |
| 3 | +Compiling a program |
| 4 | +******************* |
| 5 | + |
| 6 | +Requirements |
| 7 | +============ |
| 8 | + |
| 9 | +Matplotlib for C++ requires a working Python installation as well as |
| 10 | +Matplotlib. Python2.7 and Python3 (>= 3.6) have been tested, but |
| 11 | +other versions should work as well. In the linking process the exact |
| 12 | +version of Python to use can be specified by linking the according library. |
| 13 | + |
| 14 | +On Unix it is recommended to install Python via the package manager to |
| 15 | +assert that all dependencies are installed properly. |
| 16 | + |
| 17 | +.. code-block:: bash |
| 18 | +
|
| 19 | + <package-manager> install python3 python3-dev # or -devel depending on the platform |
| 20 | +
|
| 21 | +If Python is installed from source problems in the linking may occur. |
| 22 | +How to resolve these is explained in the next section, or in |
| 23 | +:ref:`this <pyfromsource>` code-block. |
| 24 | + |
| 25 | +Install matplotlib via pip |
| 26 | + |
| 27 | +.. code-block:: bash |
| 28 | +
|
| 29 | + pip3 install matplotlib # or pip for Python 2 |
| 30 | +
|
| 31 | +Includes and Linking |
| 32 | +==================== |
| 33 | + |
| 34 | + |
| 35 | +The header ``matplotlibcpp.h`` depends on the Python header, ``Python.h``, |
| 36 | +the corresponding Python library ``libpython``, and on ``numpy/arrayobject.h``. |
| 37 | +If not in the standard include paths, the paths to the header files, |
| 38 | +the path to the library, and the library itself have to be specified |
| 39 | +for the compiler using the options ``-I``, ``-L`` and ``-l`` respectively. |
| 40 | +Note, that all Python constituents should be of the same Python version. |
| 41 | +Matplotlib for C++ supports both, Python 2.7 and Python 3 versions. |
| 42 | + |
| 43 | +In detail: |
| 44 | + |
| 45 | + - The Python header ``Python.h`` |
| 46 | + |
| 47 | + The Python header comes with the Python installation. It it cannot be |
| 48 | + found on your system try installing the Python development packages. |
| 49 | + The location of this header has to be specified using the option ``-I``. |
| 50 | + |
| 51 | + Typical locations: |
| 52 | + |
| 53 | + - Linux: `/usr/local/include/python3.7` |
| 54 | + - Mac: if installed with Homebrew `/usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/include/python3.7m` |
| 55 | + |
| 56 | + - The Python library ``libpython*.so`` |
| 57 | + |
| 58 | + The program has to be linked against the compiled Python library. |
| 59 | + Depending on the Python version the name of the library differs, for |
| 60 | + Python 3.7 it is ``libpython3.7.so`` (or ``libpython3.7m.so``). |
| 61 | + Then link the library by specifying ``-lpython3.7`` (or ``-lpython3.7m``). |
| 62 | + |
| 63 | + Additionally to the linking the location of the library must be specified |
| 64 | + if not installed in the usual directory. For Linux systems this is |
| 65 | + usually not necessary, for Mac however it mostly is. |
| 66 | + The location of the library has to be specified using the option ``-L``. |
| 67 | + |
| 68 | + If Python has not been installed using the package manager (but e.g. |
| 69 | + from source) twofold problems with linking the library can occur. |
| 70 | + The first are missing dependencies of the Python library, these can be |
| 71 | + added via ``-lpthread -lutil -ldl``. |
| 72 | + The second is that dynamic libraries have to be exported which is |
| 73 | + resolved by adding ``-Xlinker -export-dynamic``. |
| 74 | + |
| 75 | + Typical locations: |
| 76 | + |
| 77 | + - Linux: Path usually already included |
| 78 | + - Mac: `/usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/lib` |
| 79 | + |
| 80 | + - Numpy array ``numpy/arrayobject.h`` |
| 81 | + |
| 82 | + By default Matplotlib for C++ uses Numpy arrays. This requires the above |
| 83 | + header file. However it is possible to avoid this header by defining |
| 84 | + ``-DWITHOUT_NUMPY``. |
| 85 | + |
| 86 | + - Linux: `/usr/local/lib/python3.7/site-packages/numpy/core/include` |
| 87 | + - Mac: If installed via Homebrew, same as for Linux. |
| 88 | + |
| 89 | +**Examples** |
| 90 | + |
| 91 | +On Linux with the GNU compiler ``g++`` and |
| 92 | +C++11. |
| 93 | + |
| 94 | +.. code-block:: bash |
| 95 | +
|
| 96 | + # using Python 2.7 |
| 97 | + g++ main.cpp -std=c++11 -I/usr/local/include/python2.7 \ |
| 98 | + -I/usr/local/lib/python2.7/site-packages/numpy/core/include -lpython2.7 |
| 99 | +
|
| 100 | +.. code-block:: bash |
| 101 | +
|
| 102 | + # using Python3.7 and no Numpy |
| 103 | + g++ main.cpp -std=c++11 -DWITHOUT_NUMPY -I/usr/local/include/python2.7 -lpython2.7 |
| 104 | +
|
| 105 | +On Mac with the GNU compiler ``g++`` and C++14. |
| 106 | + |
| 107 | +.. code-block:: bash |
| 108 | +
|
| 109 | + g++ main.cpp -std=c++14 \ |
| 110 | + -I /usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/include/python3.7m \ |
| 111 | + -I /usr/local/lib/python3.7/site-packages/numpy/core/include \ |
| 112 | + -L /usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/lib \ |
| 113 | + -lpython3.7 |
| 114 | +
|
| 115 | +With exporting dynamic libraries and linking to all dependencies of |
| 116 | +the Python library on a Linux system: |
| 117 | + |
| 118 | +.. _pyfromsource: |
| 119 | + |
| 120 | +.. code-block:: bash |
| 121 | +
|
| 122 | + g++ main.cpp -std=c++11 -I/usr/local/include/python3.7m \ |
| 123 | + -I/usr/local/lib/python3.7/site-packages/numpy/core/include \ |
| 124 | + -lpython3.7m \ |
| 125 | + -lpthread -lutil -ldl \ # library dependencies |
| 126 | + -Xlinker -export-dynamic \ # export dynamic libraries |
0 commit comments