Using CPP on RIOT

This wiki page is meant for those who has starting difficulties at developing C++ programs to run on RIOT OS. We currently support the basic C++, and OOP programming in native and several arm platforms. C++ supported platforms are marked in this list

Dependencies

On 64-bit host systems you need to install a cross-compiler gcc for 32-bit platforms to build for Board: native. Find below the required packages for your Linux distribution

• Ubuntu: gcc-multilib, g++-multilib (for GCC).

Variables to control C++ build procedure

• CXX: c++ compiler. (provided by RIOT in every boards)
• 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.

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.

A note when you're building a 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. In this circumstance, CPPMIX flag should be set explicitly in user's project makefile in case all c++ source files are in sub-folders.

Reduce C++ overheads for embedded platforms

To reduce the overheads when compile C++, you may want to add -fno-exceptions and -fno-rtti to CXXEXFLAGS in your project's makefile.

CXXEXFLAGS += -fno-exceptions -fno-rtti

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 error(s), 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.