Documentation | Chat

HarmonyOS 移植版本

项目仓库: https://gitcode.com/ystyle/neovim-harmonyos

本项目是将 Neovim 移植到 HarmonyOS PC（鸿蒙PC）的完整解决方案，支持 HarmonyOS HongMeng Kernel 1.11.0（aarch64 架构）。移植使用独立的依赖构建系统 harmonyos-deps 编译所有必要的依赖库。

核心特性

• ✅ 完整依赖构建 - Lua、libuv、lpeg、libiconv、luv、lua_compat53 等
• ✅ HarmonyOS适配 - 特定补丁和兼容性修复
• ✅ 静态链接方案 - 绕过 HarmonyOS 动态加载限制
• ✅ 自动化工具 - 补丁生成、构建脚本、环境配置

Lua 版本支持

本项目提供两个版本分支以满足不同需求：

1. 主分支 (harmonyos-port) - 推荐使用

• Lua 版本: LuaJIT 2.1.ROLLING（禁用JIT版本）
• 特点: 使用LuaJIT，性能最佳，保持Lua 5.1 API兼容性
• 适用场景: 生产环境，需要最高性能和稳定性
• 注意: 在HarmonyOS上JIT编译被禁用（mmap(PROT_EXEC)失败），但仍提供其他优化
• 状态: ✅ 稳定可用

2. Lua 5.4 分支 (harmonyos-lua54) - 实验性

• Lua 版本: 5.4（实验版）
• 特点: 支持现代Lua特性，包含Lua 5.1兼容层
• 适用场景: 需要使用Lua 5.2+特性的插件，实验性环境
• 注意: 可能存在兼容性问题，不建议生产环境使用
• 状态: ⚠️ 实验性，可能存在兼容性问题

Lua 5.1 兼容层

Lua 5.4分支包含完整的Lua 5.1兼容层，重新实现了在Lua 5.2+中被移除的API：

• table.maxn, loadstring, table.unpack, module函数
• package.loaders, getfenv/setfenv
• math.log10, math.pow, bit32库等

兼容性测试结果：✅ 所有Lua 5.1 API在Lua 5.4中可用，第三方插件无需修改即可工作。

快速开始

# 1. 克隆项目
git clone https://gitcode.com/ystyle/neovim-harmonyos.git
cd neovim-harmonyos

# 2. 克隆依赖仓库
git clone https://gitcode.com/ystyle/neovim-harmonyos-deps.git harmonyos-deps

# 3. 构建依赖
cd harmonyos-deps && ./build-deps-harmonyos.sh && cd ..

# 4. 构建 Neovim
./build-ohos-with-log.sh

# 5. 运行测试
./run-nvim.sh

运行建议：

• 推荐使用./run-nvim.sh脚本启动，该脚本已正确配置环境变量
• 如果直接运行nvim遇到终端控制问题，可使用sh -c 'nvim'方式
• 在zsh中直接运行可能遇到终端检测问题，建议使用脚本或sh方式

切换到不同 Lua 版本分支

1. 切换到 LuaJIT 分支（主分支）- 推荐

# 切换到主分支（LuaJIT）
git checkout harmonyos-port

# 重新构建依赖（需要LuaJIT版本）
cd harmonyos-deps && ./build-deps-harmonyos.sh && cd ..

# 重新构建 Neovim
./build-ohos-with-log.sh

2. 切换到 Lua 5.4 分支 - 实验性

# 切换到 Lua 5.4 分支（实验性）
git checkout harmonyos-lua54

# 重新构建依赖（需要Lua 5.4版本）
cd harmonyos-deps && ./build-deps-harmonyos.sh && cd ..

# 重新构建 Neovim
./build-ohos-with-log.sh

---

技术实现细节

静态链接方案

由于 HarmonyOS 对动态加载的限制，本项目采用完全静态链接方案：

• 所有 Lua 模块预编译并嵌入二进制
• 依赖库编译为静态库（.a 文件）
• 使用静态 Lua 解释器进行代码生成

HarmonyOS 特定适配

1. TTY 权限修复：修改 libuv 跳过文件描述符复制，避免 SELinux 权限问题
2. MessagePack 兼容性：实现动态数据大小检测，解决 sizeof() 计算错误
3. Lua 环境初始化：使用 preload_minimal.lua 确保模块加载顺序正确

LuaJIT 在 HarmonyOS 上的实现

主分支使用 LuaJIT 2.1.ROLLING，但在 HarmonyOS 上 JIT 编译被禁用：

技术细节：

• JIT 禁用: 由于 HarmonyOS 上 mmap(PROT_EXEC) 失败，构建时使用 -DLUAJIT_DISABLE_JIT
• 性能影响: 虽然 JIT 被禁用，但 LuaJIT 仍提供比标准 Lua 5.1 更好的性能
• API 兼容性: 完全兼容 Lua 5.1 API，所有 Lua 5.1 插件可用
• 构建配置: 通过修改 src/nvim/CMakeLists.txt 确保优先使用 LuaJIT

Lua 5.4 兼容层（harmonyos-lua54 分支）

Lua 5.4 分支包含完整的 Lua 5.1 兼容层，确保第三方插件无需修改即可工作：

核心特性：

• 重新实现 Lua 5.2+ 中移除的 API：table.maxn、loadstring、module 等
• 提供 bit32 库完整实现
• 自动加载兼容层模块 (vim.compat)
• 支持 Lua 5.2+ 的 goto 语句等现代特性

兼容性保证：✅ 所有 Lua 5.1 API 在 Lua 5.4 中可用，第三方插件无需修改即可工作。

构建脚本说明

• build-ohos-with-log.sh - 主构建脚本，包含完整日志记录
• harmonyos.toolchain.cmake - HarmonyOS 工具链配置
• src/gen/static_bridge.sh - 静态 Lua 解释器桥接脚本

---

已知问题和解决方案

问题	症状	解决方案
TTY 权限被拒绝	uv_tty_set_mode 返回 UV_EACCES	修改 libuv 跳过 fd 复制
MessagePack 解析失败	unpack() 返回 "trailing data" 错误	实现动态数据大小检测
Lua 模块加载失败	vim.g、vim.F 等字段为 nil	使用静态解释器和预加载机制
帮助文档生成失败	"Operation not permitted" 错误	手动生成或跳过此步骤
二进制文件执行失败	"Operation not permitted" 错误	使用 binary-sign-tool 手动签名
ShaDa文件写入错误	E137: ShaDa file is not writable	禁用ShaDa功能或清理临时文件
LuaJIT JIT编译失败	mmap(PROT_EXEC) 失败	构建时禁用JIT（-DLUAJIT_DISABLE_JIT）

---

详细文档

• 移植任务跟踪 - 完整的移植过程和问题解决记录
• HarmonyOS 构建指南 - 构建步骤和配置说明
• 混合解决方案 - 技术实现细节
• 插件兼容性分析 - 插件生态评估

---

详细构建说明

环境要求

• 操作系统: HarmonyOS HongMeng Kernel 1.11.0 或更高版本
• IDE: CodeArts IDE
• 架构: aarch64 (ARM64)
• 编译器: BiSheng Clang 15.0.4（鸿蒙官方编译器, CodeArts IDE自带）
• 构建工具:
  • CMake ≥ 3.16
  • Ninja 构建系统
  • Git、Curl、Tar 等基础工具

构建过程说明

1. 依赖构建 (harmonyos-deps/build-deps-harmonyos.sh)

   • 下载所有依赖源码
   • 应用 HarmonyOS 特定补丁
   • 编译为静态库（避免动态加载限制）
   • 安装到 harmonyos-deps/build/ 目录

2. Neovim构建 (build-ohos-with-log.sh)

   • 检测 HarmonyOS 系统并设置编译选项
   • 使用静态 Lua 解释器进行代码生成
   • 链接所有依赖静态库
   • 生成签名的可执行文件

手动签名说明（可选）

如果构建过程中自动签名失败，或需要在CodeArts IDE中手动签名，可以使用以下命令：

# 手动签名二进制文件（自签名）
binary-sign-tool sign -inFile build/bin/nvim -outFile build/bin/nvim -selfSign 1

# 验证签名
binary-sign-tool verify -inFile build/bin/nvim

CodeArts IDE中手动签名步骤：

1. 在CodeArts IDE中打开终端
2. 导航到项目目录：cd /path/to/neovim-harmonyos
3. 执行签名命令
4. 签名后即可在本机执行已签名的二进制命令

注意事项：

• 自签名仅用于开发和测试环境
• 生产环境建议使用正式签名证书
• 签名失败可能导致"Operation not permitted"错误

运行说明

项目提供 run-nvim.sh 脚本自动配置环境变量：

推荐使用脚本运行：

# 使用脚本运行（推荐）- 已正确配置环境变量和终端兼容性
./run-nvim.sh

备用运行方式： 如果直接运行遇到终端控制问题（如光标无法控制），建议使用以下方式：

# 使用sh方式运行（解决zsh终端检测问题）
sh -c './build/bin/nvim'

# 或手动设置环境变量后使用sh方式
export VIMRUNTIME=$(pwd)/runtime
export LUA_PATH="$(pwd)/runtime/lua/?.lua;$(pwd)/runtime/lua/?/init.lua;;"
export LUA_CPATH=";;"
sh -c './build/bin/nvim'

终端兼容性说明：

• 在HarmonyOS上，zsh的终端检测可能与Neovim不完全兼容
• 使用sh方式可以避免终端检测问题
• run-nvim.sh脚本已处理这些兼容性问题

构建产物:

• build/bin/nvim - HarmonyOS 版本的 Neovim 二进制文件
• harmonyos-deps/build/ - 所有依赖库和头文件
• logs/ - 构建日志文件
• run-nvim.sh - 运行脚本（已包含环境配置）

---

在鸿蒙PC上长期使用

为了在鸿蒙PC上长期使用Neovim，建议将构建产物安装到用户目录~/.local中，这样可以在任何终端中直接使用nvim命令。

1. 查看当前~/.local目录结构

ls -l ~/.local

典型输出：

drwxrws--x - 20001006 19 Dec 02:15 bin
drwxrws--x - 20001006 17 Dec 22:45 opt
drwxrws--x - 20001006 18 Dec 01:36 share
drwxrws--x - 20001006  9 Dec 22:46 state

2. 安装到~/.local目录

# 创建必要的目录（如果不存在）
mkdir -p ~/.local/bin
mkdir -p ~/.local/share/nvim
mkdir -p ~/.local/state/nvim
mkdir -p ~/.local/opt/nvim

# 复制nvim二进制文件到bin目录
cp build/bin/nvim ~/.local/bin/

# 如果需要，对复制的二进制文件进行手动签名
# binary-sign-tool sign -inFile ~/.local/bin/nvim -outFile ~/.local/bin/nvim -selfSign 1

# 复制runtime文件到share目录
cp -r runtime ~/.local/share/nvim/

# 复制依赖库到opt目录（如果需要）
cp -r harmonyos-deps/build ~/.local/opt/nvim/deps

# 设置可执行权限
chmod +x ~/.local/bin/nvim

3. 配置环境变量

将以下内容添加到~/.zshrc中：

# Neovim HarmonyOS 环境配置
export XDG_CONFIG_HOME="$HOME/.config"
export PATH="$HOME/.local/bin:$PATH"
export VIMRUNTIME="$HOME/.local/share/nvim/runtime"
export NVIM_LOG_FILE="$HOME/.local/state/nvim/nvim.log"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_STATE_HOME="$HOME/.local/state"
export XDG_CACHE_HOME="$HOME/.local/state"

# Lua模块搜索路径（如果环境变量没展开的话，可以改成绝对路径， 可能是lua兼容性问题）
export LUA_PATH="$HOME/.local/share/nvim/runtime/lua/?.lua;$HOME/.local/share/nvim/runtime/lua/?/init.lua;;"
export LUA_CPATH=";;"

# 依赖库路径（如果需要）
export LD_LIBRARY_PATH="$HOME/.local/opt/nvim/deps/lib:$LD_LIBRARY_PATH"

4. 应用配置并测试

# 重新加载shell配置
source  ~/.zshrc

# 测试安装
which nvim        # 应该显示 ~/.local/bin/nvim
nvim --version    # 应该显示HarmonyOS版本信息

# 创建运行脚本
cat > ~/.local/bin/run-nvim << 'EOF'
#!/bin/sh
export VIMRUNTIME="$HOME/.local/share/nvim/runtime"
export LUA_PATH="$VIMRUNTIME/lua/?.lua;$VIMRUNTIME/lua/?/init.lua;;"
export LUA_CPATH=";;"
exec nvim "$@"
EOF
chmod +x ~/.local/bin/run-nvim

5. 创建配置文件（可选）

# 创建配置目录
mkdir -p ~/.config/nvim

# 创建基本init.lua配置
cat > ~/.config/nvim/init.lua << 'EOF'
-- HarmonyOS Neovim 基本配置
vim.opt.number = true          -- 显示行号
vim.opt.relativenumber = true  -- 相对行号
vim.opt.tabstop = 4           -- Tab宽度
vim.opt.shiftwidth = 4        -- 缩进宽度
vim.opt.expandtab = true      -- 使用空格代替Tab
vim.opt.shada = ""            -- 禁用ShaDa功能，避免HarmonyOS上文件写入错误

-- 插件管理器配置（如果需要）
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git",
    "clone",
    "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable",
    lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

-- 更多配置...
EOF

6. 使用说明

安装完成后，您可以在任何终端中：

• 直接运行nvim命令启动编辑器
• 使用run-nvim脚本（包含环境变量配置）
• 配置文件位于~/.config/nvim/init.lua

重要提示：

• 主分支使用 LuaJIT（JIT禁用版本），性能优于标准Lua 5.1
• 配置文件中的vim.opt.shada = ""用于禁用ShaDa功能，避免HarmonyOS上文件写入错误
• 如果遇到ShaDa错误，请检查配置文件是否正确设置了shada选项
• 终端兼容性建议：
  • 推荐使用提供的run-nvim.sh脚本启动Neovim，该脚本已正确配置环境变量
  • 如果直接运行nvim命令遇到终端控制问题（如光标无法控制），建议使用以下方式：

    # 使用sh方式运行
    sh -c 'nvim'
    
    # 或使用脚本
    ./run-nvim.sh
    

  • 在zsh中直接运行nvim可能遇到终端检测问题，这是因为HarmonyOS上zsh的终端检测与Neovim不完全兼容

7. 更新和卸载

更新：

cd /path/to/neovim-harmonyos
git pull
./build-ohos-with-log.sh
cp build/bin/nvim ~/.local/bin/

卸载：

rm ~/.local/bin/nvim
rm ~/.local/bin/run-nvim
rm -rf ~/.local/share/nvim
rm -rf ~/.local/opt/nvim/deps
# 从.bashrc/.zshrc中移除相关环境变量

---

Neovim is a project that seeks to aggressively refactor Vim in order to:

• Simplify maintenance and encourage contributions
• Split the work between multiple developers
• Enable advanced UIs without modifications to the core
• Maximize extensibility

See the Introduction wiki page and Roadmap for more information.

Features

• Modern GUIs
• API access from any language including C/C++, C#, Clojure, D, Elixir, Go, Haskell, Java/Kotlin, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, Ruby, Rust
• Embedded, scriptable terminal emulator
• Asynchronous job control
• Shared data (shada) among multiple editor instances
• XDG base directories support
• Compatible with most Vim plugins, including Ruby and Python plugins

See :help nvim-features for the full list, and :help news for noteworthy changes in the latest version!

Install from package

Pre-built packages for Windows, macOS, and Linux are found on the Releases page.

Managed packages are in Homebrew, Debian, Ubuntu, Fedora, Arch Linux, Void Linux, Gentoo, and more!

Install from source

See BUILD.md and supported platforms for details.

The build is CMake-based, but a Makefile is provided as a convenience. After installing the dependencies, run the following command.

make CMAKE_BUILD_TYPE=RelWithDebInfo
sudo make install

To install to a non-default location:

make CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_INSTALL_PREFIX=/full/path/
make install

CMake hints for inspecting the build:

• cmake --build build --target help lists all build targets.
• build/CMakeCache.txt (or cmake -LAH build/) contains the resolved values of all CMake variables.
• build/compile_commands.json shows the full compiler invocations for each translation unit.

Transitioning from Vim

See :help nvim-from-vim for instructions.

Project layout

├─ cmake/           CMake utils
├─ cmake.config/    CMake defines
├─ cmake.deps/      subproject to fetch and build dependencies (optional)
├─ runtime/         plugins and docs
├─ src/nvim/        application source code (see src/nvim/README.md)
│  ├─ api/          API subsystem
│  ├─ eval/         Vimscript subsystem
│  ├─ event/        event-loop subsystem
│  ├─ generators/   code generation (pre-compilation)
│  ├─ lib/          generic data structures
│  ├─ lua/          Lua subsystem
│  ├─ msgpack_rpc/  RPC subsystem
│  ├─ os/           low-level platform code
│  └─ tui/          built-in UI
└─ test/            tests (see test/README.md)

License

Neovim contributions since b17d96 are licensed under the Apache 2.0 license, except for contributions copied from Vim (identified by the vim-patch token). See LICENSE for details.

Vim is Charityware.  You can use and copy it as much as you like, but you are
encouraged to make a donation for needy children in Uganda.  Please see the
kcc section of the vim docs or visit the ICCF web site, available at these URLs:

        https://iccf-holland.org/
        https://www.vim.org/iccf/
        https://www.iccf.nl/

You can also sponsor the development of Vim.  Vim sponsors can vote for
features.  The money goes to Uganda anyway.