Using CPP on RIOT

This wiki page is meant for those who has starting difficulties at developing C++ programs to run on RIOT OS. It is focused on the native port for now. (C++ support for other platform will be implemented later ;-) ).

C++ build procedure overview

• C source file such as RIOT source file and C file in user's project directory (only files in top-level of user's project directory) and C++ source file will be compiled separately by CC (gcc) and CXX (g++), respectively.
• If there are any c++ files exists in user's project directory, CPPMIX flags will be set automatically (set means not null) or CPPMIX can be setted explicitly by user to switch the linker to CXX.
• Compiling flags for c files are defined in CFLAGS like normal C projet. Compiling flags for c++ files is derived from CFLAGS by filtering out some unwanted flags and adding some additional ones.

Variables to control C++ build procedure

• CXX: c++ compiler. (provided by RIOT in every boards (only native for now))
• CPPMIX: not null to switch the linker from LINK to CXX. (can be set automatically or manually by user)
• CXXUWFLAGS: unwanted flags to be removed from CFLAGS when compiling c++ files.
• CXXEXFLAGS: extra compiling flags for c++.

Calling between c and c++ functions

• Calling from c functions from c++ files: As RIOT source files doesn't have extern "C" in its headers right now, we need to wrap every included C header of RIOT with extern "C" when include in c++ files. For example:

extern "C" {
#include "thread.h" // RIOT's C header

#include "c_functions.h" // user's C header
}

#include <cstdio>
#include <vector>
#include "cpp_class.h" // user's C++ header

using namespace std;

• Calling from c++ functions from c files: we can't call c++ functions from c files directly. RIOT will never call user c++ function, of course, so it will be left for user to address such problem. ;-)

Writing your first application in C++

1. Create a directory for your project.
2. Create a Makefile in your project's directory. Within your project's Makefile you can define the modules you want to use. A template Makefile is available in the dist folder of the RIOT repository.
3. Defined flags in CXXUWFLAGS, CXXEXFLAGS if needed.
4. Create a file main.cpp (required) and other files (if needed) containing your source code in your project's directory. The file main.cpp is required because the RIOT compiler looks for a main.c or main.cpp file to start. The main.cpp file has to provide a main function according to this prototype: int main(void);

Now you can build your application for RIOT:

• Enter the projects directory and change to your project's directory.
• Edit the Makefile to set the variables RIOTBASE and RIOTBOARD according to where your copies of the RIOT repositories are located.
• Dependent on your target platform set the BOARD environment variable and call make, e.g. BOARD=native make.
• Now you can compile your code by calling make .
• Finally see the output of the application by running ./bin/<boardname>/<projectname>

Further development & Troubleshooting

We have noticed that a certain trouble can be different toolchain and library versions for the target platforms.

Also, if you have a linker mistake, then it can be related to the missing support of some libraries. For example in our project (using RIOT version from April 2013) we could not import the following C++ headers:

<algorithm>; <array>; <atomic>; <bitset>; <condition_variable>; <complex>; <forward_list>; <fstream>; <functional>; <future>; <iomanip>; <ios>; <iostream>; <istream>; <iterator>; <locale>; <map>; <memory>; <mutex>; <ostream>; <random>; <regex>; <sstream>; <stdexcept>; <streambuf>; <string>; <system_error>; <thread>; <tuple>; <unordered_map>; <unordered_set>; <valarray>

These are only suggestions based on our experience with using C++ on RIOT in a small project. Anyone is welcome to improve, update or extend them.