readme.1st

db.* (pronounced dee-be star) is an advanced, high performance, small footprint embedded database fo

/***************************************************************************
 *                                                                         *
 * db.*                                                                    *
 * open source database kernel                                             *
 *                                                                         *
 * Copyright (c) 2000 Centura Software Corporation. All rights reserved.   *
 *                                                                         *
 * Use of this software, whether in source code format, or in executable,  *
 * binary object code form, is governed by the CENTURA OPEN SOURCE LICENSE *
 * which is fully described in the LICENSE.TXT file, included within this  *
 * distribution of source code files.                                      * 
 *                                                                         *
 * Except as provided herein, the contents of this file are subject to the *
 * Centura Open Source Public License Version 1.0 (the "License"); you may *
 * not use this file except in compliance with the License.  A copy of the *
 * License will be provided to you by Club ITTIA.                          *
 *                                                                         *
 * Software distributed under the License is distributed on an "AS IS"     *
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the *
 * License for the specific language governing rights and limitations      *
 * under the License.                                                      *
 *                                                                         *
 * The Original Code is db.linux version 1.0, released February 29, 2000.  *
 *                                                                         *
 * The Initial Developer of the Original Code is Centura Software          *
 * Corporation. Portions created by Centura Software Corporation are       *
 * Copyright (C) 1984-2000 Centura Software Corporation. All Rights        *
 * Reserved.                                                               *
 *                                                                         *
 * This file contains modifications to the Original Code made by ITTIA.    *
 * This file may only be used in accordance with the ITTIA DB.* V.2        *
 * License Agreement which is available at WWW.ITTIA.COM.                  *
 *                                                                         *
 **************************************************************************/

Building db.*
=============

Extract the db.* source code tree to a directory on your filesystem and enter
that directory:

tar xzf db-star-2.0.tar.gz
cd db-star-2.0/

To build db.*, issue the following commands:

./configure
make

You may test your build by running the tims example:

cd examples/tims
./tims

A test suite is included with db.* to automatically test basic functionality.
To run these tests, use:

make check


Installing db.*
===============

To install db.* to your system, issue the command:

make install

This will install the db.* libraries, headers, and utilities to the default
location (usually /usr/local). You may also strip debug information from the
libraries when installing them with the command:

make install-strip

This produces much smaller library files but may make debugging more difficult.

In the path to which db.* is installed, the following utilities will be
available in the bin directory:
    console
    dal
    datdump
    dbcheck
    dbclrlb
    dbedit
    dbexp
    dbimp
    dchain
    ddlp
    ida
    initdb
    keybuild
    keydump
    keypack
    lm
    lmclear
    prdbd

The db.* static and shared libraries will be in the lib directory:
    libdbstar.a
    libpsp.a
    libdbstar.so
    libpsp.so

To install the test suite, use:

make installcheck

This will install a program named "testdbstar".


Configuring db.*
================

You may further customize your build of db.* by passing options to the
configure script before running make. For a list of all options, run:

./configure --help

By default, db.* is installed to /usr/local. To specify that db.* should be
installed to the absolute path DESTINATION, use:

./configure --prefix=DESTINATION

Other options allow you to reduce the size of the db.* libraries by disabling
unnecessary features: --disable-threads, --disable-console, --disable-net,
--disable-stdio.

For example, to build db.* without thread support and install stripped
libraries to $HOME/tmp, use:

./configure --prefix=$HOME/tmp --disable-threads
make
make install-strip

If you want to experiment with several different configurations, you can run
configure from a subdirectory:

mkdir output
cd output
../configure
make

This will isolate the build to the output directory. You can create any number
of build directories in this way, each with its own configuration options.

You must install db.* using "make install" or "make install-strip". You cannot
simply copy the files that are created by "make". Always specify the path that
db.* will be installed to through the --prefix configure option. If you need to
install to a temporary path, for example when creating a package or installing
to an embedded filesystem, use the DESTDIR make variable when installing:

make DESTDIR=/tmp install-strip

If the prefix is /usr/local, this will install to /tmp/usr/local.

A number of utilities are used with db.*. To select which utilities to build,
give configure the --enable-tools option:

./configure --enable-tools="ddlp dbinit"

By default, all utilities are enabled. To build no utilities, use the
--disable-tools option.

db.* comes with several example programs. To select which example programs to build, use the --enable-examples option:

./configure --enable-examples="bom tims"

By default, all examples are enabled. To build no examples, use the
--disable-examples option.


Cross-compiling db.*
====================

Cross-compiling allows the db.* library to be compiled on one system
architecture and deployed on another. To cross-compile db.*, you will 
need a cross-compiler, build tools (assembler, linker), and shared libraries 
for your target architecture.

First you will need to build the ddlp utility for your native development
environment in order to create db.* applications, such as the test suite:

mkdir build-native
cd build-native
../configure --enable-tools="ddlp" --disable-examples
make

Next set the environment variables necessary to cross-compile
export CC=/path/to/cross-compile/tools/gcc 
export LD=/path/to/cross-compile/tools/ld 
export AS=/path/to/cross-compile/tools/as  
export AR=/path/to/cross-compile/tools/ar 

Now build a cross-compiled version of the library:

cd ..
mkdir build-cross
cd build-cross
../configure --disable-tools --disable-examples \
             --build=build_arch-build_os --host=cross_arch-cross_os
make

You should replace build_arch and build_os with the architecture and operating
system of the machine you are building on, e.g. --build=i686-redhat-linux-gnu.
Sometimes --build is detected automatically. Similarly, you should replace
cross_arch and cross_os with the architecture and operating system of the
system you are cross-compling for, e.g. --host=arm-linux.

Finally, install the files to the target filesystem:

make DESTDIR=/mnt/target-system install-strip

To ensure that the libraries are installed correctly, you may want to install
the test suite program. Use the installcheck make rule to build and install the
testdbstar program:

make DDLP=/full/path/to/dbstar/build-native/utilities/ddlp DESTDIR=/mnt/target-system installcheck

The ddlp utility is needed to build any applications that use db.*, such as 
the test suite. By setting the DDLP variable when running make, the test suite
will be able to run the version of ddlp that was generated for your build
environment.


Verification
============

A test suite is included with db.* to automatically test basic functionality.
To run these tests, use:

make check

A script to analyze d_ function test coverage may be run:
    ./usage.bsh examples/ > d_usage.txt

An example of db.star.ini is included showing default values.   


About
=====

This software is an open source database kernel, db.*, distributed by ITTIA.

ITTIA - U.S. Headquarters
1611 116th Avenue NE Suite 202
Bellevue Washington 98004
USA

Download the latest version of db.* at http://www.ittia.com