MRC/Tutorials/Setting up your project

Of course, we not only want to use software during this course, but we want to create some! Let's create a workspace directory in which we will put this code:

mkdir ~/emc

Let's start off with a simple example project. Go inside the ~/emc directory, and create a new folder with the name awesome_project:

cd ~/emc
mkdir awesome_project

Often, the code files are not put directly in the root of a folder, but in a directory called src. This stands for source, and is called this way because the files in there are the source of the compilation process, and are converted into binaries (files that are no longer human-readable, but are understandable for the machine). So, let's go. Remember that when using cd (and many other commands in linux) you can use tab-completion to type quicker, i.e, try:

cd a<<< now push the TAB key >>>

You will see that the terminal fills out the rest, because awesome_project is the only directory in the current directory that starts with an a. Ok, create the src directory, and go inside:

mkdir src
cd src

Finally, let's do some programming! You should have finished the C++ tutorials by now, so you know how to create a basic C++ program. Let us do it now. Open your favourite editor to create a file called example.cpp and put some code inside:

#include <iostream>

int main()
{
    std::cout << "Hello world!" << std::endl;
    return 0;
}

Remember that you can compile the project using g++:

g++ -o example example.cpp

This will generate a file called example that you can run. Now, actually, our nice src is already not as clean as it should be. It should contain only source files, not binaries! No worries, let's go one directory down:

cd ..

Create a bin folder for our libraries:

mkdir bin

And run compilation as follows:

g++ -o bin/example src/example.cpp

Now our binary is create in the bin directory, while the source is in src: nicely seperated! You can run the program using:

bin/example

By the way, just remove the example binary we created 'wrongly' in the src directory using:

 rm src/example

And we are good to go.

Using the EMC framework

So, we've got a C++ source file that we can compile, but it is still not very useful. We have to build software that runs on a robot and performs the complex task of solving a maze. Starting from scratch would take a lot of time, but fortunately a lot is already provided! Actually it was already secretly sitting on your computer, being installed by the install script. This software that is provided is not something that is runnable on its own, but a set of functions and C++ classes that we can use in our own project. Such as set of reusable software parts is called a software library. Now, we have to include this installed library in the project.

Open the example.cpp file, and add change it to the following:

#include <emc/engine.h>

int main()
{
    emc::Engine engine;
    return 0;
}

The include statement on top includes the emc framework in your source file, which means that all functions, classes, etc declared there can be used by your project. The engine object is something we will use to build our application with. Don't worry about it now, we'll get back to that later.

Try to compile the project (make sure to 'be' in your project root, i.e.: ~/emc/awesome_project):

g++ -o bin/example src/example.cpp

Woah, errors! Note that the error states something about undefined reference. We included emc/engine.h so we should be fine right? No: often *.h-files only declare functions etc, but they do not define them, that is: they tell the compiler something with that name is out there, but do not provide the actual implementation. We need to tell the compiler where the implementation, which is already compiled into binary form, is. This is called linking, and we need to specify it in the g++ command:

g++ -o bin/example src/example.cpp -lemc-framework

Here, the -l specifies g++ should link the program to the library that is specified after that: emc-framework. For those who are wondering, the compiler does not grab emc-framework out of thin air. Take a look in the /usr/lib directory: you will find libemc-framework.so sitting there. The extension so stands for shared object: it is a piece of software that can be shared across different applications.

CMake

Before we are going to do something useful with the provided library