核心内容摘要
2026崇礼论坛：论道“非GPU”崛起
摘要本文详细介绍了使用 lycium 框架将 nginx
1.
2
2 交叉编译适配到 OpenHarmony 系统的完整解决方案。
文章涵盖了在 macOS 主机上进行 ARM 交叉编译时遇到的核心技术挑战包括 configure 脚本的运行时检测问题、类型大小探测失败等并提供了不修改原库代码的创新性解决方案。
最终成功在 macOS 上完成了 nginx 的鸿蒙交叉编译生成了可在 OpenHarmony 设备上运行的 ARM 32-bit 和 ARM 64-bit 可执行文件。
关键词: OpenHarmony, nginx, 交叉编译, lycium, macOS
引言
1 背景随着万物互联时代的到来OpenHarmony 作为面向全场景的分布式操作系统正在快速发展。
将成熟的开源软件移植到 OpenHarmony 平台是丰富其生态系统的重要途径。
nginx 作为全球最流行的 Web 服务器和反向代理服务器其高性能、高并发的特性使其成为 OpenHarmony 设备端服务的理想选择。
2 挑战将 nginx 移植到 OpenHarmony 面临以下挑战交叉编译环境差异: nginx 的 configure 脚本设计之初并未充分考虑交叉编译场景运行时检测机制: configure 脚本通过编译并运行测试程序来检测系统特性这在交叉编译环境中无法工作不修改原库代码的约束: 为便于后续版本升级和维护需要在不修改 nginx 原始代码的前提下完成适配
3 解决方案概述本文提出了一种基于 lycium 框架的适配方案通过在 HPKBUILD 构建脚本中对 nginx 的 auto 脚本进行运行时修改成功解决了上述挑战。
该方案的核心优势是完全不修改 nginx 原库代码所有适配工作都在构建脚本层面完成。
lycium 框架简介
1 框架概述lycium 是一个专门用于 OpenHarmony 第三方 C/C 库交叉编译的框架。
它借鉴了 Arch Linux 的 PKGBUILD 机制提供了一套标准化的构建流程。
2 HPKBUILD 文件结构HPKBUILD 是 lycium 的核心配置文件定义了库的元信息和构建流程# 包元信息pkgnamenginx# 包名pkgver
1.
2
2# 版本号pkgdesc...# 描述urlhttps://nginx.org/archs(armeabi-v7aarm64-v8a)# 目标架构depends(pcre2opensslzlib-ng)# 依赖库# 构建流程函数prepare()# 准备阶段解压、打补丁build()# 编译阶段configure、makepackage()# 打包阶段make installcheck()# 测试阶段cleanbuild()# 清理阶段
3 构建流程┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ download │───▶│ prepare │───▶│ build │───▶│ package │ │ 源码下载 │ │ 环境准备 │ │ 编译构建 │ │ 安装打包 │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
nginx 交叉编译的技术挑战
1 问题一C 编译器检测失败现象:checking for C compiler ... found but is not working ./configure: error: C compiler arm-linux-ohos-clang is not found根本原因分析:nginx 的auto/cc/name脚本使用以下逻辑检测编译器ngx_feature_runyes# 关键要求运行编译后的测试程序当设置ngx_feature_runyes时configure 会编译一个测试程序并尝试执行它。
在交叉编译场景下编译出的是 ARM 二进制文件无法在 x86_64 的 macOS 主机上运行导致检测失败。
2 问题二数据类型大小检测失败现象:checking for int size ...auto/types/sizeof: line 43: objs/autotest: cannot execute binary file ./configure: error: can not detect int size根本原因分析:nginx 的auto/types/sizeof脚本通过以下方式获取类型大小# 编译测试程序ngx_test$CC... -o$NGX_AUTOTEST$NGX_AUTOTEST.c ...eval$ngx_test# 运行测试程序获取 sizeof 值ngx_size$NGX_AUTOTEST# 第 43 行执行 ARM 二进制文件失败这是交叉编译的经典难题目标平台的类型大小可能与主机平台不同必须通过某种方式获取正确的值。
3 问题三功能特性检测失败nginx 的auto/unix脚本包含大量功能检测许多都使用了运行时检测ngx_feature_runyes# 需要运行测试程序ngx_feature_runvalue# 需要运行测试程序并获取返回值ngx_feature_runbug# 需要运行测试程序检测 bug这些检测在交叉编译环境中都会失败。
4 问题四路径硬编码问题现象:在鸿蒙设备上运行 nginx 时报错找不到配置文件或日志文件路径显示为 macOS 编译机器上的绝对路径nginx: [alert] could not open error log file: open() /path/to/build/machine/logs/error.log failed根本原因分析:nginx 的configure脚本通过--prefix参数设置安装前缀该路径会被硬编码到二进制文件中// src/core/nginx.c 第
行ngx_str_set(cycle-conf_prefix,NGX_PREFIX);ngx_str_set(cycle-prefix,NGX_PREFIX);如果使用绝对路径如--prefix$LYCIUM_ROOT/usr/nginx/$ARCH则编译主机上的绝对路径会被编译进二进制文件导致在鸿蒙设备上无法找到对应路径。
5 问题五鸿蒙系统兼容性问题现象一FIOASYNC 警告nginx: [alert] ioctl(FIOASYNC) failed while spawning worker process (25: Not a tty)现象二页面空白无法加载nginx 启动成功端口监听正常但浏览器访问时页面一直转圈无法加载静态文件。
根本原因分析:FIOASYNC 问题: 鸿蒙系统的 musl libc 对FIOASYNCioctl 调用支持有限该调用用于设置异步 I/O 通知。
此警告通常不影响基本功能。
sendfile 问题: nginx 默认启用sendfile on这是一个零拷贝系统调用用于高效传输文件。
鸿蒙系统对 sendfile 的实现可能存在兼容性问题导致静态文件无法正确传输。
解决方案设计与实现
1 设计原则不修改原库代码: 所有修改在 HPKBUILD 脚本中完成运行时修改: 在 prepare() 阶段使用 sed/cat 修改 auto 脚本架构感知: 针对不同目标架构提供正确的预设值平台兼容: 仅在 macOS 上应用修改Linux 环境保持原有行为
2 解决方案一跳过编译器运行检测在prepare()函数中修改auto/cc/name# 将需要运行测试程序的检测改为仅编译检测sed-i.baks/ngx_feature_runyes/ngx_feature_runno/gauto/cc/name原理: 当ngx_feature_runno时nginx 只检查测试程序是否能成功编译不再尝试运行它。
3 解决方案二提供预设的类型大小值完全替换auto/types/sizeof脚本使用基于目标架构的预设值# ARM 32-bit 类型大小case$ngx_typeinint)ngx_size4;;long)ngx_size4;;# 32-bit: long 是 4 字节long long)ngx_size8;;void *)ngx_size4;;# 32-bit: 指针是 4 字节size_t)ngx_size4;;off_t)ngx_size8;;time_t)ngx_size4;;sig_atomic_t)ngx_size4;;esac# ARM 64-bit 类型大小case$ngx_typeinint)ngx_size4;;long)ngx_size8;;# 64-bit: long 是 8 字节long long)ngx_size8;;void *)ngx_size8;;# 64-bit: 指针是 8 字节size_t)ngx_size8;;off_t)ngx_size8;;time_t)ngx_size8;;sig_atomic_t)ngx_size4;;esac关键差异说明:类型ARM 32-bitARM 64-bitint4 字节4 字节long4 字节8 字节void *4 字节8 字节size_t4 字节8 字节
4 解决方案三禁用功能运行时检测批量修改auto/unix中的所有运行时检测sed-i.baks/ngx_feature_runyes/ngx_feature_runno/gauto/unixsed-i.baks/ngx_feature_runvalue/ngx_feature_runno/gauto/unixsed-i.baks/ngx_feature_runbug/ngx_feature_runno/gauto/unix影响分析: 这会导致某些功能检测不够精确但对于 OpenHarmony 这类 Linux 兼容系统大多数 POSIX 功能都是可用的仅编译检测通常足够。
5 解决方案四预设字节序ARM 处理器使用小端字节序直接在 prepare() 中设置sed-i.baks/ngx_feature_runvalue/ngx_feature_runno/gauto/endiannessmkdir-p objsecho#define NGX_HAVE_LITTLE_ENDIAN 1objs/ngx_auto_config.h.tmp
6 解决方案五使用相对路径避免硬编码为解决路径硬编码问题在build()函数中使用相对路径配置 nginx./configure\--crossbuild$host\--prefix../\--conf-pathconf/nginx.conf\--error-log-pathlogs/error.log\--pid-pathlogs/nginx.pid\--lock-pathlogs/nginx.lock\--http-log-pathlogs/access.log\# ... 其他参数关键配置说明:参数值说明--prefix../使用上一级目录必须以/结尾--conf-pathconf/nginx.conf配置文件相对路径--error-log-pathlogs/error.log错误日志相对路径--pid-pathlogs/nginx.pidPID 文件相对路径--http-log-pathlogs/access.log访问日志相对路径重要: prefix 必须以/结尾。
nginx 在运行时通过-p参数指定 prefix 时会自动补全斜杠但使用编译时的NGX_PREFIX宏时不会自动添加。
如果使用--prefix..不带斜杠会导致路径拼接错误如..html而非../html。
原理: 当--prefix../时nginx 从sbin/目录运行会将 prefix 解析为上一级目录。
例如从/data/nginx/sbin/运行./nginxprefix 会解析为/data/nginx/从而正确找到conf/、logs/等目录。
7 解决方案六鸿蒙系统兼容性配置针对鸿蒙系统的兼容性问题需要在nginx.conf中进行以下配置worker_processes 1; error_log logs/error.log; pid logs/nginx.pid; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; # 关键禁用 sendfile解决鸿蒙系统静态文件无法加载的问题 sendfile off; keepalive_timeout 65; server { listen 8080; server_name localhost; location / { root html; index index.html index.htm; } error_page 500 502 503 504 /50x.html; location /50x.html { root html; } } }关键配置说明:配置项值说明sendfileoff禁用零拷贝传输解决静态文件无法加载问题listen8080使用非特权端口避免权限问题worker_processes1单进程模式简化调试
8 完整的 prepare() 函数prepare(){# 设置交叉编译环境if[$ARCHarmeabi-v7a];thensetarm32ENVhostarm-linux-ohosngx_machinearmv7lelif[$ARCHarm64-v8a];thensetarm64ENVhostaarch64-linux-ohosngx_machineaarch64ficd$builddir# 仅在 macOS 上应用修改if[$LYCIUM_BUILD_OSDarwi];then#
跳过编译器运行检测sed-i.baks/ngx_feature_runyes/ngx_feature_runno/gauto/cc/name#
替换 sizeof 脚本根据架构选择预设值catauto/types/sizeofEOF# ... 预设的类型大小检测脚本EOF#
禁用 auto/unix 的运行时检测sed-i.baks/ngx_feature_runyes/ngx_feature_runno/gauto/unixsed-i.baks/ngx_feature_runvalue/ngx_feature_runno/gauto/unixsed-i.baks/ngx_feature_runbug/ngx_feature_runno/gauto/unix#
设置字节序sed-i.baks/ngx_feature_runvalue/ngx_feature_runno/gauto/endiannessficd$OLDPWD}
依赖库的适配nginx 依赖三个核心库它们也需要适配
1 pcre2正则表达式库pcre2 使用标准的 CMake 构建系统交叉编译相对简单lycium 框架已有现成适配。
2 openssl加密库openssl 有完善的交叉编译支持通过指定目标平台即可完成编译lycium 框架已有现成适配。
3 zlib-ng压缩库zlib-ng 在 macOS 上交叉编译时遇到了 libtool 兼容性问题问题: macOS 的 libtool 无法处理 ARM 格式的目标文件解决方案: 在 HPKBUILD 中替换 libtool 为 OHOS SDK 的 llvm-arif[$LYCIUM_BUILD_OSDarwi];thensed-i.baks|^ARlibtool|AR${AR}|gMakefilesed-i.baks|ARFLAGS-o|ARFLAGSrcs|gMakefilefi
构建与验证
1 执行构建cdlycium ./build.sh nginx
2 构建输出Build OS Darwin Start building nginx
1.
2
2! Compileing OpenHarmony armeabi-v7a nginx
1.
2
2 libs... Compileing OpenHarmony arm64-v8a nginx
1.
2
2 libs... Build nginx
1.
2
2 end! ALL JOBS DONE!!!
3 验证编译产物$filelycium/usr/nginx/armeabi-v7a/sbin/nginx ELF32-bit LSB pie executable, ARM, EABI5 version1(SYSV), dynamically linked $filelycium/usr/nginx/arm64-v8a/sbin/nginx ELF64-bit LSB pie executable, ARM aarch64, version1(SYSV), dynamically linked
4 设备端部署与验证
6.
1 目录结构部署到鸿蒙设备后nginx 目录结构如下nginx/ ├── sbin/ │ ├── nginx # 主程序 │ └── libc_shared.so # 运行时依赖库 ├── conf/ │ ├── nginx.conf # 主配置文件 │ ├── mime.types # MIME 类型配置 │ └── ... ├── logs/ # 日志目录需要写权限 └── html/ ├── index.html # 默认首页 └── 50x.html # 错误页面
6.
2 部署步骤#
推送到 OpenHarmony 设备hdcfilesend lycium/usr/nginx/arm64-v8a /data/local/tmp/nginx#
进入设备 shellhdc shell#
设置权限cd/data/local/tmp/nginxchmodx sbin/nginxchmod755logs
6.
3 运行方式由于使用了--prefix..编译nginx 会自动将路径解析为可执行文件所在目录的上一级。
直接从sbin/目录运行即可# 进入 sbin 目录cd/data/local/tmp/nginx/sbin# 测试配置文件./nginx -t# 启动 nginx./nginx# 重新加载配置./nginx -s reload# 停止 nginx./nginx -s stop路径解析示例:当从/data/local/tmp/nginx/sbin/目录运行./nginx时prefix 解析为:/data/local/tmp/nginx/sbin/..//data/local/tmp/nginx/配置文件:/data/local/tmp/nginx/conf/nginx.conf错误日志:/data/local/tmp/nginx/logs/error.log
6.
4 验证服务# 检查版本./nginx --version
技术
总结
1 核心创新点运行时脚本修改技术: 通过在 prepare() 阶段使用 sed 和 cat 命令修改 nginx 的 auto 脚本实现了不修改原库代码的适配架构感知的类型大小预设: 根据目标架构ARM 32-bit/64-bit提供正确的数据类型大小避免了运行时探测的需求平台条件编译: 通过检测LYCIUM_BUILD_OS环境变量仅在 macOS 上应用修改保持 Linux 环境的原有行为相对路径配置: 使用--prefix../配置 nginx注意必须以/结尾使其自动解析为可执行文件上一级目录避免将编译主机的绝对路径硬编码到二进制文件中鸿蒙系统兼容性适配: 禁用sendfile系统调用解决鸿蒙系统上静态文件无法加载的问题
2 方案优势优势说明零侵入性不修改 nginx 原始代码便于版本升级跨平台支持同时支持 macOS 和 Linux 作为构建主机多架构支持同时支持 ARM 32-bit 和 ARM 64-bit 目标可移植部署使用相对路径可部署到任意目录鸿蒙兼容针对鸿蒙系统特性进行配置优化可维护性所有适配逻辑集中在 HPKBUILD 文件中
3 已知问题问题现象解决方案FIOASYNC 警告ioctl(FIOASYNC) failed (25: Not a tty)可忽略不影响功能sendfile 不兼容静态文件无法加载页面空白在 nginx.conf 中设置sendfile off端口权限80 端口需要 root 权限使用 8080 等非特权端口
4 适用范围本文介绍的技术方案不仅适用于 nginx还可以推广到其他使用类似 configure 脚本的开源项目。
关键是识别出哪些检测依赖于运行测试程序并提供相应的绕过或预设值方案。
结论本文详细介绍了使用 lycium 框架将 nginx 适配到 OpenHarmony 系统的完整解决方案。
通过创新性的运行时脚本修改技术成功解决了交叉编译环境下 configure 脚本的运行时检测问题实现了在 macOS 主机上完成 nginx 的鸿蒙交叉编译。
该方案的
核心价值在于完全不修改原库代码这对于开源软件的长期维护和版本升级具有重要意义。
同时本文介绍的技术思路和方法论可以推广应用到其他第三方库的 OpenHarmony 适配工作中。
参考资料nginx 官方文档: https://nginx.org/en/docs/OpenHarmony 官方文档: https://www.openharmony.cn/lycium 框架源码: tpc_c_cplusplus/lycium/OHOS NDK 交叉编译指南0 等非特权端口 |
4 适用范围本文介绍的技术方案不仅适用于 nginx还可以推广到其他使用类似 configure 脚本的开源项目。
关键是识别出哪些检测依赖于运行测试程序并提供相应的绕过或预设值方案。
结论本文详细介绍了使用 lycium 框架将 nginx 适配到 OpenHarmony 系统的完整解决方案。
通过创新性的运行时脚本修改技术成功解决了交叉编译环境下 configure 脚本的运行时检测问题实现了在 macOS 主机上完成 nginx 的鸿蒙交叉编译。
该方案的
核心价值在于完全不修改原库代码这对于开源软件的长期维护和版本升级具有重要意义。
同时本文介绍的技术思路和方法论可以推广应用到其他第三方库的 OpenHarmony 适配工作中。
参考资料nginx 官方文档: https://nginx.org/en/docs/OpenHarmony 官方文档: https://www.openharmony.cn/lycium 框架源码: tpc_c_cplusplus/lycium/OHOS NDK 交叉编译指南欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/