Windows Build Guide.

Roman Telezhynskyi 2024-02-21 19:18:28 +02:00
parent 8bb29174d9
commit 5ff7a4d32a
2 changed files with 297 additions and 1 deletions

296
Windows-Build-Guide.md Normal file

@ -0,0 +1,296 @@
[[_TOC_]]
## Introduction
This documentation guides you through the process of building the Valentina project from its source code on a Windows system. Before you begin, ensure that your system meets the prerequisites.
## Prerequisites
- **Windows Version:**
- Windows 7 or higher for Qt 5.15 or higher.
- Windows 10 or higher for Qt 6 or higher.
- Windows 10 (1809 or later) or higher for Qt 6.2 or higher.
- Windows 10 (21H2 or later) or higher for Qt 6.3 or higher.
- Windows 10 (1809 or later) or higher for Qt 6.5 or higher.
- Compiler with C++17 support or higher
- CMake (needed for third-party dependencies)
- InnoSetup (if you want to build an installer)
- Git
- Qt (version 5.15 or higher)
- For Qt 5: qmake or Qbs build system
- For Qt 6: Qbs build system
## Check CI Configuration for Hints
Inspect the project's AppVeyor configuration (`appveyor.yml`) for hints on setting up the build environment. This can provide valuable insights into recommended configurations and build steps.
## Install Chocolatey (Optional)
This is an optional step. You may choose to install build dependencies manually.
[Chocolatey](https://chocolatey.org/) or Choco as it is sometimes referred to, is a free, open-source package manager for Windows that is very similar to Apt or DNF in the Linux realm. In other words, this is a program used for installing software via the Windows command line. It downloads a program, installs it, then it will check for updates, and installs those updates automatically if needed. Those who use Linux are quite familiar with the package management systems like this.
Use Chocolatey to simplify installing build dependencies.
Please visit the [official documentation](https://chocolatey.org/install) for detailed instructions on how to install Chocolatey.
## Build Dependencies
Before building the Valentina project, you need to install the necessary dependencies on your system.
### Qt Version
We recommend always building Valentina with the latest Qt version (Qt 6). Select Qt 5 for legacy support or qmake.
To install Qt, visit The Qt Project Website. There, you can download Qt using the [Online installer](https://www.qt.io/download-qt-installer-oss). Together with Qt, you will get Qbs and Qt Creator.
### Installing Qbs
If you do not use the latest version of the Qt library, we recommend updating your Qbs version to the latest version. There are several ways to do it:
1. **Install with Chocolatey**: Run the following command in CMD: `choco install qbs`. Make sure that the path to the Chocolatey version is higher in the PATH variable.
2. **Download prebuilt version from The Qt Project Website**: Visit [https://download.qt.io/official_releases/qbs](https://download.qt.io/official_releases/qbs). Pick the latest version and download `qbs-windows-x86_64-x.x.x.zip`. Unzip it and add the path to this version of Qbs to the PATH variable.
3. **Use the latest version of Qt Creator**: The laterst version of Qt Creator always shipped with the latest version of Qbs.
### Installing MinGW
Certain MinGW versions contain errors which prevent a successful build. To fix it, you will need to install a newer version of MinGW. Run the following command:
```bash
choco install mingw
```
## Build with Qmake
Starting from Qt 6, The Qt Company has deprecated QMake in favor of CMake. However, QMake remains supported as a legacy build system, primarily for building Valentina with Qt 5. Please note that while it is possible to add support for Qt 6 in QMake, there are no such plans currently. QMake lacks many modern features compared to Qbs, and we have decided migrating to the Qbs build system for Qt 6 version.
### Using Qmake to Build Valentina
1. **Create Build Directory:**
Navigate to the root folder of Valentina and create a build directory.
```bash
mkdir build
cd build
```
2. **Generate Makefile:**
Call qmake to generate the make file.
```bash
qmake ../Valentina.pro -r "CONFIG += noTests noRunPath no_ccache noDebugSymbols"
```
- The `-r` option allows qmake to look through supplied directories recursively.
3. **Optional: Change Install Prefixes:**
If you want to change the default install prefixes, you can do so with `PREFIX` and `PREFIX_LIB`.
```bash
qmake PREFIX=/usr PREFIX_LIB=/usr/lib64 ../Valentina.pro -r
```
4. **Optional: Specify Platform and Compiler Type:**
You may need to specify the platform and compiler type explicitly. For example, `linux-g++` or `linux-clang`.
```bash
qmake ../Valentina.pro -r -spec linux-g++
```
5. **Build Valentina:**
To build Valentina, call `nmake` in case of MSVC and `mingw32-make` in case of MinGW.
```bash
make
```
6. **Faster Builds with Multiple Cores:**
To make the build faster, specify the `-j` flag followed by the number of CPU cores to use.
```bash
mingw32-make -j24
```
### Config Options
Qmake supports several config options to provide more control over the build process. You can pass these options to qmake using `CONFIG+=<name of the option>`.
- `debug`: Build in debug mode.
- `release`: Build in release mode. Enabled by default.
- `no_pch`: Disable precompiled headers (PCH).
- `noDebugSymbols`: Do not generate debug symbols in release mode.
- `noAddressSanitizer`: Disable address sanitizer in debug mode.
- `gccUbsan`: Enable Undefined Behavior Sanitizer in debug mode.
- `checkWarnings`: Treat all warnings as errors.
You can pass several options independently or together. For example:
```bash
CONFIG+=noDebugSymbols
```
or
```bash
CONFIG+=noDebugSymbols CONFIG+=checkWarnings
```
or together:
```bash
"CONFIG += noTests noRunPath no_ccache noDebugSymbols"
### Running Tests
To run tests after a successful build, you can call tests using `make`.
```bash
mingw32-make -s check TESTARGS="-silent"
```
The `--silent` option suppresses unnecessary output, making it easier to view the test results. You can remove it if you prefer to see detailed output during the test run.
This way you can ensure that tests are executed after a successful build, helping to verify the functionality and stability of Valentina.
## Build with Qbs
Qbs is a build automation tool designed to conveniently manage the build process of software projects across multiple platforms. Although The Qt Project has deprecated Qbs in favor of CMake, the project continues to be actively developed by the community.
### Using Conan Package Manager
Since Qt 6, Valentina requires third-party dependencies, such as the xerces-c library. To build dependencies, you must use the Conan package manager. Conan allows you to build source code locally and use cached versions for subsequent builds of Valentina.
#### Installation
To start using Conan, you need to install it using pip. If your system doesn't have Python 3 installed, you must install it first.
```bash
pip3 install 'conan<2.0'
```
**Note:** Currently, Valentina does not support Conan 2.x.
#### Setup Conan Profile
After installing Conan, set up a Conan profile for Valentina:
```bash
conan profile new valentina --detect
```
#### Building Dependencies
Next, navigate to the root directory of your Valentina project and install the project's dependencies using Conan:
```bash
cd /path/to/valentina
conan install . -s os=Windows --build=missing -pr valentina
```
By default, the use of Conan is disabled. To enable it, pass `project.enableConan:true` to the Qbs configuration.
### Configuring Qbs for Valentina
Before building Valentina with Qbs, you need to configure it to use the correct Qt version and compiler.
```bash
# Detect Qt version in PATH
qbs setup-toolchains --detect
# Create a new profile for your build
qbs setup-qt %QTDIR%/bin/qmake qt6
# Set the default profile
qbs config defaultProfile qt6
```
Replace `%QTDIR%` with path to your Qt library.
In case you have several compilers installed on your system, you may need to additionally specify the path to them.
#### For MSVC:
```bash
qbs-setup-toolchains.exe --type msvc $MSVC_PATH\cl.exe msvc
qbs-config.exe profiles.qt6.baseProfile msvc
```
#### For MinGW:
```bash
qbs-setup-toolchains.exe --type mingw $MINGW_PATH\g++.exe mingw
qbs-config.exe profiles.qt6.baseProfile mingw
```
### Building Valentina with Qbs
Now, you can build Valentina using Qbs. Run the following command inside the project root folder:
```bash
qbs build -f valentina.qbs -d ..\build --jobs 24 profile:qt6 config:release qbs.installRoot:..\build\install-root\valentina project.enableConan:true project.conanProfiles:valentina modules.buildconfig.enableCcache:false modules.buildconfig.enablePCH:true modules.buildconfig.enableUnitTests:false modules.windeployqt.compilerRuntime:true modules.windeployqt.noCompilerRuntime:false
```
This command assumes that `qbs` is called inside the project root folder. Adjust paths and options as needed based on your project's specific configuration and requirements.
### Running Tests
To run tests, you simply need to call the following command:
```bash
qbs -p autotest-runner -d ..\build profile:qt6 config:release
```
This command calls the specific product `autotest-runner` to execute the tests. Adjust paths and options as needed based on your project's specific configuration and requirements.
### Qbs Configuration Options
Similarly to qmake, Qbs supports a wide range of configuration options. Here are a few of the most important ones:
- **modules.buildconfig.enableUnitTests**: Enables building unit tests. Use the format `modules.buildconfig.enableUnitTests:<value>`, where `<value>` can be `true` or `false`.
- **modules.buildconfig.enableRPath**: Enables the use of rpath. Use the format `modules.buildconfig.enableRPath:<value>`, where `<value>` can be `true` or `false`. This can be useful when packaging Valentina for distributions which do not permit the use of rpath, such as Fedora.
- **modules.buildconfig.enablePCH**: Enables the use of precompiled headers. Use the format `modules.buildconfig.enablePCH:<value>`, where `<value>` can be `true` or `false`. This can be useful when packaging Valentina for distributions which provide limited space on build servers.
- **modules.buildconfig.enableCcache**: Enables the use of ccache, a caching compiler wrapper. Use the format `modules.buildconfig.enableCcache:<value>`, where `<value>` can be `true` or `false`.
- **modules.buildconfig.treatWarningsAsErrors**: Enables treating all warnings as errors. Use the format `modules.buildconfig.treatWarningsAsErrors:<value>`, where `<value>` can be `true` or `false`.
- **project.enableConan**: Enables building dependencies with Conan, a C/C++ package manager. Use the format `project.enableConan:<value>`, where `<value>` can be `true` or `false`.
- **project.conanProfiles**: A list of Conan profiles to use. Use the format `project.conanProfiles:<value>`, where `<value>` is a list of Conan profiles separated by commas.
These configuration options provide flexibility in customizing the build process according to your specific requirements and preferences.
### Create Installer
As an optional step, you may decide to create an installer. Qbs can help you with this. To automatically create the installer, you need to install Inno Setup 6 on your system.
Similarly to building, you can create the installer using the following command:
```bash
qbs build -f valentina.qbs -d ..\build -p ValentinaSetup --jobs 24 profile:qt6 config:release qbs.installRoot:..\build\install-root\valentina project.enableConan:true project.conanProfiles:valentina modules.buildconfig.enableCcache:false modules.buildconfig.enablePCH:true modules.buildconfig.enableUnitTests:false modules.windeployqt.compilerRuntime:true modules.windeployqt.noCompilerRuntime:false
```
## Build with Qt Creator
The easiest way to build Valentina is to use Qt Creator. It provides automation features and allows for easy execution of the application. Additionally, Qt Creator facilitates debugging, which can be helpful in diagnosing crashes.
We recommend installing the latest version of Qt Creator from the [Qt Project website](https://www.qt.io/offline-installers). This ensures that you have access to the latest features and the most up-to-date version of Qbs.
Qt Creator simplifies tasks such as switching between debug and release modes, managing Qt versions, and more.
### Using Qt Creator with QMake
If you're using qmake as the build system, you need to open the `Valentina.pro` file located in the root folder of the project with Qt Creator.
### Using Qt Creator with Qbs
If you're using Qbs as the build system, open the `valentina.qbs` file with Qt Creator. You may need to add configuration options mentioned earlier in this documentation to achieve the expected results.
Qt Creator provides a user-friendly interface for configuring build options and managing project settings. It streamlines the development process and makes it easier to navigate and work with the project files.
By leveraging Qt Creator, you can enhance your development workflow and efficiently build and manage the Valentina project.

@ -1,4 +1,4 @@
[Home](home) [Home](home)
[Linux Build and Install Guide](Linux-Build-and-Install-Guide) [Linux Build and Install Guide](Linux-Build-and-Install-Guide)
[MacOS Build Guide](Macos-Build-Guide) [MacOS Build Guide](Macos-Build-Guide)
[Windows Build](windows-build) [Windows Build Guide](Windows-Build-Guide)