QOwnNotes 源码编译指南:从 Git 检出、qmake/Qt Creator 构建到 Nix/Devenv 自动化构建

原创2026-10-12 11:51:261,049 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

QOwnNotes 源码编译指南:从 Git 检出、qmake/Qt Creator 构建到 Nix/Devenv 自动化构建

本篇指南围绕 QOwnNotes 的源码构建展开,系统讲解三种主流构建路径:使用 Qt Creator 进行图形化调试构建、在终端中通过 qmake/make 完成命令行构建,以及基于 Nix + Devenv 的可复现自动化构建。同时结合仓库内的 src/QOwnNotes.pro、src/CMakeLists.txt、justfile、default.nix 等工程文件,补充依赖说明、可选编译开关与常见构建细节,帮助读者在不同平台上稳定地编译出可运行的 QOwnNotes 二进制。

构建前的环境准备

QOwnNotes 是基于 Qt 的 C++ 桌面应用,源码工程同时提供 qmake 工程文件 src/QOwnNotes.pro 与 CMake 工程文件 src/CMakeLists.txt。开始构建前需要准备以下基础环境:

  • Qt 开发环境:项目同时支持 Qt 5 与 Qt 6 两条构建线。使用 Qt 6 构建时,除了基础模块外,还依赖 qtwebsockets 包(WebSocket 服务器与 Web App 客户端功能依赖,见 src/QOwnNotes.pro 中 QT += ... websockets 声明)。
  • 编译工具链:Windows 上官方推荐使用 MinGW 64-bit 工具链;Linux 上通常可以直接从发行版软件仓库安装 QtCreator 及相关 Qt 开发包;macOS 上则使用系统自带的 clang 与 Qt 官方安装包。
  • 构建工具:qmake(随 Qt 安装)、make(或 nmake/jom)、lrelease(Qt 语言工具,位于 qttools 包中,用于生成翻译二进制文件)。

从源码结构看,工程还内置了大量第三方库(Botan 加密库、qmarkdowntextedit、md4c、qtkeychain 等),绝大多数以子模块或内嵌源码形式随主仓库一并构建,无需手动单独安装;仅 Botan、libgit2、aspell、libsecret 等少量依赖可通过编译开关选择"使用系统库"或"使用内置库"。

从 Git 检出源码(release 分支)

QOwnNotes 将最新发布版代码维护在 release 分支上,检出的命令如下:

git clone https://github.com/pbek/QOwnNotes.git -b release
cd QOwnNotes
git submodule update --init

第三步 git submodule update --init 必不可少:仓库通过 git 子模块引入多个第三方组件。查看 .gitmodules 可以看到这些子模块的完整清单,包括:

  • src/libraries/qmarkdowntextedit(Markdown 编辑器核心组件)
  • src/libraries/piwiktracker(指标统计追踪)
  • src/libraries/qkeysequencewidget(快捷键捕获控件)
  • src/libraries/qttoolbareditor(工具栏编辑器)
  • src/libraries/qtcsv(CSV 读写)
  • src/libraries/md4c(Markdown 解析器)
  • src/libraries/qhotkey(全局快捷键)
  • src/libraries/qtkeychain(系统密钥环集成)

若跳过子模块初始化,构建时会出现头文件缺失或链接失败的报错。

使用 Qt Creator 构建(调试首选)

对于需要调试源码的场景,官方推荐使用 Qt Creator:

  1. 从 Qt 官网下载 Qt Creator 与 Qt 开发套件(Qt 6 场景下需确保安装 qtwebsockets 模块)。
  2. 使用 Qt Creator 打开工程文件 src/QOwnNotes.pro。
  3. 点击 Build → Build Project QOwnNotes(或直接按快捷键构建)即可完成编译。

一些实用提示:

  • Windows 下请务必选择 MinGW 64-bit 套件,而不是 MSVC 或 32 位 MinGW。QOwnNotes.pro 中为 win32-msvc 保留了 C++11 标志分支,但官方构建流程以 MinGW 为主流。
  • Linux 下大多数发行版软件仓库都提供 QtCreator 包,可直接安装使用。
  • 若使用 Qt 6 构建,src/QOwnNotes.pro 会自动追加 QT += quick 模块(为脚本功能提供 QML 支持),并且默认启用 USE_QLITEHTML(QLiteHtml 预览内核要求 Qt 6+,Qt 5 下会被自动禁用)。

终端命令行构建(qmake + make)

熟悉 Qt 构建流程的开发者可以完全脱离 IDE,在终端中完成构建:

cd src

# 如果需要英文以外的语言界面,先编译生成二进制翻译文件
lrelease QOwnNotes.pro

# 生成 Makefile 并开始构建
qmake
make

执行 qmake 后,会在当前目录生成 Makefile;make 默认会并行度较低地编译整个工程,产物为 QOwnNotes 可执行文件(Windows 下为 QOwnNotes.exe)。

语言翻译文件

src/QOwnNotes.pro 中通过 TRANSLATIONS 变量声明了 70 余种语言的 .ts 源翻译文件(包括 QOwnNotes_zh_CN.ts、QOwnNotes_zh_TW.ts 等)。lrelease 会把 .ts 编译为运行期加载的 .qm 二进制翻译文件;跳过这一步只会得到英文界面。仓库 justfile 中同样提供 translations-build 配方(执行 lrelease src/QOwnNotes.pro)完成相同操作。

常用 qmake 配置开关

结合 src/QOwnNotes.pro 源码,构建时可以追加如下 CONFIG+= 参数:

开关 作用 说明
DEV_MODE 开发者模式 启用预编译头 pch.h,并在 Linux 上开启 -Werror -pedantic 等严格告警(见 src/QOwnNotes.pro 与 src/QOwnNotes.pro)
USE_SYSTEM_BOTAN 使用系统 Botan 加密库 默认使用仓库内置的 src/libraries/botan 源码;置 1 时改用系统安装的 Botan 3
USE_QLITEHTML 启用 QLiteHtml 预览内核 仅 Qt 6 有效,通过 include(libraries/qlitehtml/src/qlitehtml.pri) 引入
with_aspell 启用 aspell 拼写检查 工程默认开启(见 src/QOwnNotes.pro)

例如,仓库维护者在 justfile 的 src-build 配方中使用的完整构建命令是:

mkdir -p build-QOwnNotes; cd build-QOwnNotes && qmake "CONFIG+=debug USE_SYSTEM_BOTAN=1" ../src/QOwnNotes.pro CONFIG+=DEV_MODE && make -j$(nproc)

这里推荐在独立构建目录中运行 qmake(而不是直接进入 src/),避免把 Makefile 和中间产物污染到源码目录。构建完成后,可使用 just src-run 运行产物(macOS 下为 build-QOwnNotes/QOwnNotes.app/Contents/MacOS/QOwnNotes,其余平台为 build-QOwnNotes/QOwnNotes)。

安装规则(Unix 平台)

unix 分支下,src/QOwnNotes.pro 定义了安装目标与默认路径:

  • PREFIX:默认 /usr
  • BINDIR:默认 $$PREFIX/bin
  • DATADIR:默认 $$PREFIX/share

make install 会安装可执行文件、PBE.QOwnNotes.desktop 桌面入口、languages/*.qm 翻译文件(Qt 6 安装到 share/qt6/translations)以及 images/icons/* 图标。构建发行版打包时可通过 qmake PREFIX=/usr/local 自定义前缀。

使用 CMake 构建(替代路径)

除 qmake 外,工程还提供完整的 CMake 支持(src/CMakeLists.txt),主要服务于 Nix 打包与自动化构建。其核心编译选项如下:

CMake 选项 默认值 作用
QON_QT6_BUILD OFF 使用 Qt 6 构建;OFF 时使用 Qt 5
DEV_MODE OFF 开发者模式(Clang 下启用 -Wall -Wextra -pedantic,Linux 上启用 -Werror)
LANGUAGETOOL_ENABLED ON 启用 LanguageTool 语法检查支持
HARPER_ENABLED ON 启用 Harper 语法检查器支持
BUILD_WITH_LIBGIT2 OFF 使用系统 libgit2 库(用于 Git 集成)
BUILD_WITH_ASPELL OFF 使用系统 aspell 库(拼写检查)
USE_QLITEHTML ON 使用 QLiteHtml 预览内核(仅 Qt 6)

注意:CMake 构建下 QT_VERSION_MAJOR 由 QON_QT6_BUILD 决定,随后通过 find_package(Qt...) 定位所需模块(Core、Widgets、Gui、Sql、Svg、Network、Xml、PrintSupport、WebSockets、Qml、Concurrent 及 LinguistTools,见 src/CMakeLists.txt)。若本机装有 ccache,CMake 配置会自动将其作为编译与链接缓存启用。

获取源码归档(Source Archive)

如果不想 clone 完整仓库,也可以直接下载发布页提供的源码压缩包。源码归档位于 GitHub Releases 页面,命名遵循 qownnotes-<版本号>.tar.xz 模式,例如:

https://github.com/pbek/QOwnNotes/releases/download/v23.7.0/qownnotes-23.7.0.tar.xz

即把 v23.7.0 替换为任意发布版本号即可拼出对应归档地址。与 Git 检出不同,源码归档通常已包含第三方库源码,解压后可直接进入 src 目录执行 qmake && make,无需再初始化子模块。当前仓库的版本号定义在 src/version.h(#define VERSION "26.10.3"),Nix 打包时也会自动读取该文件以确定软件版本(见 default.nix)。

使用 Nix 与 Devenv 构建

仓库为 Nix 用户提供了完整的可复现构建环境。前提是安装 Nix 包管理器 与 Devenv,随后克隆仓库并执行:

# 打开一个包含全部所需工具的开发 Shell
devenv shell

# 构建应用程序
just nix-build

# 运行构建产物
just nix-run

Devenv 开发环境

devenv.nix 定义了开发 Shell 的内容:

  • 语言支持:启用 languages.cplusplus
  • 工具包:just、cmake、qmake(取自 KDE Qt 包)、qttools、botan3、libsecret、pkg-config、clang-format 相关依赖、crowdin-cli 等
  • 进入 Shell 时自动执行 update-qmake-symlinks 脚本,在 ${DEVENV_ROOT}/bin 下创建 qmake6、qmake5 符号链接,供 Qt Creator 与 CLion 直接使用
  • 通过 cachix.pull 启用 devenv 与 qownnotes-devenv 缓存,大幅加速首次构建

Nix 构建配方

justfile 中与 Nix 相关的核心配方:

配方 命令 说明
nix-build nix build '.?submodules=1#qownnotes-qt6' Qt 6 构建(默认)
nix-build-qt5 nix build '.?submodules=1#qownnotes-qt5' Qt 5 构建
nix-build-qt5153 nix build '.?submodules=1#qownnotes-qt5153' 锁定 Qt 5.15.3 构建
nix-build-qt69 nix build '.?submodules=1#qownnotes-qt69' 锁定 Qt 6.9 构建
nix-build-qlitehtml nix build '.?submodules=1#qownnotes-qt6-qlitehtml' 启用 QLiteHtml 的 Qt 6 构建
nix-build-force nix build ... --rebuild 强制重新构建
nix-run ./result/bin/QOwnNotes --session test 运行 Nix 构建产物(使用独立测试会话)
nix-build-system nix build ... --override-input nixpkgs nixpkgs 改用系统 nixpkgs,使 Qt 版本与桌面环境匹配(便于加载 KDE Plasma 平台主题插件)

nix run 与 nix build 的产物会软链接到 ./result,因此 nix-run 直接执行 ./result/bin/QOwnNotes --session test——--session test 使用独立会话,避免污染日常使用数据。

Flake 与打包定义

flake.nix 声明了四种支持的系统架构(x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin)及多个包输出:qownnotes-qt6、qownnotes-qt6-qlitehtml、qownnotes-qt69、qownnotes-qt5、qownnotes-cmake-qt5、qownnotes-qt5153,其中 default 指向 Qt 6 版本。底层打包由 default.nix 完成:

  • 版本号从 src/version.h 自动解析
  • CMake 构建,携带 -DQON_QT6_BUILD=ON、-DBUILD_WITH_SYSTEM_BOTAN=ON、-DBUILD_WITH_LIBGIT2=ON、-DBUILD_WITH_ASPELL=ON 等编译参数
  • 依赖 qtbase、qtdeclarative、qtsvg、qtwebsockets、botan3、libgit2、aspell,Linux 下额外加入 libsecret 与 qtwayland
  • 安装阶段自动生成 bash/fish 的 shell 补全(通过 --completion bash / --completion fish),并创建 qownnotes 小写符号链接

如果你希望自行验证构建结果,仓库还提供了 just src-test 配方,通过 CMake 编译并运行 tests 目录下的单元测试(cmake -S tests -B build-tests-QOwnNotes && cmake --build ... && bin/tests -platform minimal),以及 just vm-test 运行基于 NixOS 的虚拟机集成测试(定义见 tests/vm/qownnotes.nix)。

参与源码贡献

构建成功只是第一步。若你想把修复或新功能回馈给项目,请遵守以下约定(详见 webpage/src/contributing/code-contributions.md):

  • PR 目标分支为 main:官方文档明确要求拉取请求提交到 main 分支,而不是 release 分支。
  • 先开 issue 再提 PR:除明显的笔误、小型文档修复等琐碎改动外,请先创建 issue 讨论问题、方案与影响范围,并在 PR 中引用对应 issue 编号。
  • 从独立分支发起 PR:不要从自己的 main 分支直接发 PR,以免 fork 同步困难或混入无关改动。
  • 遵循提交信息风格:仓库采用 #编号 模块: 描述 的格式,例如 #3568 mainwindow: allow dragging text file to import as note;作用域(scope)与命令式描述之间用冒号分隔,每个提交保持单一逻辑变更。
  • 翻译不要直接改 .ts 文件:翻译文件由 Crowdin 自动生成,翻译贡献应走翻译流程,而非直接编辑源码中的翻译文件。

构建常见问题速查

现象 排查方向
编译报错找不到头文件 检查是否执行过 git submodule update --init
Qt 6 构建时提示缺少模块 确认安装了 qtwebsockets(必要时还有 qtdeclarative、qtsvg)
运行后界面不是中文 先执行 lrelease QOwnNotes.pro 生成 .qm 翻译文件
调试信息不足 使用 CONFIG+=debug 或 CONFIG+=DEV_MODE 重新 qmake 后再 make
想快速复现构建环境 使用 devenv shell + just nix-build,或直接 nix run 相关 flake 输出

以上构建路径覆盖了从日常开发调试(Qt Creator)到命令行快速构建(qmake/make),再到生产级可复现打包(Nix/Devenv)的完整场景。读者可根据自身平台与需求选择最合适的一条,逐步验证 QOwnNotes 的完整编译流程。

登录后查看全文
QOwnNotes