Installation¶
Overview¶
Downloading¶
The project also requires some third party dependencies (see below for more details).
Those dependencies are divided into heavy, potentially system-wide, dependencies and lighter dependencies which can easily be bundled in a source package along with Code_TYMPAN.
Lightweight dependencies¶
Those dependencies are to be downloaded as a companion source package
and unzipped into the 3rdparty
directory. Please refer to the
3rdparty/README
file which provides the exact URL for your current
version of Code_TYMPAN.
Major dependencies¶
The following dependencies are a bigger deal as their are likely to be already installed in your development environment in a system-wide way. If you are running a Linux box, the best way to get them is through your distribution package manager. If you are running a Windows box, you should run the dedicated installers.
More details are given in further sections, on an OS and variant basis.
- Boost
Boost is a set of C++ libraries which provide a higher level of expressiveness and convenience for C++. Version 1.77 is currently used.
- Qt 5
Qt is a toolkit for developing Graphical User Interface and providing portable and commonly used facilities such as multi-threading or reading XML files… Version 5.15.2 is currently used.
- OpenGL
is a common 3D rendering API. It is mainly accessed through the QtOpenGL components.
- CMake
CMake is a multi platform built tool used to build Code_TYMPAN (and CGAL and many other OpenSource projects by the way). A version 3.22 is currently used.
- CGAL
CGAL is a Computational Geometry library and itself depends upon both Boost and Qt and as such needs to be installed in a compatible way with your Qt and Boost installation. CGAL is used in the Python code for altimetry mesh triangulation and refinement. It is also used in the C++ code (business part) for infrastructure polygons triangulation.
- Python
A Python interpreter is required, version 3.10.x
- Cython
Cython is a programming language inspired from Python, allowing to write Python code with C/C++ declarations. The cython code is then translated into C/C++ and compiled as a Python library. It is used in Code_TYMPAN to interface Python code with TYMPAN C++ libraries. A version 0.29 or above is required.
- Shapely
Shapely is a Python package for manipulation and analysis of planar geometric objects. Version 1.7.1 is currently used.
- SWIG
Swig is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. It is needed by the 3rd party dependency CGAL-bingings, to connect C++ with Python code.
Documentation dependencies¶
The C++ source code is annotated and API documentation can be extracted with Doxygen and Graphviz whereas this documentation is generated from reStructuredText sources thanks to Sphinx. MathJax is used to nicely display equations.
Windows 10¶
NB : Since 4.2, Code_TYMPAN targets 64 bit CPU architecture.
To install the development environment for Windows, here are the various installers to download and execute.
Boost
Binary versions of Boost are available on SourceForge. For instance, you can download the 64 bits 1.77.0 Boost version for Visual Studio 2019 toolchain at https://sourceforge.net/projects/boost/files/boost-binaries/1.77.0/boost_1_77_0-msvc-14.2-64.exe/download. Adapt version and toolchain to your needs. See Installing Boost for detailed instructions.
Qt 5
Download the installer for the Qt at https://www.qt.io/download-thank-you?hsLang=en Currently Qt 5.15.2 is used with msvc2019_64 toolchain.
- CMake
- CGAL
See the Installing CGAL (no real binary installer available on Windows) : https://github.com/CGAL/cgal/releases/download/v5.5.1/CGAL-5.5.1.zip
- Cython
Cython can be installed in python virtual environment. See Python environment installation for details.
- Shapely
Shapely can be installed in Python environment. See Python environment installation for details.
- SWIG
A prebuilt executable of SWIG can be downloaded at https://www.swig.org/download.html Download and unzip here C:\dists\swigwin-4.0.2, for example. Add this folder path to the environment variable PATH. Add the following environment variables :
set SWIG_DIR=C:\dists\swigwin-4.0.2 set SWIG_EXECUTABLE=C:\dists\swigwin-4.0.2\swig.exe set PATH=C:\dists\swigwin-4.0.2;%PATH%
Python environment installation¶
Launch a command window, adapt and execute following commands to create a 3.10.x python virtual environment :
c:
cd \
cd dists/python
C:\Python310\python.exe -m venv venv310tympan
# Activate virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
Installing Boost¶
Boost is a mandatory dependency of CGAL. Binary versions of Boost are available on SourceForge. The Boost installers install both Boost headers and precompiled libraries.
The procedure below applies for 1.77.0 version of Boost and Visual C++ 2019 :
Download and run the file boost_1_77_0-msvc-XX.Y-64.exe (where XX.Y = 14.0 for VC 2015, XX.Y = 14.1 for VC 2017, XX.Y = 14.2 for VC 2019). Currently, we suggest to download this file
Extract the files to a new directory, e.g. c:\Boost\boost_1_77_0.
Set the following two environment variables to point respectively to the path of the libraries and the headers
BOOST_LIBRARYDIR = C:\Boost\boost_1_77_0\lib64-msvc-14.2 BOOST_INCLUDEDIR = C:\Boost\boost_1_77_0
This will help CMake to find Boost.
Installing CGAL¶
Installing CGAL is mandatory in order to build Code_TYMPAN.
CGAL depends upon some libraries amongst which Boost and Qt or build tool such as CMake which are supposed to have already been installed. It also depends on GMP and MPFR which are available here : https://github.com/CGAL/cgal/releases/download/v5.5.1/CGAL-5.5.1-win64-auxiliary-libraries-gmp-mpfr.zip
The following procedure is adapted from CGAL documentation named Installing from the Source Archive
Download CGAL-5.5.1.zip and extract sources to C:\dists\CGAL-5.5.1.
Install GMP and MPFR libraries: go to CGAL directory (cd C:\dists\CGAL-5.5.1), dowload and extract CGAL-5.5.1-win64-auxiliary-libraries-gmp-mpfr.zip
Add environment variable CGAL_DIR with value C:\dists\CGAL-5.5.1
Building Code_TYMPAN¶
Prerequisite : Major dependencies must be installed.
First clone git repository to obtain the sources. In a Git Bash windows or a command windows with git accessible on the PATH :
C:
cd \
mkdir projects
cd projects
git clone https://gitlab.com/Code_TYMPAN/code_tympan.git
Second, download and extract Lightweight dependencies.
Third, install python libraries
pip install -U pip
pip install -U -r requirements.txt
pip install -U -r requirements-dev.txt
Fourth, check and adapt environment variables which should be set as follow :
BOOST_INCLUDEDIR = C:\Boost\boost_1_77_0
BOOST_LIBRARYDIR = C:\Boost\boost_1_77_0\lib64-msvc-14.2
CGAL_DIR = C:\dists\CGAL-5.5.1
PATH = C:\Qt\5.15.2\msvc2019_64\bin;C:\Qt\5.15.2\msvc2019_64\plugins\platforms;C:\dists\swigwin-4.0.2;C:\Program Files\doxygen\bin;C:\Program Files (x86)\Graphviz2.38\bin;C:\Boost\boost_1_77_0\lib64-msvc-14.2;%PATH%
SWIG_DIR = C:\dists\swigwin-4.0.2
SWIG_EXECUTABLE = C:\dists\swigwin-4.0.2\swig.exe
You can then build Code_TYMPAN in Release or Debug mode using CMake.
Release Build¶
Create build and install repositories :
cd C:\projects
mkdir code_tympan_build
mkdir code_tympan_install
Build and install Code_TYMPAN using CMake :
cd code_tympan_build
# Activate python virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
cmake ..\code_tympan -G "Visual Studio 16 2019" -DCMAKE_GENERATOR_TOOLSET=v142 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=C:\Qt\5.15.2\msvc2019_64\lib\cmake -DCMAKE_INSTALL_PREFIX=..\code_tympan_install -DCGAL_DIR=%CGAL_DIR% -A x64 >> output_file.txt 2>&1
# System build output written in output.txt file
cmake --build . --config Release
cmake --build . --target install --config Release
Debug Build¶
Debug and release system builds must be separated. Create build and install repositories :
cd C:\projects
mkdir code_tympan_build_d
mkdir code_tympan_install_d
Build and install Code_TYMPAN using CMake :
cd code_tympan_build_d
# Activate python virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
cmake ..\code_tympan -G "Visual Studio 16 2019" -DCMAKE_GENERATOR_TOOLSET=v142 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=C:\Qt\5.15.2\msvc2019_64\lib\cmake -DCMAKE_INSTALL_PREFIX=..\code_tympan_install_d -DCGAL_DIR=%CGAL_DIR% -A x64 >> output_file.txt 2>&1
# System build output written in output.txt file
cmake --build . --config Debug
cmake --build . --target install --config Debug
Running Tests¶
cd code_tympan_build
# Activate python virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
SetEnvTympanTests.bat
set TYMPAN_PYTHON_INTERP=C:\dists\python\venv310tympan\Scripts\python.exe
ctest -C Release --output-on-failure
Running Linters¶
cd code_tympan_build
# Activate python virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
SetEnvTympanTests.bat
# run lint target
cmake --build . --target lint
Build Documentation¶
cd code_tympan_build
# Activate python virtual environment
C:\dists\python\venv310tympan\Scripts\activate.bat
SetEnvTympanTests.bat
# run doc target
cmake --build . --target doc
Working with Visual Studio¶
In Visual Studio, please check build mode (Debug / Release) is consistent with the solution build mode.
Note
More about the CMake build system
If you want to add components or otherwise change the build system for Code_TYMPAN you might want to have a look at Build System Documentation first.
Ubuntu / Debian standard install¶
This section introduces the installation from the package manager of a Linux based distribution. It assumes a pretty recent version of the system on the date of writing, so that most packages are available from standard package repositories in a compatible version. Here we use Debian buster.
You will need to install packages first, then the Code_Tympan third party package. Build, install, running tests and documentation creation are described.
You will need to add sudo command before apt-get cause packages should be installed as administrator:
# Install needed packages:
sudo apt update
sudo apt install -y software-properties-common
sudo apt install -y cmake swig cython git
sudo apt install -y qt5-default libqt5opengl5 libqt5opengl5-dev
sudo apt install -y python3 python3-dev
sudo apt install doxygen
# Install CGAL
mkdir CGAL
cd CGAL
wget https://github.com/CGAL/cgal/releases/download/v5.5.1/CGAL-5.5.1.zip
unzip CGAL-5.5.1.zip
cd CGAL-5.5.1
# Boost
cd ../../../
mkdir boost
cd boost
wget https://boostorg.jfrog.io/artifactory/main/release/1.70.0/source/boost_1_70_0.tar.gz
tar xf boost_1_70_0.tar.gz
# clone CodeTympan
cd ..
git clone https://gitlab.com/Code_TYMPAN/code_tympan
# virtual-env
cd code_tympan
python3 -m venv env-CodeTympan
. env-CodeTympan/bin/activate
pip install -U pip
pip install -U -r requirements.txt
pip install -U -r requirements-dev.txt
# Third party install
cd 3rdparty
wget https://sourceforge.net/projects/code-tympan/files/3rdparty/Code_TYMPAN-4.3.0_third-party.zip/download -O Code_TYMPAN-4.3.0_third-party.zip
unzip Code_TYMPAN-4.3.0_third-party.zip
# build Code Tympan
cd ..
mkdir build
cd build
cmake ../ -DCMAKE_INSTALL_PREFIX=../../code_tympan_install -DPYTHON_INCLUDE_DIR=/usr/include/python3.10m/ -DCMAKE_BUILD_TYPE:STRING=Release -DCGAL_DIR=../../CGAL/CGAL-5.5.1 -DPYTHON_EXECUTABLE=../../env-CodeTympan/bin/python -DBOOST_ROOT=../../boost/boost_1_70_0
make -j4
# tests
ctest -C Release --output-on-failure
# doc
make doc
# install
make install