Merge branch 'master' of github.com:royqh1979/RedPanda-CPP

royqh1979 · Aug 21, 2023 · 0c64aaf · 0c64aaf
2 parents 6690599 + 9e868d1
commit 0c64aaf
Show file tree

Hide file tree

Showing 9 changed files with 422 additions and 23 deletions.
diff --git a/BUILD.md b/BUILD.md
@@ -3,12 +3,200 @@
  Red Panda C++ need Qt 5 (>=5.12) to build.
 
 # Windows
- I build Red Panda Cpp with the latest gcc and mingw-w64, distributed by msys2 mingw-w64. Visual C++  and other version of gcc may not work.
 
- - Install msys2 (https://www.msys2.org)
- - Use msys2's pacman to install mingw-w64-x86_64-qt5 and mingw-w64-x86_64-gcc
- - Install qtcreator
- - Use qtcreator to open Red_Panda_CPP.pro
+| Library + Toolchain \ Target | x86 | x64 | ARM64 |
+| ---------------------------- | --- | --- | ----- |
+| MSYS2 + GNU-based MinGW | ✔️ | ✔️ | ❌ |
+| MSYS2 + LLVM-based MinGW | ✔️ | ✔️ | ✔️ |
+| Qt.io + MinGW | ✔️ | ✔️ | ❌ |
+| Qt.io + MSVC | ✔️ | ✔️ | ❌ |
+| vcpkg + MSVC | ✔️ | ✔️ | ❌ |
+
+Notes for Windows on ARM:
+- Red Panda C++ can be built for ARM64 ABI only on Windows 11 ARM64, while it is supposed (but not tested) to run on Windows 10 ARM64.
+- The ARM64EC (“emulation compatible”) ABI, which highlights interoperability with x64, is currently not supported.
+  - ARM64EC does not bring significant benefit, since Red Panda C++ can be built to ARM64 classic ABI.
+  - However, ARM64EC will allow users to use their favorite input methods, fancy Qt styles.
+- With the [ARM32 deprecation in Windows 11 Insider Preview Build 25905](https://blogs.windows.com/windows-insider/2023/07/12/announcing-windows-11-insider-preview-build-25905/), ARM32 support will never be added.
+
+## MSYS2 Qt Library with MinGW Toolchain (Recommended)
+
+Red Panda C++ should work with any MinGW toolchain from MSYS2, including GCCs and Clangs in three GNU-based environments (MINGW32, MINGW64 and UCRT64), and Clangs in three LLVM-based environments (CLANG32, CLANG64 and CLANGARM64; see also [MSYS2’s document](https://www.msys2.org/docs/environments/)), while the following toolchains are frequently tested:
+- MINGW32 GCC,
+- MINGW64 GCC,
+- UCRT64 GCC (recommended for x64)
+- CLANGARM64 Clang (the only and recommended toolchain for ARM64).
+
+Official distributions of Red Panda C++ are built with MINGW32 GCC and MINGW64 GCC.
+
+Prerequisites:
+
+0. Windows 8.1 x64 or later, or Windows 11 ARM64.
+1. Install MSYS2.
+2. In selected environment, install toolchain and Qt 5 library:
+   ```bash
+   pacman -S $MINGW_PACKAGE_PREFIX-toolchain $MINGW_PACKAGE_PREFIX-qt5-static
+   ```
+
+For build only:
+
+1. In selected environment, set related variables:
+   ```bash
+   SRC_DIR="/c/src/redpanda-src" # “C:\src\redpanda-src” for example
+   BUILD_DIR="/c/src/redpanda-build" # “C:\src\redpanda-build” for example
+   INSTALL_DIR="/c/src/redpanda-pkg" # “C:\src\redpanda-pkg” for example
+   ```
+2. Navigate to build directory:
+   ```bash
+   rm -rf "$BUILD_DIR" # optional for clean build
+   mkdir -p "$BUILD_DIR" && cd "$BUILD_DIR"
+   ```
+3. Configure, build and install:
+   ```bash
+   $MSYSTEM_PREFIX/qt5-static/bin/qmake PREFIX="$INSTALL_DIR" "$SRC_DIR/Red_Panda_CPP.pro"
+   mingw32-make -j$(nproc)
+   mingw32-make install
+   ```
+
+For development:
+
+1. Install Qt Creator (either MSYS2 edition from package `$MINGW_PACKAGE_PREFIX-qt-creator` or standalone edition from [Qt.io downloads site](https://download.qt.io/official_releases/qtcreator/)).
+2. Open `Red_Panda_CPP.pro` with Qt Creator.
+
+## Qt.io Qt Library with MinGW Toolchain or MSVC Toolchain
+
+Prerequisites:
+
+0. Windows 7 x64 or later. ARM64 is not supported.
+1. Install Qt with online installer from [Qt.io](https://www.qt.io/download-qt-installer-oss).
+   - Select the library (in _Qt_ group, _Qt 5.15.2_ subgroup, check at lease one of _MinGW 8.1.0 32-bit_, _MinGW 8.1.0 64-bit_, _MSVC 2019 32-bit_ or _MSVC 2019 64-bit_).
+   - For MinGW toolchain, select the toolchain (in _Qt_ group, _Developer and Designer Tools_ subgroup, check _MinGW 8.1.0 32-bit_ or _MinGW 8.1.0 64-bit_, matching the library).
+   - Optionally select Qt Creator (in _Qt_ group, _Developer and Designer Tools_ subgroup; recomended for MSVC toolchain for parallel build support).
+2. For MSVC toolchain, install Visual Studio 2019 or later, or Visual Studio Build Tools 2019 or later, with _Desktop Development with C++_ workload.
+   - In _Installation Details_ panel, under the _Desktop Development with C++_ workload, select at least one _MSVC x86/x64 build tools_ and one _Windows SDK_.
+
+For build only:
+
+1. Launch Qt environment from Start Menu.
+2. In Qt environment, set related variables:
+   ```bat
+   rem no quotes even if path contains spaces
+   set SRC_DIR=C:\src\redpanda-src
+   set BUILD_DIR=C:\src\redpanda-build
+   set INSTALL_DIR=C:\src\redpanda-pkg
+   rem for MSVC toolchain
+   set VS_INSTALL_PATH=C:\Program Files\Microsoft Visual Studio\2022\Community
+   rem for MSVC toolchain; or x86
+   set VC_ARCH=amd64
+   rem for MSVC toolchain; keep unset if Qt Creator is not installed
+   set QT_CREATOR_DIR=C:\Qt\Tools\QtCreator
+   ```
+3. Navigate to build directory:
+   ```bat
+   rem optional for clean build
+   rmdir /s /q "%BUILD_DIR%"
+   mkdir "%BUILD_DIR%" && cd /d "%BUILD_DIR%"
+   ```
+4. Configure, build and install. For MinGW toolchain:
+   ```bat
+   qmake PREFIX="%INSTALL_DIR%" "%SRC_DIR%\Red_Panda_CPP.pro"
+   mingw32-make -j%NUMBER_OF_PROCESSORS%
+   mingw32-make install
+   windeployqt "%INSTALL_DIR%\RedPandaIDE.exe"
+   ```
+   For MSVC toolchain:
+   ```bat
+   call "%VS_INSTALL_PATH%\Common7\Tools\VsDevCmd.bat" -arch=%VC_ARCH%
+   qmake PREFIX="%INSTALL_DIR%" "%SRC_DIR%\Red_Panda_CPP.pro"
+
+   set JOM=%QT_CREATOR_DIR%\bin\jom\jom.exe
+   if "%QT_CREATOR_DIR%" neq "" (
+      "%JOM%" -j%NUMBER_OF_PROCESSORS%
+      "%JOM%" install
+   ) else (
+      nmake
+      nmake install
+   )
+   windeployqt "%INSTALL_DIR%\RedPandaIDE.exe"
+   ```
+
+For development:
+
+1. Open `Red_Panda_CPP.pro` with Qt Creator.
+
+## Advanced Option: vcpkg Qt Static Library with MSVC Toolchain
+
+Prerequisites:
+
+0. Windows 7 x64 or later. ARM64 is not supported.
+   - For a fresh installation of Windows 7, install following components in order:
+     1. SHA-2 code signing support (prerequisite of .NET Framework 4.8),
+     2. .NET Framework 4.8 (prerequisite of Windows Management Framework 5.1 and Visual Studio; also optional dependency of Git for Windows),
+     3. Windows Management Framework 5.1 (prerequisite of vcpkg bootstrapping).
+1. Install Visual Studio 2017 or later, or Visual Studio Build Tools 2017 or later, with _Desktop Development with C++_ workload.
+   - In _Installation Details_ panel, under the _Desktop Development with C++_ workload, select at least one _MSVC x86/x64 build tools_ and one _Windows SDK_.
+2. Install [standalone vcpkg](https://vcpkg.io/en/getting-started).
+   - As of 2023.08.09, [a patch](./packages/windows/vcpkg-win7-2023.08.09.patch) is required for Windows 7 to use compatible version of Python. Affected files will change over time, so manually edit them to apply the patch.
+3. Install Qt with vcpkg.
+   ```ps1
+   $TARGET = "x64-windows-static" # or "x86-windows-static"
+   vcpkg install qt5-base:$TARGET qt5-svg:$TARGET qt5-tools:$TARGET
+   ```
+
+To build with VS 2019 or later in PowerShell (Core) or Windows PowerShell:
+
+1. Set related variables:
+   ```ps1
+   $SRC_DIR = "C:\src\redpanda-src"
+   $BUILD_DIR = "C:\src\redpanda-build"
+   $INSTALL_DIR = "C:\src\redpanda-pkg"
+   $VCPKG_ROOT = "C:\src\vcpkg"
+   $VCPKG_TARGET = "x64-windows-static" # or "x86-windows-static"
+   $VS_INSTALL_PATH = "C:\Program Files\Microsoft Visual Studio\2022\Community"
+   $VC_ARCH = "amd64" # or "x86"
+   $JOM = "$VCPKG_ROOT\downloads\tools\jom\jom-1.1.3\jom.exe" # check the version
+   ```
+2. Navigate to build directory:
+   ```ps1
+   Remove-Item -Recurse -Force "$BUILD_DIR" # optional for clean build
+   (New-Item -ItemType Directory -Force "$BUILD_DIR") -and (Set-Location "$BUILD_DIR")
+   ```
+3. Configure, build and install:
+   ```ps1
+   Import-Module "$VS_INSTALL_PATH\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
+   Enter-VsDevShell -VsInstallPath "$VS_INSTALL_PATH" -SkipAutomaticLocation -DevCmdArguments "-arch=$VC_ARCH"
+   & "$VCPKG_ROOT\installed\$VCPKG_TARGET\tools\qt5\bin\qmake.exe" PREFIX="$INSTALL_DIR" "$SRC_DIR\Red_Panda_CPP.pro"
+   & "$JOM" "-j${Env:NUMBER_OF_PROCESSORS}"
+   & "$JOM" install
+   ```
+
+To build with VS 2017 or later in Command Prompt:
+
+1. Launch proper VC environment from Start Menu.
+2. Set related variables:
+   ```bat
+   rem no quotes even if path contains spaces
+   set SRC_DIR=C:\src\redpanda-src
+   set BUILD_DIR=C:\src\redpanda-build
+   set INSTALL_DIR=C:\src\redpanda-pkg
+   set VCPKG_ROOT=C:\src\vcpkg
+   rem or x86-windows-static
+   set VCPKG_TARGET=x64-windows-static
+   rem check the version
+   set JOM=%VCPKG_ROOT%\downloads\tools\jom\jom-1.1.3\jom.exe
+   ```
+3. Navigate to build directory:
+   ```bat
+   rem optional for clean build
+   rmdir /s /q "%BUILD_DIR%"
+   mkdir "%BUILD_DIR%" && cd /d "%BUILD_DIR%"
+   ```
+4. Configure, build and install:
+   ```bat
+   "%VCPKG_ROOT%\installed\%VCPKG_TARGET%\tools\qt5\bin\qmake.exe" PREFIX="%INSTALL_DIR%" "%SRC_DIR%\Red_Panda_CPP.pro"
+   "%JOM%" -j%NUMBER_OF_PROCESSORS%
+   "%JOM%" install
+   ```
 
 # Linux