Compiling using CMake
Clone this wiki locally
This guide briefly overviews how to compile (and install) qBittorrent using CMake build system on Linux and Windows. The guide does not go into details how to install particulars software packages or how to compile them. One can gather this information from the other compilation guides in this wiki. This is not a step-by-step guide.
Table of Contents
- A C++ compiler, supported by CMake.
- CMake, version 3.5 or newer. Get it from your packages repository or download an installer from the CMake website
- Installed Qt, libtorrent and their dependencies (Boost, zlib, openssl). Please note that Boost support in CMake is version-explicit, and thus CMake version has to be younger than the Boost version or, otherwise, CMake might not recognize boost libraries.
- Development files (headers and libraries) for Qt, libtorrent, and Boost.
Things will be easier if you install all the dependencies into the same prefix, for instance into
c:\usr. This complicates uninstalling, but you receive the following advantages:
%PREFIX%/lib can be added to your compiler search paths and you don't need to care about every library; CMake can be instructed to look for the libraries in this prefix (once for all of them). If you want to compile qBittorrent against both Qt 4 and 5 versions, you may install both Qt versions into different prefixes, for example
CMake encourage you to use so called out-of-source builds (i.e. build into a different directory than the one with source files). In fact, CMake does not even provide a "clean" command to remove generated files --- you simply delete the build directory (do not confuse with a "clean" command of the build system, which removes files, generatad during a build, this CMake does provide). You may have different build directories, configured with options (see below). And, of course, you do not pollute your sources, that are always ready for
CMake does not build a project by itself. Instead it generates rules for an actual build software. These generators include traditional makefiles as well as other platform-specific (like XCode or Visual Studio) or not (Ninja) build tools. At the same time CMake projects can be integrated with IDEs. This is done in two ways: either CMake generates project files, which include call to CMake itself to update those files if needed, or an IDE may load CMake project structure directly. The generators for Visual Studio and XCode implement the former approach, while Qt Creator and KDevelop use the latter model. Before continuing you have to decide which generator you will use and will you integrate with an IDE or not. You may get a list of available generators running
cmake -G or
- Qt Creator
- This IDE can just open the top-level project
CMakeLists.txtfile and load the project structure. Then it will ask you where to put build files and which make tool to use. Please note that Ninja will give you significantly shorter rebuild times, as comparing to a regular make. From version 4.3 of Qt Creator and 3.7 of CMake, support is excellent (see this blog post for details).
- KDevelop from version 4 provides excellent support for CMake-based projects, simply open the top-level project
CMakeLists.txtfile and select a build directory.
- You have to use "XCode" generator to generate project files. Then when any of the CMake project files get updated, the next build command will re-generate the XCode projects and XCode will reload them.
- Visual Studio
- You have to use "Visual Studio" generator to generate project files. Then when any of the CMake project files get updated, the next build command will re-generate the projects files and Visual Studio will ask to reload them.
- No IDE
- Create build directory. For example, it can be a sub-directory of the source directory, like
build/debugfor a debug build. Cd into that directory and issue a command:
cmake -G <chosen generator> -D<option1> -D<option2> <source directory>. If your build directory is as above (
build/debug), the command may be:
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DQT5=ON -DSYSTEM_QTSINGLEAPPLICATION=ON ../... For the list of supported by qBittorrent and CMake options (and where to look them up) see below.
- Visual Studio
- Create build directory. This directory will contain Visual Studio project files as well. Cd into that directory and issue a command:
cmake -G "Visual Studio xxxx" -D<option1> -D<option2> <source directory>. If your build directory is as above (
build/debug), the command may be:
cmake -G "Visual Studio 2015" -DQT5=ON -DSYSTEM_QTSINGLEAPPLICATION=ON ../... For the list of supported by qBittorrent and CMake options (and where to look them up) see below.
- Same as for Visual Studio, replace generator with "XCode".
- KDevelop, Qt Creator
- Open the top level
CMakeLists.txtfile. When the IDE asks you for options, enter
-D<option1> -D<option2>into the input field. The options might be, for instance:
When you run
cmake either directly or via an IDE, it will perform tasks similar to those done be automake's
configure script: it will detect environment, try to find all the needed dependencies and generate build files. One might get errors from CMake at this step if it is unable to find a package (library file or include headers). In case of UNIX (Linux or OSX) this usually mean that the package is indeed not installed, while on Windows you might need to change configuration options or edit the files manually (see the next section).
There is no common place for software installation as well as no a common way to share development requirements (like, for instance, pkgconfig). As such, there is no way to pass required information automatically. Therefore, qBittorrent provides a reasonable defaults, and you can override them via CMake options in its cache (via command line or GUI tools) or in the
The defaults describe the following build environment:
- All the prerequisites are installed into the same prefix (same directory) with exception for two versions of Qt installed simultaneously, see below. This path will be referenced as
- Qt versions 4 an 5 are installed into
- Boost libraries are linked statically.
cmakefor configure state, or edit them in
cmake\Modules\winconf.cmakefile. CMake variable names are given below:
- To set boost location, use
-DBOST_ROOT=<your_boost_location>). Alternatively, you may set include and librariess directories independently(
BOOST_LIBRARYDIR. To set libtorrent location, use
Falseto change the default setting.
CMake may report errors during the configuration stage. Most likely those errors arise when CMake is unable to find a dependency, either because it does not know where to look for it, or it is indeed absent.
Here are the options that you can use to change to tune qBittorent build for your needs. The options may be passed to
-D<option>=<value> as well as may be changed in the build cache later via
cmake-gui, or your IDE (the build cache is located in your build dir).
|Name||Type||Description||Default value||Condition if any|
|QT5||bool||Whether to build against version 5 of the Qt toolkit||True|
|SYSTEM_QTSINGLEAPPLICATION||bool||Whether to link to the system (already installed) qtsingleapplication library, or use the bundled one.||False|
|SYSTEM_QJSON||bool||Use system qjson library or the bundled one||False||
|GUI||bool||Enable graphical user interface||True|
|WEBUI||bool||Enable Web interface||True|
|STACKTRACE_WIN||bool||Enable stacktrace in crash reports||False||Windows|
|SYSTEMD||bool||Install the systemd service file||False||
|DBUS||bool||Enable use of DBus for various purposes||True||
When configure phase completes successfully, CMake generates build control files for your chosen build tool. Those might be Makefiles, Ninja rules or your IDE project files. At this stage run your tool of choice in the build directory to build qBittorrent or use your IDE command. Take a look at CMAKE_BUILD_TYPE variable to control debug/release build kind.
If you want to change any of the listed above CMake options, there is no need to run
cmake again with all the options in the command line. Just use
cmake-gui, or your IDE to edit those options in the cmake cache (located in the build directory), and the next build command (e.g.
make) will run
cmake to reflect the option change automatically. Alternatively, you may use several build directories with different set op options (and IDEs like KDevelop and QtCreator allows one to switch between build directories).
To install built software, either use
install target (i.e.
make install) or your IDE command (or "build" project named 'INSTALL' in Visual Studio).
To control installation dir, use CMAKE_INSTALL_PREFIX (and
DESTDIR for UNIX systems).