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

MacOS build guide.

Roman Telezhynskyi 2024-02-21 16:16:08 +02:00
parent 4b14f94684
commit 1e840d9c72
1 changed files with 407 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

407
macos-build.md Normal file

@ -0,0 +1,407 @@
[[_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
1. **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.
2. **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.
3. **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)
1. Navigate to the "more" section of the [Apple Developer website](https://developer.apple.com/download/all/).
2. Sign in with your Apple ID account.
3. 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.
4. Once the download completes, double-click on the `.xip` file to extract it. The extraction process is automatic and will take a few minutes.
5. *(Optional)* If you're using multiple versions of Xcode, consider renaming the application to something like “Xcode_15.x.x”.
6. Drag the extracted Xcode application to the Applications folder.
7. *(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
1. Open the Applications folder and launch the newly installed Xcode application. If you renamed Xcode, ensure to open the correct application.
2. Xcode may prompt you to install additional components. Click "Install" and wait for the process to complete.
3. 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:
1. **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`
2. **Install Qt from The Qt Project Website:**
Alternatively, you can download Qt from the Qt Project website using the [Online installer](https://www.qt.io/download-qt-installer-oss). 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](#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).
## 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](https://github.com/dismine/macdeployqt/tree/main) of `macdeployqt`, which contains fixes for compatibility issues with Homebrew.
Follow these steps to download and install the utility:
1. Run the following commands in your Terminal:
```bash
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
```
2. 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:
```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 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
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 Makefile.
```bash
qmake ../Valentina.pro -r "CONFIG += noTests no_ccache noDebugSymbols"
```
- The `-r` option allows `qmake` to look through supplied directories recursively.
3. **Build Valentina:**
To build Valentina, call `make`.
```bash
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.
```bash
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:
```bash
CONFIG+=noDebugSymbols
```
or
```bash
CONFIG+=noDebugSymbols CONFIG+=checkWarnings
```
or together:
```bash
"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.
1. **Detect Qt Version in PATH:**
Run the following command to detect the Qt version in your PATH:
```bash
qbs setup-toolchains --detect
```
2. **Create a New Profile for Your Build:**
Set up a new profile for your build using the detected Qt version:
```bash
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`.
3. **Set the Default Profile:**
Set the newly created profile as the default:
```bash
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
```bash
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
```bash
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:<value>, where <value> 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:
```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 . --build=missing -pr valentina
```
By default, the use of Conan is disabled. To enable it, pass `project.enableConan:true` 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
```bash
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
```bash
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](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.