valentina

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

Prerequisites

Linux distribution (e.g., Ubuntu, Fedora)
Compiler with C++17 support or higher
CMake (needed for third-party dependencies)
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 Cirrus CI configuration (.cirrus.yml) for hints on setting up the build environment. This can provide valuable insights into recommended configurations and build steps.

Build Dependencies

Before building the Valentina project, you need to install the necessary dependencies on your system. The following steps outline the general requirements, but note that depending on your distribution, the package names may vary.

Compiler

Valentina is tested with GCC and Clang compilers. Ensure you have either GCC or Clang installed on your system.

# Install GCC (example for Ubuntu)
sudo apt-get install build-essential

Build Tools

Install essential build tools and utilities:

# Install Git (example for Ubuntu)
sudo apt-get install git

# Install CMake (example for Ubuntu)
sudo apt-get install cmake

# Install pkg-config (optional, required if Conan not used, example for Ubuntu)
sudo apt-get install pkg-config

# Install wget and curl (optional, if not using browser for downloads, example for Ubuntu)
sudo apt-get install wget curl

Qt Version

Select the Qt version based on your preference and requirements:

Qt 6 (Recommended):

# Install Qt 6 (example for Ubuntu)
sudo apt-get install qt6-base-dev qt6-l10n-tools libqt6svg6-dev qt6-base-dev-tools qmake6 libgl1-mesa-dev

Qt 5 (For legacy support or qmake):

# Install Qt 5 (example for Ubuntu)
sudo apt-get install qtbase5-dev libqt5svg5-dev qttools5-dev-tools libqt5xmlpatterns5-dev libqt5core5a libqt5gui5 libqt5printsupport5 libqt5svg5 libqt5widgets5 libqt5xml5 libqt5xmlpatterns5

Install Qt from The Qt Project Website: You can also download Qt from the Qt Project website using the Online installer. This option is recommended if the version available in your distribution's repository is outdated. Download the Online installer from the Qt Project website and follow the installation instructions provided.

By installing Qt from The Qt Project website, you ensure access to the latest version with all the latest features and bug fixes.

Note: If you choose Qt 6, it is recommended to install the xerces-c library through your package manager:

# Install xerces-c (example for Ubuntu)
sudo apt-get install libxerces-c-dev

If installing xerces-c through the package manager is not possible, consider using the Conan package manager system.

PDF to PS Conversion

If you require PDF to PS conversion functionality, you need the pdftops utility. Install the necessary package based on your distribution.

# Install Poppler Utilities (example for Ubuntu)
sudo apt-get install poppler-utils

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, and we have decided migrating to the Qbs build system for Qt 6 version.

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 make file.
```
qmake ../Valentina.pro -r "CONFIG += noTests noRunPath no_ccache noDebugSymbols"
```
- The -r option allows qmake to look through supplied directories recursively.
Optional: Specify Qt Version: Depending on your distribution and Qt version, qmake binary may have different names: qmake, qmake-qt5, qmake6. If you're using both Qt 5 and Qt 6, you may need to specify the correct library version. For Qt 5 - QT_SELECT=qt5, for Qt 6 - QT_SELECT=qt6.
```
QT_SELECT=qt5 qmake ../Valentina.pro -r
```
Optional: Change Install Prefixes: If you want to change the default install prefixes, you can do so with PREFIX and PREFIX_LIB.
```
qmake PREFIX=/usr PREFIX_LIB=/usr/lib64 ../Valentina.pro -r
```
Optional: Specify Platform and Compiler Type: You may need to specify the platform and compiler type explicitly. For example, linux-g++ or linux-clang.
```
qmake ../Valentina.pro -r -spec linux-g++
```
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
```
Install Valentina: To install Valentina, use sudo make install.
```
sudo make install
```
Additionally, you can specify the installation root directory using the INSTALL_ROOT option. This can be useful when collecting all installation files for archiving or local use.
```
make INSTALL_ROOT=$HOME/valentina install
```

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"

Running Tests

To run tests after a successful build, you need to ensure Valentina can find paths to the required libraries, such as vpropertyexplorer and qmuparser. You can achieve this by setting the LD_LIBRARY_PATH environment variable.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"<root_path>/build/src/libs/vpropertyexplorer/bin:<root_path>/build/src/libs/qmuparser/bin"

Replace <root_path> with the actual path to your Valentina project root directory.

After setting the environment variable, you can call tests using make.

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

By following these steps, 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.

Installing Qbs

Due to Qbs' newety and rapid development, it's recommended to use the latest available version to ensure compatibility and access to the latest features and bug fixes. However, the version available through the package manager may be outdated. You can install a newer version of Qbs from The Qt Project build for Linux.

# Install Qbs 2.2.2 from The Qt Project
mkdir -p /opt/qbs 
wget -q -c "https://download.qt.io/official_releases/qbs/2.2.2/qbs-linux-x86_64-2.2.2.tar.gz" -O - | tar --strip-components=1 -xz -C /opt/qbs

Optional: Installing Linker Mold

Linker mold is a faster drop-in replacement for existing Unix linkers. It significantly reduces linking time and is highly recommended if you plan to rebuild code frequently.

git clone https://github.com/rui314/mold.git
cd mold
git checkout v2.4.0
mkdir build
cd build
../install-build-deps.sh
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=c++ ..
cmake --build . -j 24
cmake --build . --target install
rm -rf /mold

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.

Example of how to setup Qbs with custom compiler and Qt library.

# If you use custom path to compiler
qbs setup-toolchains /usr/bin/gcc gcc

# Create a new profile for your build
qbs setup-qt $QTDIR/bin/qmake qt6

# Link the profile with the compiler
qbs config profiles.qt6.baseProfile gcc

# Set the default profile
qbs config defaultProfile qt6

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 modules.buildconfig.enableCcache:false modules.cpp.linkerVariant:mold modules.buildconfig.enableUnitTests: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.

After a successful build, you will find Valentina's files inside the install-root directory. To run Valentina from install-root, set up the LD_LIBRARY_PATH environment variable.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"<root_path>/../build/install-root/usr/local/lib/valentina"

Replace <root_path> with the actual path to your Valentina project root directory.

Installing Valentina

Similarly to make, you can install Valentina with Qbs. First, you need to build Valentina with the --no-install option.

qbs build --no-install -f valentina.qbs --jobs 24 profile:qt6 config:release qbs.installPrefix:/usr modules.buildconfig.enableCcache:false modules.cpp.linkerVariant:mold modules.buildconfig.enableUnitTests:false

This command builds Valentina without installing it. Adjust paths and options as needed based on your project's specific configuration and requirements.

After successfully building Valentina, you can then install it using Qbs:

sudo qbs install --no-build --install-root /

This command installs Valentina to the specified installation root (/ in this example). Adjust the root path as needed based on your preferences and requirements.

For more details about installing files with Qbs, you can refer to the official documentation.

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.

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, Conan integration is disabled in 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.

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.

Building AppImage

To create an AppImage for Valentina, we use the project appimage-builder. Before proceeding, it's essential to read their documentation for a comprehensive understanding of the process.

Recommendations

When building an AppImage, we recommend following the suggestions provided by the appimage-builder project and this guide. It's advisable to build with the oldest LTS version of Ubuntu. While it's possible to create an AppImage version on other distributions and with other AppImage build tools, it may require additional changes to the code.

Setting up the Build Stage

To create an AppImage version, you must first set up the build stage. Add the following keys to your Qbs configuration:

modules.buildconfig.enableAppImage:true
modules.buildconfig.enableRPath:false

Additionally, set the path to the AddDir folder using qbs.installRoot:<your path>/AppDir.

Creating the AppImage Package

Once the build stage is set up, you can create the AppImage package using the following command:

appimage-builder --recipe <project root>/dist/AppImage/AppImageBuilder.yml --appdir <your path>/AppDir --skip-test

Replace <project root> with the root directory of your Valentina project, and <your path> with the desired path to the AppDir.

This command generates the AppImage package based on the provided recipe and configuration. The --skip-test flag skips any test execution during the packaging process.

By following these steps, you can create an AppImage version of Valentina for distribution across different Linux systems.

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