From fc9f66d56d86b75aec5a105188d3159dce3a4f21 Mon Sep 17 00:00:00 2001 From: luochen570 <1160510664@qq.com> Date: Sat, 30 May 2026 17:24:05 +0800 Subject: [PATCH] docs: add Windows build instructions and script --- build-windows.ps1 | 100 +++++++++++++++++++++++++++++++ readme.md | 150 +++++++++++++++++++++++++++++++++++++--------- 2 files changed, 222 insertions(+), 28 deletions(-) create mode 100644 build-windows.ps1 diff --git a/build-windows.ps1 b/build-windows.ps1 new file mode 100644 index 0000000..c06961c --- /dev/null +++ b/build-windows.ps1 @@ -0,0 +1,100 @@ +param( + [Parameter(Mandatory = $true)] + [string]$QtPrefix, + + [string]$BuildDir = "build-windows", + [string]$DistDir = "dist-windows\chengnan", + [string]$Generator = "Visual Studio 17 2022", + [string]$Arch = "x64", + [ValidateSet("Debug", "Release", "RelWithDebInfo", "MinSizeRel")] + [string]$Config = "Release" +) + +$ErrorActionPreference = "Stop" + +function Resolve-FullPath([string]$PathValue) { + if ([System.IO.Path]::IsPathRooted($PathValue)) { + return [System.IO.Path]::GetFullPath($PathValue) + } + return [System.IO.Path]::GetFullPath((Join-Path (Get-Location) $PathValue)) +} + +function Require-Command([string]$Name) { + $command = Get-Command $Name -ErrorAction SilentlyContinue + if (-not $command) { + throw "找不到命令：$Name。请先安装并加入 PATH。" + } + return $command.Source +} + +$ProjectDir = Split-Path -Parent $MyInvocation.MyCommand.Path +Set-Location $ProjectDir + +$QtPrefix = Resolve-FullPath $QtPrefix +$BuildPath = Resolve-FullPath $BuildDir +$DistPath = Resolve-FullPath $DistDir +$QtBin = Join-Path $QtPrefix "bin" +$WinDeployQt = Join-Path $QtBin "windeployqt.exe" + +if (-not (Test-Path $QtPrefix)) { + throw "QtPrefix 不存在：$QtPrefix" +} + +if (-not (Test-Path $WinDeployQt)) { + throw "找不到 windeployqt：$WinDeployQt。请确认 -QtPrefix 指向 Qt 套件目录，例如 C:\Qt\6.7.2\msvc2019_64。" +} + +Require-Command "cmake" | Out-Null + +$env:PATH = "$QtBin;$env:PATH" +$env:CMAKE_PREFIX_PATH = $QtPrefix + +Write-Host "== chengnan Windows 构建 ==" -ForegroundColor Cyan +Write-Host "项目目录：$ProjectDir" +Write-Host "Qt 目录：$QtPrefix" +Write-Host "构建目录：$BuildPath" +Write-Host "发布目录：$DistPath" +Write-Host "生成器：$Generator" +Write-Host "配置：$Config" + +$configureArgs = @( + "-S", $ProjectDir, + "-B", $BuildPath, + "-G", $Generator, + "-DCMAKE_PREFIX_PATH=$QtPrefix" +) + +if ($Generator -like "Visual Studio*") { + $configureArgs += @("-A", $Arch) +} else { + $configureArgs += "-DCMAKE_BUILD_TYPE=$Config" +} + +Write-Host "`n== 配置 CMake ==" -ForegroundColor Cyan +& cmake @configureArgs + +Write-Host "`n== 编译 ==" -ForegroundColor Cyan +& cmake --build $BuildPath --config $Config --parallel + +$ExeCandidates = @( + (Join-Path $BuildPath "$Config\chengnan.exe"), + (Join-Path $BuildPath "chengnan.exe") +) +$ExePath = $ExeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1 +if (-not $ExePath) { + throw "构建完成但找不到 chengnan.exe。已检查：$($ExeCandidates -join ', ')" +} + +Write-Host "`n== 准备发布目录 ==" -ForegroundColor Cyan +if (Test-Path $DistPath) { + Remove-Item -Recurse -Force $DistPath +} +New-Item -ItemType Directory -Force -Path $DistPath | Out-Null +Copy-Item $ExePath $DistPath + +Write-Host "`n== 收集 Qt 运行库 ==" -ForegroundColor Cyan +$DistExe = Join-Path $DistPath "chengnan.exe" +& $WinDeployQt --release --no-translations $DistExe + +Write-Host "`n构建完成：$DistExe" -ForegroundColor Green +Write-Host "请整体复制目录：$DistPath" diff --git a/readme.md b/readme.md index 6cdb05c..394017c 100644 --- a/readme.md +++ b/readme.md @@ -1,16 +1,12 @@ -# chengnan Dev 分支 +# chengnan -这是 `chengnan` 的简化开发分支，只保留根目录下的最小 Qt Widgets 源码文件： +项目链接： -- `CMakeLists.txt` -- `main.cpp` -- `MainWindow.h` -- `MainWindow.cpp` -- `readme.md` +`chengnan` 是一个轻量级 Windows 图片查看器 / 简单图片处理工具，使用 **Qt Widgets + CMake + C++17** 开发。 ## 功能 -当前实现了一个轻量级图片查看器 / 简单图片处理工具： +当前实现： - 打开图片：PNG、JPG、JPEG、BMP、GIF、WebP 等 Qt 支持的格式 - 保存当前图片 @@ -22,34 +18,132 @@ - 翻转：水平翻转、垂直翻转 - 简单处理：灰度化、反色 -## 技术栈 +## 文件结构 -- C++17 -- Qt 5 或 Qt 6 Widgets -- CMake - -此分支不依赖 OpenCV，便于保持文件数量最少。 - -## 构建方式 - -本地已安装 Qt 和 CMake 后，可执行： - -```bash -cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -cmake --build build --config Release +```text +chengnan/ +├── CMakeLists.txt +├── MainWindow.cpp +├── MainWindow.h +├── build-windows.ps1 +├── main.cpp +└── readme.md ``` -如果 Qt 安装在非默认路径，可指定： +## Windows 编译需要的工具 -```bash -cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/lib/cmake -cmake --build build --config Release +推荐环境：Windows 10 / Windows 11 x64。 + +必须安装： + +1. **Git for Windows** + - 下载： + - 用于克隆项目源码。 + +2. **CMake 3.16 或更高版本** + - 下载： + - 安装时建议勾选 `Add CMake to the system PATH`。 + +3. **Qt 6 或 Qt 5，包含 Widgets 模块** + - 下载： + - 推荐安装 Qt 6.x 的 MSVC 64-bit 套件，例如 `msvc2019_64` 或 `msvc2022_64`。 + - 项目不依赖 OpenCV。 + +4. **Visual Studio 2022 Build Tools 或 Visual Studio 2022** + - 下载： + - 需要安装组件：`使用 C++ 的桌面开发`。 + - 提供 MSVC 编译器和 Windows SDK。 + +可选工具： + +- **Ninja**： +- 如果使用 Ninja，可以把 `build-windows.ps1` 的 `-Generator` 参数改成 `Ninja`。 + +## 获取源码 + +```powershell +git clone https://git.luochen570.cn/luochen570/chengnan.git +cd chengnan ``` -## 文件说明 +如果仓库主分支已切换到当前版本，直接构建即可；否则可手动切换： + +```powershell +git checkout main +``` + +## 一键构建（推荐） + +在 Windows PowerShell 中进入项目目录，然后执行： + +```powershell +powershell -ExecutionPolicy Bypass -File .\build-windows.ps1 -QtPrefix "C:\Qt\6.7.2\msvc2019_64" +``` + +请把 `-QtPrefix` 改成你本机实际 Qt 安装目录。例如： + +```powershell +powershell -ExecutionPolicy Bypass -File .\build-windows.ps1 -QtPrefix "C:\Qt\6.8.0\msvc2022_64" +``` + +脚本会完成： + +1. 检查 Qt、CMake、编译器环境 +2. 生成 CMake 构建目录 +3. 编译 Release 版本 +4. 调用 `windeployqt` 收集 Qt 运行库 +5. 把发布文件放到 `dist-windows\chengnan` + +构建成功后，运行： + +```powershell +.\dist-windows\chengnan\chengnan.exe +``` + +## 手动构建 + +如果不使用脚本，也可以手动执行： + +```powershell +cmake -S . -B build-windows -G "Visual Studio 17 2022" -A x64 -DCMAKE_PREFIX_PATH="C:\Qt\6.7.2\msvc2019_64" +cmake --build build-windows --config Release +``` + +打包 Qt 运行库： + +```powershell +C:\Qt\6.7.2\msvc2019_64\bin\windeployqt.exe --release --no-translations build-windows\Release\chengnan.exe +``` + +## 常见问题 + +### 找不到 Qt + +确认 `-QtPrefix` 指向 Qt 套件目录，而不是 Qt 根目录。例如应使用： + +```text +C:\Qt\6.7.2\msvc2019_64 +``` + +不要写成： + +```text +C:\Qt +``` + +### 找不到 MSVC 编译器 + +请安装 Visual Studio 2022 的 `使用 C++ 的桌面开发`，然后在 “x64 Native Tools Command Prompt for VS 2022” 或已配置 VS 环境的 PowerShell 里运行构建脚本。 + +### exe 复制到其它电脑无法运行 + +请运行 `build-windows.ps1`，并整体复制 `dist-windows\chengnan` 文件夹，不要只复制单个 `chengnan.exe`。 + +## 开发说明 - `main.cpp`：应用入口，创建并显示主窗口 - `MainWindow.h`：主窗口和图片标签类声明 - `MainWindow.cpp`：菜单、工具栏、图片显示和处理逻辑 - `CMakeLists.txt`：Qt Widgets CMake 构建配置 -- `readme.md`：当前说明文档 +- `build-windows.ps1`：Windows 一键构建与打包脚本 +- `readme.md`：项目说明文档