Send icon name instead of pixmap
[quassel.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index e6c74be..824695a 100644 (file)
--- a/INSTALL
+++ b/INSTALL
 Quassel IRC - Installation Notes
 ================================
 
-These should help you to install Quassel IRC from source. Please also have a
-look at the README file!
-
-Quassel IRC provides three binaries: quasselcore, quasselclient, and
-quassel. While quasselcore and quasselclient obviously provide the
-separated core and client functionality, the latter one (quassel) is a
-monolithic version containing both of them for convenience.
-
-Note that quasselcore is no longer being built by default, since it tends to
-confuse users more than it helped. It will be back as soon as we have simple mode
-implemented.
-
-We now use CMake as our build system. CMake supports and encourages out-of-source 
-builds, which do not clutter the source directory. You can (and should) thus use 
-an arbitrary directory for building.
-
-There is no "make distclean"; "make clean" should usually be enough since CMake
-actually cleans up properly (qmake often didn't). If you really want to get rid
-of all build files, just remove the build directory.
-
-Usually, you will build Quassel as follows:
-
-cd /path/to/build/dir
-cmake /path/to/quassel
+These should help you to install Quassel IRC from source. Note that this focuses
+mostly on building on Linux; please feel free to send patches for build
+instructions on other platforms. We are not familiar with them.
+
+There are three versions of Quassel that can be built:
+
+* quasselcore   - The server daemon. Typically runs on a headless server and
+                  is permanently online. The core connects to IRC and stores
+                  both settings and backlog.
+* quasselclient - The GUI client. Requires a running quasselcore to connect to.
+                  Upon connection, the client will fetch all session data and
+                  a certain amount of backlog from the core and restore its
+                  session almost as if you were never gone.
+* quassel       - This standalone version, often called "monolithic" or
+                  "mono client", contains both a client and a core and can be
+                  used like a "normal" IRC client, without having to setup
+                  a server daemon.
+
+Prerequisites
+-------------
+
+Of course, for building Quassel you need the usual set of build tools, for
+example a compiler. The codebase uses the C++14 standard, so a reasonably recent
+compiler is needed:
+
+- GCC 5.0+ (available for most platforms), or
+- Clang 3.4+ (available for most platforms), or
+- XCode 6.0+ (available for Max OS X and based on Clang), or
+- MSVC 19+ (part of Visual Studio 2017 on Windows™)
+
+Other compilers may work, but are not officially supported.
+
+As Quassel is a Qt application, you need the Qt SDK, version 5.5 or higher.
+Furthermore, the Boost header-only libraries (at least version 1.54) and
+CMake 3.5 or later are required. CMake will tell you about any missing
+dependencies when configuring the project.
+
+Compiling Quassel - short version
+---------------------------------
+
+Quassel uses CMake as its build system. The canonical way to build any CMake-
+based project is as follows:
+
+cd /path/to/source
+mkdir build
+cd build
+cmake ..
 make
+make install
 
-Additionally, you may add some options to the cmake call, prefixed by -D. These need
-to follow the source directory PATH:
+Compiling Quassel - long version
+--------------------------------
 
-cmake /path/to/quassel -D<option1> -D<option2>
+First of all, it is highly recommended for any CMake-based project to be built
+in a separate build directory rather than in-source. That way, your source
+checkout remains pristine, and you can easily remove any build artifacts by just
+deleting the build directory. This directory can be located anywhere; in the
+short example above, we've just created a directory called "build" inside the
+source checkout.
 
-NOTE: In order to reconfigure, you need to remove CMakeCache.txt (or empty
-      the build directory), otherwise cmake will ignore modified -D options!
+From inside the build directory, you can then run the "cmake" command, followed
+by the path to the source. Additionally, you can append various options. Note
+that CMake caches the options you provide on the command line, so if you rerun
+it later in the same build directory, you don't need to specify them again.
 
-Quassel recognizes the following options:
+Quassel supports several options to enable or disable features, and can make
+use of several optional dependencies if installed. CMake will give a nice
+summary of all that after its run, so we'll just mention the most important
+options here:
 
 -DWANT_(CORE|QTCLIENT|MONO)=(ON|OFF)
-    Allow to choose which Quassel binaries to build.
-
--DQT=/path/to/qt
-    Use a non-system Qt installation. This is for example useful if you have a static
-    Qt installed in some local dir.
-
--DSTATIC=1
-    Enable static building of Quassel. You should link the static versions of some libs
-    (in particular libstdc++.a) into /path/to/build/dir/staticlibs in oder to create
-    a portable binary!
-
-BUILDING ON WINDOWS:
---------------------
-We have tested building on Windows with a statically built Qt (with its /bin directory in %PATH%)
-and MSVC 2005/2008. Make sure that you use a "shell" that has all needed env variables setup,
-such as the "Visual Studio Command Prompt". You will also need the /bin of the Microsoft SDK in
-your %PATH% at least for VS 2008, otherwise rc.exe is not found.
-Currently, only building in the shell using nmake seems to work; CMake can also create MSVC project
-files, but they seem to be problematic. However, YMMV. Software development on Windows is a real
-PITA.
-
-After you have everything setup:
-
-cd C:\path\to\quassel-build
-cmake -G"NMake Makefiles" C:\path\to\quassel\source -DSTATIC=1
-nmake
+    Choose which Quassel binaries to build.
+
+-DUSE_CCACHE=ON
+    Enable ccache if the ccache binary is available. This avoids the need for
+    hacks using PATH or the CXX variable to make ccache work.
+    Distributors may want to disable automatic detection if they have their
+    own caching mechanism set up.
+
+-DWITH_KDE=ON
+    Enable integration with the KDE Frameworks runtime environment
+
+-DWITH_BUNDLED_ICONS=ON
+    Quassel requires a number of icons that are part of the KDE/Plasma icon themes
+    Breeze and Oxygen, but are generally not supported by other themes. In order
+    to avoid missing icons, Quassel bundles the subset of icons it uses from the
+    afforementioned themes, and uses that as a fallback if the system theme does
+    not provide a required icon.
+    If it is ensured that Breeze and/or Oxygen are installed on your system (e.g.
+    through package dependencies), this option can be turned off to save less
+    than 2 MB of disk space.
+
+-DWITH_OXYGEN_ICONS=(ON|OFF)
+    Support the Oxygen icon theme. Oxygen was the default theme in KDE 4, and
+    also the bundled icon theme in Quassel before version 0.13. Since the move
+    to Qt5, the more modern Breeze icon theme is preferred, and thus Oxygen
+    is disabled by default.
+
+-DWITH_WEBENGINE=ON
+    Use WebEngine for showing previews of webpages linked in the chat. Requires
+    the QtWebEngine module to be available, and increases the client's RAM usage
+    by *a lot* if enabled at runtime. The default is ON.
+
+-DWITH_WEBKIT=OFF
+    Use WebKit for showing previews of webpages linked in the chat. Requires
+    the QtWebKit module to be available, and increases the client's RAM usage
+    by *a lot* if enabled at runtime.
+    Note that WebKit support is deprecated and mostly unmaintained in Qt, and
+    should no longer be used for security reasons. The default is OFF.
+
+-DEMBED_DATA=(ON|OFF)
+    Specifies whether Quassel's data files (icons, translations and so on)
+    should be installed normally, or embedded into the binaries. The latter is
+    useful if you want to run Quassel from the build directory, or don't want
+    to use a standard installation. In particular, EMBED_DATA defaults to ON
+    on Windows and OS X, and to OFF on Linux.
+
+You can find the list of optional packages for additional features in CMake's
+feature summary; install missing packages for enabling the functionality listed
+in the explanation. If you want to forcefully disable an optional feature, use
+-DCMAKE_DISABLE_FIND_PACKAGE_Foo=TRUE, where "Foo" is the package name listed.
+
+Quassel also supports the usual CMake options, most importantly
+
+-DCMAKE_INSTALL_PREFIX=/prefix/path - specify the installation prefix
+-DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebug) - specify the build type
+
+If you want to narrow down the languages to be installed, you can set the
+LINGUAS environment variable with a space-separated list of language codes,
+for example LINGUAS="de en_US".
+
+After running CMake, you can just run "make" in the build directory, and
+"make install" for installing the result into the installation prefix.