Skip to content

Commit 6fdc1e4

Browse files
pablogs9pablogs9
authored
Add static library tutorial (#284)
* Initial * Update * Update * Fix CI * Address changes
1 parent 8cde3f1 commit 6fdc1e4

2 files changed

Lines changed: 119 additions & 0 deletions

File tree

‎_data/docs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
- tutorials/advanced/tracing
6262
- tutorials/advanced/benchmarking
6363
- tutorials/advanced/zephyr_emulator
64+
- tutorials/advanced/create_custom_static_library
6465

6566
- title: Demos
6667
docs:

‎_docs/tutorials/advanced/create_custom_static_library/index.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Creating custom static micro-ROS library
3+
permalink: /docs/tutorials/advanced/create_custom_static_library/
4+
---
5+
6+
This tutorial aims at providing step-by-step guidance for those users interested in compiling micro-ROS as a standalone library in order to integrate it in custom development tools.
7+
8+
This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms.
9+
10+
Once your micro-ROS workspace is created and the `micro_ros_setup` tool is installed, we are going to prepare the micro-ROS environment:
11+
12+
```bash
13+
ros2 run micro_ros_setup create_firmware_ws.sh generate_lib
14+
```
15+
16+
Once all the packages are downloaded, we need to create a couple of files in order to crosscompile a custom static library and a set of header files:
17+
18+
```bash
19+
touch my_custom_toolchain.cmake
20+
touch my_custom_colcon.meta
21+
```
22+
23+
## Example of a CMake toolchain
24+
25+
For example for a Cortex M3 a sample toolchain could be:
26+
27+
```cmake
28+
set(CMAKE_SYSTEM_NAME Generic)
29+
set(CMAKE_CROSSCOMPILING 1)
30+
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
31+
32+
# SET HERE THE PATH TO YOUR C99 AND C++ COMPILERS
33+
set(CMAKE_C_COMPILER gcc)
34+
set(CMAKE_CXX_COMPILER g++)
35+
36+
set(CMAKE_C_COMPILER_WORKS 1 CACHE INTERNAL "")
37+
set(CMAKE_CXX_COMPILER_WORKS 1 CACHE INTERNAL "")
38+
39+
# SET HERE YOUR BUILDING FLAGS
40+
set(FLAGS "-O2 -ffunction-sections -fdata-sections -fno-exceptions -mcpu=cortex-m3 -nostdlib -mthumb --param max-inline-insns-single=500 -DF_CPU=84000000L -D'RCUTILS_LOG_MIN_SEVERITY=RCUTILS_LOG_MIN_SEVERITY_NONE'" CACHE STRING "" FORCE)
41+
42+
set(CMAKE_C_FLAGS_INIT "-std=c11 ${FLAGS} -DCLOCK_MONOTONIC=0 -D'__attribute__(x)='" CACHE STRING "" FORCE)
43+
set(CMAKE_CXX_FLAGS_INIT "-std=c++11 ${FLAGS} -fno-rtti -DCLOCK_MONOTONIC=0 -D'__attribute__(x)='" CACHE STRING "" FORCE)
44+
45+
set(__BIG_ENDIAN__ 0)
46+
```
47+
48+
## Example of a colcon meta file
49+
50+
A sample colcon.meta file with micro-ROS external transports could be:
51+
52+
```json
53+
{
54+
"names": {
55+
"tracetools": {
56+
"cmake-args": [
57+
"-DTRACETOOLS_DISABLED=ON",
58+
"-DTRACETOOLS_STATUS_CHECKING_TOOL=OFF"
59+
]
60+
},
61+
"rosidl_typesupport": {
62+
"cmake-args": [
63+
"-DROSIDL_TYPESUPPORT_SINGLE_TYPESUPPORT=ON"
64+
]
65+
},
66+
"rcl": {
67+
"cmake-args": [
68+
"-DBUILD_TESTING=OFF",
69+
"-DRCL_COMMAND_LINE_ENABLED=OFF",
70+
"-DRCL_LOGGING_ENABLED=OFF"
71+
]
72+
},
73+
"rcutils": {
74+
"cmake-args": [
75+
"-DENABLE_TESTING=OFF",
76+
"-DRCUTILS_NO_FILESYSTEM=ON",
77+
"-DRCUTILS_NO_THREAD_SUPPORT=ON",
78+
"-DRCUTILS_NO_64_ATOMIC=ON",
79+
"-DRCUTILS_AVOID_DYNAMIC_ALLOCATION=ON"
80+
]
81+
},
82+
"microxrcedds_client": {
83+
"cmake-args": [
84+
"-DUCLIENT_PIC=OFF",
85+
"-DUCLIENT_PROFILE_UDP=OFF",
86+
"-DUCLIENT_PROFILE_TCP=OFF",
87+
"-DUCLIENT_PROFILE_DISCOVERY=OFF",
88+
"-DUCLIENT_PROFILE_SERIAL=OFF",
89+
"-UCLIENT_PROFILE_STREAM_FRAMING=ON",
90+
"-DUCLIENT_PROFILE_CUSTOM_TRANSPORT=ON"
91+
]
92+
},
93+
"rmw_microxrcedds": {
94+
"cmake-args": [
95+
"-DRMW_UXRCE_MAX_NODES=1",
96+
"-DRMW_UXRCE_MAX_PUBLISHERS=5",
97+
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=5",
98+
"-DRMW_UXRCE_MAX_SERVICES=1",
99+
"-DRMW_UXRCE_MAX_CLIENTS=1",
100+
"-DRMW_UXRCE_MAX_HISTORY=4",
101+
"-DRMW_UXRCE_TRANSPORT=custom"
102+
]
103+
}
104+
}
105+
}
106+
```
107+
108+
## Building the custom library
109+
110+
Once you have both files ready, just run the build step in the micro-ROS build system:
111+
112+
```bash
113+
ros2 run micro_ros_setup build_firmware.sh $(pwd)/my_custom_toolchain.cmake $(pwd)/my_custom_colcon.meta
114+
```
115+
116+
Once the build finishes you will have a precompiled static library with all the micro-ROS functionality in `firmware/build/libmicroros.a` and you will have all the required headers for your application in `firmware/include`.
117+
118+
Just use them to link against in your development tools, and remember **if you are using a commercially available board we are accepting micro-ROS ports from the community**.

0 commit comments

Comments
 (0)