从零搭建CJQT开发环境：从准备到验证的完整指南

准备阶段：环境适配清单

核心价值

仓颉语言绑定库（类似Python的PyQt），实现跨平台GUI开发

技术特性

• 基于QT5.14.2构建，覆盖QWidgets、QCore、QGui模块
• 提供仓颉语言风格API封装，降低Qt使用门槛
• 包含俄罗斯方块、记事本等多场景示例程序

系统与依赖要求

项目	规格要求	验证命令
操作系统	64位Windows/Linux	uname -m (Linux)
C++编译器	gcc-mingw64或兼容编译器	gcc --version
Qt版本	5.14.2	qmake --version
仓颉包管理器	最新版	cjpm --version

🔍 预检查命令：

# Linux用户：检查系统架构和编译器版本
uname -m && gcc --version

# Windows用户：检查系统架构
wmic os get osarchitecture

预期输出：x86_64（Linux）或64位（Windows），gcc版本需≥7.0

常见问题

1. Q：执行gcc命令提示"未找到命令"？
   A：Linux用户需安装build-essential包：sudo apt install build-essential；Windows用户需安装MinGW并配置环境变量

2. Q：qmake版本不符？
   A：确保安装Qt5.14.2时勾选"Qt 5.14.2 -> GCC 64-bit"组件

获取阶段：项目资源部署

克隆项目仓库

▶️ 执行克隆命令：

git clone https://gitcode.com/Cangjie-TPC/CJQT.git

预期输出：创建CJQT目录并下载项目文件

项目结构概览

核心目录说明：

• native/：C++原生代码与编译配置
• src/：仓颉语言封装源码（core/gui/widgets模块）
• example/：示例程序集合
• doc/：文档与资源文件

常见问题

1. Q：克隆速度慢？
   A：检查网络连接，或使用国内镜像加速

2. Q：项目文件缺失？
   A：执行git status检查是否完整克隆，必要时重新克隆

配置阶段：编译环境搭建

安装Qt5.14.2

▶️ Linux用户执行：

# 下载安装包
wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-opensource-linux-x64-5.14.2.run

# 赋予执行权限
chmod +x qt-opensource-linux-x64-5.14.2.run

# 启动安装程序
./qt-opensource-linux-x64-5.14.2.run

⚙️ 环境变量配置：

# 添加Qt工具链到PATH
export PATH=$PATH:/opt/Qt5.14.2/5.14.2/gcc_64/bin

编译Native库

▶️ 执行编译脚本：

cd CJQT/native
./make.sh

预期输出：在native/build目录生成libcjqt.so等库文件

⚙️ 配置文件调整： 若修改默认构建目录，需同步更新cjpm.toml：

[native]
nativeQt = "native/build"  # 改为实际构建路径

编译CJQT项目

▶️ 执行构建命令：

cd CJQT
cjpm build

预期输出：显示"Build succeeded"，生成可执行文件

常见问题

1. Q：编译提示"Qt5Core not found"？
   A：检查Qt环境变量配置，或重新运行qmake -query确认安装路径

2. Q：cjpm命令未找到？
   A：安装仓颉语言环境并配置PATH：export PATH=$PATH:~/.cangjie/bin

验证阶段：功能测试与示例运行

基础示例验证

▶️ 运行Hello示例：

cd example/hello
./run.sh

预期输出：显示"Hello CJQT"窗口

进阶示例体验

图：CJQT框架实现的QFrame组件演示，展示多色区块布局的GUI界面

场景化示例列表：

1. 界面组件：example/lineEdit（文本输入框）、example/scrollBar（滚动条）
2. 应用程序：example/notepad（记事本）、example/tetris（俄罗斯方块）

▶️ 运行俄罗斯方块示例：

cd example/tetris
./run.sh

框架架构确认

图：CJQT框架架构示意图，展示core核心模块与整体框架关系

常见问题

1. Q：运行示例提示"库文件缺失"？
   A：将native/build目录添加到系统库路径：export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../native/build

2. Q：窗口中文显示乱码？
   A：检查系统语言环境，确保UTF-8编码：export LANG=en_US.UTF-8

扩展阅读

• API文档：doc/api/index.html - 完整API参考手册
• 开发指南：doc/develop/develop.md - 进阶开发教程
• 模块说明：doc/qt_widgets.md - 组件使用说明