Following this guide, anyone even completely unexperienced in C/C++ software building process can successfully build qBittorent. Only very basic skills in command line usage are required.
This guide could seem too detailed or even odd, but that was done intentionally, because first of all it aims to help novice users. Any experienced users may just overview it to find section they are interested in. For example, [the last one](#building-with-qmake) may be interesting for new contributors who want to debug or just poke around the code.
This guide describes build process using qBittorrent sources from `master` branch, but it also can be suitable for 4.3.x releases. It assumes only using of libtorrent 1.2.x series. Building qBittorrent 4.1.x series or 4.2.x with libtorrent 1.1.x is out of scope, similar concept can be used in any case, but various build options must be adjusted.
This guide assumes building **everything** (i.e. all dependencies) from sources, so whole build process is pretty time consuming (takes ~1 hour on old MacBook Pro Retina Mid 2014).
- Launch XCode for the first time. You will be asked to install additional command-line tools, which you should do, as they are required for building Qt-based apps such as qBittorrent.
- Download and install CMake from the [official website][cmake-off-site]. A GUI and some command-line tools will be installed. The GUI will not be needed for this tutorial.
Actually, some additional libraries (like zlib) are required, but they are available on each system and have stable binary interfaces, so there is no reason to build them from sources. Moreover, such libraries are part of the SDK.
OpenSSL is available for download from [official website][openssl-site], just download archive for 1.1.x series. At the moment of writing it was 1.1.1g.
Place downloaded archive to `$HOME/tmp/qbt/src` and extract it here:
`git` is used for Qt download. It is much effective rather than using source archive, and brings a lot of advantages for build process (less configure options are required). Moreover, it requires less space and time rather than using sources from archive, due to only few required submodules can be downloaded, not all available/provided by default.
It is recommended to use stable releases, but using any other branch with newer Qt version is also possible. At the moment of writing Qt 5.14.2 was the latest, so use it. Switch (checkout) to desired branch/tag:
```sh
cd qt5
git checkout v5.14.2
```
Now top-level repo is initialized, but NO any Qt sources were downloaded. To download sources issue next command:
This downloads only required parts of Qt. Download process takes few minutes depending on connection speed. About ~500 MB will be downloaded.
### Downloading Boost
Boost is available for download from [official website][boost-site]. Latest available release is a good choice in most cases, so pick it firstly. If libtorrent build fails, download previous version. Preferable archive format is `.tar.bz2` or `.tar.gz`. At the moment of writing latest version was 1.73.0.
Place downloaded archive to `$HOME/tmp/qbt/src` (see [conventions](#conventions-used-in-this-document)) and extract it here:
It is important to build all libraries with the same value of minimum supported macOS version, otherwise the build may fail at the final linker stage. Qt sets such value, so use it for any other libraries.
Please note `-mmacosx-version-min` option at the end of line, this is NOT some OpenSSL configure script option, this option is passed directly to compiler, it is important to place it last. Its value must be the value that was found in Qt sources.
This configures Qt as shared library (.framework in case of macOS) with no any debug info included.
Note `-I` and `-L` options in that line, they are required to allow Qt' build system to find OpenSSL (it is an optional dependency, but it is required in case of qBittorrent). If you change paths used in this guide to your own, please make sure that these options have correct values, also please set `-prefix` value to corresponding path too.
The rest of options mostly to minimize the scope of building stuff and decrease build time.
Actually no Boost binaries are required, libtorrent requires Boost.System and it became header-only since Boost 1.70 (or even 1.69), boost_system library is just a stub left for compatibility, but a lot of tools/scripts rely on it when detecting the presence of Boost. Moreover, there is no option to build header-only version of Boost. Of course, 'stage' version can be used without any building, but it is not suitable for usage with cmake - it doesn't have files allowing cmake to detect it. Such files are generated only during installation process. So build only boost_system library regardless this is just a stub and will not be used:
This produces static version of boost_system library with no debug information. Custom `cxxflags` are left for historical reasons, when Boost.System was not header-only library and apps using it must link boost_system library.
### Building libtorrent
libtorrent provides few build systems to choose from to build it. Unfortunately, convenient and easy to use GNU autotools option is not available on macOS, so let's use cmake.
cmake supports build in separate directory, usually subdirectory is used for it, so create such directory and run cmake in it:
Few important things to note in this line are C++ standard version and minimum supported macOS version (`CMAKE_CXX_STANDARD` and `CMAKE_OSX_DEPLOYMENT_TARGET` options), this is required for successful linkage.
cmake just performs configuration steps and generates platform-specific makefile, so build and install it as usual (remember, you are still in 'build' directory):
Like libtorrent, qBittorrent also provides few build systems to choose from to build it. GNU autotools is not available on macOS, qmake requires some additional work to setup project, so let's use cmake again.
qBittorrent 4.3.x series and master branch requires C++17 features available only starting from macOS 10.14. This requirement must be explicitly expressed as cmake arguments.
This configures qBittorrent with all default build options. Only one important option to note - `CMAKE_PREFIX_PATH`, tells cmake where to find dependencies.
Build process takes about 10 minutes, and as result you will get `qbittorrent.app` in the build directory (where cmake and make were run). But this app bundle is incomplete - Qt runtime must be integrated into it. This can be achieved with special Qt tool called `macdeployqt`, it even can produce dmg image ready for redistribute.
You can use [this script][macos-build-script] to build qBittorrent master branch in "fully automatic mode". Just launch it and wait. This script is a little bit tricky, but it is not too complex to understand. Moreover, it is pretty well documented, sometimes it contains very detailed explanations. Initially, I created it just to fulfil my own needs, but later it was published due to often user requests. It can be a good starting point for creating your own build script serving your own needs/requirements/preferences.
First of all, this section for advanced or just very curious users, who want to know how to build qBittorrent using qmake.
As was written before, qBittorrent supports several build systems, one of them is Qt native build system - qmake.
Unfortunately, it is not so convenient as cmake or autotools in case of qBittorrent (due to complex dependencies), but qBittorrent authors envisaged it by providing the way for user-specific configuration (e.g. paths to dependencies) as separate file called `conf.pri`.
Except paths to dependencies, this file also should contain defines describing libtorrent configuration (libtorrent is very sensitive to it, if it itself and app are built with different set of defines it won't link).
If you just followed this guide to build all required dependencies, next `conf.pri` is suitable for building qBittorrent (with no any adjustments). In other cases adjustments are required (at least for paths).
Most of its content is libtorrent-related stuff (libtorrent dependencies and mentioned above defines). Line `CONFIG -= silent` is just my preference, it may be useful in development process, it disables "silent build", i.e. all build commands are fully shown with all arguments.
In case if you built libtorrent with your own options (for example with disabled deprecated stuff), you have to adjust defines set. There are some tips on how to find them.
libtorrent defines used for building it can be found in few places: .pc file (used by pkg-config tool on Linux) and cmake config files. The set of defines is the same in these files.
.pc file is regenerated regardless than pkg-config can't used on macOS (at least out of the box), this file can be found at `$HOME/tmp/qbt/ext/lib/pkgconfig/libtorrent-rasterbar.pc` (adjust path to yours if required). You are interested in line staring with "Cflags".
Mentioned cmake config file can be found at `$HOME/tmp/qbt/ext/lib/cmake/LibtorrentRasterbar/LibtorrentRasterbarTargets.cmake` (adjust path to yours if required). You are interested in line starting with "set_target_properties".
I recommend to use cmake file, it looks more reliable, but pkg-config is easy to read.
`conf.pri` must be placed to sources root, then qBittorrent can be built using qmake from command line or by opening project in [QtCreator](#building-with-qtcreator).
First line just creates out of tree build directory, second runs qmake to generate makefile (release configuration is used by default), and the last just runs make to build everything.
As result, you will get `qbittorrent.app` under `src` subdirectory in your build directory (not like in case of cmake). This bundle is also incomplete, and Qt runtime must be deployed for it:
Now `qbittorrent.app` build is ready to use. Again, if you don't want .dmg image, just drop `-dmg` option, it is used just to show that `macdeployqt` has it.
To build qBittorrent using QtCreator few additional steps are required.
First of all, custom Qt Kit should be added. Just open QtCreator settings dialog, [add Qt compiled for qBittorrent][adding-qt-version] and then [create new kit][adding-qt-kits] that uses it.
Next important thing that some project files must be edited, otherwise it could be impossible to launch qBittorrent from QtCreator. Just **delete/comment** next line in `macxconf.pri` (in qBittorrent sources root):
```qmake
QMAKE_BUNDLE_DATA += qt_conf
```
Now everything is ready for development or just building.
One more note for new contributors: for a better debugging experience, build at least Qt with debug symbols. Just drop `-release` option from suggested configuration command for it. Please note build time will be approximately twice longer.
