C/C++ 应用开发入门

本文档讲在 RK3588 平台上开发 C/C++ 应用的一整套流程：搭建编译环境、常用编译命令、Makefile / CMake 工程组织、共享库与多线程，最后是远程调试。这里说的应用指用户态程序，也就是你自己编写的普通程序，和内核代码是两回事。

适用范围： 在 x86 PC 上交叉编译 ARM64 程序，部署到 RK3588 Linux 6.1 Debian 12 / Ubuntu 22.04 系统（C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板）运行。

---

1. 概念基础

1.1 开发流程

源代码 (.c/.cpp)
  ↓ 交叉编译 (aarch64-linux-gnu-gcc)
可执行文件 (ELF, ARM64)
  ↓ scp / tftp / adb push
RK3588 目标板运行

整个流程分三步：在 PC 上写代码，用交叉编译器编出 ARM64 可执行文件，再把可执行文件传到板子上运行。所谓交叉编译，就是用 x86 PC 给板子的 ARM64 CPU 编程序：两种机器架构不同，PC 上自带的编译器干不了这活，必须用专门的交叉编译器。scp（通过 SSH 拷贝文件）、tftp、adb push 都是常用的传文件手段。

RK3588 Linux SDK 使用 GCC 10.3 交叉编译工具链，支持 C99 / C11 / C++11 / C++14 / C++17。

1.2 应用场景

• 系统服务 / 守护进程（长时间在后台跑的程序）
• 音视频处理（多媒体）
• 网络应用（TCP/UDP、HTTP）
• NPU / GPU 加速

---

2. 准备工作

2.1 硬件清单

组件	型号/规格	数量	备注
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板	1
调试串口线	USB 转 TTL（3.3V）	1	波特率 1500000
网线	标准 RJ45	1	用于 scp
电源适配器	12V/2A DC	1

2.2 硬件确认

动手前先确认板子系统符合预期。在开发板上（串口终端或 SSH 都行）执行下面两条命令：

uname -m
# 输出：aarch64

gcc --version | head -1
# 输出：gcc (Debian 12.2.0-14+deb12u1) 12.2.0

uname -m 输出 aarch64，说明架构和后面用的 ARM64 工具链对得上。本机的 gcc 12.2.0 也可以直接在板上编译程序（这种做法叫 native 编译），在板上快速验证时很方便。

---

3. 软件准备

3.1 交叉编译工具链（PC 端）

交叉编译工具链是装在 PC 上、产出 ARM64 代码的编译器，最明显的特征是可执行文件名带 aarch64-linux-gnu- 前缀。RK3588 Linux SDK 自带一套：

# SDK 工具链路径
SDK_DIR/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/

# 添加到 PATH
export PATH=$SDK_DIR/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin:$PATH

# 验证
aarch64-linux-gnu-gcc --version
# 输出：aarch64-linux-gnu-gcc (GCC) 10.3.1 20210621

把工具链加进 PATH 后执行验证命令，看到上面的版本号输出，工具链就能用了。如果没装 SDK，也可以在 Ubuntu/Debian PC 上直接装发行版工具链：

sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

3.2 常用编译选项速查

选项	作用
-o	指定输出文件
-c	仅编译不链接（生成 .o）
-g	带调试信息
-O0/-O2/-O3	无 / 中 / 高优化
-Wall	启用常用警告
-std=c99/c11/c++17	指定语言标准
-fPIC	编译位置无关代码（动态库用）
-static	静态链接
-I	头文件搜索路径
-L	库文件搜索路径
-l	链接指定库（去掉 lib 前缀）

---

4. 第一个 C / C++ 程序

4.1 hello.c

先写一个最小的 C 程序，调用 uname 打印内核版本和 CPU 架构：

// hello.c
#include <stdio.h>
#include <sys/utsname.h>

int main(void)
{
    struct utsname buf;
    if (uname(&buf) == 0) {
        printf("System: %s %s\n", buf.sysname, buf.release);
        printf("Machine: %s\n", buf.machine);
    }
    return 0;
}

[电脑端] 交叉编译，然后用 file 命令确认产物的架构：

aarch64-linux-gnu-gcc -o hello hello.c
file hello
# 输出：ELF 64-bit LSB executable, ARM aarch64, ...

file 输出里有 ARM aarch64，说明编译目标正确。这个二进制在 x86 PC 上跑不起来，要发给板子。

[电脑端] 推送到开发板（IP 按网段）：

scp hello root@192.168.49.60:/root/

[开发板] 加执行权限后运行：

chmod +x /root/hello
/root/hello

板子上也能 native 编译这个程序，省去交叉编译环节。下面是在设备上用 gcc 12.2.0 原生编译并验证的过程：

gcc -O2 -o /tmp/hello /tmp/hello.c
file /tmp/hello
# /tmp/hello: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV),
#   dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, ...
/tmp/hello

System: Linux 6.1.141
Machine: aarch64

输出两行说明程序在板上跑通了：内核版本 6.1.141，架构 aarch64。

设备上已预装 gcc (Debian 12.2.0) 12.2.0 和交叉工具链 /usr/bin/aarch64-linux-gnu-gcc（见 9.1 节验证），native 编译和交叉编译两条路都能直接走。

4.2 hello.cpp（C++17）

这个例子用了 C++17 的两个特性：结构化绑定 auto [min_it, max_it] 和 std::minmax_element，求数组的最小值、最大值和总和：

// hello.cpp
#include <iostream>
#include <vector>
#include <algorithm>
#include <numeric>

int main()
{
    std::vector<int> nums = {1, 2, 3, 4, 5, 6, 7, 8};
    auto [min_it, max_it] = std::minmax_element(nums.begin(), nums.end());
    int sum = std::accumulate(nums.begin(), nums.end(), 0);

    std::cout << "RK3588 C++17 Test" << std::endl;
    std::cout << "Min: " << *min_it << " Max: " << *max_it << " Sum: " << sum << std::endl;
    return 0;
}

编译命令里的 -std=c++17 告诉编译器按 C++17 标准编译：

aarch64-linux-gnu-g++ -std=c++17 -O2 -o hello_cpp hello_cpp.cpp

下面的输出取自设备上的 native 编译：

g++ -std=c++17 -O2 -o /tmp/hello_cpp /tmp/hello_cpp.cpp
/tmp/hello_cpp

RK3588 C++17 Test
Min: 1 Max: 8 Sum: 36

C++17 结构化绑定 auto [min_it, max_it] 和 std::minmax_element 在 gcc 12.2.0 下均工作。

---

5. 工程管理

源文件一多，就该用构建工具管编译规则，不要每次手敲 gcc 命令。Make 和 CMake 是最常见的两种选择。

5.1 Makefile 示例

Makefile 是 make 命令读的规则文件，记录每个源文件怎么编译、怎么链接。下面这份 Makefile 里，CROSS_COMPILE ?= 用变量换编译器：在 PC 上交叉编译时填交叉前缀，在板上就留空，直接用板子自带的 gcc 和 g++。deploy 目标会先编译再用 scp 推到板子，省一次手动拷贝：

CROSS_COMPILE ?= aarch64-linux-gnu-
CC  = $(CROSS_COMPILE)gcc
CXX = $(CROSS_COMPILE)g++

CFLAGS   = -Wall -O2 -g
CXXFLAGS = -Wall -O2 -g -std=c++17
LDFLAGS  =

C_SRCS   = main.c utils.c
CXX_SRCS = app.cpp logger.cpp
C_OBJS    = $(C_SRCS:.c=.o)
CXX_OBJS  = $(CXX_SRCS:.cpp=.o)
OBJS      = $(C_OBJS) $(CXX_OBJS)
TARGET    = myapp

.PHONY: all clean deploy

all: $(TARGET)

$(TARGET): $(OBJS)
	$(CXX) $(LDFLAGS) -o $@ $^

%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

%.o: %.cpp
	$(CXX) $(CXXFLAGS) -c -o $@ $<

clean:
	rm -f $(OBJS) $(TARGET)

deploy: $(TARGET)
	scp $(TARGET) root@192.168.49.60:/root/

make           # 编译
make clean     # 清理
make deploy    # 编译并推送到开发板

下面是在设备上用板子自带工具链、CROSS_COMPILE 留空做的构建：

make CROSS_COMPILE=
./myapp

gcc -Wall -O2 -g -c -o main.o main.c
gcc -Wall -O2 -g -c -o utils.o utils.c
g++ -Wall -O2 -g -std=c++17 -c -o logger.o logger.cpp
g++  -o myapp main.o utils.o logger.o
[LOG] app start
add(3,4) = 7
[LOG] app end

5.2 CMake + 交叉编译

CMake 比 Make 再高一层：你写 CMakeLists.txt 描述工程，CMake 负责生成 Makefile。下面把语言标准设成 C11 / C++17，并列出源文件：

# CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(myapp C CXX)
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_compile_options(-Wall -O2)
add_executable(myapp src/main.cpp src/utils.cpp src/logger.cpp)
target_link_libraries(myapp pthread)

交叉编译时还要配一个工具链文件，告诉 CMake 用哪个交叉编译器、去哪找目标系统的头文件和库；那份目标板的头文件和库目录就叫 sysroot：

电脑端 工具链文件 toolchain-aarch64.cmake：

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-aarch64.cmake ..
make

下面的输出取自设备上的 native 构建（cmake 3.25.1，没有用 toolchain 文件）：

mkdir build && cd build && cmake .. && make
./myapp

-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- Configuring done
-- Generating done
-- Build files have been written to: .../build
[ 25%] Building CXX object CMakeFiles/myapp.dir/src/main.cpp.o
[ 50%] Building CXX object CMakeFiles/myapp.dir/src/utils.cpp.o
[ 75%] Building CXX object CMakeFiles/myapp.dir/src/logger.cpp.o
[100%] Linking CXX executable myapp
[LOG] cmake demo start
add(5,7) = 12

有个容易踩的坑：logger.cpp 里的 log_msg 要么在 .h 和 .cpp 两侧都加 extern "C"，要么用 extern "C" 包裹函数体；.cpp 端漏加的话，链接时会报 undefined reference to 'log_msg'（踩过）。

---

6. 共享库 / 多线程

6.1 编译共享库

共享库就是 .so 文件：把常用代码单独编译一份，运行时由多个程序共同加载。-fPIC 生成位置无关代码（共享库必须），-shared 表示输出是库文件，-L. 让链接器在当前目录找库，-lmylib 指的是 libmylib.so（引用时去掉 lib 前缀和 .so 后缀）：

// mylib.c
#include <stdio.h>
void greet(const char *name) { printf("Hello, %s!\n", name); }
int add(int a, int b) { return a + b; }

aarch64-linux-gnu-gcc -fPIC -shared -o libmylib.so mylib.c
aarch64-linux-gnu-gcc -o use_lib use_lib.c -L. -lmylib

# 推送到开发板
scp libmylib.so use_lib root@192.168.49.60:/root/

# 开发板上运行
ssh root@192.168.49.60
cd /root
export LD_LIBRARY_PATH=/root:$LD_LIBRARY_PATH
./use_lib

程序运行时加载器并不知道 libmylib.so 放在哪，所以要先把库所在目录加进 LD_LIBRARY_PATH（加载器查找动态库的环境变量），再运行程序。下面的输出取自设备上的 native 编译：

gcc -fPIC -shared -o libmylib.so mylib.c
gcc -o use_lib use_lib.c -L. -lmylib
LD_LIBRARY_PATH=. ./use_lib

libmylib.so: ELF 64-bit LSB shared object, ARM aarch64, ...
use_lib:     ELF 64-bit LSB pie executable, ARM aarch64, ...
Hello, RK3588!
add(10,20) = 30

输出里的 Hello, RK3588! 和 add(10,20) = 30 说明库里两个函数都调用成功。

6.2 多线程（pthread）

pthread 是 Linux 上的线程库。示例启动 8 个线程，每个线程打印自己落在哪个 CPU 核上。RK3588 有 8 个核（4×A76 + 4×A55），8 个线程正好能散到各个核：

// pthread_example.c
#include <stdio.h>
#include <pthread.h>
#include <unistd.h>
#define NUM_THREADS 8   /* RK3588: 4×A76 + 4×A55 */

void *worker(void *arg) {
    int id = *(int *)arg;
    printf("Thread %d on CPU %d\n", id, sched_getcpu());
    return NULL;
}

int main(void) {
    pthread_t threads[NUM_THREADS];
    int ids[NUM_THREADS];
    for (int i = 0; i < NUM_THREADS; i++) {
        ids[i] = i;
        pthread_create(&threads[i], NULL, worker, &ids[i]);
    }
    for (int i = 0; i < NUM_THREADS; i++) pthread_join(threads[i], NULL);
    return 0;
}

aarch64-linux-gnu-gcc -o pthread_demo pthread_example.c -lpthread

下面是设备上 native 编译并运行的验证，8 个线程分散在 8 个 CPU 上；nproc 输出 8 表示板子有 8 个逻辑核：

gcc -O2 -o pthread_demo pthread_example.c -lpthread
nproc   # 8
./pthread_demo

Thread 0 on CPU 6
Thread 1 on CPU 1
Thread 2 on CPU 0
Thread 3 on CPU 4
Thread 5 on CPU 5
Thread 4 on CPU 3
Thread 6 on CPU 0
Thread 7 on CPU 1

注意：示例代码缺 #include <sched.h>（sched_getcpu 需要它），编译会出 implicit declaration 警告但运行正常（glibc 兼容），建议加上头文件。

---

7. ELF 文件分析

ELF 是 Linux 上可执行文件的格式。下面四条命令分别回答四个问题：程序是什么架构、依赖哪些动态库、定义了哪些函数、体积多大：

# 架构
file myapp
# 输出：ELF 64-bit LSB executable, ARM aarch64, ...

# 动态库依赖
aarch64-linux-gnu-readelf -d myapp | grep NEEDED

# 符号
aarch64-linux-gnu-nm myapp | grep " T "

# 体积
size myapp

下面的输出取自在设备上对 6.1 节的 use_lib 跑这几条命令：

file use_lib
readelf -d use_lib | grep NEEDED
nm use_lib | grep " T "
size use_lib

use_lib: ELF 64-bit LSB pie executable, ARM aarch64, ...
 0x... (NEEDED)  libmylib.so
 0x... (NEEDED)  libc.so.6
0000000000000850 T _fini
0000000000000638 T _init
0000000000000814 T main
0000000000000700 T _start
   text    data     bss     dec     hex   filename
   1802     656       8    2466     9a2   use_lib

两行 NEEDED 说明这个程序运行时要依赖 libmylib.so 和 libc.so.6。

---

8. 远程调试（GDB）

远程调试的思路是：板子上跑一个小服务程序 gdbserver，由它控制被调试进程；PC 上跑 gdb 客户端，通过 TCP 连过去。这样程序在板子上运行，你在 PC 上打断点、看变量。

开发板 启动 gdbserver：

apt install -y gdbserver
gdbserver :2345 ./hello

电脑端 远程调试：

aarch64-linux-gnu-gdb ./hello
(gdb) target remote 192.168.49.60:2345
(gdb) break main
(gdb) continue
(gdb) print i

GDB 客户端在 x86 PC，gdbserver 在 ARM64 板，两端通过 TCP 通信。

当时 PC 端 aarch64-gdb 缺失，没跑真正的远程 session；改用板上本机 gdb 连本机 gdbserver 验证了流程（设备上 gdbserver 13.1 + gdb 13.1）：

# 板端
setsid gdbserver :2345 /var/tmp/gdb_target > /tmp/gdb.log 2>&1 &
ss -tln | grep 2345
# LISTEN 0  0  *:2345  *:*

# 板端 gdb 客户端
gdb /var/tmp/gdb_target
(gdb) target remote localhost:2345
(gdb) break compute
(gdb) continue

Breakpoint 1, compute (n=100) at gdb_target.c:5
5           int s = 0;
(gdb) print n
$1 = 100
(gdb) bt 3
#0  compute (n=100) at gdb_target.c:5
#1  0x... in main () at gdb_target.c:10

输出里断点停在 compute (n=100)，print n 返回 100，函数回溯正常，说明这套调试流程走得通。

实际使用时记住三点：

1. 目标二进制必须带 -g 编译；无调试符号时断点能设，但寄存器和栈不可读。
2. gdbserver 默认会等客户端 attach；用 setsid ... & 让它完全脱离终端。
3. 客户端首次 attach 时会从远端 read 动态库和符号，速度慢（5-10s），可用 set sysroot / 改用本地符号。

---

9. 故障排除

9.1 找不到交叉编译器

先检查 PATH 里有没有工具链路径：

echo $PATH | grep aarch64   # 路径是否包含工具链
ls /usr/bin/aarch64-linux-gnu-gcc 2>/dev/null

没装的话安装：

sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

设备上已经预装了 aarch64 交叉工具链：

$ ls -la /usr/bin/aarch64-linux-gnu-gcc
-rwxr-xr-x 1 root root ... /usr/bin/aarch64-linux-gnu-gcc
$ /usr/bin/aarch64-linux-gnu-gcc --version | head -1
aarch64-linux-gnu-gcc (Debian 12.2.0-14+deb12u1) 12.2.0

9.2 目标板运行报 "ld-linux-aarch64.so.1 缺失"

这个报错的意思是运行时找不到 ARM64 的动态链接器。最快的办法是改静态链接，把库全部打进可执行文件，体积大一些但不依赖运行环境里的库：

# 用静态编译
aarch64-linux-gnu-gcc -static -o hello hello.c

9.3 段错误

带调试信息、关优化重新编译，这样调试时才能对上源码，然后用 gdbserver + aarch64-linux-gnu-gdb 远程调试（流程见第 8 节）：

aarch64-linux-gnu-gcc -g -O0 -o hello hello.c
# 用 gdbserver + aarch64-linux-gnu-gdb 远程调试

---

相关文档

• ch02 Python 应用开发
• ch03 Qt 嵌入式开发实战
• ch05 网络编程与应用
• system-development/ch01 Linux SDK 编译