本仓库中的文档用于 Windows x64 上的 BesLyric-for-X 的开发环境配置。
本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。
返回主分支。
- 本文档可能不提供通过编译源码进行环境配置的方法；
- 本文档可能不提供有关已结束支持的操作系统 [1] 和软件 [2] [3] 的内容；
- BesLyric-for-X 仅支持 Qt 5.12.4 及更高版本。
按照本文档进行配置后，通过测试的操作系统与开发环境的版本组合：
| OS ReleaseID [4] Kernel [5] | Toolchain | Qt | SDL | FFmpeg | TLS Impl. |
|---|---|---|---|---|---|
| Windows 10 Pro 2004 10.0.19041.329 | VC++ 14.26.28801 SDK 10.0.18362.1 |
5.15.0 | 2.0.12 | 4.3.1 | OpenSSL 1.1.1g 21 Apr 2020 |
| Windows 10 Pro 2004 10.0.19041.329 | VC++ 14.16.27023 SDK 10.0.17763.0 |
5.12.9 | 2.0.12 | 4.3.1 | OpenSSL 1.1.1g 21 Apr 2020 |
| Windows 10 Pro 1909 10.0.18363.592 Windows 10 Pro 1903 10.0.18362.592 Windows 10 Enterprise LTSC 1809 10.0.17763.973 [6] |
VC++ 14.24.28314 SDK 10.0.18362.1 |
5.14.1 | 2.0.10 | 4.2.2 | OpenSSL 1.1.1d 10 Sep 2019 |
| Windows 10 Pro 2004 10.0.19041.685 | gcc 8.1.0 x86_64-posix-seh-rev0 | 5.15.0 | 2.0.12 | 4.3.1 | OpenSSL 1.1.1g 21 Apr 2020 |
为了正确配置 BesLyric-for-X 所需的第三方库，在 Windows 平台，需要设置环境变量B4X_DEP_PATH。
B4X_DEP_PATH的值应该仅包含操作系统允许在路径中使用的 ASCII 字符，同时，不应该包含空格，两端也不需要添加引号，例如C:\b4x-lib。
B4X_DEP_PATH指向的文件夹应该按照规定的结构包含所有需要的文件（头文件、静态链接库文件和动态链接库文件）。 BesLyric-for-X 中的 qmake 指令将分别向变量$$INCLUDEPATH和$$LIB添加%B4X_DEP_PATH%\include和-L%B4X_DEP_PATH%\lib，使 MinGW 或 MSVC 能够找到第三方库的头文件和静态链接库文件。
不建议将该环境变量配置到操作系统或当前用户中，而是应该配置到项目内。例如，通过 Qt Creator 的左侧列表切换到“ Projects ”页面，在“ Build & Run ”-“ Build Settings ”-“ Build Environment ”或“ Project Settings ”-“ Environment ”中配置环境变量 [7] 。
MinGW 将 gcc 等工具进行了移植以构建 Windows 程序。推荐使用 Qt 的在线安装程序配置该环境。
使用 Visual Studio Installer 安装“ Desktop development with C++ ”工作负载以安装 MSVC toolset 和 Windows SDK 。
MSVC toolset 包含 C/C++ 编译器（cl.exe）、资源编译器（rc.exe）、链接器（link.exe）、构建工具（nmake.exe）等程序。
Windows SDK 包含 Windows 开发所需要的文档、头文件（例如Windows.h和stdio.h）、库文件（例如ncrypt.lib和libucrt.lib）、调试器（例如 CDB ）等组件。
CDB 与 WinDbg 同为 Windows 上的调试器 [8] 。 Qt Creator 需要使用 CDB 调试程序。
不推荐使用 Qt 的在线安装程序安装 CDB ，也不推荐使用独立的 Windows SDK 安装程序安装 CDB [9] ，而是应该在安装 Windows SDK 之后使用 Windows SDK 的维护程序安装 CDB ：
- 在“设置”-“应用和功能”列表中找到“ Windows Software Development Kit - Windows 10... ”，选择它并单击“修改”，弹出“ Windows Software Development Kit - Windows 10... ”窗口；
- 在“ Maintain your Windows Software Development Kit - Windows 10... features ”页面选择“ Change ”，单击“ Next ”；
- 在“ Select the features you want to change ”页面勾选“ Debugging Tools for Windows ”，单击“ Change ”。
- 从 Index of /official_releases/online_installers 下载在线安装程序；
- 勾选预构建组件，例如“ Qt - Qt 5.15.2 - MinGW 8.1.0 64-bit ”；
- 勾选 MinGW 工具链，例如“ Qt - Developer and Designer Tools - MinGW 8.1.0 64-bit ”。如果之前已经配置了 MinGW 工具链，就不要勾选该组件以避免重复的安装。
- 从 Index of /official_releases/online_installers 下载在线安装程序；
- 勾选预构建组件，例如“ Qt - Qt 5.15.2 - MSVC 2019 64-bit ”。 MSVC 2019 与 2015 和 2017 二进制兼容 [10] ，所以“ MSVC 2015 ”和“ MSVC 2017 ”版本的预构建组件都可用于 MSVC 2019 的开发环境 [11] ；
- 勾选 CDB 的支持组件，例如“ Qt - Developer and Designer Tools - Qt Creator 4.14.0 CDB Debugger Support ”；
- 如果之前已经通过 Windows SDK 的维护程序安装了 CDB ，就取消勾选默认随 Qt 一起安装的 CDB ，例如“ Qt - Developer and Designer Tools - Debugging Tools for Windows ”，以避免不正确的覆盖安装。
- 如果 Qt Creator 在 General Messages 中输出
C and C++ compiler paths differ. C compiler may not work.，就需要检查各个 Kit （构建套件）中的 C 和 C++ 编译器的路径是否一致。
由于 MinGW 接受拓展名为.lib的库文件，将 Visual C++ 的第三方库文件用于 MinGW 不会有问题 [12] 。
- 下载用于 Windows 的、 devel 版本的、用于 Visual C++ 的 SDL 2 ；
- 将各个文件从压缩包中按照类型提取到指定位置：
- 提取
\SDL2-...\include\下的所有.h文件到%B4X_DEP_PATH%\include\SDL2\下； - 提取
\SDL2-...\lib\x64\下的SDL2.dll和SDL2.lib文件到%B4X_DEP_PATH%\lib\下。
- 提取
SDL 2 库文件的文件夹结构如下（点击收起）：
> tree /A /F %B4X_DEP_PATH%
.
+---include
| \---SDL2
| SDL.h
| ...
|
\---lib
SDL2.dll
SDL2.lib- 从 Releases · BtbN/FFmpeg-Builds 下载 ffmpeg-...-win64-gpl-shared-....zip ，或从 FFmpeg Windows Builds - gyan.dev § release 下载 ffmpeg-release-full-shared.7z （曾经是 FFmpeg Builds - Zeranoe ）；
- 将各个文件从压缩包中按照类型提取到指定位置：
- 提取
\ffmpeg-...-shared...\include\下的所有文件夹以及其中的文件到%B4X_DEP_PATH%\include\下； - 提取
\ffmpeg-...-shared...\bin\下的所有.dll文件到%B4X_DEP_PATH%\lib\下； - 提取
\ffmpeg-...-shared...\lib\下的所有.lib文件到%B4X_DEP_PATH%\lib\下。
- 提取
FFmpeg 4 库文件的文件夹结构如下（点击收起）：
> tree /A /F %B4X_DEP_PATH%
.
+---include
| +---libavcodec
| | avcodec.h
| | ...
| |
| +---libavdevice
| | avdevice.h
| | ...
| |
| +---libavfilter
| | avfilter.h
| | ...
| |
| +---libavformat
| | avformat.h
| | ...
| |
| +---libavutil
| | avutil.h
| | ...
| |
| +---libpostproc
| | postprocess.h
| | ...
| |
| +---libswresample
| | swresample.h
| | ...
| |
| \---libswscale
| swscale.h
| ...
|
\---lib
avcodec-58.dll
avcodec.lib
avdevice-58.dll
avdevice.lib
avfilter-7.dll
avfilter.lib
avformat-58.dll
avformat.lib
avutil-56.dll
avutil.lib
postproc-55.dll
postproc.lib
swresample-3.dll
swresample.lib
swscale-5.dll
swscale.libQt 5 使用的 TLS 实现默认为 OpenSSL ，无法使用 Windows 的 Schannel SSP [13] [14] [15] ，所以 BesLyric-for-X 需要 OpenSSL 的动态链接库文件。这些动态链接库文件在运行时被链接（ Run-time Dynamic Linking ），因此并不能通过 Dependency Walker 或 lucasg/Dependencies 等类似工具在 BesLyric-for-X 的导入表中找到相关的信息。
OpenSSL 的 1.0 与 1.1 版本并非二进制兼容 [16.a] ，且从 Qt 5.12.4 开始，包含 Qt 5.13.0 在内，所有 Qt 均使用 OpenSSL 1.1.1 [16.b] [17] ，所以 BesLyric-for-X 也使用 OpenSSL 1.1.1 。
由于某些国家和地区的法律对密码学技术的进出口限制 [18] [19] ， Qt 不能（自动，或通过windeployqt等途径）将 OpenSSL 一并交付 [20] ，开发者需要自行编译，或者从第三方获得 OpenSSL 库文件 [21] 。
Binaries - OpenSSLWiki 上有一个包含一些第三方网站链接的表格，这些网站提供了预编译的 OpenSSL 库文件。为了更容易地获取库文件，也为了避免库文件本身的依赖可能造成的问题（例如 BesLyric-for-X#27 ），经过对比，最终选择了用于 ICS 项目的 OpenSSL 库文件。
注意：使用这些未经过 OpenSSL 项目评估或测试的 OpenSSL 的衍生产品，后果自负。 [22]
- 下载用于 64 位 Windows 的 OpenSSL ；
- 对于动态库文件，从压缩包中提取
libcrypto-1_1-x64.dll和libssl-1_1-x64.dll文件到%B4X_DEP_PATH%\win64\lib\下。
完整的 OpenSSL 1.1 库文件的文件夹结构如下（点击收起）：
> tree /A /F %B4X_DEP_PATH%
.
\---lib
libcrypto-1_1-x64.dll
libssl-1_1-x64.dll- ^ Windows 10 - release information - Windows Release Information | Microsoft Docs
https://docs.microsoft.com/windows/release-information/ - ^ Visual Studio Product Lifecycle and Servicing | Microsoft Docs § Support for older versions of Visual Studio
https://docs.microsoft.com/visualstudio/releases/2019/servicing#support-for-older-versions-of-visual-studio - ^ Qt version history - Wikipedia § Qt 5
https://en.wikipedia.org/wiki/Qt_version_history#Qt_5 - ^ Windows: Get Windows Feature Version/Release ID
https://michlstechblog.info/blog/windows-get-windows-feature-version-release-id/ - ^ How to Find Your Windows 10 Build Number, Version, Edition and Bitness
https://www.winhelponline.com/blog/find-windows-10-build-version-edition-bit/ - ^
Invalid parameter passed to C runtime function.on Windows 10 1809
https://blog.csdn.net/u014132751/article/details/91876385
https://bugreports.qt.io/browse/QTBUG-70917
https://developercommunity.visualstudio.com/content/problem/363323/getadaptersaddresses-invalid-parameter-passed-to-c.html
https://blog.csdn.net/u014132751/article/details/91876385 - ^ Specifying Environment Settings | Qt Creator Manual
https://doc.qt.io/qtcreator/creator-project-settings-environment.html - ^ The debugger that comes with Debugging Tools for Windows goes by the name WinDbg, short for Windows Debugger, and generally pronounced win-debug or win-dee-bee-gee. It’s part of a suite of lightweight debuggers, along with
ntsd(short for NT Symbolic Debugger) andcdb(Console Debugger), which are all based on the same debugging engine, creatively namedDbgEng...
How do you pronounce WinDbg? | The Old New Thing
https://devblogs.microsoft.com/oldnewthing/20200128-00/?p=103371 - ^ ... One thing I would add is if you use the Visual Studio Installer, you get an option to install the latest Windows SDK. However, it seems the debugging tools are not installed by default with the SDK - I had to go to Control Panel -> Programs and Features and change the SDK installation to include the debugging tools.
c++ - Debugging in QtCreator using MSVC2017 compiler - Stack Overflow
https://stackoverflow.com/questions/47773289/debugging-in-qtcreator-using-msvc2017-compiler#comment94564781_47773290 - ^ C++ binary compatibility 2015-2019 | Microsoft Docs
https://docs.microsoft.com/cpp/porting/binary-compat-2015-2017 - ^ Qt Tools and Versions & MSVC 2019 | Qt Forum
https://forum.qt.io/topic/104123/qt-tools-and-versions-msvc-2019 - ^ MinGW supports libraries named according to the "<name>.lib" and "<name>.dll" conventions, in addition to the normal "lib<name>.a" convention common on *nix systems...
http://www.mingw.org/wiki/Specify_the_libraries_for_the_linker_to_use（失效）
https://stackoverflow.com/questions/7241047/linking-lib-files-with-mingw#answer-17209507 - ^ [QTBUG-62637] [Windows]: Add support for using Secure Channel for SSL sockets - Qt Bug Tracker
https://bugreports.qt.io/browse/QTBUG-62637 - ^ Windows: Secure Channel support for SSL socket (QTBUG-62637)
New Features in Qt 5.13 - Qt Wiki
https://wiki.qt.io/New_Features_in_Qt_5.13 - ^ [QTBUG-82876] [Windows]: Switch default builds to use Secure Channel for SSL sockets - Qt Bug Tracker
https://bugreports.qt.io/browse/QTBUG-82876 - ^ a ... Unfortunately OpenSSL 1.1 is binary incompatible with 1.0, so users need to switch to the new one and repackage their applications...
b ... As an important new item it provides binaries build with OpenSSL 1.1.1, including the new TLS 1.3 functionality.
Qt 5.12.4 Released with support for OpenSSL 1.1.1
https://www.qt.io/blog/2019/06/17/qt-5-12-4-released-support-openssl-1-1-1 - ^ [Releasing] Meeting minutes from Qt Release Team meeting 26.03.2019
https://lists.qt-project.org/pipermail/releasing/2019-March/002614.html - ^ Legal Restrictions on Cryptography - Web Security, Privacy & Commerce, 2nd Edition [Book]
https://www.oreilly.com/library/view/web-security-privacy/0596000456/ch04s04.html（失效） - ^ Import and export restrictions apply for some types of software, and for some parts of the world...
Qt 5.13.0 Known Issues - Qt Wiki § OpenSSL
https://wiki.qt.io/Qt_5.13.0_Known_Issues#OpenSSL - ^ ... It's not handled because by default, OpenSSL is dlopened and Qt doesn't ship OpenSSL because of international laws about cryptographic software...
How to properly include openssl for a windows deployment when using mingw? | Qt Forum
https://forum.qt.io/topic/86420/how-to-properly-include-openssl-for-a-windows-deployment-when-using-mingw/2
By default Qt is build to dlopen the OpenSSL dlls. This allows Qt to be build to support cryptographie while letting the developer handle all related paperwork for its application to be distributed (different countries have different rules regarding cryptographically enabled software).
Windows and OpenSSL Woes | Qt Forum
https://forum.qt.io/topic/91255/windows-and-openssl-woes/12 - ^ The application may require additional 3rd-party libraries (for example, database libraries), which are not taken into account by windeployqt...If Qt was configured to link against ICU or OpenSSL, the respective DLL's need to be added to the release folder, too.
Qt for Windows - Deployment | Qt 5.15
https://doc.qt.io/qt-5/windows-deployment.html#creating-the-application-package - ^ Use these OpenSSL derived products at your own risk; these products have not been evaluated or tested by the OpenSSL project.
Binaries - OpenSSLWiki
https://wiki.openssl.org/index.php/Binaries
- 本文档在 VSCode 上使用 Markdown All in One 辅助编辑。