Elvio Basello (HelLViS69)                                       Tue Jun 03 2008
###############################################################################
General notes for the installation of the 4.0 release of KVIrc
###############################################################################

    This document contains the procedures to compile and install
    the version 4.0 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



/*
    old autotools doc. remove when cmake stuff is complete
    i. Human (detailed) installation instructions
    ii. How to compile KVIrc with Qt-embedded
    iii. A note about Windows 95/98/ME
*/

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

    This document contains the procedures to compile and install
    the version 4.0 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 the svn then well...
    this is a standard INSTALL file :)

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

    In order to compile KVIrc 4.0 you need at least these softwares:
    - Qt GUI Toolkit 4.3.4 - http://www.trolltech.com
    - CMake 2.4.6 - http://www.cmake.org
    - C++ compiler, such as g++ - http://gcc.gnu.org
    - Pthread implementation
    - 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 so I actually execute

    # export QTDIR=/usr/lib/qt4

    To check you have the right version of Qt, simply run:

    # qmake -v

    On my system the output is:

    # QMake version 2.01a
    # Using Qt version 4.3.4 in /usr/lib/qt4/lib


    #
    # CMake
    #

    This is usually included in the last distros.
    To check which cmake you have, simply run:

    # cmake --version

    On my system the ouput is:

    # cmake version 2.4-patch 8


    #
    # 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.
    To check your gcc version, just run:

    # gcc -v

    The output on my system is:

    # Reading specs from /usr/lib/gcc/i486-slackware-linux/4.2.3/specs
    # Target: i486-slackware-linux
    # Configured with: ../gcc-4.2.3/configure --prefix=/usr --enable-shared
      --enable-languages=ada,c,c++,fortran,java,objc --enable-threads=posix
      --enable-__cxa_atexit --disable-checking --with-gnu-ld --verbose
      --with-arch=i486 --target=i486-slackware-linux --host=i486-slackware-linux
    # Thread model: posix
    # gcc version 4.2.3


    #
    # 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 with the "find" command:

    # find / -name 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.
/*
    On Solaris you can use the native libthread.so library instead but you will
    have to pass the specific option to configure (see below).
    FreeBSD has a native implementation of pthreads in libc_r and the gcc
    compiler has a special -pthread flag to link to it.
    If you're on FreeBSD, use the --with-freebsd-pthread configure option and
    make sure that you don't have other pthread wrappers installed (that might
    collide with the native header files).

    The configure script will also fail if the library is hidden somewhere on
    your system (eg. not in /lib , /usr/lib or /usr/local/lib): you should
    probably move it.
*/

    #
    # KDE (Optional)
    #

    If you want to compile the KDE integration support you obviousy 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 language other than english.


    #
    # Perl (Optional)
    #

    If you want to generate the on-line documentation you 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


    #
    # 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' command.

    # find / -name libgsm*

    The output should be sometihg 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 returned only something similar to "/usr/lib/libgsm.a" , you might
    create manually the shared archive 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 have a look in 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, a running esd 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 it.
*/












###############################################################################
# 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 useful
    to have a clean working 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 make a good environment for you :)
    To use these flags, you have to pass a bool value or a string.
    For example, to install in /usr instead of /usr/local and enable Phonon
    support, the command would be:

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

    Here's a list with explainations:

    -DDEBUG
        Compiles the executable with debug symbols.
        Useful to report bugs.

    -DVERBOSE
        Generate verbose output when compiling.

    -DCMAKE_INSTALL_PREFIX=/path
        It will install all stuff under /path directory

    -DLIB_INSTALL_PREFIX=/path
        It will install libkvilib under /path directory. It defaults to
        ${CMAKE_INSTALL_PREFIX}/lib.

    -DCOEXISTENCE
        Append version information to kvirc and libkvilib, so that different
        kvirc versions can cohexist in the same system.

    -DCMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
        It 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 binary for MacOS X platform

    -DUSE_PCH
        Use pre-compiled headers

    -DWITHOUT_QTDBUS
        Disable Qt-DBus support.

    -DWITHOUT_QTPHONON
        Disable Qt-Phonon support.

    -DWITHOUT_QTWEBKIT
        Disable Qt-WebKit support.

    -DWITH_KDE4
        Compile KDE4 support. It will look for the KDE4 headers and libraries
        and if found it will enable the KDE4 support.

    -DWITH_AUDIOFILE
        Compile Audiofile support. It will look for Audiofile headers and libraries
        and if found it will enable the Audiofile 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

    -DWITHOUT_IPV6
        The IPv6 support is compiled by default on the platforms that
        support it: this option disables it.
        Even if you have a plain IPv4-only connection, you might want to
        keep the IPv6 support: you will be able to lookup 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: this is
        just a nice-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 in
        all the window managers).
        It is cool-looking but usually eats some memory when enabled.
        It also eats some executable size.
        So this option allows to disable the pseudo-transparency.

    -DWITHOUT_PERL
        Forcibly disable perl support.
        You will not able to make perl scripts

    -DWITHOUT_IPC
        Disables support for inter-process communication.
        You will be not 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 some KB of the KVIrc executable,
        so if you're 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 :)

    -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 make DCC VOICE not usable).




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

    -DWITH_MEMORY_PROFILE
        Debug stuff...enables memory allocation profiling (don't use it :)

    -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.
        Actually you probably have no reason in using it.

    -DWITH_PIZZA
        Add some pizza for dinner :)

    -DWITH_BEER
        Add some beers to chat :)



# To add here and in main CMakeLists.txt
COMPILE_ARTS_SUPPORT
COMPILE_DCC_CANVAS
COMPILE_ESD_SUPPORT
COMPILE_GET_INTERFACE_ADDRESS
COMPILE_IGNORE_SIGALARM
COMPILE_MMX_ASM
COMPILE_OSS_SUPPORT
COMPILE_SCRIPTTOOLBAR
COMPILE_WITH_NO_SOUND
COMPILE_XSS_SUPPORT

###############################################################################
# 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_INSTALL_PREFIX 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
    there, put it there and run

    # 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

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

    There is a detailed compilation and installation HOWTO for MacOSX 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 [your options] ..
    # 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 choosed 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.










###############################################################################
# i. Human (detailed) installation:
###############################################################################

        --enable-pipes
            Asks the compiler to use pipes instead of files for the
            compilation stage. The pipes will help in reducing disk usage and
            will probably shorten the compilation a bit. Use this option if
            your platform supports it.

        --with-qt-library-dir=<DIR>
            Look for the qt library in <DIR>.
            You might want to use this if the configure script has trouble
            in finding the qt library.
            You should have no problems if you use export QTDIR="<DIR>"
            before launching the configure script, but it might help you
            if you have a non standard Qt installation.

        --with-qt-include-dir=<DIR>
            Look for the qt headers in <DIR>.
            You might want to use this if the configure script has trouble
            in finding the qt headers. It may especially help if your headers
            are in a place different than $QTDIR/include (and thus you have
            a non standard installation)

        --with-qt-moc=<PATH>
            Use the qt meta-object compiler found in <PATH>
            The path is usually $QTDIR/bin/moc , and the
            configure script will find it if you have a standard
            Qt installation and $QTDIR points to the right directory.
            Thus should have no problems if you use export QTDIR="<DIR>"
            before launching the configure script, but it might help you
            if you have a non standard Qt installation.
            This will also help if you have the moc compiler renamed
            in some way: like "moc2" or sth...
            <PATH> in this case is a FULL path: directory/program_name!

        --without-kde-support
            The configure script will look for the KDE headers and libraries
            and if found it will enable the KDE support. If you don't want
            the KDE support even if KDE is detected, just use this switch.

        --with-kde-services-dir=<DIR>
            Install the kde service protocol files in <DIR>
            If $KDEDIR points to the right place, you shouldn't need this.
            This is also non-critical for kvirc: if the configure script
            can't find this directory, you will only looose the support for
            irc:// urls in konqueror

        --enable-optimisation=<NUMBER>
            Enables the compiler optimisation flag -o<NUMBER>.
            Possible values are 0 , 1, 2 and 3 (but if you compiler supports
            more optimisation levels , you might use other numbers here).
            Increases compilation time but may produce a slightly faster
            executable. 

        --with-other-libs=<libraries>
            Explicitly link to the specified libraries.
            Example: --with-other-libs="-lmylib -lstrangesystemsupport"

        --with-other-ldirs=<paths>
            Explicitly add the specified library search paths
            Example: --with-other-ldirs="-L/home/pippo/lib/ -L/my/library/"

        --with-other-idirs
            Explicitly add the specified include search path
            Example: --with-other-idirs="-I/home/pippo/include/ -I/tmp/inc/"

        --enable-objprelink
            This is an experimental support for object prelinking that improves
            significantly the executable startup time. In order to use it you
            need to have the "objprelink" program in the PATH. The objprelink
            program is included in the distribution in the admin directory.
            In order to use it, you will need to:

            # cd admin
            # make objprelink
            # cp objprelink /somewhere_on_your_path

            All this AFTER running ./configure and BEFORE running make.

        --x-includes=DIR
            Specifies explicitly the path to the X header files.
            You might want to use this if the configure script
            has trouble in finding it.

        --x-libraries=DIR
            Specifies explicitly the path to the X libraries.
            You might want to use this if the configure script
            has trouble in finding it.

        --with-qt-name=<NAME>
            Use <NAME> instead of "qt" as the Qt library name.
            This is useful on systems where Qt has been installed with
            a name different than the default "qt".
            It happens often that to allow multiple copies of qt to work
            the newest have the version name appended to it.
            For example, on FreeBSD I have found "qt" being Qt1.* and
            "qt2" being Qt 2.*. Since you need Qt 2.* for kvirc to work,
            you will need to use --with-qt-name=qt2.
            If you use this option, you will probably also need to remap
            the moc compiler path/name with --with-qt-moc.

        --disable-qt-mt
            Disable checking for the multithreaded version of Qt.
            By default , KVIrc will try to link to the multithreaded version
            if found on the system.
            NOTE: if you enable the KDE support , KVIrc MUST be linked to the
                  qt library that KDE is linked to.

        --with-ignore-sigalarm
            This is a hack mainly for Solaris.
            Use this option if kvirc exits with no apparent reason and
            the system prints a message related to an "Alarm" :)

            This is a mail that suggests an explaination for the SIGALARM fault.
            If you experience the problem please drop me a mail at pragma at kvirc dot net
            and we'll try to look for a solution.

              From: "Andre Stechert" (astechert at email dot com)
              Date:  26/7/2005 09:36

              Hi,
              I noticed in your readme that you were having problems with sigalarm
              in your solaris port and you weren't sure why. I quickly scanned your
              source code and noticed that you use usleep and threads. That's the problem,
              if you haven't already figured it out. On Solaris, usleep is implemented with
              SIGALARM. So is threading. So if you the active thread changes while
              a usleep is in progress, bang, the process is dead.

        --with-solaris-lthread
            If you're on Solaris and don't have the pthread library (A wrapper
            I guess) you might try this option: it attempts to use the native
            Solaris threading support.

        --with-freebsd-pthread
            If you're on FreeBSD, you NEED this option. This enables the usage
            of the native FreeBSD pthread implementation found in libc_r.
            This requires you to use the native gcc compiler: it has a special
            -pthread flag that enables the linkage to libc_r instead
            of plain libc.

        --with-libresolv
            Link to libresolv. I guess that this is required for Solaris

        --with-libsocket
            Link to libsocket. I guess that this is required for Solaris

        --with-libnsl
            Link to libnsl. I guess that this is required for Solaris

        --with-libcompat
            Link to libcompat. This might be required for some systems...
            but I have no idea which ones. If you find it useful: mail me.

        --enable-fno-rtti
            Disables compiler runtime type information generation.
            This is probably needed only with qt-embedded.
            DON'T use it if you don't exactly know what it does.
            Actually this may even make KVIrc crash in some situations.
            For example the KDE sources use __dynamic_cast...

        --with-qt-embedded
            You need this to compile KVIrc with qt-embedded

        --enable-profiling
            Asks the compiler/linker to include profiling informations in the
            executable. This is useful only if you want to profile KVIrc by
            using the gprof program. Note that this will generate a bigger
            and slower executable.

###############################################################################
# ii. Compiling KVIrc on qt-embedded
###############################################################################

    Do you want KVIrc 3 on your hand computer ?
    On your Nokia 9999910 ?
    On your LINUX CONSOLE?

    Well, for the third it's really easy, just follow carefully those steps:

    1. Install qt-embedded libraries (including the development files).
       This can be as easy as: apt-get install libqt-emb-dev on Debian.

    2. cd to the KVIrc3 source directory

    3. run configure with the following parameters:

        # ./configure --with-qt-name=qte --with-fno-rtti --without-x-calls
               --without-ipc --without-splash-screen --without-transparency
               --with-qt-embedded --without-x-bell

       then run make and make install as usual

    4. Try to have a life for the next minutes while kvirc3 compiles

    5. You need your kernel with framebuffer support (it's under 'Console')
       so if your kernel don't have it reconfigure and recompile your kernel.

    6. switch to a console

    7. export QTDIR=[path] On Debian is '/usr'

    8. Read http://doc.trolltech.com/3.0/envvars.html and configure your
       environment vars until kvirc3-emb loads (it will give you an error
       indicating what went wrong else). Pay especial attention to
       QWS_MOUSE_PROTO, QWS_CARD_SLOT and QWS_DISPLAY

    9. Enjoy :)

###############################################################################
# iii. A note about Windows 95/98/ME
###############################################################################

    On Windows versions prior to 2000 the KVIrc binary may refuse to start
    because of an incompatible msvcrt.dll included in the distribution.

    If this happens to you then you may try the following tricks:

    - Find msvcrt.dll in your C:\Windows directory. It may also be
      in C:\Windows\System or C:\Windows\System32
      Copy it to the KVIrc installation folder overwriting the existing
      msvcrt.dll shipped with kvirc.

    - Find msvcrt.dll somewhere on the net. An url hint might be:
      http://www.dll-files.com/dllindex/dll-files.shtml?msvcrt
      Download the file and copy it to the KVIrc installation folder
      overwriting the existing msvcrt.dll shipped with kvirc.

    If none of the two steps work for you please write a mail to
    pragma at kvirc dot net reporting your exact Windows version and build
    and including the exact messages that the system reports when trying
    to run the KVIrc executable.

    Thanx to Dusan Hokuv for reporting this and suggesting the fixes.
