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

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

📋 目录

一、项目概述
[二、为什么需要 HNP 包](#二、为什么需要 HNP 包)
[三、HNP 包打包方法](#三、HNP 包打包方法)
四、安装与使用
[五、Ruby 使用示例](#五、Ruby 使用示例)
[六、Gem 包管理](#六、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上进行开发时，我们经常需要：

✅ 运行 Ruby 脚本：执行自动化脚本、工具脚本等
✅ 开发 Ruby 应用：使用 Ruby 开发命令行工具或应用
✅ 使用 Ruby 生态：利用丰富的 gem 包生态系统
✅ 与其他工具集成：许多工具（如 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 页面下载官方适配完成的预构建包：

bash 复制代码

# 下载 Ruby 预构建包

wgethttps://github.com/Harmonybrew/ohos-ruby/releases/download/3.4.5/ruby-3.4.5-ohos-arm64.tar.gz

3.1.2 解压并查看结构

bash 复制代码

# 解压 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 配置文件：

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 包的路径规则，准备安装目录：

bash 复制代码

# HNP 包的路径规则：${HNP_PUBLIC_PATH}/<包名>.org/<包名>_<版本号>

# 例如：/data/service/hnp/ruby.org/ruby_3.4.5


exportHNP_PUBLIC_PATH=/data/service/hnp

exportRUBY_INSTALL_PATH=${HNP_PUBLIC_PATH}/ruby.org/ruby_3.4.5


# 创建安装目录

mkdir-p ${RUBY_INSTALL_PATH}

3.3 打包脚本

3.3.1 方法一：手动打包

创建打包脚本 pack_hnp.sh：

bash 复制代码

#!/bin/bash

set-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}" ]; then

echo"解压 ${TAR_FILE}..."

tar-zxf ${TAR_FILE}

fi


# 创建安装目录

echo"创建安装目录..."

mkdir-p ${RUBY_INSTALL_PATH}


# 复制文件（保留目录结构）

echo"复制文件..."

cp-r ${EXTRACT_DIR}/* ${RUBY_INSTALL_PATH}/


# 创建 hnp.json

echo"创建 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; then

echo"使用 hnpcli 打包..."

hnpclipack-i ${RUBY_INSTALL_PATH} -o ${OUTPUT_DIR}/

echo"HNP 包已生成: ${OUTPUT_DIR}/ruby.hnp"

else

echo"警告: 未找到 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/null


echo"打包完成！"

echo"输出文件："

echo"  - ${OUTPUT_DIR}/ruby.hnp (如果 hnpcli 可用)"

echo"  - ${OUTPUT_DIR}/ohos_ruby_${RUBY_VERSION}.tar.gz"

3.4 验证打包结果

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

bash 复制代码

# 检查 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）

bash 复制代码

# 在鸿蒙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 验证安装

bash 复制代码

# 检查 Ruby 是否在 PATH 中

whichruby

whichirb

whichgem


# 检查版本

ruby--version

# 应该输出：ruby 3.4.5...


# 检查 gem 版本

gem--version

4.3 配置 PATH（可选）

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

bash 复制代码

# 临时添加到 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 脚本

bash 复制代码

# 创建简单的 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)

bash 复制代码

# 启动 irb

irb


# 在 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 一行命令执行

bash 复制代码

# 使用 -e 参数执行一行 Ruby 代码

ruby-e"puts 'Hello, HarmonyOS!'"


# 使用 -e 执行多行代码

ruby-e"

  name = 'HarmonyOS'

  puts \"Hello, #{name}!\"

"

5.2 文件操作示例

ruby 复制代码

# 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 网络请求示例

ruby 复制代码

# http_request.rb

require'net/http'

require'uri'


uri=URI('https://api.github.com')

response=Net::HTTP.get_response(uri)

puts response.code

puts response.body

5.4 系统命令执行

ruby 复制代码

# system_cmd.rb

# 执行系统命令

result=`ls -la`

puts result


# 使用 system 方法

system('echo "Hello from Ruby"')

5.5 实际应用场景

场景 1：自动化脚本

ruby 复制代码

# deploy.rb

#!/usr/bin/env ruby


require'fileutils'


defdeploy

puts"开始部署..."


# 备份

FileUtils.cp_r('app', 'app.backup')


# 构建

system('make build')


# 部署

FileUtils.cp_r('dist', '/opt/app')


puts"部署完成！"

end


deploy

场景 2：数据处理脚本

ruby 复制代码

# process_data.rb

#!/usr/bin/env ruby


require'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

bash 复制代码

# 列出所有已安装的 gem

gemlist


# 查看特定 gem 的信息

gemlistjson

6.2.2 安装 gem

bash 复制代码

# 安装单个 gem

geminstalljson


# 安装指定版本

geminstalljson-v2.6.0


# 安装到用户目录（不需要 root 权限）

geminstalljson--user-install

6.2.3 卸载 gem

bash 复制代码

# 卸载 gem

gemuninstalljson

6.2.4 更新 gem

bash 复制代码

# 更新所有 gem

gemupdate


# 更新特定 gem

gemupdatejson

6.3 Gemfile 和 Bundler

6.3.1 创建 Gemfile

ruby 复制代码

# Gemfile

source 'https://rubygems.org'


gem 'json', '~> 2.6'

gem 'net-http', '~> 0.3'

gem 'colorize', '~> 0.8'

6.3.2 使用 Bundler

bash 复制代码

# 安装 bundler（如果还没有）

geminstallbundler


# 安装 Gemfile 中指定的所有 gem

bundleinstall


# 运行使用 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 安装路径

bash 复制代码

# 查看 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: 检查以下几点：

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

Q4: 如何卸载 ruby？

A: 手动卸载：

bash 复制代码

# 删除安装目录

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.网络问题：检查网络连接，或使用国内镜像源

bash 复制代码

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

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

bash 复制代码

gem install json --user-install

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

Q6: Ruby 脚本无法找到 gem？

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

ruby 复制代码

# 在脚本开头添加

require'rubygems'

require'json'# 或其他 gem

或者使用 bundler：

bash 复制代码

bundleexecrubyscript.rb

Q7: 如何更新到新版本？

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

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

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

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

bash 复制代码

hdcfilesendruby-3.4.5-ohos-arm64.tar.gz/data

hdcshell

cd/data

tar-zxfruby-3.4.5-ohos-arm64.tar.gz

exportPATH=$PATH:/data/ruby-3.4.5-ohos-arm64/bin