root/04/bugfix/doc/install.txt

Installation of Kombilo 0.4

Contents:
Installing Python
Installing Kombilo 0.4
Installing the C++ search function
Systemwide installation under Unix/Linux

The program is written in Python, a high-level interpreted programming
language. That means that you need to install Python before you
can run Kombilo. Any version better than 2.0 should do; I tested
the program with Python 2.0, 2.1 and 2.2. If you have to install
Python, you should get the current version 2.2.
The current version definitely does not work with version 1.5.2.

--- Installing Python

If you do not have python installed yet, here is what you have to do:
You can get everything you need, including further explanation,
at http://www.python.org/
If you are using Windows, just download the installer and run it; that
should be very easy.
If you are running Linux, it is likely that Python is already included
in your distribution. It is also easy to build it yourself from the
sources from the Python website. 
Python is also available for the Apple Macintosh (and numerous
other platforms, actually), but unfortunately I cannot give you
any further information about the installation there. You should
find everything you need on the website mentioned above, though.

--- Installing Kombilo

Once you have Python working, just download and unpack the
Kombilo file (kombilo04.tar.gz, kombilo04win.zip or kombilo04.zip). 
It will create  a subdirectory called kombilo04 in the directory where 
you unzip it, and all files needed for Kombilo will be placed in that
subdirectory. Then just start kombilo.py (or kombilo.pyw on Windows):
On a Linux box, just change into the corresponding directory,
and type 'python kombilo.py'. (You can also make 'kombilo.py'
executable, possibly adapt the path in its first line to
point to your Python installation, and run it as 'kombilo.py'.)
Under Windows, double-clicking on 'kombilo.pyw' should be enough.
You also can run it from a MS-DOS prompt, by 
'c:\python22\pythonw kombilo.pyw' (of course you might have to
adjust the path of your Python installation).

If you also had installed the first version of Kombilo,
you should nevertheless install Kombilo 0.4 as explained above,
in a directory kombilo04. You can just delete the kombilo04
directory. The sgf databases have to be added and processed anew.
(If this doesn't work, try to delete the files namelist.db, finalpos.db
and lists.db from the directories with SGF files.)

The Kombilo subdirectory should contain the following files:

kombilo.py, v.py, board1.py, sgfparser.py, sgfparserC.cc, matchC.cc,
kombilo.app, v.app, menus.def,
unixinst.py (Unix only)
doc/ kombilo.doc, license.txt, install.txt, readme.txt
     tutorial.html, *.jpg, onepixel.gif
gifs/ logok.gif, board.gif, 
      bw.gif, wb.gif, b.gif, w.gif, 
      fwd.gif, bwd.gif, ffwd.gif, fbwd.gif, start.gif, end.gif
      pass.gif, ab.gif, info.gif, 
      back.gif, reset.gif,
      psearch.gif, isearch.gif, ssearch.gif 

After the installation, just start Kombilo, add a database to
the database list (File-Edit DB list), enter a search pattern and
a search-relevant region (right mouse key) and press the 'pattern search'
button!
 
Most things should be self-explanatory. More information can be found 
in the file kombilo.doc, which is also available from the Help menu 
('Documentation'). In addition you might want to look at Kombilo's
web site at http://www.g0ertz.de/kombilo/ . There you will find
a more detailed tutorial with 
some screenshots where many of Kombilo's features are explained.

--- Installing the C++ search function

Because the C++ search function is much faster than the Python one,
it is desirable to install it, too. You can either compile it
yourself, or (for Linux (i386) or Windows) use the appropriate 
binary from the Kombilo web site.

- Linux:

The source code comes with the basic Kombilo package, in the
file matchC.cc, and since the GNU C++ compiler gcc is almost
certainly installed on your system, you should be able to
compile it yourself with the following commands:

gcc matchC.cc -O2 -I/usr/include/python -fpic -shared -o matchC.so 
gcc sgfparserC.cc -O2 -I/usr/include/python -fpic -shared -o sgfparserC.so

The only thing you might have to change is the path of the
python include files (after the -I). On some systems, this
is /usr/local/include/python, or might even be something else.

Alternatively, you can use the compiled version from the
Kombilo web site.

- Windows:

The C++ search function is already included in the 
stand-alone Kombilo installer. If you use the kombilo04win.zip
package, proceed as follows.

The source code is in the files matchC.cc and sgfparserC.cc, so if you 
have a C++ compiler (for example the free MinGW32 package, based
on the GNU C/C++ Compiler gcc, see http://www.mingw-org/ ) 
installed, you can compile it yourself. (See below for more 
details).

If you don't want to compile the file yourself, you can try
to download the compiled, binary file from the Kombilo
web site. These were compiled with the Borland compiler
on my Windows 2000 box. I think they should work in general,
but since I am no Windows expert at all, I cannot promise
anything. In any case, it is important that you download the
file which corresponds to the Python version you have 
installed! The file depends on which version you use.

Here are some basic instructions on how to compile
the source code with MinGW. First of all, you need the
MinGW package, which you can get from http://www.mingw.org/ .

Then everything is very simple. Make sure that the programs
from MinGW are in your path. Create a setup-ext.py file
like the following (and place it in the Kombilo directory):

------ setup-ext.py -------
import sys
from distutils.core import setup, Extension

matchCext = Extension('matchC', sources=['matchC.cc'])
sgfparserCext = Extension('sgfparserC', sources=['sgfparserC.cc']
                          
setup(name = 'matchC', ext_modules = [ matchCext ])
setup(name = 'sgfparserC', ext_modules = [sgfparserCext])
---------------------------

The rest will be done for you by the Python distutils package:
you can simply compile the extension modules by

python setup-ext.py build --compiler=mingw32

With Microsoft's compiler it should be just as easy. (I think
that you can just omit the --compiler option. Read more on
these things in the Python documentation.) 

- Macintosh

I'm pretty sure that for someone who has a C++ compiler
on a Mac and maybe some basic experience writing Python
extensions in C++, it is easy to compile the C++ search 
routine on a Macintosh, but since I don't have access to
a Mac, I cannot give any advice about this. If someone
succeeded to make this work on a Mac, I would like to hear
about it, and I will gladly put the resulting binary file on my
web page.

--- Systemwide installation under Unix/Linux

To install Kombilo system-wide (in /usr/local/share, for instance),
proceed as follows:

Put the Kombilo files in /usr/local/share/kombilo04 (if you put them
somewhere else, you have to adapt the unixinst.py script accordingly).

Carefully read, and -if/where necessary- edit the script unixinst.py .
(I think that you probably will not want to change much.)
Basically, the unixinst.py script writes a 'global' kombilo.def
file (in the kombilo04 directory) which tells Kombilo to look
for individual .def files (in $HOME/.kombilo ) when it is
started. So for every user who uses Kombilo, a subdirectory
called .kombilo will be created in the user's home directory.
In this directory, the individual .def file (which stores
mainly the database list, and some additional information 
about paths etc.) and the .opt file (which stored the saved 
options), and the .dat files are stored.

Furthermore the unixinst.py script creates a link
in /usr/local/bin, pointing to kombilo.py.

After you edited the unixinst.py script, execute it with
'python unixinst.py'. The only other thing you might have 
to do (if your python interpreter is not in /usr/bin),
is to change the very first line of the files kombilo.py,
(and v.py if you want to use the viewer separately, too)
which must contain the location of the python interpreter,
so that kombilo can be started by 'kombilo.py'.