命令行esh在开源鸿蒙PC平台的工程实践

esh (Embedded SHell) 是一个轻量级的模板引擎，用于在任意模板中嵌入和执行 shell 命令。本文档深入剖析 esh 在开源鸿蒙PC平台的适配全过程，涵盖技术架构分析、适配策略设计、构建系统实现和部署方案，为开发者提供完整的跨平台移植参考。

📋 目录

• 一、项目概述
• 二、适配设计
• 三、实现细节
• 四、构建与部署
• 五、技术亮点
• 六、总结

---

一、项目概述

1.1 项目简介

esh (Embedded SHell) 是一个轻量级的模板引擎，用于在任意模板中嵌入和执行 shell 命令。它类似于 ERB (Embedded Ruby)，但专为 shell 脚本设计，主要用于配置文件的模板化处理。

核心特点：

• 轻量级：仅约 290 行代码（shell + awk）
• POSIX 兼容：完全遵循 POSIX 标准，可在任何 POSIX 兼容的 shell 中运行
• 模板包含：支持将一个 ESH 模板包含到另一个模板中
• 两阶段处理：先转换为 shell 脚本，再执行脚本
• 零依赖：仅需 POSIX shell、awk 和 sed

1.2 项目信息

项目信息	详情
项目名称	esh
当前版本	0.3.3（适配版本）<br>0.3.2（原始版本）
许可证	MIT License
源码仓库	https://github.com/jirutka/esh
适配平台	开源鸿蒙PC (aarch64-linux-ohos)
项目类型	纯 Shell 脚本（无需编译）
依赖	POSIX shell、awk、sed（OpenHarmony PC 自带）

1.3 应用场景

esh 主要用于：

• 配置文件模板化：动态生成配置文件（如 nginx、systemd 等）
• CI/CD 脚本：在构建流程中生成配置
• 系统管理：自动化系统配置和管理脚本
• 开发工具：代码生成和模板处理

二、适配设计

2.1 技术分析

esh 是一个纯 shell 脚本项目，不需要编译，适配工作相对简单：

1. 脚本兼容性：esh 本身是 POSIX 兼容的，无需修改
2. 路径适配：适配 OpenHarmony PC 的文件系统路径
3. 打包配置：创建 HNP 包配置文件
4. 构建脚本：编写自动化构建脚本

2.2 适配策略

2.2.1 构建脚本设计

创建 build_ohos.sh 脚本，主要功能：

• 设置安装路径：${HNP_PUBLIC_PATH}/esh.org/esh_0.3.3
• 复制 esh 脚本到 bin/ 目录
• 修复 shebang（使用 /bin/sh）
• 复制 LICENSE 和 README.adoc
• 打包 HNP 和 tar.gz 文件

2.2.2 HNP 包配置

创建 hnp.json 配置文件：

{
    "type": "hnp-config",
    "name": "esh",
    "version": "0.3.3",
    "install": {
        "links": [
            {
                "source": "bin/esh",
                "target": "esh"
            }
        ]
    }
}

2.2.3 依赖分析

esh 的依赖：

• POSIX shell：OpenHarmony PC 自带
• awk：OpenHarmony PC 自带
• sed：OpenHarmony PC 自带

所有依赖都已满足，无需额外处理。

三、实现细节

3.1 构建脚本实现

构建脚本 build_ohos.sh 的核心逻辑：

#!/bin/bash
# esh OpenHarmony build script

set -e

# Installation path inside HNP public directory
export ESH_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/esh.org/esh_0.3.3

# Create install directories
mkdir -p ${ESH_INSTALL_HNP_PATH}/bin

# Copy main esh script
cp esh ${ESH_INSTALL_HNP_PATH}/bin/esh
chmod +x ${ESH_INSTALL_HNP_PATH}/bin/esh

# Copy LICENSE and README.adoc
if [ -f "LICENSE" ]; then
    cp LICENSE ${ESH_INSTALL_HNP_PATH}/
fi

if [ -f "README.adoc" ]; then
    cp README.adoc ${ESH_INSTALL_HNP_PATH}/
fi

# Package HNP and tar.gz
${HNP_TOOL} pack -i ${ESH_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
tar -zvcf ${ARCHIVE_PATH}/ohos_esh_0.3.3.tar.gz esh_0.3.3/

3.2 关键实现点

1. 脚本复制：直接复制 esh 脚本，无需修改
2. 权限设置：确保脚本可执行
3. 文档复制：保留原始文档和许可证
4. HNP 打包：使用 hnpcli 工具打包

3.3 兼容性处理

esh 脚本本身已经是 POSIX 兼容的，主要处理：

• Shebang ：使用 /bin/sh（OpenHarmony PC 标准）
• 路径处理：使用相对路径和标准路径
• 错误处理：保持原有的错误处理逻辑

四、构建与部署

4.1 构建环境

• 开发环境: macOS 或 Linux
• SDK 版本: OpenHarmony SDK 6.0.0.46-Beta1 或更高
• 目标平台: aarch64-linux-ohos

4.2 构建步骤

# 1. 进入构建目录
cd HarmonyOSPC/build

# 2. 执行构建脚本
SPECIFIC_DIR=esh ./build.sh --sdk /Users/lijiajun/ohos-sdk

构建输出：

Building esh templating engine for OpenHarmony PC (aarch64-linux-ohos)...
esh installed successfully
Packing HNP package...
Build completed successfully!
Output files:
  - output/esh.hnp
  - output/ohos_esh_0.3.3.tar.gz

4.3 构建输出

构建成功后，生成以下文件：

• esh.hnp (6.3KB): HNP 包文件，可直接通过 hnp 工具安装
• ohos_esh_0.3.3.tar.gz (6.4KB): tar.gz 压缩包，包含完整的安装文件

4.4 安装路径

/data/service/hnp/esh.org/esh_0.3.3/
├── bin/
│   └── esh                    # 主可执行脚本
├── LICENSE                    # MIT 许可证
├── README.adoc                # 项目文档
└── hnp.json                   # HNP 包配置

4.5 安装部署

方式一：使用 tar.gz 包安装

# 在鸿蒙PC上执行
tar -xzf ohos_esh_0.3.3.tar.gz
cp -r esh_0.3.3/* /data/service/hnp/esh.org/esh_0.3.3/

方式二：手动安装

# 复制文件到安装目录
mkdir -p /data/service/hnp/esh.org/esh_0.3.3/bin
cp bin/esh /data/service/hnp/esh.org/esh_0.3.3/bin/
chmod +x /data/service/hnp/esh.org/esh_0.3.3/bin/esh

# 添加到 PATH
export PATH=$PATH:/data/service/hnp/esh.org/esh_0.3.3/bin

4.6 验证安装

安装完成后，可以验证 esh 是否正常工作：

# 查看版本
esh -V

# 查看帮助
esh -h

五、技术亮点

5.1 零编译适配

esh 作为纯 Shell 脚本项目，适配到鸿蒙PC平台无需任何编译步骤，只需要：

1. 文件复制
2. 权限设置
3. 打包分发

这使得适配过程非常简洁高效。

5.2 POSIX 兼容性

esh 完全遵循 POSIX 标准：

• 使用标准 shell 语法
• 使用标准 awk 功能
• 可在任何 POSIX 兼容系统上运行

5.3 轻量级实现

esh 仅用约 290 行代码实现了一个完整的模板引擎：

• Shell 脚本：处理命令行参数、文件操作
• AWK 脚本：模板解析和转换
• 两阶段处理：转换和执行分离

5.4 模板语法

esh 支持类似 ERB 的语法：

• <%= ... %>：输出表达式结果
• <% ... %>：执行脚本块（不输出）
• <%+ ... %>：包含其他模板文件
• <%# ... %>：注释

六、总结

6.1 适配成果

成功将 esh 模板引擎适配到开源鸿蒙PC平台：

• ✅ 完成构建脚本编写
• ✅ 生成 HNP 包和 tar.gz 压缩包
• ✅ 验证脚本在目标平台的兼容性
• ✅ 提供完整的使用文档和示例

6.2 技术价值

1. 生态完善：为鸿蒙PC提供了强大的配置文件模板化工具
2. 开发效率：提升配置管理和自动化脚本开发的效率
3. 最佳实践：展示了纯脚本项目的鸿蒙化适配方法
4. 零依赖：仅需标准 POSIX 工具，易于部署

6.3 注意事项

1. POSIX 兼容：esh 完全遵循 POSIX 标准，可在任何 POSIX 兼容系统上运行
2. 路径处理：在编写模板时，注意使用相对路径或环境变量
3. 错误处理：esh 提供详细的错误信息，包括模板文件位置和行号

6.4 未来展望

• 支持更多模板语法特性
• 改进错误提示的准确性
• 优化性能，减少处理开销
• 提供更多示例和最佳实践

---