===============
            |     BOP     |
            ===============


What is it ?
============

"Bop" stands for "Boite  Outils de Patrick" which means "Patrick Tool Kit",
more precisely "Patrick Tool Box" in french, but to my ears 'Bop' sounds
better than "Ptk" or "Ptb".

It aims to be an object oriented C library to be used by C developpers.

In this version, you will find :

. Bopc : an any-object container class.

. Bopd : Debugging tools.

. Boph : a hash tables class.

. Bopl : a double linked lists class.

. Bopm : memory allocation functions.

. Bops : an extensible stack with extended functions class.

. Bopx : miscellaneous functions.

Legal informations.
===================

All the files in this distribution, unless clearly stated otherwise are
copyrighted :
Copyright (c) 2004 Patrick Davalan. All rights reserved.

Bop is free software, distributed under the terms and conditions of
the GNU General Public License, version 2.  For further informations,
read the file COPYING.

In the directory ./samples, you'll find hash functions from Berkeley DB,
I put them there as examples.
These functions, as Berkeley DB itself, are copyrighted :
Copyright (c) 1996-2004 Sleepycat Software.  All rights reserved.
Copyright (c) 1990, 1993, 1994 Margo Seltzer.  All rights reserved.
Copyright (c) 1990, 1993, 1994 The Regents of the University of California.  All rights reserved.
This is free software too.
You may use these functions under the terms and conditions of the
licenses you can find in file ./samples/LICENSE-DB

Distribution directories structure.
===================================

.                   Installation files, legal files, build directory.
|-- doc             Documentation in html format.
|   `-- examples    Examples programs using Bop.
|-- man             Manual pages.
|   `-- man3        *The* bop man page can be found here.
|-- samples         Samples, for now Berkeley DB hashing functions
|-- src             Library functions sources.
|   `-- tests       Test programs sources.
`-- testsuite       Testsuite scripts.
    |-- files       Files used by testsuite scripts.
    |-- ref         Expected results of testsuite scripts.
    `-- res         Results of testsuite scripts.


How to install ?
================

I tested the installation procedures on a Debian GNU/Linux "Sarge".
It should work on other GNU/Linux systems and maybe on other Unix-like
systems, but I can't certify anything.

You must have a decent C compiler (I suggest GCC, the GNU C compiler),
make, and other utilities probably shipped in your base distribution.

At the shell prompt, from the main directory of the package, type :

./configure
make
make check  # optional but recommended
make install    # you probably need to be root for this
make post-check # optional but recommended

It takes a short time to compile and to check. There would be no
compilation warning if you use the gcc compiler on GNU/Linux. But it
may depend on the compiler version, don't panic !

As an alternative, an interactive shell script, './installme', may be
used to install. It performs the steps above and stops on error.
Its arguments are passed along to ./configure.
As it promts you to hit <enter> from time to time, you have the time to
read informative messages from bop, It also gives more informations than
make, it's the reason why using this verbose script is recommended.
You will be prompted for the root password when this script needs to have
root privileges.

By default, Bop is installed on /usr/local/ , if you want to install
it somewhere else, specify '--prefix=my-install-dir at configure
time, e.g. :
./configure --prefix=$HOME
Or, if you use 'installme"
./installme --prefix=$HOME

There is no other configuration option. You can change compilation options
when running "make", if you use gcc, you'll probably not want to do it.

The installation directory should contains the following directories, but
bop creates them when it can't find them .

./sbin
./include
./lib
./sbin
./man   or ./share/man  # it may depend ...
./share
./share/doc

The directories created by Bop will not be removed at uninstall time.

At least on a GNU/Linux system, in order to be found at program execution,
the libraries directory (except when trusted like /lib or /usr/lib) should be
declared in /etc/ld.so.conf, so check if $(PREFIX)/lib appears in file
/etc/ld.so.conf.

You now have to run /sbin/ldconfig
/sbin/ldconfig

The standard installation does *NOT* install the static library, if you
want to install it, type :
make install-static

More briefly, do as usual.

How to uninstall ?
==================

You have to uninstall with the version you have installed before
installing a newer version. The reason is that some file names will
change in future versions and some will not.
The typical way to do it is to jump into the version distribution
directory you want to uninstall and, without even the shade of any regret,
type :
make uninstall

if you don't want to keep this distribution files after you install, an
uninstall script is created at install time in :
$(PREFIX)/sbin/bop.[version].uninstall with permission 744
Thus, you can safely remove the distribution files, the uninstall script will
be able to uninstall. just type :
/usr/local/sbin/bop.[version].uninstall
(if you installed in /usr/local (the default)).
This uninstall script is *not* removed by the uninstall process nor by the
uninstall script.
You might want to do it by hand, anyway it is very small.

How can I use it ?
==================

You have to follow the term and conditions of the license, Bop comes
with absolutly *NO* warranty, therefore if you think your milk turned
sour because of Bop, I will *NOT* be liable to you for damages.
You have been warned !

There is a man page (bop(3)) which says that Bop doesn't use man pages
for documentation purpose.

You can find documentation in the doc directory, mostly in html.
... Documentation is in french, but it will quite soon be translated
into english, it might already be done at the time you read this file and
the doc placed in a page linked to http://patrick.davalan.free.fr/bop/
You'll have to follow the union jack flag.
a sample script can be used to update your distro doc directory:
./samples/getdoc
fix it first to meet your installation needs.

The documentation is likely *NOT* to be maintained in french afterward.

Doc files are installed in $(PREFIX)/share/doc/bop/

Bop library is created with "soname" 'libbop.2.so'. At link time (at
least if you use gcc to link the programs), you'll have to specify this
soname :
gcc myprogram.o -lbop.2 -o myprogram

If you installed in a non standard directory (e.g your home directory),
you also need to specify the library directory :
gcc myprogram.o -L/$HOME/lib -lbop.2 -o myprogram

If you're reckless enough to try to use such a program, you'll have to
specify the library directory path in variable LD_LIBRARY_PATH if bop is
not installed in a trusted directory.

To use the bop library header files, you have to include bop.2/bop.h
in C program source files :
#include <bop.2/bop.h>

How much does it cost ?
=======================

It's up to you.

I suggests that you take time to send bug reports if you find some,
suggestions are also welcomed. These are the most important things you
can do for me.

If you use bop *intensively* in one of your softwares, please put my
name in your "CREDITS" or "THANKS" file. It's not because I'm proud of
having written it, but sometimes I look for a job and it may be useful
for me to be able to say "I worked on many softwares all around this
world. As an example, I took much pleasure in writing code for the
well-known <your software> blah ...".
Then send me an email to tell me you did it.
(Patrick Davalan) jigmepema <at> wanadoo.fr

Bugs.
=====

If you find one, please tell me.

The installation procedures should have been better, they will be
improved. the same for the test procedures.
I planned to test these procedures on Debian Sid, Testing and Stable
(and maybe other GNU/Linux distributions), on GNU/Hurd and on Open-BSD.
I don't know when but it's likely to be in the future.
(a not so far future, I hope).

English documentation lacks, It's likely that I'll write it on the web
site before next version release. http://patrick.davalan.free.fr/bop/

Bop will stay as a pre-2.1.0 release (i.e. 2.0.9x) until better tests and
documentation had been achieved. You are encouraged to install it, use it
and, when appropriate, send bug reports.

Some performance improvements will also be done in future releases.

The author.
===========

Patrick Davalan. <jigmepema<at>wanadoo.fr>   # s/<at>/@/

The end.
========

Thank you for following me so far despite my poor english.

That's all folks.