Skip to content

Latest commit

 

History

History
181 lines (128 loc) · 4.13 KB

CONTRIBUTING.md

File metadata and controls

181 lines (128 loc) · 4.13 KB
Raw

Contributing

General guidelines

kalmanif is developed according to Vincent Driessen's Gitflow Workflow. This means,

  • the master branch is for releases only.
  • development is done on feature branches.
  • finished features are integrated via PullRequests into the branch devel.

For a PullRequest to get merged into devel, it must pass

  • Review by one of the maintainers.
    • Are the changes introduced in scope of kalmanif?
    • Is the documentation updated?
    • Are enough reasonable tests added?
    • Will these changes break the API?
    • Do the new changes follow the current style of naming?
  • Compile / Test / Run on all target environments.

Note: The test suite detailed below is run in CI for many targets environments including,

  • Ubuntu 18.04/20.04 g++/clang++
  • MacOS 10.15
  • Visual Studio 15

Development environment

We will detail here how to set up a development environment. It is recommended to use containers if you do not want to install the dependencies on your host. You may refer to this blog post to set up a LXD container.

Dependencies

First, let's install all the dependencies,

Eigen3

Linux (Ubuntu and similar),

apt install build-essential cmake libeigen3-dev

OS X,

brew install cmake eigen

Windows,

vcpkg install eigen3:x64-windows

manif

git clone https://github.com/artivis/manif.git
cd manif && mkdir build && cd build
cmake ..
cmake --build . --config Release --target install

gnuplot (optional)

Linux (Ubuntu and similar),

apt install gnuplot

OS X,

brew install gnuplot

Windows (Chocolatey),

choco install Gnuplot

Fetching kalmanif source code

Now let us clone the kalmanif repo,

git clone https://github.com/artivis/kalmanif.git
cd kalmanif

Building kalmanif

We can now build kalmanif examples and tests,

mkdir build && cd build
cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON ..
cmake --build . --config Release

Optionally, to build the examples with plots, assuming you have installed gnuplot, add the following flag,

cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DPLOT_EXAMPLES=ON ..
cmake --build . --config Release

Running examples/tests

Examples are located in build/examples. To try one out, e.g.

cd examples
./demo_se2

See the run results on the dedicated page.

❗ Pro tip, if you only want to run the example, or to deploy your application, don't forget to compile in Release together with the appropriate optimization flags, e.g. -DBUILD_TESTING=OFF -DBUILD_EXAMPLES=ON -DPLOT_EXAMPLES=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-march=native -O3 -DNDEBUG -mtune=native -mavx2 -mfma" to get the most out of it. :heavy_exclamation_mark:

To run the C++ tests, execute the following in the build directory,

ctest --output-on-failure

Generate the documentation

To generate the Doxygen documentation,

cd kalmanif/docs
doxygen Doxyfile

Use kalmanif in your project

In your project CMakeLists.txt :

project(foo)

# Find the kalmanif library
find_package(kalmanif REQUIRED)

add_executable(${PROJECT_NAME} src/foo.cpp)
# 'Link' kalmanif interface library to the target
target_link_libraries(${PROJECT_NAME} INTERFACE kalmanif::kalmanif)
# Set c++17 flag
set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_STANDARD 17)