|
|
[[_TOC_]]
|
|
|
|
|
|
# Build from source
|
|
|
When you want to use `PeTrack` on a operating system we do not provide an executable or you want to improve `PeTrack`, you need to build `PeTrack` from source. In the following the dependencies and the building process is described.
|
|
|
|
|
|
## Dependencies
|
|
|
In order to compile `PeTrack` it is necessary to first install the required libraries.
|
|
|
|
|
|
### Compilers
|
|
|
Any compiler with support for C++ 17 should work. At the moment the following compilers are tested:
|
|
|
- MinGW 8.1 on Windows
|
|
|
- g++-10 on Linux (Arch)
|
|
|
|
|
|
### Required tools and libraries
|
|
|
For using `PeTrack` following tools and libraries are needed:
|
|
|
- git
|
|
|
- CMake (>=
|
|
|
- Qt (>= 5.14)
|
|
|
- OpenCV (== 4.2)
|
|
|
- Qwt (>= 5.6)
|
|
|
|
|
|
When developing `PeTrack` and using the test framework following additional tools and libraries are needed:
|
|
|
- Catch2
|
|
|
- trompeloeil
|
|
|
- Python (>= 3.6)
|
|
|
- pytest
|
|
|
|
|
|
## Linux/MacOS/Windows
|
|
|
|
|
|
Before starting building `PeTrack` it is necessary to install the required dependencies. If done, you can start to build `PeTrack`. Here only the process to compile with the command line is described. You can use your favorite IDE (which supports CMake projects), e.g., QtCreator, CLion, Visual Studio Code, Visual Studio, XCode.
|
|
|
|
|
|
For windows users, the linux notation of paths `/` instead of `\` is used. It is highly recommended to install [Windows Terminal](https://aka.ms/terminal) for the same behavior.
|
|
|
|
|
|
|
|
|
### Get the code
|
|
|
In this tutorial we will assume that we start at `/home/dev/`. The following notation will be used for the commands (when no <command> is displayed, it shows the result of the previous command, usually a change of directory):
|
|
|
```
|
|
|
[<current_directory>] $ <command>
|
|
|
```
|
|
|
|
|
|
First thing you need to do is clone the repository to get the source code. This can be done in any directory. Be aware that a new directory with the name `petrack` will be created.
|
|
|
|
|
|
```
|
|
|
[/home/dev] $ git clone https://jugit.fz-juelich.de/ped-dyn-emp/petrack.git
|
|
|
```
|
|
|
|
|
|
### How to build (User)
|
|
|
After getting the source code, you need to switch to the newly created directory:
|
|
|
|
|
|
```
|
|
|
[/home/dev/] $ cd petrack
|
|
|
[/home/dev/petrack] $
|
|
|
```
|
|
|
|
|
|
Next you need to create a build directory in which CMake will create all the files needed for compiling `PeTrack`. It can also be used to have different executable for different versions of `PeTrack`. Also we need to move into the build directory.
|
|
|
|
|
|
```
|
|
|
[/home/dev/petrack] $ mkdir build
|
|
|
[/home/dev/petrack] $ cd build
|
|
|
[/home/dev/petrack/build] $
|
|
|
```
|
|
|
|
|
|
Now you can start to build `PeTrack`.
|
|
|
```
|
|
|
[/home/dev/petrack/build] $ cmake -DCMAKE_BUILD_TYPE=Release ..
|
|
|
[/home/dev/petrack/build] $ cmake --build .
|
|
|
```
|
|
|
|
|
|
Afterwards `PeTrack` can be executed with:
|
|
|
```
|
|
|
[/home/dev/petrack/build] $ ./petrack
|
|
|
```
|
|
|
|
|
|
When you add your building directory to your path (here `/home/dev/petrack/build`). You can call `PeTrack` from anywhere with
|
|
|
```
|
|
|
[/home/dev/some/where/else] $ petrack
|
|
|
```
|
|
|
|
|
|
Please check the documentation of your operating system how to do this.
|
|
|
|
|
|
|
|
|
### How to build (Developer)
|
|
|
When you want to start developing on `PeTrack` following might also be helpful, it will help you to setup also the test suite and give some more compile options for debugging proposes.
|
|
|
|
|
|
We start right after the users compiled their version of `PeTrack`, hence the repository is already cloned to `/home/dev/petrack/` and a build directory `/home/dev/petrack/build` has been created.
|
|
|
|
|
|
To run the tests you first need to download the test data, which is stored in the git large file system. To do so you first need to download everything:
|
|
|
```
|
|
|
[/home/dev/petrack] $ git lfs install --skip-smudge
|
|
|
[/home/dev/petrack] $ git lfs pull
|
|
|
```
|
|
|
|
|
|
Now to compile a version of `PeTrack` which allows better debugging and also creates the unit tests. To have the fast `Release` version and the slower `Debug` version, we create a new directory and run
|
|
|
`cmake` with additional arguments:
|
|
|
|
|
|
```
|
|
|
[/home/dev/petrack] $ mkdir build-debug
|
|
|
[/home/dev/petrack] $ cd build-debug
|
|
|
[/home/dev/petrack/build-debug] $ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_UNIT_TESTS=ON ..
|
|
|
[/home/dev/petrack/build-debug] $ cmake --build .
|
|
|
```
|
|
|
|
|
|
Afterwards the debuggable executable can be called with:
|
|
|
|
|
|
```
|
|
|
[/home/dev/petrack/build-debug] $ ./petrack
|
|
|
```
|
|
|
|
|
|
To run the unit tests just execute, this will just take a couple of seconds:
|
|
|
```
|
|
|
[/home/dev/petrack/build-debug] $ ./tests/unit_test/petrack_tests
|
|
|
```
|
|
|
|
|
|
To run the regression tests, you need to switch to the regression test directory and call python to run the tests. Be aware that these tests may run up to half an hour depending on the machine!
|
|
|
|
|
|
```
|
|
|
[/home/dev/petrack/build-debug] $ cd ../tests/regression_test/tests
|
|
|
[/home/dev/petrack/tests/regression_test/tests] $ python -m pytest --path=../../../build-debug/petrack
|
|
|
```
|
|
|
|
|
|
### CMake configuration flags
|
|
|
Following CMake options might be helpful for you when compiling, see [CMake Documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html) for more details. Some of higher interest are explained here:
|
|
|
- `-G` sets the generator, which is used to compile the source code later. Default on linux/MacOS are `Makefiles` and on Windows `Visual Studio XX YEAR` depending on the installed MSVS version. Also other generators as `Ninja` can be used. Usage:
|
|
|
```
|
|
|
$ cmake -G Ninja <path_to_cmakelist>
|
|
|
```
|
|
|
- `-DCMAKE_BUILD_TYPE=` sets the build type. Typical options are `Release` for faster and better optimized builds. And `Debug` for slower debugging builds. Usage:
|
|
|
```
|
|
|
$ cmake -DCMAKE_BUILD_TYPE=Debug <path_to_cmakelist>
|
|
|
```
|
|
|
- `-DCMAKE_PREFIX_PATH=[paths where additionally to search for libraries etc]` adds directories where CMake will search for libraries, useful if you do not want to install a library to the `PATH`.
|
|
|
- `-DCMAKE_CXX_COMPILER=` sets the C++ compilers used when building the project. Usage:
|
|
|
```
|
|
|
$ cmake -DCMAKE_CXX_COMPILER=clang++ <path_to_cmakelist>
|
|
|
```
|
|
|
|
|
|
We extended the options with our own, which allow better configuration of the projects:
|
|
|
- `-DBUILD_UNIT_TESTS=` can be set to `ON` or `OFF`. Defines with the unit tests are build. Default if `ON`
|
|
|
|
|
|
### Known issues
|
|
|
- CMake fails when searching one of the needed libraries.
|
|
|
- Possible solution: Check if the libraries are installed to your `PATH` or use `-DCMAKE_PREFIX_PATH` CMake option
|
|
|
|
|
|
- Change of CMake option seem to have no influence
|
|
|
- Possible solution: It may be necessary to delete the CMakeCache and run CMake again with the new options.
|
|
|
|