Szymon Stefanek                                                 Wed 24 Jan 2001
Triskelios                                                      Fri 27 Jul 2001
###############################################################################

Installation instructions for the KVIrc IRC client, version 2.1.2.

###############################################################################
# 1. Quick install
###############################################################################

Steps for a quick installation:

$ ./configure (with requested options from './configure --help')
$ make kvirc
$ su (if you're not root)
# make install

If something goes wrong, continue reading.

###############################################################################
# 2. Step-by-step guide to the installation of this KVIrc release
###############################################################################

-------------------------------------------------------------------------------
Step 1: CHECKING FOR REQUIRED LIBRARIES (Required)
-------------------------------------------------------------------------------

	-Qt GUI toolkit, version >= 2.2.3

		First, check if Qt is installed on your system:

		$ find / -name libqt.so*

		The output should be something like:

		/usr/lib/qt/lib/libqt.so.2.2.3
		/usr/lib/qt/lib/libqt.so
		/usr/lib/qt/lib/libqt.so.2
		/usr/lib/qt/lib/libqt.so.2.2

		If there is no output at all, or if the version number is lower
		than 2.2.3, you must install a newer version of Qt.

		Some distributions have only a binary package of the libraries;
		if you installed Qt this way, be sure to also install the
		"devel" version of the package (the header files) in order to
		compile.

		If you do not have Qt installed, grab a "qt-x11" source package
		from:
			ftp://ftp.trolltech.com/qt/source/
		and follow the instructions provided with it to install. The
		installation instructions for the source distribution are also
		available at:
			ftp://ftp.trolltech.com/qt/source/INSTALL

		If you prefer to install Qt in binary form (!), check the
		Website of your distribution's vendor.

		More information about Qt can be found at:
			http://www.trolltech.com/products/qt/qt.html

	Note: This version of KVIrc MIGHT also work with releases of Qt 2.x
		prior to 2.2.3, but versions lower than 2.1.0 will NOT work.
		Qt 2.3.x works flawlessly, but Qt 3.x has not been tested yet.

-------------------------------------------------------------------------------
Step 2: CHECKING FOR OTHER ITEMS (Optional)
-------------------------------------------------------------------------------

	-Thread-safe X libraries

		All glibc 2.x-based distributions should have X libraries that
		work properly with threads, so this should not be a problem. If
		your system is libc5-based, you MUST upgrade to glibc 2.x and
		install thread-safe X libraries, or you will get unexplicable
		errors later.

	-JPEG library

		jpeg is not really required; configure will detect it for you
		if it is installed on your system. It is needed in order to
		use JPEG images. If your Qt has built-in JPEG support, KVIrc
		will not need to use its own implementation.

	If KDE 2.x is present on your system (configure hopefully will detect
	it for you), it will be possible to compile KVIrc as a KDE application
	if you have the KDE header files (you may need to install a "devel"
	package if you installed KDE from binaries). KVIrc will link to the KDE
	libraries to take advantage of some KDE features. If you have KDE 2.x
	installed and running on your system, and want KDE support, you will
	have to pass the '--with-kde-support' option to configure (see Step 3).

-------------------------------------------------------------------------------
Step 3: PREPARING THE COMPILATION (Required)
-------------------------------------------------------------------------------

	First, you should check the available configure options:

	$ ./configure --help

	Read the 'Notes' section for explanations of some of those options.

	Then, run the configure script with the options you want:

	$ ./configure [options]

	If the script executes without errors, jump to the Step 4. Otherwise,
	continue reading.

	Common configuration problems
	-----------------------------

	The most common error here is that the Qt library cannot be found.

	The easiest way to make ./configure find the library is to point the
	environment variable 'QTDIR' to the base of the Qt source tree; before
	running configure, execute the following command:

	$ export QTDIR="<Qt base directory>"

	Or, in csh:

	$ setenv QTDIR="<Qt base directory>"

	The same can be done with the KDEDIR when you want to build with KDE
	support:

	$ export KDEDIR="<KDE base directory>"

	Or, in csh:

	$ setenv KDEDIR="<KDE base directory>"

	Then, just run ./configure with options; this will work for most Qt
	installations (surely for ones that have been built from the source).

	If you have a nonstandard Qt installation (like the ones made by some
	rpm packages, that spread the Qt pieces all over the system), you can
	pass individual path options.

	Configure accepts commandline options that allow you to specify the
	paths and options for Qt:

	  --enable-mt             link to multithreaded Qt
	  --with-qt-dir=DIR       base directory of the Qt installation
	  --with-qt-includes=DIR  directory where the Qt headers are
	  --with-qt-libraries=DIR directory where the Qt library is
	  --with-qt-moc=PATH      filename of the Qt meta object compiler
	  --without-qt-check      do not check whether Qt and X compile

	So, if configure cannot find Qt, but you know that it is installed,
	for example, in '/usr/mylibs/qt', try running ./configure with the
	following option:

		--with-qt-dir="/usr/mylibs/qt"

	If the library is installed from a rpm package, and there is no Qt base
	directory, you can specify individual paths:

		--with-qt-libraries="/usr/somelibdir/"
		--with-qt-includes="/usr/myincludes/include"
		--with-qt-moc="/somewhereonyoursystem/bin/moc"

	If you built Qt with threading, you can use the '--enable-mt' option.

	If your Qt library is not named 'qt' ('qt2', for example) you can use:

		--with-qt-library-name=NAME

	./configure --help will show a list of other available configure
	options.

	If you're compiling on Solaris, you may need to use:

		--with-solaris-libs     (adds the usual lsocket lnsl)
		--with-ignore-sigalarm  (workaround for a common threads bug)

	Notes:

	Useful configure options
	------------------------

	On an x86-based machine, you can use '--with-i386-asm' to compile
	assembly versions of some commonly used functions. This will produce a
	faster executable.
	WARNING: This option has been tested only on i686 and i586 machines. If
	you experience problems with this option, just rebuild without it.
	This option is known NOT to work if you use pgcc (Pentium GCC).

	If you want to build the character set translation support (useful
	mainly for cyrillic charsets), you have to use the
	'--with-charset-translation' option.

	If you have KDE 2.x installed and running on your system, including
	the KDE headers, and want KDE support, you will have to use the
	'--with-kde-support' option.

-------------------------------------------------------------------------------
Step 4: BUILDING AND INSTALLING KVIRC (Required)
-------------------------------------------------------------------------------

	The rest should be easy...:

	$ make kvirc

	If you are on FreeBSD or another non-GNU OS, you should use 'gmake
	kvirc' instead; we're using GNU tools.

	If the compilation finishes without errors, (there may be some
	warnings; just ignore them) you can install KVIrc:

	# make install

	Use 'gmake install' instead on FreeBSD or another non-GNU OS.
	You may need to be root to execute this command. If you are not. and
	the installation fails, 'su' and enter the root password, then 'make
	install' again.

	KVIrc should now be installed.
	The default installation prefix is /usr/local
	If you enabled KDE support, the default prefix may be the KDEDIR.
	The 'kvirc' executable installs in <prefix>/bin
	The libraries are in <prefix>/lib
	The images, plugins, and the other files are in <prefix>/share/kvirc

	Note for Red Hat 7.x Linux users:
		If your compiler complains about '##' symbols in the source
		files, upgrade your gcc. It is a VALID C++ preprocessor symbol.
		If your gcc gets weird crashes, upgrade it also...

-------------------------------------------------------------------------------
Step 5: INSTALLING THE ON-LINE DOCUMENTATION (Optional, but highly recommended)
-------------------------------------------------------------------------------

	KVIrc has an extensive on-line help system for many of its features,
	including the KVI++ scripting language. You will probably want to
	install it. The following command will generate and install the
	documentation:

	# make docs

	As usual, use 'gmake docs' on machines where 'make' is not GNU make.
	You may need to be root to execute this command.

-------------------------------------------------------------------------------
Step 6: RUNNING KVIRC (Optional :) )
-------------------------------------------------------------------------------

	If you had a previous KVIrc installation and want the new config files
	(e.g. sample popups!), delete (or rename) your old local KVIrc
	directory (usually ~/kvirc-<version>) before running the new KVIrc.

	$ kvirc

	If KVIrc does not start, and you get an error like:

	kvirc: error in loading shared libraries:
	libkvilib.so.1: cannot open shared object file: No such file or
	directory

	Add <prefix>/lib to your /etc/ld.so.conf and run ldconfig.
	You may also need to add <prefix>/lib to your LD_LIBRARY_PATH variable.

-------------------------------------------------------------------------------
Step 7: HAVE FUN :)
-------------------------------------------------------------------------------

Note:
	KVIrc will start a setup program the first time that it is run. You
	will be asked to choose an EXISTING directory. KVIrc will create a
	'.kvirc' subdirectory inside, and will store its configuration
	files and other local files there.

Restoring a previous configuration:
	If you had a previous installation of KVIrc and want to restore your
	old aliases and popups, you must move the config files by hand.
	Once you have run this version of KVIrc once (so that the local
	configuration directory has been created), shut KVIrc down and run:

	cp -rf /path1/kvirc-2.*.0/config/ /path2/.kvirc/config/

	where "path1" is the path that you have selected in your previous
	installation of KVIrc, and "path2" is the one that you have selected
	in THIS installation.
	The two paths may be eventually the same.
	KVIrc 2.1.2 configuration files are 100% compatible with the old ones.

###############################################################################
Appendix 1: USING DIFFERENT LANGUAGES
###############################################################################

	Like most other GNU programs, KVIrc supports localization. Currently
	only the Italian locale is implemented. KVIrc looks up the current
	locale setting from the LANG environment variable. For example, to make
	KVIrc use the Italian translations of all of the strings contained in
	the program, the LANG variable must be set to 'it'.

	$ export LANG="it"

	Now, you can run KVIrc. :)

###############################################################################
Appendix 2: INSTALLING/UPGRADING Qt
###############################################################################

	Once you have the sources, extract it to a suitable installation
	directory (e.g. '/usr/lib'). Refer to the included 'INSTALL' file or:
		ftp://ftp.trolltech.com/qt/source/INSTALL
	for build instructions.
	WARNING: If you're using OLD applications that depend the OLD version
	(1.4x) of Qt (such as KDE 1.1.x and its applications), you must keep a
	copy of the OLD Qt library on your system. Just copy 'libqt.so.1*' to
	'QTDIR/lib'. If you want to be able to compile Qt 1.4x programs, you
	must keep the old Qt base directory, and preferably add its lib dir to
	'/etc/ld.so.conf', and run 'ldconfig'.

###############################################################################
Appendix 3 : CONFIGURE OPTIONS
###############################################################################

List of meaningful configure script options:

--prefix=PREFIX
	installation path for the  architecture-independent files
        this defaults to /usr/local or KDEDIR, if building with KDE support

--exec-prefix=EPREFIX
	installation path for the  architecture-dependent files in EPREFIX
        [default: same as prefix]

--x-includes=DIR
	path to the X include files

--x-libraries=DIR
	path to the X libraries

--without-locale
	specifies to do not support localization (smaller executable)

--without-jpeg-support
	specifies to do not compile the jpeg support even if the jpeg
	library is found on the system

--without-plugin-support
	do not compile the plugin support.
	You will get a smaller executable, but you will loose a lot
	of interesting features.

--enable-mt
	link to multithreaded Qt


--with-qt-lib-name=NAME
	Use NAME instead of 'qt' as qt library name
	This is useful on systems where more than one
	version of Qt is used; often, distributions install the Qt 2.x
	library as 'qt2'.
	In this case, you will have to use '--with-qt-lib-name="qt2"'.
	I have found it useful, at least on FreeBSD.

--with-qt-dir=DIR
	base directory of the Qt installation

--with-qt-includes=DIR
	directory the Qt headers are in

--with-qt-libraries=DIR
	directory the Qt library is in

--with-qt-moc=PATH
	filename of the Qt meta object compiler

--without-qt-check
	do not check whether Qt compiles

--with-kde-support
	specifies to try to compile the KDE 2.0 support

--with-kde-library-dir
	path to the KDE libraries

--with-kde-include-dir
	path to the KDE headers

--without-kde-check
	specifies to not check if Qt,KDE and X compile

--with-solaris-libs
	specifies to link also to lsocket,lresolv and lnsl
	useful for Solaris & co.

--with-pipes
	specifies to use pipes for compilation: saves your disks,
	so use it! :)

--with-ignore-sigalarm
	specifies to ignore SIGALARM in all threads
	mainly useful for Solaris

--with-own-inet-aton
	specifies to use own inet aton implementation
	Useful on system that do not provide these functions
	If you see undefined references to inet_aton somewhere,
	pass this option to configure.

--with-own-inet-ntoa
	specifies to use own inet ntoa implementation
	same as above

--with-ipv6-support
	specifies to compile the experimental IPv6 support

--with-pedantic-gcc
	specifies to compile with all the warnings enabled

--with-verbose-compilation
	specifies to add the v option to the gcc commandline
	You will see your compiler spit a lot of output :)

--with-i386-asm
	Specifies to compile x86 assembly optimisations
	If you have an i386 based machine, you may give it a try...

--with-charset-translation
	Enables the compiation of the charset translation support
	(It is useful mainly for those that use the various cyrillic
	language charsets).

--with-debug-symbols
	Specifies to leave the debug symbols in the kvirc executable.
	It makes the kvirc binary really big, but suitable for debugging
	with gdb. If you have found a bug, be sure to enable it.

--with-o3-optimisation
	Adds the -O3 flag to the gcc commandline when compiling.
	This will turn on some optimisations that are not used with
	the default -O2 flag.

--with-local-8bit-encoding
	Use this if your locale has a charset that is not LATIN1.
	This slows down some non critical parts but allows
	you to see your localized characters.