valentina

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[[TOC]]

Introduction

This documentation guides you through the process of building the Valentina project from its source code on a MacOS system. Before you begin, ensure that your system meets the prerequisites.

Prerequisites

MacOS Version:
- MacOS 10.13 (Xcode 11 or higher) or higher for Qt 5.15 or higher.
- MacOS 10.15 (Xcode 13 or higher) or higher for Qt 6.4 or higher.
- MacOS 11 (Xcode 13 or higher) or higher for Qt 6.5 or higher.
Compiler with C++17 support or higher
CMake: Needed for third-party dependencies
Git
Homebrew
Qt:
- For Qt 5: qmake or Qbs build system
- For Qt 6: Qbs build system

Check CI Configuration for Hints

Inspect the project's Cirrus CI configuration (.cirrus.yml) and AppVeyor configuration (appveyor.yml) for hints on setting up the build environment. This can provide valuable insights into recommended configurations and build steps.

Install Homebrew

To check if you already have Homebrew installed, run this command in your Terminal:

brew config

If it says brew: command not found, then you don’t have Homebrew, and you can install it with this command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This command will download and execute the Homebrew installation script.

Additional Steps

Xcode Command Line Tools: Homebrew will automatically download and install the Xcode Command Line Tools as part of the installation process. However, if you encounter any issues with this, you can manually install them using the command:
```
xcode-select --install
```
This command will prompt you to install the Command Line Tools if they are not already installed.
Permissions: During the installation process, Homebrew may prompt you to enter your password. This is required to grant permission for Homebrew to make changes to your system directories.
Post-Installation Verification: After the installation is complete, you can verify that Homebrew was installed correctly by running:
```
brew doctor
```
This command checks for common issues and provides guidance on how to resolve them.

Installing Xcode

Before proceeding to build, you must install Xcode on your system. We recommend always installing the latest available version of Xcode. Keep in mind that you need to select an Xcode version compatible with your Qt version.

Before installing Xcode, ensure you have a good, stable internet connection as the latest version is around 3 gigabytes in size. Additionally, make sure you have at least 20 gigabytes of free space on your computer.

There are two methods to download Xcode:

Method 1: Apple Developer Website (Recommended)

Navigate to the "more" section of the Apple Developer website.
Sign in with your Apple ID account.
Search for the desired Xcode version and download the Xcode_x_x_x.xip file. Note that Xcode 15.2 is approximately 3 gigabytes, so the download time will depend on your internet connection speed.
Once the download completes, double-click on the .xip file to extract it. The extraction process is automatic and will take a few minutes.
(Optional) If you're using multiple versions of Xcode, consider renaming the application to something like “Xcode_15.x.x”.
Drag the extracted Xcode application to the Applications folder.
(Optional) Set the new Xcode version as the default by opening Terminal and typing:
```
sudo xcode-select -switch /Applications/Xcode_x.x.x.app
```
Replace x.x.x with the version number, for example: Xcode_15.2.0.app. You will need to enter your computer admin password.

Method 2: App Store (Not Recommended)

While you can download Xcode from the App Store for an easier installation process, we do not recommend this option due to potential limitations.

Open Xcode

Open the Applications folder and launch the newly installed Xcode application. If you renamed Xcode, ensure to open the correct application.
Xcode may prompt you to install additional components. Click "Install" and wait for the process to complete.
While it's installing, verify that your default Xcode version is the one you just downloaded:
- Open Terminal.
- Type brew config.
- Check the "CLT" and "Xcode" versions to ensure they match the version you downloaded.

Once the components are installed, Xcode will launch. You should be able to pick up your old projects and continue seamlessly.

Build Dependencies

Before installing any software package with Homebrew, it's recommended to update Homebrew to ensure you have the latest version of all packages. Run the following command in your Terminal:

brew update

Updating Homebrew can take several minutes, so it's advisable to run the update manually before installing a package. This ensures that any core dependencies your package may need are up to date.

Installing Dependencies

Use the brew install command to install the necessary dependencies for building the Valentina project.

Qt Version

Select the Qt version based on your preference and requirements. We recommend using the latest available Qt version (Qt 6) for optimal performance and compatibility with newer features. However, Qt 5 is also available for legacy support or if your project specifically requires it.

You have two ways to install Qt:

With Homebrew: This is the recommended method as it ensures compatibility with other packages installed via Homebrew.
- For Qt 6: brew install qt6
- For Qt 5: brew install qt@5
Install Qt from The Qt Project Website: Alternatively, you can download Qt from the Qt Project website using the Online installer. However, we do not recommend this version if you are using Qt 6. This is because the original macdeployqt utility may not be compatible with packages provided by Homebrew.

Note: You can bypass this requirement if you build the macdeployqt utility provided by our project, which ensures compatibility with Homebrew packages.

Select the option that best suits your needs and proceed with the installation accordingly.

Dependencies for Qt 6:

brew install qt6 coreutils qbs cmake ninja git openssl@1.1 pkg-config poppler xerces-c curl unzip

Dependencies for Qt 5:

brew install qt@5 coreutils git pkg-config qbs qt6 cmake ninja poppler curl unzip

Note: We require Qt 6 to build the macdeployqt utility.

macdeployqt Utility

The original macdeployqt utility is not compatible with Homebrew as Homebrew packages Qt libraries differently, using absolute install name paths for the library instead of the relative paths expected by macdeployqt.

For this reason, we maintain our version of macdeployqt, which contains fixes for compatibility issues with Homebrew.

Follow these steps to download and install the utility:

Run the following commands in your Terminal:

curl -LJ https://github.com/dismine/macdeployqt/archive/refs/heads/main.zip --output ${HOME}/macdeployqt-main.zip --silent
unzip ${HOME}/macdeployqt-main.zip -d ${HOME}
cmake ${HOME}/macdeployqt-main -GNinja -S ${HOME}/macdeployqt-main -B ${HOME}/macdeployqt-build-dir -DCMAKE_INSTALL_PREFIX=${HOME}/macdeployqt-install-dir -DCMAKE_BUILD_TYPE=Release
cmake --build ${HOME}/macdeployqt-build-dir --target install

These commands will:
- Download the custom macdeployqt utility from our GitHub repository.
- Extract the downloaded files to your home directory.
- Configure and build the utility using CMake with the Ninja build system.
- Install the utility to your home directory.

Once the installation is complete, you can use the macdeployqt command to deploy Qt applications built with Homebrew.

Clone the Valentina Repository

To obtain the latest code from the develop branch of the Valentina repository, you can use the following commands:

git clone https://gitlab.com/smart-pattern/valentina.git
cd valentina

This will clone the repository and automatically switch to the develop branch, which contains the latest development changes.

If you need a specific release version, you can checkout to a tag corresponding to that release after cloning the repository. For example:

git checkout <tag_name>

Replace <tag_name> with the specific release tag you wish to use. For example v0.7.52.

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 to migrate to the Qbs build system for the Qt 6 version of Valentina.

Using QMake to Build Valentina

Create Build Directory: Navigate to the root folder of Valentina and create a build directory.
```
mkdir build
cd build
```
Generate Makefile: Call qmake to generate the Makefile.
```
qmake ../Valentina.pro -r "CONFIG += noTests no_ccache noDebugSymbols"
```
- The -r option allows qmake to look through supplied directories recursively.
Build Valentina: To build Valentina, call make.
```
make
```
Faster Builds with Multiple Cores: To make the build faster, specify the -j flag followed by the number of CPU cores to use.
```
make -j24
```
This will utilize multiple CPU cores for parallel compilation, speeding up the build process.

Once you've built the application, you will have a partly filled app bundle. To prepare a ready-to-use version, you must manually use the macdeployqt utility to copy all necessary files inside the app bundle.

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).
no_ccache: Disable ccache, instead enable PCH if not forbidden explicitly.
noDebugSymbols: Do not generate debug symbols in release mode.
noRunPath: Suppress the default RPATH. Helps to run the program without Qt Creator. Fixes problems with paths to libqmuparser and libpropertybrowser.
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

CONFIG+=noDebugSymbols CONFIG+=checkWarnings

or together:

"CONFIG += noTests noRunPath no_ccache noDebugSymbols"

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.

Installing Qbs

Due to Qbs' novelty and rapid development, it's recommended to use the latest available version to ensure compatibility and access to the latest features and bug fixes. On MacOS, we recommend installing Qbs from Homebrew.

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: Run the following command to detect the Qt version in your PATH:
```
qbs setup-toolchains --detect
```
Create a New Profile for Your Build: Set up a new profile for your build using the detected Qt version:
```
qbs setup-qt $QTDIR/bin/qmake qt
```
Replace $QTDIR with the path to your Qt library. For Homebrew installations, it will be the path to the installed Qt version, such as brew --prefix qt6 or brew --prefix qt@5.
Set the Default Profile: Set the newly created profile as the default:
```
qbs config defaultProfile qt
```

Building Valentina with Qbs

Now, you can build Valentina using Qbs. Run the following command inside the project root folder:

Example for Qt 6

qbs build -f valentina.qbs -d ../build --jobs 24 profile:qt config:release qbs.installRoot:../build/install-root modules.buildconfig.enableCcache:false modules.buildconfig.enableUnitTests:false moduleProviders.qbspkgconfig.extraPaths:$(brew --prefix xerces-c)/lib/pkgconfig,$(brew --prefix qt6)/lib/pkgconfig,$(brew --prefix openssl@1.1)/lib/pkgconfig,$(brew --prefix poppler)/lib modules.macdeployqt.libpath:$(brew --prefix qt6)/lib,$(brew --prefix poppler)/lib modules.macdeployqt.pluginspath:$(brew --prefix qt6)/plugins modules.macdeployqt.macdeployqtProgramBinPath:${HOME}/macdeployqt-install-dir

Example for Qt 5

qbs build -f valentina.qbs -d ../build --jobs 24 profile:qt config:release qbs.installRoot:../build/install-root modules.buildconfig.enableCcache:false modules.buildconfig.enableUnitTests:false modules.macdeployqt.libpath:$(brew --prefix qt@5)/lib,$(brew --prefix poppler)/lib modules.macdeployqt.pluginspath:$(brew --prefix qt@5)/plugins modules.macdeployqt.macdeployqtProgramBinPath:${HOME}/macdeployqt-install-dir

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.

After a successful build, you will find Valentina's files inside the install-root directory.

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. By default enabled.
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 building Valentina with limited space. By default enabled.
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. By default enabled.
modules.buildconfig.treatWarningsAsErrors: Enables treating all warnings as errors. Use the format modules.buildconfig.treatWarningsAsErrors:<value>, where <value> can be true or false. By default enabled.
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. By default disabled.
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.
modules.buildconfig.enableMultiBundle: By default, Valentina is built in single bundle mode, where all binaries (Valentina, Tape, Puzzle) are included in one single app bundle. However, you may prefer to use the multi-bundle version, where each application is represented as a separate app bundle. Use the format modules.buildconfig.enableMultiBundle:, where can be true or false. By default disabled.

These configuration options provide flexibility in customizing the build process according to your specific requirements and preferences.

Using Conan Package Manager

Since Qt 6, Valentina requires third-party dependencies, such as the xerces-c library. While we highly recommend installing dependencies through your distribution's package manager, you may decide to build them locally. In such cases, Valentina supports building with 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:

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

Making DMG

After a successful build, you may want to share your version of Valentina with other people. The usual way to distribute macOS applications is by creating a .dmg file. Qbs allows you to automate this process.

Example for Qt 6

qbs build -f valentina.qbs -d ../build -p 'Valentina DMG' --force-probe-execution --jobs 24 profile:qt config:release qbs.installRoot:../build/install-root modules.buildconfig.enableCcache:false modules.buildconfig.enableUnitTests:false moduleProviders.qbspkgconfig.extraPaths:$(brew --prefix xerces-c)/lib/pkgconfig,$(brew --prefix qt6)/lib/pkgconfig,$(brew --prefix openssl@1.1)/lib/pkgconfig,$(brew --prefix poppler)/lib modules.macdeployqt.libpath:$(brew --prefix qt6)/lib,$(brew --prefix poppler)/lib modules.macdeployqt.pluginspath:$(brew --prefix qt6)/plugins modules.macdeployqt.macdeployqtProgramBinPath:${HOME}/macdeployqt-install-dir

Example for Qt 5

qbs build -f valentina.qbs -d ../build -p 'Valentina DMG' --force-probe-execution --jobs 24 profile:qt config:release qbs.installRoot:../build/install-root modules.buildconfig.enableCcache:false modules.buildconfig.enableUnitTests:false modules.macdeployqt.libpath:$(brew --prefix qt@5)/lib,$(brew --prefix poppler)/lib modules.macdeployqt.pluginspath:$(brew --prefix qt@5)/plugins modules.macdeployqt.macdeployqtProgramBinPath:${HOME}/macdeployqt-install-dir

These commands will create a .dmg file for Valentina after a successful build. Adjust paths and options as needed based on your project's specific configuration and requirements.

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