pnana 依赖文档

July 20, 2026 · View on GitHub

本文档基于 CMakeLists.txt 和 build.sh，说明 pnana 的构建依赖与可选功能。

目录

构建工具

工具版本说明
CMake≥ 3.10构建系统
C++ 编译器C++17GCC 7+ / Clang 5+ / MSVC 2017+

安装

Ubuntu/Debian

sudo apt update
sudo apt install cmake build-essential g++

Fedora/RHEL

sudo dnf install cmake gcc-c++

macOS

brew install cmake
xcode-select --install

必需依赖

FTXUI

FTXUI (Functional Terminal User Interface) 为必需库，用于终端 UI。

Ubuntu/Debian sudo apt install libftxui-dev
Fedora/RHEL sudo dnf install ftxui-devel
macOS brew install ftxui

验证：pkg-config --modversion ftxui

可选功能与依赖

以下功能默认关闭，需通过 CMake 或 build.sh 显式启用。

LSP 支持（自动检测）

依赖：third-party/nlohmann/json.hpp、third-party/JSON-RPC-CXX

若项目内存在上述库，LSP 会自动启用，无需系统包。否则 LSP 功能不可用。

git submodule update --init --recursive  # 初始化子模块

图片预览（-DBUILD_IMAGE_PREVIEW=ON）

依赖：Chafa 开发库

Ubuntu/Debian sudo apt install libchafa-dev
Fedora/RHEL sudo dnf install chafa-devel
macOS brew install chafa

验证：pkg-config --modversion chafa

Tree-sitter 语法高亮（-DBUILD_TREE_SITTER=ON）

依赖：Tree-sitter 开发库

Ubuntu/Debian sudo apt install libtree-sitter-dev
Fedora/RHEL sudo dnf install tree-sitter-devel
macOS brew install tree-sitter

验证：pkg-config --modversion tree-sitter

未启用时使用内置语法高亮器。

Lua 插件系统（-DBUILD_LUA=ON）

依赖：Lua 5.3 或 5.4

Ubuntu/Debian sudo apt install liblua5.4-dev
Fedora/RHEL sudo dnf install lua-devel
macOS brew install lua

Go SSH 模块（-DBUILD_SSH_MODE=GO）

依赖：Go 编译器

Ubuntu/Debian sudo apt install golang-go
Fedora/RHEL sudo dnf install golang
macOS brew install go

C++ SSH 模块（-DBUILD_SSH_MODE=CPP）

依赖：libssh2 开发库

Ubuntu/Debian sudo apt install libssh2-1-dev
Fedora/RHEL sudo dnf install libssh2-devel
macOS brew install libssh2

不启用 SSH（-DBUILD_SSH_MODE=NONE，默认）

无需额外依赖，使用系统 SSH 命令作为后备。

libvterm 终端模拟（-DBUILD_LIBVTERM=ON）

依赖：libvterm 开发库

Ubuntu/Debian sudo apt install libvterm-dev
Fedora/RHEL sudo dnf install libvterm-devel
macOS brew install libvterm

用于完整的终端模拟功能。

验证：pkg-config --modversion vterm

终端图像协议（-DBUILD_IMAGE_PROTOCOL=ON）

依赖：libsixel（可选，用于 Sixel 编码）

Ubuntu/Debian sudo apt install libsixel-dev
Fedora/RHEL sudo dnf install libsixel-devel
macOS brew install libsixel

支持 Kitty、iTerm2 和 Sixel 终端图像协议。若 libsixel 未安装则使用内置编码。

注意：在支持 Kitty 图像协议的终端中可能存在渲染残留问题，按 F3 输入 proto 可关闭协议。

Nerd Font 图标（-DBUILD_ICON_SUPPORT=ON，默认：ON）

依赖：无（Nerd Font 字形以 Unicode 字符串内嵌）

启用时（默认），使用 Nerd Font Unicode 字符显示文件类型和 UI 图标。 关闭时（-DBUILD_ICON_SUPPORT=OFF），使用 ASCII 字符替代。 运行时需终端安装 Nerd Font 字体才能正常显示图标。

AI 客户端（-DBUILD_AI_CLIENT=ON）

依赖：libcurl

Ubuntu/Debian sudo apt install libcurl4-openssl-dev
Fedora/RHEL sudo dnf install libcurl-devel
macOS brew install curl

iconv（自动检测，可选）

用于编码转换。若未找到，使用内置实现。多数 Linux 发行版已包含，无需单独安装。

内置第三方库

以下库随源码提供，无需单独安装：

库路径用途
nlohmann/jsonthird-party/nlohmann/json.hppJSON，LSP 与 AI 配置
jsonrpccxxthird-party/JSON-RPC-CXXJSON-RPC，LSP
stbthird-party/dsa/stb_image.h图像处理

构建与启用

使用 build.sh

./build.sh                                    # 基础编译（LSP 自动检测）
./build.sh BUILD_ICON_SUPPORT=OFF             # ASCII 图标（禁用 Nerd Font）
./build.sh BUILD_IMAGE_PREVIEW=ON             # 图片预览（Chafa）
./build.sh BUILD_IMAGE_PROTOCOL=ON            # 终端图像协议
./build.sh BUILD_TREE_SITTER=ON               # Tree-sitter
./build.sh BUILD_LUA=ON                       # Lua 插件
./build.sh BUILD_SSH_MODE=GO                  # Go SSH 模块
./build.sh BUILD_SSH_MODE=CPP                 # C++ SSH 模块（基于 libssh2）
./build.sh BUILD_SSH_MODE=NONE                # 不启用 SSH（默认）
./build.sh BUILD_LIBVTERM=ON                  # libvterm 终端模拟
./build.sh BUILD_AI_CLIENT=ON                 # AI 客户端
./build.sh --clean BUILD_LUA=ON               # 清理后编译
./build.sh --clean --install BUILD_AI_CLIENT=ON  # 编译并安装

使用 CMake

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

# 启用可选功能
cmake .. -DBUILD_IMAGE_PREVIEW=ON \
        -DBUILD_IMAGE_PROTOCOL=ON \
        -DBUILD_TREE_SITTER=ON \
        -DBUILD_LUA=ON \
        -DBUILD_SSH_MODE=GO \
        -DBUILD_LIBVTERM=ON \
        -DBUILD_AI_CLIENT=ON \
        -DBUILD_ICON_SUPPORT=ON

make -j$(nproc)

CMake 选项一览

选项默认依赖功能
BUILD_ICON_SUPPORTON无（Nerd Font 内嵌）Nerd Font 图标
BUILD_IMAGE_PREVIEWOFFChafa图片预览
BUILD_IMAGE_PROTOCOLOFFlibsixel（可选）终端图像协议
BUILD_TREE_SITTEROFFTree-sitter语法高亮
BUILD_LUAOFFLua 5.3/5.4Lua 插件
BUILD_SSH_MODENONEGo/libssh2SSH 模块（GO/CPP/NONE）
BUILD_LIBVTERMOFFlibvterm终端模拟
BUILD_AI_CLIENTOFFlibcurlAI 客户端

LSP 由内置 nlohmann/json 与 jsonrpccxx 决定，无单独选项。

依赖版本表

依赖最低版本必需/可选
CMake3.10必需
C++ 编译器C++17必需
GCC7.0必需
Clang5.0必需
FTXUI最新必需
Chafa1.12+可选（-DBUILD_IMAGE_PREVIEW=ON）
Tree-sitter0.20+可选（-DBUILD_TREE_SITTER=ON）
Lua5.3 / 5.4可选（-DBUILD_LUA=ON）
libsixel最新可选（-DBUILD_IMAGE_PROTOCOL=ON，自动检测）
libvterm0.3+可选（-DBUILD_LIBVTERM=ON）
libssh21.9+可选（-DBUILD_SSH_MODE=CPP）
Go1.18+可选（-DBUILD_SSH_MODE=GO）
libcurl最新可选（-DBUILD_AI_CLIENT=ON）
iconv-可选（自动检测）
libatomic-可选（RISC-V 架构需显式链接）
nlohmann/json3.x内置（third-party）
jsonrpccxx最新内置（third-party）
github.com/pkg/sftpv1.13.10Go SSH 模块（传递依赖）
golang.org/x/cryptov0.47.0Go SSH 模块（传递依赖）

常见问题

Q: 如何确认各功能是否启用？

A: 配置阶段会输出状态，例如：

✓ Chafa found - image preview enabled
✓ Tree-sitter found - syntax highlighting enabled
✓ Lua found - plugin system enabled
LSP support enabled (using local third-party libraries)
✓ iconv found - enhanced encoding conversion enabled

Q: LSP 支持需要单独安装吗？

A: 不需要。项目内含 third-party/nlohmann/json.hpp 和 third-party/JSON-RPC-CXX。确保子模块已初始化：git submodule update --init --recursive。

Q: 编译时找不到 FTXUI？

A: 安装开发包后若仍失败，可指定查找路径：

cmake .. -DCMAKE_PREFIX_PATH=/usr/local

Q: Windows 支持如何？

A: 需要 VS 2017+、CMake 3.10+、FTXUI（vcpkg 或源码）。推荐在 WSL2 或 Linux/macOS 下构建。

Q: 如何完全重新配置？

A:

rm -rf build && mkdir build && cd build
cmake .. [选项]

文档与 CMakeLists.txt 一致，如有更新以代码为准。