📋 目录

• 1. 📖 背景介绍
• 2. 🛠️ 环境准备
• 3. 📁 项目结构分析
• 4. 🔍 问题诊断与解决
• 5. ✏️ 详细修改步骤
• 6. ✅ 构建验证
• 7. 💻 使用示例
• 8. 📚 总结与最佳实践

---

1. 📖 背景介绍

1.1 🌍 sys_locale工具简介

sys-locale 是一个用Rust编写的轻量级系统locale检测库，用于获取系统或应用程序的当前活动locale。本项目基于sys-locale库创建了一个命令行工具，用于演示和测试系统locale检测功能。

核心功能：

• 🌍 系统Locale检测: 获取系统或应用程序的当前活动locale
• 📋 多Locale支持: 支持获取按优先级排序的所有locale列表
• 🎯 BCP 47标准: 返回符合BCP 47语言标签格式的locale字符串
• 🌐 跨平台: 支持Android、iOS、macOS、Linux、BSD、Windows和WebAssembly
• ⚡ 轻量级: 小型库，no_std兼容（Linux和BSD除外）
• 🔒 安全可靠: 使用平台API安全获取locale信息

应用场景：

• 🌐 国际化（i18n）应用开发
• 📝 本地化工具开发
• 🎨 多语言终端应用
• 📊 系统信息工具
• 🔍 调试和诊断工具
• 🖥️ 跨平台应用开发

1.2 🎯 适配目标

将sys_locale命令行工具适配到鸿蒙PC（OpenHarmony PC）平台，实现：

• 🦀 Rust项目交叉编译支持
• 🏗️ 支持aarch64-linux-ohos架构
• 🔧 使用OHOS SDK工具链进行编译
• 📦 生成HNP格式的安装包
• 📦 生成tar.gz格式的发布包
• 💻 提供可执行的sys_locale命令

1.3 🔧 技术栈

• 语言: 🦀 Rust 2018 Edition
• 构建系统: Cargo
• 目标平台: 🎯 aarch64-linux-ohos
• 打包格式: 📦 HNP (HarmonyOS Native Package)
• 编译工具链: OHOS SDK Native LLVM (clang/ld.lld)
• 依赖: libc (0.2) - Android平台特定依赖

1.4 💡 工具优势

相比直接使用系统调用，sys_locale提供了：

• ✅ 类型安全: Rust类型系统保证locale数据的正确使用
• ✅ 跨平台: 统一API支持多个平台
• ✅ 轻量级: 小型库，依赖少
• ✅ 易于使用: 简洁的API，返回Option<String>或Iterator<String>
• ✅ 标准兼容: 返回BCP 47格式的locale字符串
• ✅ no_std支持: 支持no_std环境（Linux和BSD除外）

---

2. 🛠️ 环境准备

2.1 💻 系统要求

• 开发环境: 💻 macOS / 🐧 Linux / 🪟 Windows (WSL)
• Python: 🐍 Python 3.x
• Rust: 🦀 Rust 1.56.0+（sys-locale最低要求）
• Cargo: 📦 Rust包管理器（随Rust安装）
• 鸿蒙SDK: 📦 OHOS SDK (包含native工具链和hnpcli打包工具)

2.2 📥 SDK安装

1. 📥 下载SDK

# 下载鸿蒙SDK
cd ~
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

# 解压SDK
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

2. 📁 SDK目录结构

ohos-sdk/
├── native/
│   ├── llvm/bin/          # 🔧 编译器工具链
│   ├── sysroot/           # 📚 系统根目录（头文件和库）
│   └── build-tools/       # 🛠️ 构建工具
└── toolchains/
    └── hnpcli            # 📦 HNP打包工具

2.3 🦀 Rust环境配置

安装Rust：

# 使用rustup安装Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

安装musl target：

# 安装aarch64-unknown-linux-musl target（用于OpenHarmony交叉编译）
rustup target add aarch64-unknown-linux-musl

验证安装：

rustc --version  # 应显示 rustc 1.56.0 或更高版本
cargo --version  # 应显示 cargo 1.56.0 或更高版本
rustup target list --installed | grep aarch64-unknown-linux-musl  # 应显示已安装

---

3. 📁 项目结构分析

3.1 📂 目录结构

sys-locale4oh/
├── Cargo.toml              # Rust项目配置
├── Cargo.lock              # 依赖版本锁定文件
├── build_ohos.sh           # OpenHarmony构建脚本
├── hnp.json                # HNP包配置
├── README.md               # 项目说明
├── LICENSE-APACHE          # Apache-2.0许可证
├── LICENSE-MIT             # MIT许可证
├── src/                    # 源代码目录
│   ├── lib.rs             # 库代码（sys_locale库）
│   ├── main.rs            # 命令行工具主程序 ⭐
│   ├── unix.rs            # Unix平台实现
│   ├── android.rs         # Android平台实现
│   ├── apple.rs           # Apple平台实现
│   ├── windows.rs         # Windows平台实现
│   └── wasm.rs            # WebAssembly平台实现
├── examples/               # 示例代码
│   └── get_locale.rs      # 基本使用示例
├── tests/                  # 测试代码
│   └── wasm_worker.rs     # WebAssembly测试
└── .cargo/                 # Cargo配置目录
    └── config.toml         # 交叉编译配置

3.2 🔧 Cargo.toml关键配置

[package]
name = "sys-locale"
version = "0.3.2"
edition = "2018"
rust-version = "1.56"

[lib]
name = "sys_locale"

[[bin]]
name = "sys_locale"
path = "src/main.rs"  # ⭐ 命令行工具入口

[target.'cfg(target_os = "android")'.dependencies]
libc = "0.2"

关键配置说明：

• ⚠️ Edition 2018: 使用Rust 2018版本
• ⭐ Binary配置: 添加了[[bin]]配置，定义命令行工具入口
• 📦 平台特定依赖: Android平台需要libc依赖
• 🎯 最小Rust版本: 1.56.0

3.3 📝 命令行工具设计

main.rs核心功能：

// 支持的命令
- default     - 获取最优先的locale（默认）
- all         - 显示所有按优先级排序的locale
- json        - 以JSON格式输出locale
- help        - 显示帮助信息

设计特点：

• ✅ 模块化设计，每个功能独立函数
• ✅ 友好的命令行界面
• ✅ 支持多种输出格式（文本和JSON）
• ✅ 完善的错误处理

---

4. 🔍 问题诊断与解决

4.1 🔍 问题1：缺少命令行工具入口

问题描述：
sys-locale是一个库项目，没有命令行工具入口点。

解决方案：
创建src/main.rs文件，实现命令行工具功能。

4.2 🔍 问题2：Cargo.toml缺少binary配置

问题描述：
Cargo.toml中没有定义binary目标，无法构建可执行文件。

解决方案：
在Cargo.toml中添加[[bin]]配置：

[[bin]]
name = "sys_locale"
path = "src/main.rs"

4.3 🔍 问题3：缺少交叉编译配置

问题描述：
需要配置Cargo使用OpenHarmony SDK的工具链进行交叉编译。

解决方案：
创建.cargo/config.toml文件，配置交叉编译参数。

---

5. ✏️ 详细修改步骤

5.1 📝 步骤1：创建命令行工具入口

创建src/main.rs文件：

//! sys_locale command-line tool
//! 
//! A command-line tool for getting and displaying system locale information.

use sys_locale::{get_locale, get_locales};

fn print_usage() {
    println!("sys_locale - Get system locale information");
    println!();
    println!("Usage:");
    println!("  sys_locale [command]");
    println!();
    println!("Commands:");
    println!("  default     - Get the most preferred locale (default)");
    println!("  all         - Display all preferred locales");
    println!("  json        - Output locale in JSON format");
    println!("  help        - Show this help message");
    println!();
    println!("Examples:");
    println!("  sys_locale              # Get default locale");
    println!("  sys_locale all         # Show all locales");
    println!("  sys_locale json        # Output as JSON");
}

fn print_locale(locale: &str, index: Option<usize>) {
    if let Some(i) = index {
        println!("Locale {}: {}", i + 1, locale);
    } else {
        println!("Locale: {}", locale);
    }
}

fn print_json_locale(locale: &str, index: Option<usize>) {
    if let Some(i) = index {
        println!("{{\"index\":{},\"locale\":\"{}\"}}", i + 1, locale);
    } else {
        println!("{{\"locale\":\"{}\"}}", locale);
    }
}

fn main() {
    let args: Vec<String> = std::env::args().collect();
    
    let command = if args.len() > 1 {
        args[1].as_str()
    } else {
        "default"
    };

    match command {
        "default" => {
            match get_locale() {
                Some(locale) => {
                    print_locale(&locale, None);
                }
                None => {
                    eprintln!("Error: Unable to get system locale");
                    std::process::exit(1);
                }
            }
        }
        "all" => {
            let locales: Vec<String> = get_locales().collect();
            if locales.is_empty() {
                eprintln!("Error: No locales found");
                std::process::exit(1);
            }
            println!("System Locales (in order of preference):");
            println!("==========================================");
            println!();
            for (i, locale) in locales.iter().enumerate() {
                print_locale(locale, Some(i));
            }
            println!();
            println!("Total: {} locale(s)", locales.len());
        }
        "json" => {
            match get_locale() {
                Some(locale) => {
                    print_json_locale(&locale, None);
                }
                None => {
                    println!("{{\"error\":\"Unable to get system locale\"}}");
                    std::process::exit(1);
                }
            }
        }
        "help" | "-h" | "--help" => {
            print_usage();
        }
        _ => {
            eprintln!("Unknown command: {}", command);
            println!();
            print_usage();
            std::process::exit(1);
        }
    }
}

关键实现：

• ✅ 使用get_locale()获取最优先的locale
• ✅ 使用get_locales()获取所有locale列表
• ✅ 支持多种输出格式（文本和JSON）
• ✅ 完善的错误处理和帮助信息

5.2 📝 步骤2：更新Cargo.toml

在Cargo.toml中添加binary配置：

[lib]
name = "sys_locale"

[[bin]]
name = "sys_locale"
path = "src/main.rs"

配置说明：

• [lib]: 定义库目标
• [[bin]]: 定义二进制目标，指定入口文件为src/main.rs

5.3 📝 步骤3：创建交叉编译配置

创建.cargo/config.toml文件：

[target.aarch64-unknown-linux-musl]
linker = "clang"
ar = "llvm-ar"
rustflags = [
    "-C", "link-arg=--target=aarch64-linux-ohos",
    "-C", "link-arg=--sysroot=${SYSROOT}",
    "-C", "link-arg=-fuse-ld=lld",
]

配置说明：

• linker: 使用clang作为链接器
• ar: 使用llvm-ar作为归档工具
• rustflags: 传递链接参数，指定目标平台和sysroot

5.4 📝 步骤4：更新build_ohos.sh

build_ohos.sh脚本已经配置好，关键部分：

#!/bin/bash
# sys_locale OpenHarmony build script

set -e
export SYS_LOCALE_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/sys_locale.org/sys_locale_0.3.3

# 创建安装目录
mkdir -p ${SYS_LOCALE_INSTALL_HNP_PATH}/bin

# 安装musl target（如果未安装）
if ! rustup target list --installed | grep -q "aarch64-unknown-linux-musl"; then
    echo "Installing aarch64-unknown-linux-musl target..."
    rustup target add aarch64-unknown-linux-musl
fi

# 配置交叉编译环境变量
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER="${CC}"
export RUSTFLAGS="-Clink-arg=--target=${TARGET_PLATFORM} -Clink-arg=--sysroot=${SYSROOT} -Clink-arg=-fuse-ld=lld"

# 构建sys_locale命令行工具
cargo build --release --target aarch64-unknown-linux-musl
BIN=target/aarch64-unknown-linux-musl/release/sys_locale
cp "$BIN" ${SYS_LOCALE_INSTALL_HNP_PATH}/bin/

# 复制HNP配置文件
cp hnp.json ${SYS_LOCALE_INSTALL_HNP_PATH}/

# 打包HNP和tar.gz
${HNP_TOOL} pack -i ${SYS_LOCALE_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
tar -zvcf ${ARCHIVE_PATH}/ohos_sys_locale_0.3.3.tar.gz sys_locale_0.3.3/

关键步骤：

1. ✅ 设置安装路径
2. ✅ 安装musl target
3. ✅ 配置交叉编译环境变量
4. ✅ 构建二进制文件
5. ✅ 复制文件到HNP目录
6. ✅ 打包HNP和tar.gz

---

6. ✅ 构建验证

6.1 🚀 执行构建

cd /Users/baixm/HarmonyOSPC/build
./build.sh --sdk /Users/baixm/ohos-sdk --module sys-locale4oh

6.2 ✅ 构建输出

Building sys_locale command-line tool for aarch64-unknown-linux-musl (compatible with aarch64-linux-ohos)...
   Compiling sys-locale v0.3.2 (/Users/baixm/HarmonyOSPC/build/code/sys-locale4oh)
    Finished `release` profile [optimized] target(s) in 4.24s
sys_locale installed successfully
Binary file type:
/Users/baixm/HarmonyOSPC/data/service/hnp/sys_locale.org/sys_locale_0.3.3/bin/sys_locale: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, not stripped
Packing HNP package...
[INFO][HNP][hnp_pack.c:116]PackHnp end. srcPath=..., hnpName=sys_locale, hnpVer=0.3.3
Creating tar.gz archive...
Build completed successfully!

6.3 🔍 验证要点

• ✅ 编译成功，无错误
• ✅ 二进制文件格式正确（ELF 64-bit LSB executable, ARM aarch64）
• ✅ 静态链接（statically linked）
• ✅ HNP包生成成功
• ✅ tar.gz包生成成功

---

7. 💻 使用示例

7.1 🚀 基本使用

🌍 获取默认locale

# 在鸿蒙PC终端执行
sys_locale

# 输出示例：
# Locale: zh_CN.UTF-8

🌍 获取所有locale

# 在鸿蒙PC终端执行
sys_locale all

# 输出示例：
# System Locales (in order of preference):
# ==========================================
# 
# Locale 1: zh_CN.UTF-8
# Locale 2: zh_CN
# Locale 3: en_US.UTF-8
# Locale 4: en_US
# 
# Total: 4 locale(s)

7.2 📋 JSON格式输出

# 在鸿蒙PC终端执行
sys_locale json

# 输出示例：
# {"locale":"zh_CN.UTF-8"}

7.3 ❓ 显示帮助信息

# 在鸿蒙PC终端执行
sys_locale help

# 或
sys_locale -h
sys_locale --help

# 输出示例：
# sys_locale - Get system locale information
# 
# Usage:
#   sys_locale [command]
# 
# Commands:
#   default     - Get the most preferred locale (default)
#   all         - Display all preferred locales
#   json        - Output locale in JSON format
#   help        - Show this help message

7.4 🔧 实际应用场景

📊 在脚本中使用

#!/bin/bash
# 获取系统locale并设置应用语言

LOCALE=$(sys_locale json | grep -o '"locale":"[^"]*"' | cut -d'"' -f4)
LANG_CODE=$(echo $LOCALE | cut -d'_' -f1)

echo "System locale: $LOCALE"
echo "Language code: $LANG_CODE"

# 根据locale设置应用语言
if [ "$LANG_CODE" = "zh" ]; then
    echo "使用中文界面"
elif [ "$LANG_CODE" = "en" ]; then
    echo "Using English interface"
else
    echo "Using default language"
fi

📋 在Rust程序中使用

use sys_locale::get_locale;

fn main() {
    match get_locale() {
        Some(locale) => {
            println!("System locale: {}", locale);
            
            // 根据locale设置应用语言
            if locale.starts_with("zh") {
                println!("使用中文界面");
            } else if locale.starts_with("en") {
                println!("Using English interface");
            } else {
                println!("Using default language");
            }
        }
        None => {
            println!("Unable to get system locale, using default");
        }
    }
}

---

8. 📚 总结与最佳实践

8.1 ✅ 适配总结

本次适配成功实现了sys_locale命令行工具在OpenHarmony PC平台上的部署：

1. ✅ 命令行工具创建: 创建了src/main.rs，实现了完整的命令行工具功能
2. ✅ 交叉编译配置: 配置了.cargo/config.toml，使用musl target进行交叉编译
3. ✅ 构建脚本优化: build_ohos.sh脚本自动处理musl target安装和交叉编译
4. ✅ HNP打包: 成功生成HNP格式的安装包和tar.gz发布包
5. ✅ 功能验证: 命令行工具功能完整，支持多种使用方式

8.2 🎯 关键技术点

1. Rust 2018 Edition: sys-locale使用Rust 2018版本
2. 平台特定实现: 不同平台使用不同的实现（unix.rs、android.rs、apple.rs、windows.rs）
3. musl target: 使用aarch64-unknown-linux-musl target进行静态链接
4. 交叉编译: 通过.cargo/config.toml和RUSTFLAGS配置交叉编译
5. HNP打包: 使用hnpcli工具打包成HNP格式

8.3 💡 最佳实践

1. 命令行工具设计:

   • ✅ 提供清晰的帮助信息
   • ✅ 支持多种输出格式（文本和JSON）
   • ✅ 完善的错误处理
   • ✅ 友好的用户界面

2. 交叉编译配置:

   • ✅ 使用标准的musl target
   • ✅ 配置正确的链接器和sysroot
   • ✅ 自动安装musl target
   • ✅ 验证二进制文件格式

3. 构建脚本:

   • ✅ 设置set -e确保错误时退出
   • ✅ 创建必要的目录结构
   • ✅ 验证安装结果
   • ✅ 提供清晰的日志输出

8.4 🚀 未来改进方向

1. 功能增强:

   • 📊 支持更多输出格式（如YAML、TOML）
   • 🔄 支持locale详细信息（语言、地区、编码等）
   • 📈 支持locale验证和转换

2. 性能优化:

   • ⚡ 优化locale获取性能
   • 🎯 减少系统调用次数

3. 文档完善:

   • 📖 添加更多使用示例
   • 🔍 添加故障排除指南
   • 📚 添加API文档

---

📚 附录

A. 相关资源

• sys-locale文档: https://docs.rs/sys-locale
• GitHub仓库: https://github.com/1Password/sys-locale
• Crates.io: https://crates.io/crates/sys-locale
• BCP 47标准: https://tools.ietf.org/html/bcp47
• OpenHarmony官网: https://www.openharmony.cn/

B. 常见问题

Q1: 为什么sys_locale返回Option类型？

A: 在某些情况下（如无法访问系统API），可能无法获取locale，返回Option类型可以表示这种情况。

Q2: BCP 47格式是什么？

A: BCP 47是IETF定义的语言标签标准，格式如zh-CN、en-US等，用于标识语言和地区。

Q3: 如何判断locale是否可用？

A: 检查get_locale()的返回值，如果是Some(locale)则表示成功获取，如果是None则表示无法获取。

Q4: 为什么需要获取所有locale？

A: 系统可能配置了多个locale，按优先级排序。应用可以根据优先级选择合适的locale。

---

🎉 结语

sys_locale工具为跨平台应用开发提供了便捷的系统locale检测能力，是开发国际化应用的重要基础工具。通过本次适配，sys_locale成功运行在OpenHarmony PC平台上，为鸿蒙生态的国际化应用开发提供了支持。

希望本文档能够帮助开发者：

• 🌍 理解系统locale检测的原理和使用方法
• 🔧 掌握Rust项目适配OpenHarmony的方法
• 📦 了解HNP包的构建和打包流程
• 💻 学习命令行工具的开发实践

💬 如有问题或建议，欢迎反馈！