-------------------------------------------------------------------------------
    Table of contents
-------------------------------------------------------------------------------

   1. Introduction
   2. Hacker Installation - Advanced or power users
   3. Dependencies and requirements
   4. Configuring the environment
   5. Getting and updating the source code
   6. Configuring KVIrc
   7. Interactive CMake KVIrc configuration
   8. Compiling KVIrc
   9. Compiling on macOS
  10. Compiling on Windows
  11. Creating a KVIrc package

-------------------------------------------------------------------------------
  1. Introduction
-------------------------------------------------------------------------------

  This document contains the procedures to Install required development libraries
  clone KVIrc's source code, configure your environment, configure and
  compile and install KVIrc.

  If you have found this document in a binary distribution then
  KVIrc has been probably already installed by your distros package
  manager and maybe something is not working as expected. In this case
  this document and the accompanying F.A.Q. can help you determining
  the issue.

  If you have found this document in a source distribution or you
  have downloaded it by using Git or downloaded tarball then well...
  this is a standard INSTALL file :)

  Note: It isn't practical to cover all Linux distributions in this doc.

  This doc provides fully working instructions for Ubuntu or variants.
  Compiling KVIrc in your preferred Linux distributions is possible,
  provided the minimum required dependencies and their versions are met.

  From here on in this doc refers to "Ubuntu or variants", where variants
  are distributions classed as Ubuntu derivatives.

  Note on lines prefixed with "$" or "0." or "1.":

  "$"  Signifies the command prompt on your shell.
  "0." Prefixes are default command variation.
  "1." Prefixes are a possible alternative variation of the command.

  Note: If anyone could find the time to test KVIrc with ICC please let us know!

-------------------------------------------------------------------------------
  2. Hacker Installation - Advanced or power users:
-------------------------------------------------------------------------------

  First of all, if you often compile applications from source on Linux
  and you know how to solve dependency problems then well, KVIrc is not
  very different. It uses a build system based on CMake and follows its
  standard procedures.

  If you feel brave try:

      $ cd <kvirc_source_directory>  // (usually KVIrc)
      $ mkdir build
      $ cd build
      $ ccmake ..
      $ make
      $ sudo make install

  If something goes wrong with the above procedure then you should read
  the step-by-step instructions below.

-------------------------------------------------------------------------------
  3. Dependencies and requirements:
-------------------------------------------------------------------------------

  KVIrc compilation process depends on a set of tools and development libraries.
  Some of them are strictly required (the process will fail without them)
  and some are optional. The ones marked as "preferred" are optional but
  without them KVIrc may lack some fundamental features.

  Where OpenSSL is concerned, you should check it is legal to use cryptographic
  libraries in your Country.

  In order to compile KVIrc you will need:

    - C++ compiler ............ (Required)
    - CMake ................... (Required)  >= 3.1.0
    - CMake GUI ............... (Optional)
    - Doxygen ................. (Optional)
    - pkg-config .............. (Required)
    - git-core ................ (Preferred)
    - Pthreads ................ (Required)
    - ZLib .................... (Required)  >= 1.2.8
    - X Rendering Extension ... (Required)
    - X11 client-side library . (Required)
    - Qt GUI Toolkit .......... (Required)  >= 4.8
    - KDE ..................... (Optional)
    - Enchant ................. (Optional)
    - Phonon framework ........ (Preferred)
    - Qt Multimedia ........... (Optional)
    - OpenSSL ................. (Preferred)
    - GSM speech compressor ... (Optional)
    - GNU gettext ............. (Optional)
    - Python .................. (Optional)
    - Perl .................... (Preferred) >= 5.004 (5.10 recommended)

  Note: For further information on these libraries read 4. Configuring the environment

  For CMake >= 3.1.0 run:

  Note: PPA for CMake for Ubuntu and variants <= 14.04 LTS:

      $ sudo add-apt-repository ppa:kvirc/kvirc -y
      $ sudo apt-get update

  For Ubuntu or variant distributions the complete list of dependencies
  and installation command is:

      $ sudo apt-get install build-essential cmake cmake-curses-gui doxygen git-core \
        libenchant-dev libgettextpo-dev libgsm1-dev libperl-dev libpthread-stubs0-dev \
        libssl-dev libx11-dev libxrender-dev pkg-config python-dev zlib1g-dev

  Note: KVIrc is complied by default against Qt5.x those libraries are:

      $ sudo apt-get install libqt5webkit5-dev libqt5svg5-dev \
        libqt5x11extras5-dev qtbase5-dev

  Note: An audio support backend is required for audio the choices are as follows:

  Compiling KVIrc with qtmultimedia5 audio support:

      $ sudo apt-get install qtmultimedia5-dev

  Compiling KVIrc with phonon audio support:

      $ sudo apt-get install libphonon4qt5-dev libphonon4qt5experimental-dev

  Note: When using Phonon, a working phonon-backend should be installed,
        else you may not get any audio coming out your speakers at runtime.

-------------------------------------------------------------------------------
  4. Configuring the environment:
-------------------------------------------------------------------------------

  If your distribution is sane, installing the development packages should set up
  your environment variables correctly. You will know that something is wrong when
  you run CMake, the configuration output will complain if paths are not found.

  If the CMake configuration terminates successfully you can skip directly to step 5.

  However when this is not the case you may need to export the path variables manually.
  e.g. $QTDIR.

  Note: Where x is the KVIrc's currently supported Qt version.
        Current only Qt supported version is 5

  For x86 e.g.

      $ export QTDIR=/usr/lib/qtx

  For x86_64 e.g.

      $ export QTDIR=/usr/lib/x86_64-linux-gnu/qtx

  Note: If you have multiple distinct versions of the same Qtx.x installed
  and want to use a specific version, exporting QTDIR won't suffice, since the
  CMake module searching for Qtx.x uses qmake itself to determine the Qtx library dir.

  You can set your $PATH variable to have CMake using your specified Qtx.x version:

      $ PATH=/opt/qtx.x/bin/:$PATH cmake ..

  Note: See step [5. Configuring KVIrc] for supported CMake configuration flags.
  The trailing dots are required when you build out-of-source
  or CMake will likely fail.

  ## KDE (Optional)

  If you want to compile the KDE integration support, you obviously need KDE.
  The kdelibs package should suffice.


  ## Pthread implementation (Required)

  This is usually included in your distribution and is probably already
  installed. In Ubuntu or variants the library is libpthread-stubs0-dev.
  The library is called libpthread.so. You can search for it using the "find"
  or, at your option, "locate" command.

  0.  $ find / -name libpthread*

  1.  $ locate -i "libpthread*"

  ## GNU gettext (Optional)

  If you use KVIrc in a language other than English, then you need
  the GNU gettext package. In particular KVIrc uses msgfmt.

  This is usually included in your distribution and is probably already installed.
  In Ubuntu or variants this library is libgettextpo-dev.
  If your distro is not Ubuntu or variant you can check it by running:

      $ msgfmt --version

  KVIrc will not complain if the command above is missing. It will just skip
  the creation of the translation files. See the CMake configuration output.


  ## Perl (Optional)

  If you want to generate the on-line documentation you'll also need Perl.

  Note: The way external software can embed Perl has changed between Perl version
  5.8 and 5.10. KVIrc should play nice with Perl as of version 5.004 and
  higher, but 5.10 is strongly recommended, since future updates can break
  backwards compatibility.

  If you want Perl scripting support to be compiled, you need a working Perl
  installation. Your libperl.so MUST be compiled with the multiplicity option.
  You can check it with:

      $ perl -V


  ## OpenSSL (Preferred)

  If you want the secure socket layer (SSL) support to be compiled, you need
  the OpenSSL development library, in Ubuntu or variants its libssl-dev


  ## GSM (Optional)

  If you want DCC VOICE to support the gsm codec,
  you need a recent copy of libgsm. This is not strictly required
  at compile time since KVIrc will look for the library at run-time
  and only if the DCC VOICE with the gsm codec is requested.
  You can check for libgsm using the 'find' or 'locate' command.

  0.  $ find / -name libgsm*

  1.  $ locate -i "libgsm*"

  This library is included in most distributions.
  Some distros ship only the static version of the library "libgsm.a".
  If the previous find or locate command returned something similar
  to "/usr/lib/libgsm.a", you might create the shared library manually
  by running:

      $ cd /usr/lib
      $ ld --whole-archive -shared -o libgsm.so.1 libgsm.a
      $ ln -s libgsm.so.1 libgsm.so
      $ ldconfig

  Notes:
  1. This won't work if the library was compiled without -fPIE.
  2. Files in /usr/lib should really be managed by package manager of the distro.
     Whenever package containing libgsm.a upgrades, the manually created libgsm.so stays old.
  3. The distribution can provide a better way to install libgsm.so.
     e.g. in Gentoo many packages have static-libs USE-flag which tells the package manager
     to install not only .so files, but also .a (which is kinda the reverse, but the point still stands)

  ## Phonon framework - (Preferred)

  If you want the /snd plugin to play various audio formats,
  you either need the phonon framework, a running ESounD daemon,
  or a reasonably recent audiofile library.
  Without these KVIrc will be only able to play *.au files.

  - You will need the dynamic linker interface library libdl.so.

  This is usually installed on your system, so don't care until configure
  complains about it. Some system have the interface builtin in libc. The
  configure script can detect this.

-------------------------------------------------------------------------------
  5. Getting and updating the source code:
-------------------------------------------------------------------------------

  The KVIrc development code is located at https://github.com/kvirc/KVIrc

  There are several ways to get KVIrc's source code, if you compile often,
  the best way is to clone the repository as this allows for the most flexibility.

      $ mkdir /home/setup && cd /home/setup
      $ git clone https://github.com/kvirc/KVIrc.git

  Keeping the git clone up-to-date  is simple.

      $ git pull --rebase origin master

  Cleaning the git directory of any files or directories generated my CMake or Make.
  This is recommended previous to configuring or compiling any updated git clones,
  it will minimize the chance of errors during the reconfiguration / compilation,
  If you experience any compile issues make sure this command is executed.

      $ git clean -xfd

  Alternatively if you prefer. you can download a tarball of the most recent
  sources.

      $ mkdir /home/setup && cd /home/setup
      $ wget https://github.com/kvirc/KVIrc/archive/master.tar.gz -O kvirc.git.tar.gz
      $ tar -zxvf kvirc.git.tar.gz

-------------------------------------------------------------------------------
  6. Configuring KVIrc
-------------------------------------------------------------------------------

  Since KVIrc 4.2 uses CMake as build system, we have to use it to create
  the Makefile's rules for make program.

  To do it, we encourage the "out-of-source" building: build all files
  without dirtying the sources directory.

      $ cd /home/setup && cd KVIrc
      $ mkdir build

  In this way you have just created an out-of-source environment which is
  clean at the beginning and can be changed afterwards, as well as a clean
  source directory.

      $ cd build
      $ cmake [your options] ..

  Note: The two trailing dots are required when you build out-of-source.

  The CMake rules support some flags. If you don't specify them, CMake will
  try to guess a good environment for you.

  To use these flags, you have to pass a bool value or a string.
  e.g. To install KVIrc in /usr instead of /usr/local and to disable
  Phonon support, the command looks like:

      $ cmake -DCMAKE_INSTALL_PREFIX=/usr -DWANT_PHONON=0 ..

  When using the configuration flags below.

  -DWANT_DEBUG=  (default: OFF)
    When enabled, compiles the executable with debug symbols.
    Useful for reporting bugs.
    Note: An alternative method of defining build type is using:
  -DCMAKE_BUILD_TYPE=

    Supported options are:

    None Debug Release RelWithDebInfo MinSizeRel

  -DWANT_STRIP=  (default: OFF)
    Available only if debug is disabled, this flag disables objects
    stripping before installation.
    (Object stripping discards symbols from object files, lowering their
    size on disk, at the expense of more complicated or rather impossible
    debugging.)

  -DWANT_VERBOSE=  (default: OFF)
    Generate verbose output when compiling.
    Note: this will be deactivated when using a job setting higher than 1
    with gmake. i.e., make -j2 will *not* show verbose compilation output.

  -DCMAKE_INSTALL_PREFIX=PATH 0 (default: a system-dependent directory)
    This will install all stuff under PATH directory.

  -DLIB_SUFFIX=SUFFIX=  (default: empty)
    This will install libkvilib and KVIrc modules to
    ${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}
    directory. It defaults to an empty suffix.
    Mainly used for x86_64 architectures.

  -DMANDIR=DIRECTORY=  (default: $CMAKE_INSTALL_PREFIX/share/man)
    This will install man pages to DIRECTORY.

  -DWANT_COEXISTENCE=  (default: OFF)
    If enabled, appends version information to KVIrc and libkvilib, so that
    different KVIrc versions can co-exist on the same system.

  -DWANT_ENV_FLAGS=  (default: OFF)
    When enabled, KVIrc install rules won't try to figure out and set
    CMAKE_C(XX)_FLAGS. Instead, it will let CMake use the ones taken
    from environment variables.
    Activating this flag will override the value of -DWANT_DEBUG.

  -DCMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT=  (default: OFF, not cached)
    This will re-initialize the installation path to a good default.
    Following compilations should use the correct path value cached by CMake.
    This flag is useful to solve macOS install problems.

  -DWANT_UNIVERSAL_BINARY=  (default: OFF)
    Enables or disables the compilation of universal binaries
    for the macOS platform.

  -DWANT_PHONON=  (default: ON)
    Enables or disables Phonon audio backend support.

  -DWANT_OSS=  (default: ON)
    Enables or disables OpenSoundSystem audio backend support.
    If disabled, audiofile support will be disabled as well.

  -DWANT_AUDIOFILE=  (default: ON)
    Enables or disables audiofile audio backend support.

  -DWANT_ESD=  (default: ON)
    Enables or disables ESounD audio backend support.

  -DWANT_QTDBUS=  (default: ON)
    Enables or disables Qt D-Bus support.

  -DWANT_QTWEBKIT=  (default: ON)
    Enables or disables Qt WebKit support.

  -DWANT_KDE=  (default: ON)
    Enables or disables KDE support. The KDE version used
    depends on the Qt version used. Qt4 implies KDE4, Qt5 implies KDE5.

  -DWANT_OPENSSL=  (default: ON)
    Enables or disables the cryptographic functions support using OpenSSL.

  -DWANT_CRYPT=  (default: ON)
    Enables or disables the cryptographic engines and the whole cryptography/text
    transformation support. Produces a slightly smaller executable.
    You will lack features, though.

  -DWANT_IPV6=  (default: ON)
    Enables or disables the IPv6 support.
    Even if you have a plain IPv4-only connection, you might want to
    keep the IPv6 support. This way you will be able to resolve
    IPv6 hostnames.

  -DWANT_TRANSPARENCY=  (default: ON)
    This option enables or disables pseudo and real transparency support.
    The pseudo-transparency support makes the KVIrc windows
    look like semi-transparent (this is NOT real transparency, it is
    just a neat-looking hack). Transparency uses compositing and needs
    proper hardware support to work.
    If KDE support is enabled, KVIrc will have an option that
    makes all windows use a faded KDE desktop background image
    as background. Without KDE support you will be able to choose
    a fake background image and use it as background. (You can still
    choose your desktop wallpaper, this will (more-or-less) work with
    all window managers).
    It is cool-looking but usually eats some memory and makes the
    executable slightly bigger, when enabled. Especially when moving
    objects around, CPU consumption may get high as well.
    You can thus disable transparency here.

  -DWANT_GTKSTYLE=  (default: OFF)
    QGtkStyle is a Qt backend that uses native GTK widgets.
    By default we disable QGtkStyle since it interferes with KVIrc's internal
    theme engine and there maybe some unwanted styling that you may consider broken.
    Some users want to use it anyway. Please don't report any theme-related bug
    if you enabled this option: we already know it's limitations and issues.
    For further information / discussion see:
    https://github.com/kvirc/KVIrc/issues/2117

  -DWANT_PERL=  (default: ON)
    Enables or disables Perl support.
    You will not be able to use Perl scripts inside of KVIrc.
    You still can execute Perl scripts outside of KVIrc, i.e. with
    the exec() command.
    Note: Perl support will be checked anyway, and used to generate
    the documentation if present.

  -DWANT_PYTHON=  (default: ON)
    Enables or disables python support.
    You will not be able to use Python scripts inside of KVIrc.

  -DWANT_IPC=  (default: ON)
    Enables or disables support for inter-process communication.
    You will not be able to send remote commands to running
    KVIrc sessions. This basically means that every time you run
    the KVIrc executable, a new session will be started.
    If you don't use this switch, a new session will be started
    only if no session is running on the same display or
    "new session" has been forced by a command-line switch.
    If a session is already running, the command-line will be
    passed to that session via IPC (X-event-based communication).
    This option saves the KVIrc executable some KByte in size,
    so if you're really, really short in memory, you might use it,
    otherwise, IPC is a nice feature.

  -DWANT_GETTEXT=  (default: ON)
    Enables or disables the use of GetText to generate translation files.

  -DWANT_DOXYGEN=  (default: ON)
     Enables or disables developers docs generation through Doxygen.

  -DWANT_GSM=  (default: ON)
    Enables or disables the usage of the GSM library. This will
    disable the DCC VOICE GSM codec but might help when the
    compilation stops complaining of something related to GSM. :)

  -DWANT_IGNORE_SIGALARM=  (default: OFF)
    Under Solaris, both usleep() and threads implementation are based on
    SIGALARM. KVIrc uses both, and this could lead to some spontaneous
    application quits. This option enables a workaround for this problem.

  -DWANT_DCC_VOICE=  (default: ON)
    Enables or disables the DCC VOICE sound support. This might help
    if you have problems in compilation of src/modules/dcc/voice.cpp.
    It will disable the sound support (and thus render DCC VOICE unusable).

  -DWANT_DCC_VIDEO=  (default: OFF)
    Enables or disables EXPERIMENTAL DCC VIDEO support.

  -DWANT_OGG_THEORA=  (default: OFF)
    Enables or disables EXPERIMENTAL Ogg/Theora Support for dcc video.

  -DWANT_DCC_CANVAS=  (default: OFF)
    Enables or disables OBSOLETE DCC CANVAS support.

  -DWANT_SPELLCHECKER=  (default: ON)
    Compile Spell-Checker Support.
    Note: If libenchant development package is installed,
    this option is automatically enabled during configuration.

  -DWANT_MEMORY_PROFILE=  (default: OFF)
    Enables or disables memory allocation profiling.
    Don't set it, unless you are a developer and know what you are doing.
    It will have high impact on executable size and most notably speed.
    Please do not use this.

  -DWANT_MEMORY_CHECKS=  (default: OFF)
    Enables or disables malloc() memory checks. This will print a nice
    message if your system goes out of memory.
    It can't save you from buying new RAM, but at least you will know that
    your system went out of memory and it is not a proper KVIrc fault.
    Most systems do actually already notice you when you are out of RAM
    (i.e. Linux and the OOM killer.)
    Most probably you will not need to enable this flag.

  -DMANUAL_REVISION=  (default: empty)
    Manually set a revision number if subversion is not found on your
    system.
    This is useful mostly on windows.
    Please do not specify useless information here, as it will make
    debugging harder and you won't profit from it.

  -DWANT_PIZZA=  (default: OFF)
    Add some pizza for dinner. :)

  -DWANT_BEER=  (default: OFF)
    Add some beers to chat. :)

-------------------------------------------------------------------------------
   7. Interactive CMake KVIrc configuration
-------------------------------------------------------------------------------

  The CMake build system provide also an interactive mode to configure
  the environment before compiling.
  Again, we encourage the "out-of-source" building: build all files
  without dirtying the sources directory.

      $ mkdir build
      $ cd build
      $ ccmake ..

  Now you're in interactive mode, just follow the instructions on screen
  to configure your compilation environment.

-------------------------------------------------------------------------------
  8. Compiling
-------------------------------------------------------------------------------

  This step is easy:
  Cross your fingers and run:

  0.  $ make

  If you have a multiprocessor or multicore machine then you can use -jN
  to speed up the compilation.

  1.  $ make -j4

  If your make is not a GNU make (this happens on FreeBSD for example) you
  should use "gmake" instead.
  The compilation process will take from 2-3 minutes to several hours
  depending on the machine capabilities and load.
  If you have a slow old CPU but have a couple of computers in a LAN you might
  consider using distcc to distribute the compilation.

  Once the compilation has finished successfully, run:

      $ sudo make install

  Same as above: use "gmake install" if your make is not GNU make.

  This will install the executable in /usr/local/bin (if you haven't
  specified a different -DCMAKE_INSTALL_PREFIX option in the CMake rules),
  the libraries in /usr/local/lib (if you don't have specified a different
  -DLIB_SUFFIX option in the CMake rules) and the shared data in
  /usr/local/share/kvirc.

  Make sure that /usr/local/lib is in your /etc/ld.so.conf. If it isn't,
  put it in there and run:

      $ sudo ldconfig

  If you have decided to use the KDE support the installation might have
  placed all these files in your $KDEDIR tree instead of /usr/local.
  In this case you should be OK since KDE requires its library dir to be
  in /etc/ld.so.conf.

-------------------------------------------------------------------------------
  9. Compiling on macOS
-------------------------------------------------------------------------------

  There is a detailed compilation and installation HOW-TO for macOS systems
  located in the doc directory. It's named INSTALL-MacOS.txt.

-------------------------------------------------------------------------------
  10. Compiling on Windows
-------------------------------------------------------------------------------

  There is a detailed compilation and installation HOW-TO for Win32 and Win64 systems
  located in the doc directory. They're named INSTALL-Win32.txt and INSTALL-Win64.txt.

-------------------------------------------------------------------------------
  11. Creating a KVIrc package
-------------------------------------------------------------------------------

  CMake supports DESTDIR argument.
  So, if you want to make a package for your distribution, you simply have to pass
  it at "make install" stage: your install files will go to the chosen path.

      $ make install DESTDIR=/tmp/kvirc-4.3

  After this step, just follow your distribution's rules to make a good
  package for the distro you're running.

  Alternatively, you can try the experimental CPack support included in
  CMakelist.txt to build a package. In this case, please refer to the CPack
  documentation.
