WhiteDB Installation
====================


Introduction
------------

There are two primary ways you can use the distribution package:

- compile the database library ('libwgdb.so' under Linux, 'wgdb.dll' under
Windows) and link your application against that

- compile your application program by including the database files directly

In both of  these cases your application using WhiteDB calls should
include the API header file: 'dbapi.h'

In addition, you may want to compile the included utility programs (`wgdb`
and `indextool`) to manage the database.

Quick-start instructions
------------------------

Under Linux, type

  ./configure
  make
  make install

This produces the database utilities, the library and installs the
them together with the database header files.

Under Windows, check that you have MSVC installed. Open the command
prompt with the Visual C environment configured and type:

  compile.bat

This produces the database utilities, 'wgdb.lib' and 'wgdb.dll'.

The shared memory
-----------------

Under Linux, the default memory settings are sufficient for testing
and initial evaluation. For increasing the maximum amount of shared
memory, type:

  sysctl kernel.shmmax=100000000

This example sets the available shared memory to 100M bytes. Under Mac OS X
you need to set a kern.sysv.shmmax and kern.sysv.shmall, type:

  sudo sysctl -w kern.sysv.shmmax=1073741824
  sudo sysctl -w kern.sysv.shmall=262144

You can add these settings to '/etc/sysctl.conf' to make it permanent.

Under Windows, the shared memory is not persistent. To maintain a
persistent database, use

  wgdb server 100000000

This example creates a shared memory database of 100M bytes. Once
this process is terminated, the shared memory is destroyed.

The configure script
--------------------

Some more relevant options to the configure script are:

'--prefix=PREFIX'  specifies the directory the program is
installed under. The binaries go in 'PREFIX/bin', the header files
in 'PREFIX/include/whitedb' and the libraries in 'PREFIX/lib'.
The Python modules, if compiled, will be placed in
'PREFIX/lib/pythonX.Y/site-packages', where X.Y is the Python version

'--with-python'  compiles the Python bindings. By default, the configure
script attempts to automatically locate a suitable version of Python. Use
'--with-python=/usr/bin/pythonX.Y' to point to a specific version
of Python.

'--enable-locking'  changes the locking protocol. The available options
are: 'rpspin' (a reader preference spinlock), 'wpspin' (a writer preference
spinlock), 'tfqueue' (task-fair queue, no preference) and 'no' (locking
is disabled). The default value is 'tfqueue' which performs best under heavy
workload. For simple applications 'rpspin' may be preferrable, as it has
lower overhead.

'--enable-logging'  enables the journal log of the database. Still
somewhat experimental; off by default.

'--enable-reasoner'  enables the Gandalf reasoner. Disabled by default.

'--disable-backlink'  disables references between records. May be used
to increase performance if the database records never contain any
links to other records.

'--disable-checking'  disables sanity checking in many internal
database operations. Increases performance by a small percentage.

`./configure --help` will provide the full list of available options.

Building the repository version
-------------------------------

The github repository (https://github.com/priitj/whitedb) does not
contain a pre-generated configure script. You'll need the autoconf and
automake packages, if you have those installed, run:

  ./Bootstrap

This generates the `configure` script and other scripts used by the
autotools build.

Building the utilities without configure and GNU make
-----------------------------------------------------

The `compile.sh` script is provided to allow compiling the utilities
with the C compiler. This is intended to simplify building in
cross-target or embedded environments. It is assumed that the
GNU C Compiler (`gcc`) is used.

When the script is executed the first time, it copies 'config-gcc.h'
to 'config.h', unless that file is already present. Edit 'config.h' to
change database options.

Under Windows, `compile.bat` serves a similar function. To change the
database options, edit the 'config-w32.h' file.

Note that in both cases, the config file for building the utilities
`indextool` and `wgdb` should match the config file for building your
database application.

Not building anything
---------------------

Building the database library and the utilities is not strictly necessary.
Alternatively you may compile the database sources directly into your
program.

See 'Examples/compile_demo.sh' ('Examples\compile_demo.bat' under
Windows). This compiles the demo program 'demo.c' with the WhiteDB source
files. These programs and scripts may be used as templates for creating
database applications.

