用 xmake 搭建 STM32 HAL 工程与自定义 C 构建链

一、先看一个最小工程#

xmake create 出来的工程长这样(参考官方文档 create-project 页面):

1
hello
2
├── src
3
│   └── main.cpp
4
└── xmake.lua

最基础的 xmake.lua:

1
add_rules("mode.debug", "mode.release")
2
target("hello")
3
    set_kind("binary")
4
    add_files("src/*.cpp")

然后 xmake 构建、xmake run 运行。这个骨架对任何平台都一样,嵌入式无非是多配一个交叉工具链。

二、target 的常用配置#

对照官方 configure-targets 文档,平时用得最多的几个:

一个混合 C/汇编的 target 示例:

1
target("demo")
2
    set_kind("binary")
3
    add_files("src/*.c", "src/*.asm", "src/*.cpp")
4
    add_defines("DEBUG", "STM32F407xx")
5
    add_includedirs("lib", "Drivers/CMSIS/Include")
6
    add_links("myhal")
7
    add_linkdirs("build")

三、创建工程的语言与模板#

xmake create 的语言参数是 -l,模板参数是 -t(文档原文如此,别记反了):

1
xmake create -l c hello          # 指定语言
2
xmake create -t static test       # 指定模板

文档列出模板有 console、static、shared、module.binary、module.shared、qt.、tbox.、wxwidgets 等,最常用的就是 console、static、shared 这三个。

模板列表里没有 stm32/arm 这类。-P 可以指定工程父目录,这条文档里没细讲,xmake create --help 里有。

四、STM32 HAL 工程怎么搭#

官方没有 STM32 专页,但交叉编译文档里写了内置的 gnu-rm 工具链,原话是”gnu-rm 就是内置的 GNU Arm Embedded Toolchain”:

1
$ xmake f -p cross --toolchain=gnu-rm --sdk=/xxx/cc-arm-none-eabi-9-2019-q4-major
2
$ xmake

结合前面的 target 配置,一个 HAL 工程的 xmake.lua 大概是这么拼的:

1
add_rules("mode.debug", "mode.release")
2

3
target("firmware")
4
    set_kind("binary")
5
    -- HAL 库源码与芯片外设代码(路径按你 CubeMX 生成的工程填)
6
    add_files("Core/Src/*.c")
7
    add_files("Drivers/STM32F4xx_HAL_Driver/Src/*.c")
8
    -- 头文件搜索路径
9
    add_includedirs("Core/Inc", "Drivers/STM32F4xx_HAL_Driver/Inc",
10
                    "Drivers/CMSIS/Include", "Drivers/CMSIS/Device/ST/STM32F4xx/Include")
11
    -- 芯片型号与 HAL 开关宏
12
    add_defines("STM32F407xx", "USE_HAL_DRIVER")
13
    -- 启动文件(汇编)
14
    add_files("startup_stm32f407xx.s")
15
    -- 链接脚本与数学库
16
    add_ldflags("-Tstm32f407xx_flash.ld", "--specs=nano.specs")

命令行切工具链:

1
xmake f -p cross --toolchain=gnu-rm --sdk=/opt/gcc-arm-none-eabi
2
xmake

五、自定义其他 C 构建链#

1
# 设置编译器
2
$ xmake f -p cross --sdk=/user/toolsdk --cc=armv7-linux-clang --cxx=armv7-linux-clang++
3
# 设置链接器/归档器
4
$ xmake f -p cross --sdk=/user/toolsdk --ld=armv7-linux-clang++ --sh=armv7-linux-clang++ --ar=armv7-linux-ar
5
# 设置前缀与 bin 目录
6
$ xmake f -p cross --cross=armv7-linux- --bin=/opt/bin

1
toolchain("my_toolchain")
2
    set_kind("standalone")
3
    set_sdkdir("/tmp/arm-linux-musleabi-cross")
4
toolchain_end()
5

6
target("hello")
7
    set_kind("binary")
8
    add_files("apps/hello/*.c")

1
target("hello")
2
    set_toolchains("my_toolchain")

六、用自定义规则扩展构建流程#

构建完总得干点别的,比如 elf 转 hex/bin、bin2c、生成校验,这些都能用 rule() 挂进构建流程(custom-rule 页面):

1
rule("rulename")
2
    -- 关联的文件扩展名
3
    set_extensions(".ext1", ".ext2")
4
    -- 构建阶段回调
5
    on_build_file(function(target, sourcefile, opt)
6
        ...
7
    end)
8
rule_end()

应用到 target 有两种方式:

1
add_rules("markdown")                                    -- 全局应用
2
add_files("src/*.md", {rule = "markdown"})               -- 按文件应用(优先级更高)

可用的生命周期阶段:on_load / on_config / before_build / on_build / after_build / on_clean / on_package / on_install。

在规则里调用外部命令的写法(官方示例,用 pandoc 举例):

1
on_build_file(function(target, sourcefile, opt)
2
    os.vrunv("pandoc", {"-s", "-o", targetfile, sourcefile})
3
    import("core.project.depend")
4
    depend.on_changed(function() ... end, {files = sourcefile})
5
end)

内置规则也有现成的,比如 add_rules("mode.debug", "mode.release")、add_rules("qt.widgetapp")。

七、总结#

• 没有 STM32 模板的情况下,「gnu-rm 工具链 + -p cross + target API」拼一拼就够搭 HAL 工程;链接脚本、--specs 这类细节要对着手上的芯片工具链确认
• 自定义构建链两条路<命令行> --sdk/--cc/--ld/--cross 快速起步;或者用 toolchain() 固化进工程,多工具链切换也方便
• 更复杂的构建流程用 rule() + 生命周期回调扩展
• 遇到文档没写清楚的,先 xmake f --help 或翻一下项目的 issues,比自己瞎猜快

参考:

• xmake 文档索引(llms.txt)
• xmake create
• 构建 target
• 交叉编译
• target 配置
• 自定义工具链
• 自定义规则