1.. _compilation:
2
3Compilation Options
4###################
5
6This page shows advanced options to customize your Open3D build. For quick start, see :ref:`getting_started_compilation`.
7
8.. _python_binding:
9
10Python binding
11==============
12
13We use `pybind11 <https://github.com/pybind/pybind11>`_ to build the Python binding.
14It tries to automatically detect the installed version of Python and link against that.
15When this fails, or when there are multiple versions of Python and it finds the wrong one, delete CMakeCache.txt and then invoke CMake as follows:
16
17.. code-block:: bash
18
19    cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> ../src
20
21.. Note:: Python binding issues can also refer to `pybind11 document page <http://pybind11.readthedocs.io/en/stable/faq.html>`_.
22
23If you do not want Python binding, you may turn off the following compilation options:
24
25- ``BUILD_PYBIND11``
26- ``BUILD_PYTHON_MODULE``
27- ``BUILD_PYTHON_TESTS``
28- ``BUILD_PYTHON_TUTORIALS``
29
30Dependencies
31============
32
33Open3D dependencies are included in ``src/External`` folder.
34The user has the option to force building the dependencies from source or to let CMake search for installed packages.
35If a build option is turned OFF and CMake can't find its corresponding package the configuration step will fail.
36
37Example error message:
38
39| ``CMake Error at External/CMakeLists.txt:32 (message):``
40| ``EIGEN3 dependency not met.``
41
42The following is an example of how to force building from source a number of dependencies:
43
44.. code-block:: bash
45
46    cmake -DBUILD_EIGEN3=ON  \
47          -DBUILD_GLEW=ON    \
48          -DBUILD_GLFW=ON    \
49          -DBUILD_JPEG=ON    \
50          -DBUILD_JSONCPP=ON \
51          -DBUILD_PNG=ON     \
52          ../src
53
54.. tip:: This can save a lot of time on Windows where it can be particularly difficult to install the Open3D dependencies.
55
56.. note:: Enabling these build options may increase the compilation time.
57
58OpenMP
59======
60
61We automatically detect if the C++ compiler supports OpenMP and compile Open3D with it if the compilation option ``WITH_OPENMP`` is ``ON``.
62OpenMP can greatly accelerate computation on a multi-core CPU.
63
64The default LLVM compiler on OS X does not support OpenMP.
65A workaround is to install a C++ compiler with OpenMP support, such as gcc, then use it to compile Open3D.
66For example, starting from a clean build directory, run
67
68.. code-block:: bash
69
70    brew install gcc --without-multilib
71    cmake -DCMAKE_C_COMPILER=gcc-6 -DCMAKE_CXX_COMPILER=g++-6 ../src
72    make -j
73
74.. note:: This workaround has some compatibility issues with the source code of GLFW included in ``src/External``.
75          Make sure Open3D is linked against GLFW installed on the OS.
76
77Unit testing
78============
79
80.. warning:: Work in progress!
81
82    - Unit test coverage: low.
83    - Tested on: macOS and Ubuntu.
84
85Unit testing is based on `Google Test <https://github.com/google/googletest>`_.
86By default unit tests are turned off. In order to enable them follow the next steps:
87
88    1. Download/Build/Install Google Test.
89    2. Set the BUILD_UNIT_TESTS flag to ON.
90
91.. code-block:: bash
92
93    cd util/scripts
94    ./install-gtest.sh
95
96    cd <path_to_Open3D>
97    mkdir build
98    cd build
99    cmake ../src -DBUILD_UNIT_TESTS=ON
100    make -j
101
102In order to perform the unit tests:
103
104.. code-block:: bash
105
106    cd util/scripts
107    ./runUnitTests.sh
108
109Documentation
110=============
111
112Documentation is written in `reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_ and compiled with `sphinx <http://www.sphinx-doc.org/>`_.
113From ``docs`` folder, run
114
115.. code-block:: bash
116
117    pip install sphinx sphinx-autobuild sphinx-rtd-theme
118    make html
119
120Documentation for C++ API is made with `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_.
121Follow the `Doxygen installation instruction <http://www.stack.nl/~dimitri/doxygen/manual/install.html>`_.
122From Open3D root folder, run
123
124.. code-block:: bash
125
126    doxygen Doxyfile
127