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 ;-) ).

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++.

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 set explicitly by user to switch the linker to CXX.
• Compiling flags for c files are defined in CFLAGS like normal C project. Compiling flags for c++ files is derived from CFLAGS by filtering out some unwanted flags and adding some additional ones.

Calling between c and c++ functions

• Calling c functions (e.g. RIOT's api) 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 c++ functions from c files in user project: As RIOT compiles c and c++ files separately so we can't call c++ functions from c files directly. (RIOT will never call user c++ function, of course) 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. Define 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); (cf. ./RIOT/examples/riot_and_cpp)

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>.elf

Example

You can try out riot_and_cpp project in examples directory. It demonstrates how to use c and c++ with RIOT.

Building bigger C++ project

Makefile of RIOT doesn't collect source files in sub-folders of user's project so it is up to user to build bigger project. To do that we should take care two more make variables: SRC and SRCXX containing c and c++ source files to be compiled respectively. SRC and SRCXX will not be overwritten by RIOT if they are not null. Similar, CPPMIX flag should be set explicitly in user's project makefile in case all c++ source files are in sub-folders (it will not be overwritten if not null).

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.