Szymon Stefanek                                                 Thu Nov 23 2000
###############################################################################
General notes for the installation of the 3.0.0 release of KVIrc 
###############################################################################

This file contains the procedures to compile and
install the version 3.0.0 of KVIrc.

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

    1. Guru-level installation
    2. Hacker-level installation
    3. Human (detailed) installation instructions
    4. How to compile KVIrc with Qt-embedded

###############################################################################
# 1. Guru installation:
###############################################################################

    # ./configure
    # make install

###############################################################################
# 2. Hacker installation:
###############################################################################

	You NEED automake 1.5

    If you're compiling the cvs version of KVirc run ./autogen.sh

    # export QTDIR="your qtlibrary path"

    eventually:

    # export KDEDIR="your kde library path"

    We're using GNU tools here.

    # ./configure --help
    # ./configure [your options]
    # make kvirc
    # make install

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

        If you're not a guru, or have problems with the installation
        read these instructions carefully.

    ###
    ### Step 0
    ###

        If (and ONLY IF) you're compiling the cvs version of kvirc
        you need to generate the configure script.
    
        # ./autogen.sh

        If it does not run correctly , check your auomake version.
        You need automake 1.5 older versions will NOT WORK with the current cvs.
        You can check the automake version with the command

        # automake --version

        If your automake version is lower than 1.5 upgrade it.
        You can find it at http://www.gnu.org/software/automake/ (source version)
        or on your favorite distribution site as auto-installing package.

            Automake installation tip: automake installs in /usr/local/ by default.
            If you have an older automake installation that resides in /usr/
            it's better to remove it: the files to be removed are
            /usr/bin/automake /usr/bin/aclocal /usr/share/automake /usr/share/aclocal
            If you feel unsure about removing it , rename it.
            Also make sure that /usr/local/bin is in your $PATH.

        If you have downloaded the sources as tar.gz (or tar.bz2) package
        or if you don't even know what cvs is, ignore this step and skip to
        the next one.

    ###
    ### Step 1 : Matching the requirements
    ###

        - You need the Qt library.
        You can download the latest version from ftp.trolltech.com.
        The main Qt www site is www.trolltech.com.
        Note for the GPL maniacs: Qt IS GPL.
        The minimum required version is 2.2.2
        Download and install it by following the rules
        explained in the documentation that comes with the library.
        
        - You need a decent pthread implementation.
        This is usually included in your distribution and is probably
        already installed. The library is 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 (the configure script 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.

        - You need the dynamic linker interface library libdl.so.
        This is usually installed on your system , so don't care until
        configure complatins about it. Some system have the interface
        builtin in libc. The configure script can detect it.

        - (Optional) If you want to compile the KDE integration support
        you obviousy need KDE. The kdelibs package should suffice.

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

        - (Optional) If you want to generate the on-line documentation
        you also need perl: any version will do (I guess).

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

    ###
    ### Step 2 : Running the configure script (mandatory)
    ###

        First of all you must run the configure script
        that will guess some info about your system and prepare the compilation.
        You may try to "simply run" it and check if it works...the configure
        script tries to be smart , but in many cases it will fail.

        So before running the script make sure that the enviroinement
        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/local/kde/qt
        so I actually execute

        # export QTDIR="/usr/local/kde/qt"

        If you want to compile the KDE support you might want to do the same
        with KDEDIR

        # export KDEDIR="your kde dir"

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

        # export KDEDIR="/usr/local/kde"
   
        The configure script has a lot of options that can be listed by using

        # ./configure --help

        Here's a brief list with explainations: (READ IT!)
        
        --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-debug-symbols
            This is for debugging and reporting problems.
            It sets the compiler options in order to leave the debugging
            informations into the kvirc executable and the libraries.
            In this way you will be able to produce a gdb backtrace
            in case of a crash. Don't use it in "normal" compilations
            since it produces an executable that is really larger in size.
        
        --with-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-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-memory-profile
            Debug stuff...enables memory allocation profiling (don't use it :)
        
        --with-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.
        
        --with-big-channels
            Minor hash table optimisations: higher memory usage but
            faster user lookups. Use it if you often stay in channels with
            a lot of users. (this is not critical anyway)
        
        --without-locale
            Disables the compilation of the localisation support.
            If you plan to use KVIrc in english only, enable this
            option: you will have a faster executable.
        
        --without-ipv6-support
            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.

        --with-system-memmove
            This will enable the use of the system memmove() memcpy() and memset() functions.
            KVirc uses own implementations by default, because on many machines these functions
            seem to be missing or fail to do the correct job. It is always a good idea
            to try this option: if it works, it will probably make your executable quite faster.
            If it does not work, just recompile without this option (and if you're on an x86 machine
            try --with-ix86-asm...this might be as fast as --with-system-memmove...).

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

        --without-crypt-support
            Disables the cryptographic engines and the whole cryptography/text-transformation
            support. Produces a slightly smaller executable.
            Anyway, if you don't know what the ctryptography/text-transformation
            support is ,I suggest you to avoid using this option.
        
        --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" :)
        
        --without-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.
        
        --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-no-pthread-check
            Do not check if the pthread stuff works.
            If configure fails in the pthread library check , you might want to
            try this...(but then you will have really to "pray" that the check has
            been broken by some "unusual" conditions and the compilation will succeed).

        --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-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.
            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-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-qt-check
            This disables Qt checking at compilation time.
            If this is the only way to compile and run
            the kvirc executable , then there is something
            wrong with the configure script.
        
        --with-kde-support
            Compile the KDE support.
            You obviously need at least the KDE libraries (kdelibs package).
            Before using this, ensure that $KDEDIR points
            to the right location. (The configure script
            will do its best to find the kde libraries and headers
            even without the $KDEDIR enviroinement variable ,
            but in that case it might wrong a wrong version if more
            than one is installed.
        
        --with-kde-library-dir=<DIR>
            Look for the KDE libraries in <DIR>
            If $KDEDIR points to the right place, you shouldn't need this.
        
        --with-kde-include-dir=<DIR>
            Look for the KDE headers in <DIR>
            If $KDEDIR points to the right place, you shouldn't need this.

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

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

        --without-kde-check
            Similar to --without-qt-check but for KDE.
        
        --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.
       
        --with-other-libs=<libraries>
            Explicitly link to the specified libraries.
            Example: --with-other-libs="-lmylib -lstrangesystemsupport -lmybraindamagedsyscallfix"
        
        --with-other-ldirs=<paths>
            Explicitly add the specified library search paths
            Example: --with-other-ldirs="-L/home/pippo/lib/ -L/my/safe/library/place/"
        
        --with-other-idirs
            Explicitly add the specified include search path
            Example: --with-other-idirs="-I/home/pippo/include/ -I/tmp/include/"

        --without-dyn-labels
            You should not need this option.
            It disables compilation of code that relies on a particular
            compiler feature (jumping to a dynamic label with a goto).
            Not all compilers support this , but configure shoud detect
            it automatically. Anyway , if you get compilation errors on
            kvi_ircview.cpp, you may try this option...
            This may also help if the configure script seems to hang
            when checking for the "compiler dynamic label support".

        --with-aa-fonts
            Enables the use of Anti-Aliased text extensions.
            You *need* XFree >= 4.0.2 and QT >= 2.3.0 compiled with the -xft option
            for this to work. You will get undefined references when linking or
            unexpected strange results if you don't match these requirements.
            (You have been warned.)
            The Anti-Aliasing is not enabled automatically even if you compile with this option:
            you need to
                # export QT_XFT="true"
            before starting kvirc.
            WARNING:
                This code is quite experimental both in KVirc and in the support libraries (libXft and libqt)
                so if you have problems, well, just recompile without this option.
                Also expect the IRCVIEW widget to slow down a lot with anti-aliasing turned on.
            TIP:
                Qt 2.3.0 tends to choose bad default application fonts at startup,
                and you might get unexpected crashes yet before any window is shown.
                If this happens, set "boolUseGlobalApplicationFont=true" in the main.kvc
                KVirc configuration file.

        --without-x-calls
            Disables completly the X drawing calls (always enabled with Qt >= 3.0.0)
			This can help if you have font problems in the view window

        --with-local-8bit
            Enable UNICODE<->Local 8bit charset translation.
            This option is *required* if you want to be able to see non latin1 characters in the GUI.
            For those of you that use the Latin1 character set , this option is useless (and it
            is better to avoid it , since it produces some translation overhead).

        --without-splash-screen
            Do not compile the splash screen code.
            This will remove you that nice "banner" image that pops up while kvirc is starting up.
            It will maybe help in making an executable smaller by a couple of KB and save a couple
            of extra milliseconds during the startup. Use it if you're tring to build
            a performance critical executable and you're short both in memory and CPU time :)

        --without-info-tips
            This will disable some informational tooltips in the option dialogs.
            It will help in making a smaller executable and modules. Use this option if you're a KVIrc guru
            and you don't need tips about using the options.

        --without-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 :)

        --without-dcc-sound
            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).

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

        --without-ssl-support
            Disables the secure socket layer support. The SSL support is automatically
            enabled if OpenSSL is detected at ./configure time. This option forces it
            to be left out.

        --with-fno-rtti
            Disables compiler runtime type information generation.
            This is mainly needed with qt-embedded.

        --without-x-bell
            Disables the usage of the XBell function (needed if you want to compile
            KVIrc with qt-embedded (no X at all))

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


        So finally you have to run

        # ./configure <your options>

        For example , my common options are:

        # ./configure --with-pipes --with-debug-symbols --with-kde-support \
                          --with-kde-transparency --with-ix86-asm --without-locale

        On FreeBSD I have found useful this command line:

        # ./configure --with-qt-name=qt2 --with-qt-moc=/<PATH_HERE>/moc2 --with-freebsd-pthread

        Once the configure script ran succesfully you can go to the next step.

    ###
    ### Step 3 : Compiling (mandatory)
    ###

        This step is easy:
        Cross your fingers and run

        # make kvirc

        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.

        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 --prefix option in
        the configure script) , the libraries in /usr/local/lib
        and the shared data in /usr/local/share/kvirc.
        If you had a previous kvirc installation , the default prefix
        will be referring to the directory where the old kvirc
        executable was found.

        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

    ###
    ### Step 4: Having fun
    ###

        # kvirc &

        That's all folks.


###############################################################################
# 4. 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 :)

