Elvio Basello (HelLViS69)                                       Mon Nov 17 2008
###############################################################################
General notes for the installation of the 4.0.4 release of KVIrc
###############################################################################

    This document contains the procedures to compile and install
    the version 4.0.4 of KVIrc.

###############################################################################
# 0. Table of contents
###############################################################################

    1. Introduction
    2. Minimal requirements
    3. Configuring the environment
    4. Interactive mode
    5. Compiling
    6. Compiling on MacOS X
    7. Compiling on Win32
    8. Hacker-level installation
    9. Creating a KVIrc package

###############################################################################
# 1. Introduction
###############################################################################

    This document contains the procedures to compile and install
    the version 4.0.4 of KVIrc.

    If you have found this document in a binary distribution then
    KVIrc has been probably already installed by your favorite package
    manager and maybe something is not working as expected. In this case
    this document and the accompanying FAQ can help you in guessing
    what's wrong.

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

###############################################################################
# 2. Minimal requirements:
###############################################################################

    In order to compile KVIrc 4.0.4 you need at least these software:
    - Qt GUI Toolkit 4.5 or newer - http://www.qtsoftware.com
    - CMake 2.6 or newer - http://www.cmake.org
    - C++ compiler, such as g++ - http://gcc.gnu.org (btw: we'd be glad if any-
        one could find the time to test KVIrc with ICC!)
    - Pthread implementation
    - ZLib - http://www.zlib.org
    - KDE (Optional) - http://www.kde.org
    - GNU gettext (Optional) - http://www.gnu.org/software/gettext
    - Perl (Optional) - http://www.perl.com
    - OpenSSL (Optional) - http://www.openssl.org

    #
    # Qt GUI Toolkit
    #

    If your distro has KDE installed, then Qt is already installed. If not,
    simply install qt4 from your distro's repositories.

    So before running CMake make sure that the environment variable $QTDIR
    points to the right location. This will help in finding the correct version
    of Qt.

    You might eventually set it with the command:

    # export QTDIR="your Qt dir"

    On my system, Qt is installed in /usr/lib/qt4, thus I actually execute:

    # export QTDIR=/usr/lib/qt4

    To check if you are using the right version of Qt, simply run:

    # qmake -v

    On my system the output is:

    QMake version 2.01a
    Using Qt version 4.5.3 in /usr/lib64/qt/lib

    If you have multiple versions of Qt4 installed in your system and want to 
    use a specific version, exporting QTDIR won't suffice. Since the CMake 
    module searching for Qt4 uses qmake itself to determine the Qt4 library dir,
    you can set your $PATH variable to have CMake using 
    your preferred qmake version:

    # PATH=/opt/qt4.5/bin/:$PATH cmake ..

    Please note that compiling with KDE4 support enabled will force KVIrc to 
    link against the Qt4 version that KDE4 is using. This may lead to problems 
    in linking. Disabling KDE4 support is the only known solution at the moment.
    Note also that in this case you'll need to override the Qt libraries used 
    when running KVIrc:

    # LD_LIBRARY_PATH=/opt/qt4.5/lib/ kvirc4

    #
    # CMake
    #

    This is usually included in nowadays distros.
    To check which CMake you have, simply run:

    # cmake --version

    On my system the ouput is:

    # cmake version 2.6-patch 4


    #
    # C++ compiler
    #

    You need a decent C++ compiler. Usually under linux it is GCC from GNU 
    tools.
    It is preferred to use GCC 4.x, but GCC 3.4.6 works as well. Older version
    *might* work.
    ICC is *neither* officially supported *nor* tested. Reports are welcome, 
    though.
    To check your GCC version, just run:

    # gcc -v

    The output on my system is:

    Reading specs from /usr/lib64/gcc/x86_64-slackware-linux/4.3.3/specs
    Target: x86_64-slackware-linux
    Configured with: ../gcc-4.3.3/configure --prefix=/usr --libdir=/usr/lib64 
--enable-shared --enable-bootstrap 
--enable-languages=ada,c,c++,fortran,java,objc --enable-threads=posix 
--enable-checking=release --with-system-zlib --disable-libunwind-exceptions 
--enable-__cxa_atexit --enable-libssp --with-gnu-ld --verbose 
--disable-multilib --target=x86_64-slackware-linux 
--build=x86_64-slackware-linux --host=x86_64-slackware-linux
    Thread model: posix
    gcc version 4.3.3 (GCC)


    #
    # Pthread implementation
    #

    This is usually included in your distribution and is probably already
    installed. The library is called libpthread.so.
    You can look for it using the "find" or, at your option, "locate" command:

    # find / -name libpthread.so
    ## or ##
    # locate libpthread.so

    On my system the output is:

    # /usr/lib/libpthread.so

    If you don't have it (CMake will tell you), you can download it from your
    favorite GNU mirror.
    The configure script will also fail if the library is hidden somewhere in
    your system (eg. not in /lib, /usr/lib or /usr/local/lib). In this case,
    you should probably move it.

    #
    # KDE (Optional)
    #

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

    So before running CMake make sure that the environment variable $KDEDIR
    points to the right location.

    You might eventually set it with the command:

    # export KDEDIR="your kde dir"

    In my case KDE is installed in /usr so I use

    # export KDEDIR=/usr


    #
    # GNU gettext (Optional)
    #

    If you want the translations to non-english languages to work, then you need
    the GNU gettext package. In particular KVIrc uses the msgfmt program.

    This is usually included in your distribution and is probably already
    installed. 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.
    If the command above fails, then you need to install the gettext package if
    you want any other language than English.


    #
    # Perl (Optional)
    #

    If you want to generate the on-line documentation you'll also need perl. Any
    version will do (I guess).

    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
    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.


    #
    # OpenSSL (Optional)
    #

    If you want the secure socket layer (SSL) support to be compiled, you need 
    the OpenSSL library and headers. (libssl.so and openssl/ssl.h)

    - (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.

    # find / -name libgsm*
    ## or ##
    # locate -i "libgsm*"

    The output should be something like

    # /usr/lib/libgsm.so

    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

    If you don't have it installed at all, you might want to have a look
    on your distribution CD, or download it from the web.


    - (Optional) If you want the /snd plugin to play various audio formats,
      you either need a running artsd (nowadays replaced by 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 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.


    - (Optional) If you want to build with no (or at least less) embedded copies
      of code or reimplementations of code which can be found in widely tested
      libraries, you need to install the following libraries (for building you 
      also need the corresponding headers):
        - Crypto++ 5.6 <http://cryptopp.com/>

###############################################################################
# 3. Configuring the environment
###############################################################################

    Since KVIrc 4.0 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.

    # mkdir release
    # cd release
    # cmake [your options] ..

    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.
    Note that the final dots are required or CMake will NOT create the right
    environment.

    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.
    For example, to install KVIrc in /usr instead of /usr/local and to disable
    Phonon support, the command looks like be:

    # cmake -DCMAKE_INSTALL_PREFIX=/usr --DWITHOUT_PHONON=1 ..

    Here's a list with explainations:

    -DDEBUG
        Compiles the executable with debug symbols.
        Useful for reporting bugs.

    -DWITH_DEBUG
        Alias of -DDEBUG flag.

    -DWITHOUT_STRIP
        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.)

    -DVERBOSE
        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 any verbose compilation 
        output.)

    -DCMAKE_INSTALL_PREFIX=PATH
        This will install all stuff under PATH directory.

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

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

    -DCOEXISTENCE
        Append version information to KVIrc and libkvilib, so that different
        KVIrc versions can co-exist on the same system.

    -DUSE_ENV_FLAGS
        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 -DDEBUG.
        (Default: Off)

    -DCMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
        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 X install problems.

    -DCOMPILE_MACOSX_UNIVERSAL_BINARY
        Compile universal binaries for the MacOS X platform.

    -DUSE_PCH
        Use pre-compiled headers.

    -DWITHOUT_PHONON
        Disables Phonon audio backend support.

    -DWITHOUT_OSS
        Disables OpenSoundSystem audio backend support. This automatically
        disables Audiofile support as well.

    -DWITHOUT_AUDIOFILE
        Disables Audiofile audio backend support.

    -DWITHOUT_ESD
        Disables ESounD audio backend support.

    -DWITHOUT_QTDBUS
        Disables Qt-DBus support.

    -DWITHOUT_QTWEBKIT
        Disables Qt-WebKit support.

    -DWITHOUT_KDE4
        Disables KDE4 support.

    -DWITHOUT_SSL
        Disables the secure socket layer support. The SSL support is
        automatically enabled if OpenSSL is detected by CMake.

    -DWITHOUT_CRYPT
        Disables the cryptographic engines and the whole cryptography/text
        transformation support. Produces a slightly smaller executable.
        You will lack features, though.

    -DWITHOUT_IPV6
        The IPv6 support is compiled by default on the platforms that
        support it. This option does disable it, no matter what CMake
        found out earlier.
        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.

    -DWITHOUT_TRANSPARENCY
        This option disables pseudo-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).
        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 pseudo-transparency here.

    -DWITHOUT_PERL
        Forcibly 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 that perl support will be checked anyway, and used to generate
        the documentation if present.

    -DWITHOUT_PYTHON
        Forcibly disables python support.
        You will not be able to use Python scripts inside of KVIrc.

    -DWITHOUT_IPC
        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 commandline switch.
        If a session is already running, the commandline 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.

    -DWITHOUT_GETTEXT
        Disables the use of GetText to generate translation files.

    -DWITHOUT_DOXYGEN
        Disables docs generation through Doxygen.

    -DWITHOUT_SYSTEM_MEMMOVE
        This will disable the use of the system memmove() memcpy() and
        memset() functions and enable the bundled implementations. Use
        it if you have undefined references to these functions while
        compiling.

    -DWITHOUT_GSM
        Explicitly disable 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. :)

    -DWITH_ix86_ASM
        KVIrc contains some ix86 assembly routines that *could* performs
        some things faster (this is not always true, depends on the compiler).
        You might want to try it if your KVIrc seems to be really slow...
        Note: don't enable this on x86_64 or other platforms!

    -DWITH_IGNORE_SIGALARM
        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.

    -DWITHOUT_DCC_VOICE
        Explicitly disable 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).

    -DWITH_DCC_VIDEO
        Enables EXPERIMENTAL DCC VIDEO support. 

    -DWITH_DCC_CANVAS
        Enables OBSOLETE DCC CANVAS support.

    -DWITH_MEMORY_PROFILE
        Enables 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 noteably speed.
        Please do not use this.

    -DWITH_MEMORY_CHECKS
        Enables 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
        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 do not profit from it.

    -DWITH_PIZZA
        Add some pizza for dinner. :)

    -DWITH_BEER
        Add some beers to chat. :)

    -DWITH_NO_EMBEDDED_CODE
        Use functions from widely tested libraries instead of embedded code or
        reimplementations of code/functions available from such libraries.
        For required dependencies see section two of this document.

###############################################################################
# 4. Interactive mode
###############################################################################

    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 dirting the sources directory.

    # mkdir release
    # cd release
    # ccmake ..

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

###############################################################################
# 5. Compiling
###############################################################################

    This step is easy:
    Cross your fingers and run:

    # make

    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 6-7 minutes to several hours
    depending on the machine capabilities and load.
    If you have a slow cpu but have a couple of computers in a lan you might
    consider using distcc to distribute the compilation.

    Once the compilation has been succesfull, run:

    # 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 don't have
    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:

    # ldconfig

    with super-user privileges.
    
    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.

###############################################################################
# 6. Compiling on MacOS X
###############################################################################

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

###############################################################################
# 7. Compiling on Win32
###############################################################################

    There is a detailed compilation and installation HOWTO for Win32 systems
    located in the doc directory. It's named INSTALL-Win32.txt.

###############################################################################
# 8. Hacker installation:
###############################################################################

    # mkdir release
    # cd release
    # cmake ..
    # make install

###############################################################################
# 9. Creating a KVIrc package
###############################################################################

    CMake supports DESTDIR argument.
    So, if you want to make a package for your distro, 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.0

    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.
