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
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
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++
- Create a directory for your project.
- Create a
Makefilein your project's directory. Within your project's
Makefileyou can define the modules you want to use. A template
Makefileis available in the
distfolder of the
- Define flags in CXXUWFLAGS, CXXEXFLAGS if needed.
- Create a file
main.cpp(required) and other files (if needed) containing your source code in your project's directory. The file
main.cppis required because the RIOT compiler looks for a
main.cppfile to start. The
main.cppfile 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
RIOTBOARDaccording to where your copies of the RIOT repositories are located.
- Dependent on your target platform, set the
BOARDenvironment variable and call
- Now you can compile your code by calling
- Finally see the output of the application by running
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-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.