aw/valentina
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Page: Windows Build Guide
Pages
Home Linux Build and Install Guide Macos Build Guide Transifex guide for Valentina GUI translators Transifex Guide Valentina GUI Windows Build Guide
3 Windows Build Guide
Roman Telezhynskyi edited this page 2024-03-30 14:46:34 +02:00
Table of Contents

[[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 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 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. 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. 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:

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.

    mkdir build
cd build

  2. Generate Makefile: Call qmake to generate the make file.

    qmake ../Valentina.pro -r "CONFIG += noTests noRunPath no_ccache noDebugSymbols"
    • The -r option allows qmake to look through supplied directories recursively.

  3. Build Valentina: To build Valentina, call nmake in case of MSVC and mingw32-make in case of MinGW.

    make

  4. Faster Builds with Multiple Cores: To make the build faster, specify the -j flag followed by the number of CPU cores to use.

    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:

CONFIG+=noDebugSymbols

or

CONFIG+=noDebugSymbols CONFIG+=checkWarnings

or together:

"CONFIG += noTests noRunPath no_ccache noDebugSymbols"

Running Tests

To run tests after a successful build, you can call tests using make.

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.

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:

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:

cd /path/to/valentina
conan install . -s os=Windows --build=missing -o with_xerces=True -pr valentina

This command installs the necessary dependencies for Valentina. The -o with_xerces=True option ensures that xerces-c is included in the dependencies and built if it's missing. The -pr valentina option specifies the Conan profile named "valentina" to use for the installation.

By default, the use of Conan is disabled. To enable it, pass project.enableConan:true to the Qbs configuration. To enable it, you'll need to pass project.enableConan:true to the Qbs configuration. To activate the correct Conan settings, you need to pass them to Qbs. To specify that xerces-c library should be built with Conan, you can set project.conanWithXerces:true in the Qbs configuration. Additionally, if you want to specify a specific Conan profile to use, you can pass project.conanProfiles:valentina 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.

# 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:

qbs-setup-toolchains.exe --type msvc $MSVC_PATH\cl.exe msvc
qbs-config.exe profiles.qt6.baseProfile msvc

For MinGW:

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:

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:

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:

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. 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.

Home
Linux Build and Install Guide
MacOS Build Guide
Windows Build Guide
Transifex Guide for Valentina GUI translators