MacOS build guide.
Roman Telezhynskyi
parent
4b14f94684
commit
1e840d9c72
407
macos-build.md
Normal file
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.
|
||||
Loading…
Reference in New Issue
Block a user