Rust构建工具插件库embuild的使用，嵌入式开发与跨平台构建的强力助手

简介

embuild是一个为嵌入式Rust提供构建支持的库，包含许多用于构建嵌入式框架、库和其他构件的实用工具。它主要用于简化esp-idf-sys crate的构建脚本中对esp-idf的构建过程，但也可以用于其他通用场景。

功能特性

embuild提供了以下功能模块，可以通过特性(features)来启用或禁用：

• pio: Platformio支持
• cmake: CMake文件API支持和实用工具
• glob: 全局实用工具(用于build模块)
• manifest: Cargo.toml和config.toml实用工具(用于cargo模块)
• espidf: 安装esp-idf框架的工具
• git: 使用git CLI操作仓库的实用工具
• kconfig: kconfig文件解析
• elf: ELF文件操作(用于bingen、symgen和espidf::ulp_fsm模块)

其他不依赖特性的实用工具包括：

• cargo: 通过CLI与cargo交互和在构建脚本中输出stdout的工具
• cmd: 运行命令并获取结果的宏和包装器
• cli: 命令行参数操作

安装

在项目目录中运行以下Cargo命令：

cargo add embuild

或者在Cargo.toml中添加：

embuild = "0.33.1"

示例代码

以下是一个使用embuild进行嵌入式开发的完整示例：

// build.rs
use embuild::{
    build::{CfgArgs, LinkArgs},
    cargo, symgen,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 设置构建配置参数
    let cfg = CfgArgs::try_from_env("ESP_IDF")?;
    
    // 设置链接参数
    let link_args = LinkArgs::try_from_env("ESP_IDF")?;
    
    // 输出配置和链接参数
    cfg.output();
    link_args.output();
    
    // 生成符号文件
    symgen::generate("target/esp32/symbols.txt", "0x4000")?;
    
    // 告诉Cargo在IDF_PATH环境变量更改时重新运行构建脚本
    cargo::track_env("IDF_PATH");
    
    Ok(())
}

完整示例demo

以下是一个更完整的嵌入式开发项目示例，展示如何使用embuild进行跨平台构建：

// build.rs
use embuild::{
    espidf::{self, EspIdfBuildOutput},
    build::{CfgArgs, LinkArgs},
    cargo, kconfig, symgen, 
    cmd::{cmd, Output},
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 检查是否启用了ESP-IDF特性
    if std::env::var_os("CARGO_FEATURE_ESPIDF").is_some() {
        // 安装或配置ESP-IDF
        let idf = espidf::install()?;
        
        // 设置构建配置
        let cfg = CfgArgs::try_from_env("ESP_IDF")?
            .define("CONFIG_ESP32_WIFI_ENABLED", "y")?
            .define("CONFIG_ESP32_BT_ENABLED", "n")?;
            
        // 设置链接参数
        let link_args = LinkArgs::try_from_env("ESP_IDF")?
            .static_lib("esp32")
            .static_lib("driver");
            
        // 输出配置
        cfg.output();
        link_args.output();
        
        // 生成符号文件
        symgen::generate("target/esp32/symbols.txt", "0x4000")?;
        
        // 解析kconfig文件
        let config = kconfig::Config::parse("sdkconfig")?;
        println!("WiFi enabled: {}", config.get_bool("CONFIG_ESP32_WIFI_ENABLED")?);
        
        // 运行自定义命令
        let output = cmd!("xtensa-esp32-elf-objdump -d target/esp32/firmware.elf")?.run()?;
        println!("Disassembly: {}", output.stdout_string_lossy());
        
        // 告诉Cargo在IDF_PATH更改时重新运行构建脚本
        cargo::track_env("IDF_PATH");
    }
    
    Ok(())
}

// src/main.rs
#[cfg(feature = "espidf")]
fn main() -> anyhow::Result<()> {
    // 嵌入式应用程序代码
    println!("Hello ESP-IDF!");
    Ok(())
}

#[cfg(not(feature = "espidf"))]
fn main() {
    println!("This example requires the 'espidf' feature to be enabled");
}

工具

embuild还提供了两个CLI工具：

• cargo-pio: Platformio集成工具
• ldproxy: 链接代理工具

许可证

embuild采用MIT或Apache-2.0双重许可证。