Szymon Stefanek                                                 Wed 24 Jan 2001
###############################################################################

Installation instructions for the KVIrc IRC client.

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

Steps for a quick installation

./configure
make kvirc
make install

If something goes wrong , continue reading.

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

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

	-Qt library in a version >= 2.2.3

		First check if it is installed on your system:

		# find / -name libqt*

		The output should be something as:

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

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

		Some newest distributions have the binary package of this library ;
		if you install it in this way be sure to install also the *devel*
		version of the package (the include files).
		If you don't have the binary package grab the library from

			ftp://ftp.troll.no/

		and follow the instructions provided with it for the installation.
		More informations on the Qt library can be found on

			http://www.troll.no/

	Note: This version of KVIrc MIGHT work also with previous releases of Qt 2.*,
		2.2.3 is surely working , versions lower than 2.1.0 will NOT work,
		versions between 2.1.1 and 2.2.2 haven't been tested: you might try it.

-------------------------------------------------------------------------------
Step 2: OTHER STUFF TO CHECK (Optional)
-------------------------------------------------------------------------------

	-A decent pthread implementation

		# find / -name pthread.h

		/usr/include/pthread.h

		On most systems it is provided by the pthread library:

		# find / -name libpthread*

		/usr/lib/libpthread.a
		/usr/lib/libpthread.so
		/usr/lib/libpthread_p.a

		Some other systems provide wrappers for other implementations.

		Most glibc2 based distributions provide the pthread package.
		The sources can be also found on your favorite gnu ftp mirror.

		KVIrc can also use the native FreeBSD support builtin in libc: in this case
		you don't need libpthread (it is even better if you don't have it at all).
		You will have to pass the proper options to configure to use it: so if you are
		on FreeBSD , plz take a look at the configure optons below.

	-Thread safe X Libraries

		All glibc2 based distributions have it, so it should not be a problem.
		If your system is libc5 based (such as Slackware 4 AFAIK)
		You MUST upgrade to glibc2 and install the thread safe
		X Libraries , otherwise you will get unexplainable errors
		later.

	-The jpeg library

		It is not really 'required' , configure will detect it for you.
		But if it is installed on your system ,KVIrc will use it.

	If KDE 2 is present on the system (configure will hopefully detect
	it for you) , it will be possible to compile KVIrc as a KDE application and
	link to that libraries to take advantage of some KDE features.
	If you have KDE 2.* installed and running on your system
	and want the KDE support you will have to add --with-kde-support
	to the configure commandline (see Step 3)

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

	First you must run the configure script.

	# ./configure

	If the script executes without errors jump to the step 4 ,
	otherwise continue reading.

	Common configure problems
	-------------------------

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

	The easiest way to make ./configure find the library is to point QTDIR to the
	root of the qt source tree: before executing configure you need to execute
	the following command:

	# export QTDIR="/root_of_qt_source_tree_path/"

	The same can be done with the KDEDIR when you're compiling KDE support

	# export KDEDIR="/root_of_the_kde_installation_directory/"

	Then just run ./configure; this will work for most qt installations (surely for
	the ones that have been compiled from the sources).

	If you have a non-standard qt installation (like the ones made by some rpm packages,
	that spread the qt pieces all around the system), you can pass
	individual path options.

	Configure accepts a commandline option that allows you to specify the
	path to the Qt library:

	  --with-qt-library-dir   path to the Qt library
	  --with-qt-include-dir   path to the Qt headers
	  --with-qt-moc           filename of the Qt meta object compiler
	  --without-qt-check      Do not check if Qt and X compile

	So if the qt library can not be found but you know that it is installed,
	for example, in "/usr/mylibs/qt"
	try running ./configure with the following options:

		--with-qt-library-dir="/usr/mylibs/qt/lib"
		--with-qt-include-dir="/usr/mylibs/qt/include"
		--with-qt-moc="/usr/mylibs/qt/bin/moc"

	If the library is installed from a rpm package, and there is no "qt sources root"...
	you can pass individual paths:

		--with-qt-library-dir="/usr/somelibdir/"
		--with-qt-include-dir="/usr/myincludes/include"
		--with-qt-moc="/somewhereonyoursystem/bin/moc"

	If your qt library has a different name (like qt2 for example) you can use

		--with-qt-name=NAME

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

	If you 're compiling on Solaris you may need to add also:

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

	Notes:

		On an i386 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 actually tested only on i686 and i586 machines.
	If you experience problems with this option , just recompile without.
	This option is also known to NOT work with pgcc (still have to guess why).

		If you want to compile the charset translation support (useful mainly
	for cyrillic charsets) you have to add --with-charset-translation

		If you have KDE 2.* installed and running on your system
	and want the KDE support you will have to add --with-kde-support

	On  FreeBSD you must pass specific options in order to
	enable the use of the native pthread support, see below.

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

	The rest should be easy...

	# make kvirc

	If the compilation finishes without errors
	(there will be some warnings , just ignore it) you can install KVIrc:
	If you are on FreeBSD , you should use "gmake kvirc" instead: we're using gnu tools.

	# make install

	You may need to be root to execute this command.
	Use "gmake install" on FreeBSD

	KVirc should now be installed in /usr/local/bin
	The libraries in /usr/local/lib
	The images, and the other stuff in /usr/local/share/kvirc

	Note for RH7 users:
		If your compiler complains about '##' symbols in the
		source files....well...update your gcc. It is a VALID
		C++ preprocessor symbol.

-------------------------------------------------------------------------------
Step 5: INSTALLING THE ON-LINE HELP FILES (Optional but highly reccomended)
-------------------------------------------------------------------------------

	KVirc has an extensive on-line help for many of its features :
	you will probably need it.
	The following command will generate the help files and install it

	# make docs

	As usual, use "gmake docs" on machines where make is not gnu make.

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

	If you already had an older KVIrc installed and want the new config files
	(sample popups!), delete (or rename) your old local KVIrc directory before
	first running KVIrc.<br>

	# kvirc

	if KVIrc does not start , and you get something as:

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

	Add /usr/local/lib to your /etc/ld.so.conf and run ldconfig.
	You may also need to add /usr/local/lib to your LD_LIBRARY_PATH

-------------------------------------------------------------------------------
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-2.1.0" subdirectory inside , and will store
	there its configuration files.


Restoring old 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 ran this version of KVIrc once (so the local configuration
	directory has been created), shut kvirc down and run:

	cp -rf /path1/kvirc-2.0.0/config/ /path2/kvirc-2.1.0/config/

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

###############################################################################
Appendix 1 : ENABLING NON-ENGLISH LANGUAGE
###############################################################################

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

	# export LANG="it"

	now you can run kvirc :)

###############################################################################
Appendix 2 : COMPILING QT
###############################################################################

	Once you have the sources , unpack it in a suitable
	directory for building.
	WARNING : If you're using OLD applications that depend
	the OLD Qt library (the entire KDE needs it) , 
	you must keep the OLD (1.4X) version of Qt on your system.
	Do NOT overwrite the old library or sources with the new ones,
	or all that applications will stop working.
	In this case better if the directory is not on your $PATH
	or $LD_LIBRARY_PATH..
	something as /home/myuser/qt
	or /usr/build/qt will be ok.
	If you've received the sources via CVS , you already have it
	in the cvs dir.
	-
	I'll assume that you have unpacked your qt snapshot to /usr/build/qt
	if not , change the directories accordingly.
	We need to change temporairly QTDIR to build the library
	Do not change it permanently!
	Let's go.

	# cd /usr/build/qt
	# export QTDIR="/usr/build/qt"
	# ./configure
	# make

	Now have a cup of coffee :)
	(WARNING : If you do not have tmake properly installed
	you may notice that the make enters in a recursive loop
	after building the library...if this happens (you will notice it :)
	just kill the process by pressinc CTRL+C....

	INSTALLING QT:

	Add the line 
	/usr/build/qt/lib
	at the end of your /etc/ld.so.conf
	and run

	# ldconfig

	If something goes wrong later , you may need also to add
	/usr/build/qt/lib to your $LD_LIBRARY_PATH.


###############################################################################
Appendix 3 : configure script options
###############################################################################

List of meaningful configure script options:

--prefix=PREFIX
	installation path for the  architecture-independent files
        this defaults to /usr/local/

--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
	specifies to do not compile the plugin support.
	You will get a smaller executable , but you will loose a lot
	of interesting features.

--without-pthread-check
	specifies to ignore the pthread library check

--with-qt-library-dir
	path to the Qt library

--with-qt-include-dir
	path to the Qt headers

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

--with-qt-name=NAME
	Use NAME instead of "qt" as qt library name.
	This is useful on systems where more than one
	version of qt is required: often the distributions install qt2.* as qt2.
	In this case you will have to use --with-qt-name="qt2".
	I've found it useful at least on FreeBSD

--without-qt-check
	specifies to not check if Qt and X compile

--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've 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-freebsd-pthread
	Use this on FreeBSD: this system has native threading
	support builtin in libc. (You NEED it)