Setting up CMake for Eigen Library

Yes. THE EIGEN Library.
It is the library lures engineers first by its name then its capability in matrix manipulation that we've only seen in good expensive almighty slow MATLAB, specifically in C++.

Yes, from my experience so far, Eigen Library is AWESOME. It gives the users a giant freedom AND efficiency in matrix operations in a way I wouldn't even be able to even think about to implement alone.

YES IT IS FREE TO USE!

Having all those good aspects, I'd say Eigen Library isn't well documented as much. It does have a bit of tutorials to start with, which surely help, but they only cover a small portion of all of it. Seriously, it is tragic to me that someone spent so much effort and time implementing all those good stuffs as a pure contribute to developer's future, yet there are so many developers who doesn't even know those functionalities are there for them to use just because they can't figure it out with the automatically generated doxygen pages. Sure, you could spend some time searching and maybe figure out the hidden APIs and their usages, but I have to say it does require certain level of experience to do so fluently.

So, I thought it would be good to share some Eigen APIs I've figured out they are there, and explain how to use them in detail.

(If you are experienced with CMake, you might want to skip right to my github for the template code here)

Why use CMake to use Eigen Library

Eigen official webpage kindly provides a getting started tutorial. It says "it is not necessary to use CMake" to utilize the library. Well, it is not a false statement because you could manually tell everytime you compile your source on terminal with g++ command, just as in the tutorial. However, you'd probably still wish to know how to 'bind' Eigen with CMake for various reasons. For example, I often use Eigen Library in ROS, a development environment for Robotic Systems, which essentially need users to create projects based on CMake. There are plenty of other cases where you'd want to use CMake for you convenience.

How to setup CMake for Eigen Library

I consider it as a mystery why the tutorial did not give a single tip to 'bind' Eigen with CMake because it is super simple once you know how to do it. You literally just need a template, assuming Eigen Library is already installed on your system.

If you correctly initiated a CMake Project, you should have a CMakeLists.txt file. One of purposes of it is to link libraries you need for the project. In our case, we need to link Eigen Library with our project. It can simply be done by having a CMakeLists.txt as below:

cmake_minimum_required(VERSION 2.8)

project(eigen_trial) #The name of your choice for the project comes here

add_compile_options(-std=c++11) #optional to use c++11

find_package(Eigen3 REQUIRED)

link_directories(${Eigen_INCLUDE_DIRS})

add_executable(${PROJECT_NAME} "eigen_trial.cpp") #The name of the cpp file and its path can vary

target_link_libraries(${PROJECT_NAME}
   ${Eigen_LIBRARIES}
   )

Using Eigen Library

You could test if it is correctly liked to you project just by typing some lines with any text editor, but I prefer using Qt Creator for CMake projects. There are other great IDEs you could use for CMake projects with no problem such as Code Block, Visual Studio, etc.

Let jump into a simple example code that utilizes Eigen Library:

#include <iostream>
#include <eigen3/Eigen/Core>
#include <eigen3/Eigen/Dense>

int print_eigen(Eigen::MatrixX3d m)
{
    // Eigen Matrices do have rule to print them with std::cout
    std::cout << m << std::endl;
    return 0;
}

int main()
{
    Eigen::Matrix3d test; //3 by 3 double precision matrix initialization

    // Let's make it a symmetric matrix
    for(int i=0; i<3; i++)
    {
        for(int j=0; j<3; j++)
            test(i,j) = (i+1)*(1+j);
    }

    // Print
    print_eigen(test);

    return 0;
}

If you are using an IDE, you should notice including Eigen library on 2nd and 3rd line do not cause an error any more. In some cases, however, you need to omit eigen3/ part. (i.e. #include <Eigen/Dense> instead of #include <eigen3/Eigen/Dense>)

Here's the output when you successfully build and run the project:

1 2 3
2 4 6
3 6 9

jeeho-ahn/eigen_cmake.md