INSTALL

   1 Quassel IRC - Installation Notes
   2 ================================
   3
   4 These should help you to install Quassel IRC from source. Note that this focuses
   5 mostly on building on Linux; please feel free to send patches for build
   6 instructions on other platforms. We are not familiar with them.
   7
   8 There are three versions of Quassel that can be built:
   9
  10 * quasselcore   - The server daemon. Typically runs on a headless server and
  11                   is permanently online. The core connects to IRC and stores
  12                   both settings and backlog.
  13 * quasselclient - The GUI client. Requires a running quasselcore to connect to.
  14                   Upon connection, the client will fetch all session data and
  15                   a certain amount of backlog from the core and restore its
  16                   session almost as if you were never gone.
  17 * quassel       - This standalone version, often called "monolithic" or
  18                   "mono client", contains both a client and a core and can be
  19                   used like a "normal" IRC client, without having to setup
  20                   a server daemon.
  21
  22 Prerequisites
  23 -------------
  24
  25 Of course, for building Quassel you need the usual set of build tools, for
  26 example a compiler. The codebase uses the C++14 standard, so a reasonably recent
  27 compiler is needed:
  28
  29 - GCC 5.0+ (available for most platforms), or
  30 - Clang 3.4+ (available for most platforms), or
  31 - XCode 6.0+ (available for Max OS X and based on Clang), or
  32 - MSVC 19+ (part of Visual Studio 2017 on Windows™)
  33
  34 Other compilers may work, but are not officially supported.
  35
  36 Furthermore, CMake 3.5 or later is required.
  37
  38 As Quassel is a Qt application, you need the Qt SDK, version 5.5 or higher.
  39
  40 There are several optional dependencies; we will talk about that later.
  41
  42 Compiling Quassel - short version
  43 ---------------------------------
  44
  45 Quassel uses CMake as its build system. The canonical way to build any CMake-
  46 based project is as follows:
  47
  48 cd /path/to/source
  49 mkdir build
  50 cd build
  51 cmake ..
  52 make
  53 make install
  54
  55 Compiling Quassel - long version
  56 --------------------------------
  57
  58 First of all, it is highly recommended for any CMake-based project to be built
  59 in a separate build directory rather than in-source. That way, your source
  60 checkout remains pristine, and you can easily remove any build artifacts by just
  61 deleting the build directory. This directory can be located anywhere; in the
  62 short example above, we've just created a directory called "build" inside the
  63 source checkout.
  64
  65 From inside the build directory, you can then run the "cmake" command, followed
  66 by the path to the source. Additionally, you can append various options. Note
  67 that CMake caches the options you provide on the command line, so if you rerun
  68 it later in the same build directory, you don't need to specify them again.
  69
  70 Quassel supports several options to enable or disable features, and can make
  71 use of several optional dependencies if installed. CMake will give a nice
  72 summary of all that after its run, so we'll just mention the most important
  73 options here:
  74
  75 -DWANT_(CORE|QTCLIENT|MONO)=(ON|OFF)
  76     Choose which Quassel binaries to build.
  77
  78 -DUSE_CCACHE=ON
  79     Enable ccache if the ccache binary is available. This avoids the need for
  80     hacks using PATH or the CXX variable to make ccache work.
  81     Distributors may want to disable automatic detection if they have their
  82     own caching mechanism set up.
  83
  84 -DWITH_KDE=ON
  85     Enable integration with the KDE Frameworks runtime environment
  86
  87 -DWITH_BUNDLED_ICONS=ON
  88     Quassel requires a number of icons that are part of the KDE/Plasma icon themes
  89     Breeze and Oxygen, but are generally not supported by other themes. In order
  90     to avoid missing icons, Quassel bundles the subset of icons it uses from the
  91     afforementioned themes, and uses that as a fallback if the system theme does
  92     not provide a required icon.
  93     If it is ensured that Breeze and/or Oxygen are installed on your system (e.g.
  94     through package dependencies), this option can be turned off to save less
  95     than 2 MB of disk space.
  96
  97 -DWITH_OXYGEN_ICONS=(ON|OFF)
  98     Support the Oxygen icon theme. Oxygen was the default theme in KDE 4, and
  99     also the bundled icon theme in Quassel before version 0.13. Since the move
 100     to Qt5, the more modern Breeze icon theme is preferred, and thus Oxygen
 101     is disabled by default.
 102
 103 -DWITH_WEBENGINE=ON
 104     Use WebEngine for showing previews of webpages linked in the chat. Requires
 105     the QtWebEngine module to be available, and increases the client's RAM usage
 106     by *a lot* if enabled at runtime. The default is ON.
 107
 108 -DWITH_WEBKIT=OFF
 109     Use WebKit for showing previews of webpages linked in the chat. Requires
 110     the QtWebKit module to be available, and increases the client's RAM usage
 111     by *a lot* if enabled at runtime.
 112     Note that WebKit support is deprecated and mostly unmaintained in Qt, and
 113     should no longer be used for security reasons. The default is OFF.
 114
 115 -DEMBED_DATA=(ON|OFF)
 116     Specifies whether Quassel's data files (icons, translations and so on)
 117     should be installed normally, or embedded into the binaries. The latter is
 118     useful if you want to run Quassel from the build directory, or don't want
 119     to use a standard installation. In particular, EMBED_DATA defaults to ON
 120     on Windows and OS X, and to OFF on Linux.
 121
 122 You can find the list of optional packages for additional features in CMake's
 123 feature summary; install missing packages for enabling the functionality listed
 124 in the explanation. If you want to forcefully disable an optional feature, use
 125 -DCMAKE_DISABLE_FIND_PACKAGE_Foo=TRUE, where "Foo" is the package name listed.
 126
 127 Quassel also supports the usual CMake options, most importantly
 128
 129 -DCMAKE_INSTALL_PREFIX=/prefix/path - specify the installation prefix
 130 -DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebug) - specify the build type
 131
 132 If you want to narrow down the languages to be installed, you can set the
 133 LINGUAS environment variable with a space-separated list of language codes,
 134 for example LINGUAS="de en_US".
 135
 136 After running CMake, you can just run "make" in the build directory, and
 137 "make install" for installing the result into the installation prefix.