aw/valentina
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Linux Build and Install Guide

Roman Telezhynskyi 2024-02-06 17:05:00 +02:00
parent 8fd0d3828f
commit de7622a503
2 changed files with 370 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
home.md → Home.md

371
Linux-Build-and-Install-Guide.md

@ -1 +1,370 @@
## Introduction
[[_TOC_]]
## Introduction
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.
```bash
# Install GCC (example for Ubuntu)
sudo apt-get install build-essential
```
### Build Tools
Install essential build tools and utilities:
```bash
# 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):**
```bash
# 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):**
```bash
# 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](https://www.qt.io/download-qt-installer-oss). 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:
```bash
# 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.
```bash
# 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:
```bash
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:
```bash
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
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: 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`.
```bash
QT_SELECT=qt5 qmake ../Valentina.pro -r
```
4. **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
```
5. **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++
```
6. **Build Valentina:**
To build Valentina, call `make`.
```bash
make
```
7. **Faster Builds with Multiple Cores:**
To make the build faster, specify the `-j` flag followed by the number of CPU cores to use.
```bash
make -j24
```
8. **Install Valentina:**
To install Valentina, use `sudo make install`.
```bash
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.
```bash
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:
```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 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.
```bash
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`.
```bash
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.
```bash
# Install Qbs 2.2.1 from The Qt Project
mkdir -p /opt/qbs
wget -q -c "https://download.qt.io/official_releases/qbs/2.2.1/qbs-linux-x86_64-2.2.1.tar.gz" -O - | tar --strip-components=1 -xz -C /opt/qbs
# Apply patch for Qbs 2.2.1 bug
curl https://gist.githubusercontent.com/dismine/43f3c51e05f3317c5d4fe16cd3c4b6d8/raw/2d297bcb53c2c022f740509923adf1eb1796afe2/qbs-pkg-config-probe.patch --output /opt/qbs/qbs-pkg-config-probe.patch --silent
patch -d /opt/qbs/ -p1 < /opt/qbs/qbs-pkg-config-probe.patch
rm /opt/qbs/qbs-pkg-config-probe.patch
```
### Optional: Installing Linker Mold
Linker [mold](https://github.com/rui314/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.
```bash
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.
```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.
Example of how to setup Qbs with custom compiler and Qt library.
```bash
# 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:
```bash
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.
```bash
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.
```bash
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:
```bash
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](https://doc.qt.io/qbs/installing-files.html).
### 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.