官方适配完的命令行ruby在鸿蒙PC上的使用方法

ohos-ruby是为 OpenHarmony 平台编译的 Ruby 编程语言解释器。本文档详细介绍如何在鸿蒙PC上安装和使用官方适配完成的 Ruby 工具，包括 HNP 包的打包、安装、gem 包管理以及 Ruby 脚本的运行方法。

📋 目录

• 一、项目概述
• 二、为什么需要 HNP 包
• 三、HNP 包打包方法
• 四、安装与使用
• 五、Ruby 使用示例
• 六、Gem 包管理
• 七、常见问题
• 八、总结与最佳实践
• 九、参考资料

一、项目概述

1.1 Ruby 语言简介

Ruby是一种动态、面向对象的编程语言，由 Yukihiro Matsumoto（Matz）开发。它以简洁优雅的语法和强大的元编程能力而闻名，是 Rails 框架的基础语言。

核心特性：

• 💎优雅语法：简洁直观的语法，注重开发者的幸福感
• 🔧动态类型：运行时类型检查，灵活高效
• 🎯面向对象：一切都是对象，包括基本类型
• 📦丰富的生态：通过 gem 包管理器拥有庞大的第三方库生态
• 🚀元编程能力：强大的反射和元编程特性
• 🌐跨平台：支持多种操作系统和平台

主要应用场景：

• Web 开发（Ruby on Rails、Sinatra）
• 脚本编写和自动化任务
• 系统管理和 DevOps 工具
• 命令行工具开发
• 数据处理和分析

1.2 项目信息

| 项目信息 | 详情 |

|---------|------|

|项目名称| ohos-ruby |

|版本| 3.4.5（官方适配版本） |

|许可证| Ruby License / 2-clause BSDL |

|目标平台| 鸿蒙PC (aarch64-linux-ohos) |

|源码仓库| https://www.ruby-lang.org/ |

|适配仓库| https://github.com/Harmonybrew/ohos-ruby |

|预构建包| https://github.com/Harmonybrew/ohos-ruby/releases |

|编译方式| 本地编译（Native Compilation） |

1.3 Ruby 与 ninja 的区别

| 特性 | Ruby | ninja |

|------|------|-------|

|类型| 编程语言解释器 | 构建工具 |

|依赖| 需要 openssl、yaml、zlib、libffi 等 | 静态链接，零依赖 |

|编译方式| 本地编译（在鸿蒙容器中） | 交叉编译（在 Linux/macOS 上） |

|可执行文件| ruby、irb、gem、rake 等多个 | 仅 ninja 一个 |

|包管理| 内置 gem 包管理器 | 无包管理 |

|使用场景| 运行 Ruby 脚本、开发应用 | 执行构建任务 |

1.4 为什么需要 ohos-ruby？

在鸿蒙PC上进行开发时，我们经常需要：

1. ✅运行 Ruby 脚本：执行自动化脚本、工具脚本等
2. ✅开发 Ruby 应用：使用 Ruby 开发命令行工具或应用
3. ✅使用 Ruby 生态：利用丰富的 gem 包生态系统
4. ✅与其他工具集成：许多工具（如 Jekyll、Bundler）依赖 Ruby

二、为什么需要 HNP 包

2.1 系统安全限制

重要说明：在鸿蒙PC上，由于系统安全规格限制等原因，暂不支持通过"解压 + 配 PATH"的方式直接使用 tar.gz 包。

这意味着：

• ❌ 不能直接解压 tar.gz 包到任意目录
• ❌ 不能通过设置 PATH 环境变量来使用
• ✅ 必须打包成 HNP（HarmonyOS Native Package）格式才能正常使用

2.2 HNP 包的优势

HNP 包是鸿蒙PC的官方包管理格式，具有以下优势：

• ✅系统集成：与鸿蒙PC的包管理系统集成
• ✅安全可靠：通过官方工具安装，符合系统安全规范
• ✅易于管理：支持安装、卸载、更新等操作
• ✅路径规范：统一安装在/data/service/hnp/目录下
• ✅依赖管理：可以管理 Ruby 的多个可执行文件和库文件

2.3 Ruby 的特殊性

Ruby 作为编程语言解释器，具有以下特殊性：

• 📦多个可执行文件：ruby、irb、gem、rake、erb 等
• 📚库文件目录：包含标准库和扩展库
• 🔧gem 目录：用于安装第三方 gem 包
• 🔗符号链接：需要创建多个命令的符号链接

三、HNP 包打包方法

3.1 准备工作

3.1.1 下载预构建包

首先，从 release 页面 下载官方适配完成的预构建包：

# 下载 Ruby 预构建包wgethttps://github.com/Harmonybrew/ohos-ruby/releases/download/3.4.5/ruby-3.4.5-ohos-arm64.tar.gz

3.1.2 解压并查看结构

# 解压 tar.gz 包tar-zxfruby-3.4.5-ohos-arm64.tar.gz# 查看目录结构treeruby-3.4.5-ohos-arm64/-L2

目录结构示例：

ruby-3.4.5-ohos-arm64/ ├── bin/ │ ├── ruby # Ruby 解释器 │ ├── irb # 交互式 Ruby Shell │ ├── gem # Gem 包管理器 │ ├── rake # Rake 构建工具 │ ├── erb # ERB 模板处理器 │ └── ... # 其他工具 ├── lib/ │ ├── ruby/ # Ruby 标准库 │ └── ... # 扩展库 ├── share/ │ └── ... # 共享文件 ├── include/ # 头文件 └── licenses.txt # 许可证文件

3.2 创建 HNP 包配置

3.2.1 创建 hnp.json

在解压后的目录中创建hnp.json配置文件：

{"type":"hnp-config","name":"ruby","version":"3.4.5","install":{"links":[{"source":"bin/ruby","target":"ruby"},{"source":"bin/irb","target":"irb"},{"source":"bin/gem","target":"gem"},{"source":"bin/rake","target":"rake"},{"source":"bin/erb","target":"erb"}]}}

配置说明：

-type: 固定为"hnp-config"

-name: 包名称（ruby）

-version: 版本号（3.4.5）

-install.links: 安装时的符号链接配置

-source: 源文件路径（相对于安装目录）

-target: 链接目标名称（命令名称）

注意：Ruby 有多个可执行文件，需要为常用的命令创建符号链接。

3.2.2 准备安装目录结构

按照 HNP 包的路径规则，准备安装目录：

# HNP 包的路径规则：${HNP_PUBLIC_PATH}/<包名>.org/<包名>_<版本号># 例如：/data/service/hnp/ruby.org/ruby_3.4.5exportHNP_PUBLIC_PATH=/data/service/hnpexportRUBY_INSTALL_PATH=${HNP_PUBLIC_PATH}/ruby.org/ruby_3.4.5# 创建安装目录mkdir-p${RUBY_INSTALL_PATH}

3.3 打包脚本

3.3.1 方法一：手动打包

创建打包脚本pack_hnp.sh：

#!/bin/bashset-e# 配置变量RUBY_VERSION="3.4.5"TAR_FILE="ruby-${RUBY_VERSION}-ohos-arm64.tar.gz"EXTRACT_DIR="ruby-${RUBY_VERSION}-ohos-arm64"HNP_PUBLIC_PATH="/data/service/hnp"RUBY_INSTALL_PATH="${HNP_PUBLIC_PATH}/ruby.org/ruby_${RUBY_VERSION}"OUTPUT_DIR="output"WORKDIR=$(pwd)# 创建输出目录mkdir-p${OUTPUT_DIR}# 解压 tar.gz 包if[!-d"${EXTRACT_DIR}"];thenecho"解压${TAR_FILE}..."tar-zxf${TAR_FILE}fi# 创建安装目录echo"创建安装目录..."mkdir-p${RUBY_INSTALL_PATH}# 复制文件（保留目录结构）echo"复制文件..."cp-r${EXTRACT_DIR}/*${RUBY_INSTALL_PATH}/# 创建 hnp.jsonecho"创建 hnp.json..."cat>${RUBY_INSTALL_PATH}/hnp.json<<'EOF' { "type": "hnp-config", "name": "ruby", "version": "3.4.5", "install": { "links": [ { "source": "bin/ruby", "target": "ruby" }, { "source": "bin/irb", "target": "irb" }, { "source": "bin/gem", "target": "gem" }, { "source": "bin/rake", "target": "rake" }, { "source": "bin/erb", "target": "erb" } ] } } EOF# 设置执行权限echo"设置执行权限..."chmod+x${RUBY_INSTALL_PATH}/bin/*# 使用 hnpcli 打包（如果可用）ifcommand-vhnpcli&>/dev/null;thenecho"使用 hnpcli 打包..."hnpclipack-i${RUBY_INSTALL_PATH}-o${OUTPUT_DIR}/echo"HNP 包已生成:${OUTPUT_DIR}/ruby.hnp"elseecho"警告: 未找到 hnpcli 工具，跳过 HNP 包生成"echo"请手动使用 hnpcli 打包:"echo" hnpcli pack -i${RUBY_INSTALL_PATH}-o${OUTPUT_DIR}/"fi# 生成 tar.gz 包（备用）echo"生成 tar.gz 包..."cd${HNP_PUBLIC_PATH}/ruby.org tar-zcf${WORKDIR}/${OUTPUT_DIR}/ohos_ruby_${RUBY_VERSION}.tar.gzruby_${RUBY_VERSION}/ cd->/dev/nullecho"打包完成！"echo"输出文件："echo" -${OUTPUT_DIR}/ruby.hnp (如果 hnpcli 可用)"echo" -${OUTPUT_DIR}/ohos_ruby_${RUBY_VERSION}.tar.gz"

3.4 验证打包结果

打包完成后，验证生成的文件：

# 检查 HNP 包ls-lhoutput/ruby.hnp# 检查 tar.gz 包ls-lhoutput/ohos_ruby_3.4.5.tar.gz# 验证安装目录结构tree${RUBY_INSTALL_PATH}/-L2

预期的安装目录结构：

/data/service/hnp/ruby.org/ruby_3.4.5/ ├── bin/ │ ├── ruby # Ruby 解释器 │ ├── irb # 交互式 Ruby Shell │ ├── gem # Gem 包管理器 │ └── ... # 其他工具 ├── lib/ │ └── ruby/ # Ruby 标准库 ├── share/ # 共享文件 ├── include/ # 头文件 ├── licenses.txt # 许可证文件 └── hnp.json # HNP 配置文件

四、安装与使用

4.1 安装 HNP 包

手动安装（使用 tar.gz）

# 在鸿蒙PC上执行# 1. 解压 tar.gz 包tar-xzfohos_ruby_3.4.5.tar.gz# 2. 复制到安装目录sudocp-rruby_3.4.5/*/data/service/hnp/ruby.org/ruby_3.4.5/# 3. 设置执行权限sudochmod+x/data/service/hnp/ruby.org/ruby_3.4.5/bin/*# 4. 创建符号链接（根据 hnp.json 配置）# hnp 系统会自动处理 links 配置，但也可以手动创建sudoln-sf/data/service/hnp/ruby.org/ruby_3.4.5/bin/ruby/usr/local/bin/ruby sudoln-sf/data/service/hnp/ruby.org/ruby_3.4.5/bin/irb/usr/local/bin/irb sudoln-sf/data/service/hnp/ruby.org/ruby_3.4.5/bin/gem/usr/local/bin/gem

4.2 验证安装

# 检查 Ruby 是否在 PATH 中whichruby whichirb whichgem# 检查版本ruby--version# 应该输出：ruby 3.4.5...# 检查 gem 版本gem--version

4.3 配置 PATH（可选）

如果 Ruby 命令不在 PATH 中，可以手动添加到 PATH：

# 临时添加到 PATH（当前会话有效）exportPATH=$PATH:/data/service/hnp/ruby.org/ruby_3.4.5/bin# 永久添加到 PATH（添加到 ~/.bashrc 或 ~/.zshrc）echo'export PATH=$PATH:/data/service/hnp/ruby.org/ruby_3.4.5/bin'>>~/.bashrc source~/.bashrc

五、Ruby 使用示例

5.1 基本使用

5.1.1 运行 Ruby 脚本

# 创建简单的 Ruby 脚本cat>hello.rb<<'EOF' #!/usr/bin/env ruby puts "Hello, HarmonyOS!" puts "Ruby version: #{RUBY_VERSION}" EOF# 运行脚本rubyhello.rb# 输出:# Hello, HarmonyOS!# Ruby version: 3.4.5

5.1.2 交互式 Ruby Shell (irb)

# 启动 irbirb# 在 irb 中执行：# irb(main):001:0> puts "Hello, World!"# Hello, World!# => nil# irb(main):002:0> 1 + 1# => 2# irb(main):003:0> exit

5.1.3 一行命令执行

# 使用 -e 参数执行一行 Ruby 代码ruby-e"puts 'Hello, HarmonyOS!'"# 使用 -e 执行多行代码ruby-e" name = 'HarmonyOS' puts\"Hello, #{name}!\""

5.2 文件操作示例

# file_ops.rb# 读取文件content=File.read('input.txt')puts content# 写入文件File.write('output.txt','Hello, HarmonyOS!')# 遍历目录Dir.glob('*.rb').eachdo|file|puts"Found:#{file}"end

5.3 网络请求示例

# http_request.rbrequire'net/http'require'uri'uri=URI('https://api.github.com')response=Net::HTTP.get_response(uri)puts response.code puts response.body

5.4 系统命令执行

# system_cmd.rb# 执行系统命令result=`ls-la` puts result# 使用 system 方法system('echo "Hello from Ruby"')

5.5 实际应用场景

场景 1：自动化脚本

# deploy.rb#!/usr/bin/env rubyrequire'fileutils'defdeploy puts"开始部署..."# 备份FileUtils.cp_r('app','app.backup')# 构建system('make build')# 部署FileUtils.cp_r('dist','/opt/app')puts"部署完成！"enddeploy

场景 2：数据处理脚本

# process_data.rb#!/usr/bin/env rubyrequire'json'# 读取 JSON 数据data=JSON.parse(File.read('data.json'))# 处理数据results=data.mapdo|item|{id:item['id'],name:item['name'].upcase,value:item['value']*2}end# 输出结果putsJSON.pretty_generate(results)

六、Gem 包管理

6.1 Gem 简介

Gem是 Ruby 的包管理器，类似于 Python 的 pip 或 Node.js 的 npm。它用于安装和管理 Ruby 的第三方库（gem 包）。

6.2 基本操作

6.2.1 查看已安装的 gem

# 列出所有已安装的 gemgemlist# 查看特定 gem 的信息gemlistjson

6.2.2 安装 gem

# 安装单个 gemgeminstalljson# 安装指定版本geminstalljson-v2.6.0# 安装到用户目录（不需要 root 权限）geminstalljson--user-install

6.2.3 卸载 gem

# 卸载 gemgemuninstalljson

6.2.4 更新 gem

# 更新所有 gemgemupdate# 更新特定 gemgemupdatejson

6.3 Gemfile 和 Bundler

6.3.1 创建 Gemfile

# Gemfilesource'https://rubygems.org'gem'json','~> 2.6'gem'net-http','~> 0.3'gem'colorize','~> 0.8'

6.3.2 使用 Bundler

# 安装 bundler（如果还没有）geminstallbundler# 安装 Gemfile 中指定的所有 gembundleinstall# 运行使用 bundler 管理的脚本bundleexecrubyscript.rb

6.4 常用 Gem 推荐

| Gem 名称 | 用途 | 安装命令 |

|---------|------|---------|

|json| JSON 处理 |gem install json|

|net-http| HTTP 客户端 |gem install net-http|

|colorize| 终端颜色输出 |gem install colorize|

|fileutils| 文件操作（标准库） | 已包含 |

|date| 日期时间处理（标准库） | 已包含 |

|yaml| YAML 处理（标准库） | 已包含 |

6.5 Gem 安装路径

# 查看 gem 安装路径gemenv# 查看 gem 路径gemwhichjson

注意：在 HNP 包安装的 Ruby 中，gem 默认安装到：

/data/service/hnp/ruby.org/ruby_3.4.5/lib/ruby/gems/3.4.0/gems/

七、常见问题

Q1: 为什么不能直接使用 tar.gz 包？

A:由于鸿蒙PC的系统安全规格限制，不允许通过"解压 + 配 PATH"的方式直接使用软件包。必须使用 HNP 包格式，通过官方包管理工具安装。

Q2: 如何获取 hnpcli 工具？

A:hnpcli 是鸿蒙PC的包管理工具，通常包含在 OHOS SDK 中。你可以：

• 从 OHOS SDK 下载
• 参考 DevBox 项目获取构建工具

Q3: 安装后找不到 ruby 命令？

A:检查以下几点：

1. 确认安装路径是否正确：/data/service/hnp/ruby.org/ruby_3.4.5/bin/ruby
2. 检查 PATH 环境变量是否包含该路径
3. 检查 hnp.json 中的 links 配置是否正确
4. 尝试手动创建符号链接

Q4: 如何卸载 ruby？

A:手动卸载：

# 删除安装目录sudorm-rf/data/service/hnp/ruby.org/ruby_3.4.5# 删除符号链接sudorm-f/usr/local/bin/ruby/usr/local/bin/irb/usr/local/bin/gem

Q5: gem install 失败怎么办？

A:可能的原因和解决方案：

1.网络问题：检查网络连接，或使用国内镜像源

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

2.权限问题：使用--user-install安装到用户目录

geminstalljson --user-install

3.依赖缺失：某些 gem 需要编译扩展，确保有编译工具链

Q6: Ruby 脚本无法找到 gem？

A:确保 gem 的路径在 Ruby 的加载路径中：

# 在脚本开头添加require'rubygems'require'json'# 或其他 gem

或者使用 bundler：

bundleexecrubyscript.rb

Q7: 如何更新到新版本？

A:

1. 下载新版本的预构建包
2. 按照打包步骤重新打包
3. 卸载旧版本：hnp uninstall ruby
4. 安装新版本：hnp install ruby.hnp

注意：更新后需要重新安装 gem 包。

Q8: 可以在开发板上使用 tar.gz 包吗？

A:可以。在鸿蒙开发板上，可以使用 hdc 推送 tar.gz 包，然后解压使用：

hdcfilesendruby-3.4.5-ohos-arm64.tar.gz/data hdcshell cd/data tar-zxfruby-3.4.5-ohos-arm64.tar.gzexportPATH=$PATH:/data/ruby-3.4.5-ohos-arm64/bin