###############################################################################
The gentle art of configuring & distributing KVIrc plugins
(that compile out of the KVIrc source tree)
###############################################################################

Facts:
	- KVIrc plugins use to interact heavily with the KVIrc executable core.
	- Compiling a KVIrc plugin out of the source tree requires a lot of
		configuration hacking.

For these two reasons I have provided this small HOWTO and a ready-to-edit
plugin package.
You can find the package in this directory , named "basicplugin.tar.gz" .
Untar it to a suitable directory and take a look inside.
The ls output should look as follows:

	-rw-r--r--   1 root     root     1192 Apr  9 15:23 Makefile.am
	-rw-rw-r--   1 root     root      106 Apr  9 15:27 README
	-rw-rw-r--   1 root     root     9269 Apr  9 14:55 acinclude.m4
	-rwxrwxrwx   1 root     root       98 Apr  9 15:01 autogen.sh
	-rwxr-xr-x   1 root     root    21543 Apr  9 14:36 config.guess
	-rwxr-xr-x   1 root     root      104 Apr  9 14:36 config.h.bot
	-rwxr-xr-x   1 root     root    19847 Apr  9 14:36 config.sub
	-rwxr-xr-x   1 root     root     2631 Apr  9 15:03 configure.in
	-rwxr-xr-x   1 root     root     4773 Apr  9 14:36 install-sh
	-rw-rw-r--   1 root     root     3744 Apr  9 15:24 libkvihelloworld.cpp
	-rwxr-xr-x   1 root     root    43107 Apr  9 14:36 ltconfig
	-rwxrwxrwx   1 root     root    70979 Apr  9 15:26 ltmain.sh
	-rwxr-xr-x   1 root     root     4639 Apr  9 14:36 missing
	-rwxr-xr-x   1 root     root      730 Apr  9 14:36 mkinstalldirs

Makefile.am is the automake source for the Makefile of your plugin library.
The README file should be filled with installation instructions.
acinclude.m4 , config.guess , config.h.bot , config.sub , install-sh ,
ltconfig , ltmain.sh , missing and mkinstalldirs are auxiliary files.
autogen.sh and configure.in are used to generate the configure
script and the Makefiles.
The main source of the sample plugin is libkvihelloworld.cpp.

Let's go to edit the package configuration stuff.
First of all open the Makefile.am file.
In this first approach the relevant part is:

	pluglib_LTLIBRARIES= libkvihelloworld.la

	libkvihelloworld_la_LDFLAGS = -module -avoid-version $(KVIRCLDFLAGS)
	libkvihelloworld_la_SOURCES = libkvihelloworld.cpp
	libkvihelloworld_la_LIBADD  = $(KVIRCLIBADD) -lkvilib

This defines the target of your compilation and the flags that will be used.
So pluglib_LTLIBRARIES should be set to the name of the library that
you're going to create. In this case the library name is libkvihelloworld.la.
The shared object libkvihelloworld.so will be automatically generated too.
If you're going to change the plugin name , you will have to adjust all
these entries accordingly.
For example , if you're building a plugin named
"myplugin" your entries will look as follows:

	pluglib_LTLIBRARIES= libmyplugin.la

	libmyplugin_la_LDFLAGS = -module -avoid-version $(KVIRCLDFLAGS)
	libmyplugin_la_SOURCES = libmyplugin.cpp
	libmyplugin_la_LIBADD  = $(KVIRCLIBADD) -lkvilib

All this assuming that you have only ONCE source file and no headers.
If you have a header file too , take a look at this entry in Makefile.am:

	# noinst_HEADERS= libkvihelloworld.h

You have to uncomment it and replace the header name with the correct one,
for example:

	noinst_HEADERS= libmyplugin.h

If one of your header files needs to be run moc on it
you should proceed as in the following example:

Assume to build libmyplugin and have four source files:

	libmyplugin.cpp
	libmyplugin.h
	libmydialog.cpp
	libmydialog.h

The libmydialog.h file declares a Qt derived widget class
and you need to run the qt meta-object compiler on it:
you can use the following rule in the Makefile.am:

	m_%.moc: %.h
		$(KVIRCQTMOC) $< -o $@

	libmydialog.cpp: m_libmydialog.moc

Then just place

	#include "m_libmydialog.moc"

at the end of the libmydialog.cpp source file.
So finally your Makefile.am should look as follows:


	AUTOMAKE_OPTIONS= foreign

	CPPFLAGS= $(KVIRCCPPFLAGS) \
			-I$(KVIRCSRCDIR)/common \
			-I$(KVIRCSRCDIR)/kvilib \
			-I$(KVIRCSRCDIR)/kvirc \
			-I$(KVIRCSRCDIR)/plugins

	pluglib_LTLIBRARIES= libmyplugin.la

	libmyplugin_la_LDFLAGS = -module -avoid-version $(KVIRCLDFLAGS)
	libmyplugin_la_SOURCES = libmyplugin.cpp libmydialog.cpp
	libmyplugin_la_LIBADD  = $(KVIRCLIBADD) -lkvilib

	noinst_HEADERS= libmyplugin.h libmydialog.h

	m_%.moc: %.h
		$(KVIRCQTMOC) $< -o $@

	libmydialog.cpp: m_libmydialog.moc

Next thing is to run autogen.sh.
It will create the Makefile.in , the configure script and it will run it
for the first time. Make sure that the kvirc sources are found ;
if not (you will notice it :) , pass the --with-kvirc-sources option
to configure.

Now you just have to run make and make install.
Your plugin should be compiled and installed in the kvirc plugin directory.

You will find plugin source code examples in the src/plugins subdirectory of
the KVIrc distribution.

###############################################################################
Szymon Stefanek
