The MetaKit Library 2.4.3                                        Februari 2002
==============================================================================


WHAT IT IS - MetaKit is an embeddable database which runs on Unix, Windows,
    Macintosh, and other platforms.  It lets you build applications which
    store their data efficiently, in a portable way, and which will not need a
    complex runtime installation.  In terms of the data model, MetaKit takes
    the middle ground between RDBMS, OODBMS, and flat-file databases - yet it
    is quite different from each of them.

TECHNOLOGY - Everything is stored variable-sized yet with efficient positional
    row access.  Changing an existing datafile structure is as simple as re-
    opening it with that new structure.  All changes are transacted, including
    restructuring.  You can mix and match software written in C++, Python,
    and Tcl.  Things can't get much more flexible...

CORE - The Metakit core library is written in C++.  It has a code footprint of
    just over 100 Kb on Windows.  It can be used as DLL, or linked statically.
    Debug builds include extensive assertion checks to catch problems early.

PYTHON - The binding for Python is called "Mk4py".  It uses SCXX by Gordon
    McMillan as C++ glue interface.  The source is in directory "python/".

TCL/TK - The MK extension for Tcl is called "Mk4tcl".  It is being used in a
    number of commercial projects, for in-house use as well as in commercially
    distributed products.  The source is in directory "tcl/".

LICENSE AND SUPPORT - MetaKit is now distributed as open source software (the
    X/MIT-style license is at the end of this document).  Commercial support
    is available through an Enterprise License, see the URL mentioned below.

DOCUMENTATION - All documentation uses HTML.  The main page is "MetaKit.html",
    which leads to the rest of the documentation in the "doc/" directory.
    The C++ API Reference is extracted from the source code using Doxygen.

WEBSITE URLS - The main pages on the world wide web, for news and downloads:
    Homepage:       http://www.equi4.com/metakit/
    Python news:    http://www.equi4.com/metakit/python.html
    Tcl/Tk news:    http://www.equi4.com/metakit/tcl.html
    License info:   http://www.equi4.com/metakit/license.html
    Contact info:   http://www.equi4.com/contact.html

ACKNOWLEDGEMENTS - Thanks to everyone who has helped shape and extend MetaKit,
    including Kyrill Denisenko, Mark Roseman, Gordon McMillan, Matt Newman,
    Christian Tismer, John Bushakra, Steve Landers, Jacob Levy, John Barnard,
    and many more people who have reported bugs and helped fix them.  Last
    but not least, many thanks to all enterprise license customers and all
    my clients for funding MetaKit work.


INSTALLATION
============

Starting with this release, all platform builds and language bindings are now
designed to work from a single common "builds/" directory.  It turns out to
be impossible to keep build side-effects limited to *just* this directory
(CodeWarrior can't be told where to place its temp data, and Visual C++ still
alters a few files next to the project ".dsw" file, to name two offenders).

UNIX

    It is no longer advised to build the Unix code in the "unix/" directory.
    Instead, you should perform the following steps:
        % cd builds
        % ../unix/configure
        % make
        % make test
    And optionally (this only installs the core lib, not script extensions):
        % make install

    By switching to the "builds/" directory, you will keep the distribution
    directory tree 100% unaltered.  All changes are made in this subdir, and
    all final build results are left behind in this same subdir.

    To build with STL containers and strings, you can do the following:
        make CXXFLAGS='-Dq4_STD' test   # add -O3 etc, as needed

    To build the Mk4py extension on Unix, change the configure to:
        % ../unix/configure --enable-python     (tweak if not Python 2.1)

    To build the Mk4tcl extension on Unix, change the configure to:
        % ../unix/configure --with-tcl=<dir-where-tclConfig.sh-is>

    See below for some platform-specific build notes.

WINDOWS

    There is a "win/" directory which contains subdirectories for a number of
    compiler systems.  MetaKit has been built with many different compilers
    in the past (Microsoft, Borland, Watcom, Symantec, Metrowerks, Optima),
    only a few are maintained (there are 12 configurations for MSVC6 alone!).

    The MS Visual C++ 6.0 project is "win/msvc60/mksrc.dsw", with subprojects
    for the C++ demo (mkdemo), building dll's (mkdll), static libs (mklib),
    regression tests (mktest), as well as Tcl (mktcl) and Python (mkpython).
    It has been set up to place all intermediate files and final results in
    the "builds/" subdirectory, even though you'll launch it from "win/".

    To build with STL containers and strings under MSVC, define "q4_STD".
    To build with MFC containers and strings under MSVC, define "q4_MFC".

    The Metrowerks Codewarrior project is in the "mac/" directory, and can be
    used to build both Mac and Windows versions (on either Mac *or* Windows).
    The core libraries are built with "mac/cw5.mcp", demos / tests are built
    with "cw5apps.mcp", Tcl is "cw5tcl.mcp", and Python is "cw5python.mcp".

    The Borland C++ Builder projects have not yet been incorporated in this
    release, but the "KitViewer" application is an example of how to use BCB.

    The Cygwin build (B20.1 / gcc 2.95.2) is different, because it uses the
    unix autoconf system, and must be launched as described above for UNIX.
    I have upgraded to the latest development of libtool to be able to build
    DLL's with Cygwin.  You can build the "-mno-cygwin" version by editing
    the Makefile by hand and adding that option to CXXFLAGS.

    Rob Bloodgood adds that the following GCC options are for maximum code
    efficiency on x86 hardware: "-O2 -m486 -malign-loops=2 -malign-jumps=2".
    I have not yet tried this myself, but am passing on the tip.

MACINTOSH

    The Mac version requires Metrowerks CodeWarrior 6.  See the info above
    in the Windows section (MWCW is multi-platform).  The projects are all
    located in the "mac/" folder, which is also where MWCW will place its own
    "... Data" folders with intermediate results.  As with all other setups,
    final results are made to end up in the "builds/" directory.


PLATFORM-SPECIFIC NOTES
=======================

* Linux / gcc 2.95.2

    Builds with gcc 2.95.2 work out of the box.  The Python extension ends up
    as Mk4py.so (ignore libmk4py.*), the Tcl extension is called Mk4tcl.so
    (ignore libmk4tcl.*).

    The core MK libs end up as ".libs/libmk4.a" and ".libs/libmk4.so.0.0.0".
    The .0.0.0 stuff comes from libtool, I usually rename it to "libmk4.so".

* FreeBSD 4.4-RELEASE

    Builds should now work out of the box (thanks Dirk Meyer).  If you first
    install Tcl 8.3 and Python 2.1, then you can build and test it all with:
    	cd builds
	../unix/configure --with-tcl=/usr/local/lib/tcl8.3 --enable-python
	make test test-tcl
    The "make install" command has the same messiness for Mk4*.so as Linux.

* Solaris 2.6 / gcc 2.8.1

    The gcc 2.8.1 optimizer appears to be buggy, I have had to turn off the
    default "-O3" flag to prevent compiler crashes (for a number of files).
    This problems appears to be resolved with gcc 2.95.

* Other Unix systems

    No further notes, most systems should build just fine.

* Windows

    MSVC 6 builds MK as static lib and as DLL (universal config, I have not
    yet created build versions with MFC or STL, mainly because MK can now be
    used in all contexts regardless of how it was built).  The Python and Tcl
    extensions build as dynamic extensions (a static build is easy to add).

    MWCW 5 (that's Metrowerks) builds as static lib and as DLL (interestingly
    enough, the DLL is slightly smaller than MSVC 6 - 102 vs 108 Kb - when
    their runtimes are linked in dynamically as well).  I have not added Win
    builds for Tcl or Python, since MSVC 6 has those already.

    Cygwin B20.1, with gcc 2.95.2 ugrade, also builds MK as static lib and as
    DLL.  Both "pure" Cygwin (i.e. requiring cygwin1.dll) and mingw32 (using
    the -mno-cygwin flag) build, but there are some hairy include issues when
    it comes to choosing the right locking model for Tcl and Python.  These
    issues have not been resolved fully.

* Macintosh

    MWCW 6 builds 4 libs: PPC and 68K, static and shared.

    Regression tests and demo apps are built from the cw5app project.
    Two additional projects can be used to build Python and Tcl extensions.

* BeOS

    John Bushakra has ported MK to BeOS, apparently just minor #define tweaks.
    His changes will be incorporated in the 2.3 release, see the beos/ subdir.

* VMS, ...

    No news yet, please report your findings with any other platform builds.


LICENSE AND COPYRIGHT STATEMENT
===============================

Copyright (c) 1996-2001 Jean-Claude Wippler

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.


==============================================================================
-- Jean-Claude Wippler <jcw@equi4.com>