Windows Build Guide.
Roman Telezhynskyi
parent
8bb29174d9
commit
5ff7a4d32a
296
Windows-Build-Guide.md
Normal file
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)
|
||||
[Linux Build and Install Guide](Linux-Build-and-Install-Guide)
|
||||
[MacOS Build Guide](Macos-Build-Guide)
|
||||
[Windows Build](windows-build)
|
||||
[Windows Build Guide](Windows-Build-Guide)
|
||||
Loading…
Reference in New Issue
Block a user