QOwnNotes 源码编译指南:从 Git 检出、qmake/Qt Creator 构建到 Nix/Devenv 自动化构建
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:
- 从 Qt 官网下载 Qt Creator 与 Qt 开发套件(Qt 6 场景下需确保安装
qtwebsockets模块)。 - 使用 Qt Creator 打开工程文件
src/QOwnNotes.pro。 - 点击 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:默认/usrBINDIR:默认$$PREFIX/binDATADIR:默认$$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 的完整编译流程。