README.metakit

   1 With the author's permission, SimGear now bundles MetaKit.  MetaKit is
   2  explained
   3
   4 The MetaKit Library 2.01                                            March 2000
   5 ==============================================================================
   6
   7
   8 WHAT IT IS - MetaKit is an embeddable database which runs on Unix, Windows,
   9     Macintosh, and other platforms.  It lets you build applications which
  10     store their data efficiently, in a portable way, and which will not need a
  11     complex runtime installation.  In terms of the data model, MetaKit takes
  12     the middle ground between RDBMS, OODBMS, and flat-file databases - yet it
  13     is quite different from each of them.
  14
  15 WHAT IT ISN'T - MetaKit is not: 1) multi-user/-threading, 2) scalable to
  16     gigabytes, 3) proprietary software, 4) full of bugs, 5) just a toy.
  17
  18 TECHNOLOGY - Everything is stored variable-sized yet with efficient positional
  19     row access.  Changing an existing datafile structure is as simple as re-
  20     opening it with that new structure.  All changes are transacted.  You can
  21     mix and match software written in C++, Python, and Tcl.  Things can't get
  22     much more flexible...
  23
  24 CORE - The Metakit core library is written in C++.  It has a code footprint of
  25     just over 100 Kb on Windows.  It can be used as DLL, or linked statically.
  26     Debug builds include extensive assertion checks to catch problems early.
  27
  28 PYTHON - The binding for Python is called "Mk4py".  It uses SCXX by Gordon
  29     McMillan as C++ glue interface.  The source is in directory "python/".
  30
  31 TCL/TK - The MK extension for Tcl is called "Mk4tcl".  It is being used in a
  32     number of commercial projects, for in-house use as well as in commercially
  33     distributed products.  The source is in directory "tcl/".
  34
  35 LICENSE AND SUPPORT - MetaKit 2.01 is distributed as open source software (the
  36     X/MIT-style license is at the end of this document).  Commercial support
  37     is available through an Enterprise License, see the URL mentioned below.
  38
  39 DOCUMENTATION - All documentation uses HTML.  The main page is "MetaKit.html",
  40     which leads to the rest of the documentation in the "doc/" directory.
  41
  42 WEBSITE URLS - The main pages on the world wide web, for news and downloads:
  43     Homepage:       http://www.equi4.com/metakit/
  44     Python news:    http://www.equi4.com/metakit/python.html
  45     Tcl/Tk news:    http://www.equi4.com/metakit/tcl.html
  46     License info:   http://www.equi4.com/metakit/license.html
  47     Contact info:   http://www.equi4.com/contact.html
  48
  49
  50 INSTALLATION
  51 ============
  52
  53 Starting with this release, all platform builds and language bindings are now
  54 designed to work from a single common "builds/" directory.  It turns out to
  55 be impossible to keep build side-effects limited to *just* this directory
  56 (CodeWarrior can't be told where to place its temp data, and Visual C++ still
  57 alters a few files next to the project ".dsw" file, to name two offenders).
  58
  59 UNIX
  60
  61     It is no longer advised to build the Unix code in the "unix/" directory.
  62     Instead, you should perform the following steps:
  63         % cd builds
  64         % ../unix/configure
  65         % make
  66         % make test
  67     And optionally (this only installs the core lib, not script extensions):
  68         % make install
  69
  70     By switching to the "builds/" directory, you will keep the distribution
  71     directory tree 100% unaltered.  All changes are made in this subdir, and
  72     all final build results are left behind in this same subdir.
  73
  74     Nastiness: if you build Mk4tcl, please do a "make Mk4tcl.so" as well.
  75     And if you intend to create the Python extension, do a "make Mk4py.so".
  76     The "libmk4tcl.so.0.0.0" and "libMk4py.so.0.0.0" targets are bogus ones.
  77
  78     You will probably have to make changes in the makefile to locate the
  79     proper includes and libs for Python (Tcl has been fixed, see "--with-tcl).
  80     You probably only need to adjust "CXX_SWITCHES_PY" to find the headers.
  81
  82     To build with STL containers and strings, you can do the following:
  83         make CXXFLAGS='-Dq4_STD' test   # add -O3 etc, as needed
  84     This passes the test suite on Linux RedHat 5.2 with gcc 2.95-2.
  85
  86     See below for some platform-specific build notes.
  87
  88 WINDOWS
  89
  90     There is a "win/" directory which contains subdirectories for a number of
  91     compiler systems.  MetaKit has been built with many different compilers
  92     in the past (Microsoft, Borland, Watcom, Symantec, Metrowerks, Optima),
  93     but to preserve my sanity (there are 12 configurations for MSVC6 alone!),
  94     I am limiting myself to MSVC6, MWCW5, Borland C++ Builder 4, and Cygwin.
  95
  96     The MS Visual C++ 6.0 project is "win/msvc60/mksrc.dsw", with subprojects
  97     for the C++ demo (mkdemo), building dll's (mkdll), static libs (mklib),
  98     regression tests (mktest), as well as Tcl (mktcl) and Python (mkpython).
  99     It has been set up to place all intermediate files and final results in
 100     the "builds/" subdirectory, even though you'll launch it from "win/".
 101
 102     To build with STL containers and strings under MSVC, define "q4_STD".
 103     To build with MFC containers and strings under MSVC, define "q4_MFC".
 104
 105     The Metrowerks Codewarrior project is in the "mac/" directory, and can be
 106     used to build both Mac and Windows versions (on either Mac *or* Windows).
 107     The core libraries are built with "mac/cw5.mcp", demos / tests are built
 108     with "cw5apps.mcp", Tcl is "cw5tcl.mcp", and Python is "cw5python.mcp".
 109
 110     The Borland C++ Builder projects have not yet been incorporated in this
 111     release, but the "KitViewer" application is an example of how to use BCB.
 112
 113     The Cygwin build (B20.1 / gcc 2.95.2) is different, because it uses the
 114     unix autoconf system, and must be launched as described above for UNIX.
 115     I have upgraded to the latest development of libtool to be able to build
 116     DLL's with Cygwin.  You can build the "-mno-cygwin" version by editing
 117     the Makefile by hand and adding that option to CXXFLAGS.
 118
 119     Rob Bloodgood adds that the following GCC options are for maximum code
 120     efficiency on x86 hardware: "-O2 -m486 -malign-loops=2 -malign-jumps=2".
 121     I have not yet tried this myself, but am passing on the tip.
 122
 123 MACINTOSH
 124
 125     The Mac version requires Metrowerks CodeWarrior 5.  See the info above
 126     in the Windows section (MWCW is multi-platform).  The projects are all
 127     located in the "mac/" folder, which is also where MWCW will place its own
 128     "... Data" folders with intermediate results.  As with all other setups,
 129     final results are made to end up in the "builds/" directory.
 130
 131     Static 68K builds appear to work fine, the 68K CFM variants will need
 132     some more work (I couldn't get the libraries to export their symbols).
 133
 134
 135 PLATFORM-SPECIFIC NOTES
 136 =======================
 137
 138 * Linux RH 5.2 / gcc 2.95.2
 139
 140     Builds with gcc 2.95.2 work out of the box.  The Tcl extension ends up as
 141     ".libs/libmk4tcl.so.0.0.0" (to please libtool), and should be renamed to
 142     "Mk4tcl.so".  Similarly, ".libs/libMk4py.so.0.0.0" is in fact the Python
 143     extension, and *must* be renamed to "Mk4py.so" to call it from Python.
 144
 145     The core MK libs end up as ".libs/libmk4.a" and ".libs/libmk4.so.0.0.0".
 146
 147 * Solaris 2.6 / gcc 2.8.1
 148
 149     The Solaris builds are nasty for several reasons:
 150
 151     - I do not own such a machine, and often have to make arrangements
 152       (or fight limited space on one of the machines I can telnet to).
 153     - The gcc 2.8.1 optimizer appears to be buggy, I have had to turn off
 154       the default "-O3" flag to prevent compiler crashes (several files).
 155       This problems appears to be resolved with gcc 2.95.
 156     - Locking on Solaris (especially w.r.t NFS) remains a mystery to me.
 157       The Tcl and Python extensions both use locking (the core not yet).
 158       See tcl/Mk4tcl.cpp around line 520, and python/PyStorage.cpp around
 159       line 80 for details.  It's all pretty messy, and not 100% correct.
 160
 161     Despite this, I'm doing my best to resolve these issues.  Having a solid
 162     build of the core *and* of Tcl / Python extensions is quite important.
 163
 164 * Other Unix systems
 165
 166     No further notes, though many systems will build fine out of the box.
 167
 168 * Windows
 169
 170     MSVC 6 builds MK as static lib and as DLL (universal config, I have not
 171     yet created build versions with MFC or STL, mainly because MK can now be
 172     used in all contexts regardless of how it was built).  The Python and Tcl
 173     extensions build as dynamic extensions (a static build is easy to add).
 174
 175     MWCW 5 builds MK as static lib and as DLL (interestingly enough, the DLL
 176     is slightly smaller than MSVC 6 - 102 vs 108 Kb - when their runtimes are
 177     linked in dynamically as well).  I have not added Win builds for Tcl or
 178     Python, since MSVC 6 has those already.
 179
 180     Cygwin B20.1, with gcc 2.95.2 ugrade, also builds MK as static lib and as
 181     DLL.  Both "pure" Cygwin (i.e. requiring cygwin1.dll) and mingw32 (using
 182     the -mno-cygwin flag) build, but there are some hairy include issues when
 183     it comes to choosing the right locking model for Tcl and Python.  These
 184     issues have not been resolved fully.
 185
 186 * Macintosh
 187
 188     MWCW 5 builds PPC shared libs, PPC static libs, and 68K static libraries.
 189
 190     Building 68K CFM libraries leads to a "MetaKit 68K.shlb" which comes out
 191     of the linker without errors, but the result does not seem to have any
 192     export symbols defined (despite the fact that the library is over 200 K).
 193     Because of that, I've been unable to build apps or Mk4tcl/Mk4py so far.
 194
 195     The other three configurations build, but for some reason MK's regression
 196     test stops at L03 (everything up to that point looks ok, i.e. over 90%).
 197
 198     The Mk4tcl PPC extension appears to work (quick manual test), and so does
 199     the Python extension, "Mk4py.PPC.slb".  I have not yet given these two
 200     a serious workout, hoping to have a basic test harness in place soon.
 201
 202 * VMS, BeOS, ...
 203
 204     No news yet, please report your findings with any other platform builds.
 205
 206
 207 WHAT'S MISSING HERE
 208 ===================
 209
 210     - a section on basic concepts (or maybe it doesn't belong here?)
 211     - a section on getting started (C++, Python, Tcl all differ - point to
 212       the respective intro pages)
 213     - maybe a small sample for each of C++ / Tcl / Python, to give an idea
 214     - mention TclKit, scripted docs (WiKit/Tequila?), VFS?
 215     - I forgot... please tell me :)
 216
 217
 218 LICENSE AND COPYRIGHT STATEMENT
 219 ===============================
 220
 221 Copyright (c) 1996-2000 Jean-Claude Wippler
 222
 223 Permission is hereby granted, free of charge, to any person obtaining a
 224 copy of this software and associated documentation files (the "Software"),
 225 to deal in the Software without restriction, including without limitation
 226 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 227 and/or sell copies of the Software, and to permit persons to whom the
 228 Software is furnished to do so, subject to the following conditions:
 229
 230 The above copyright notice and this permission notice shall be included
 231 in all copies or substantial portions of the Software.
 232
 233 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 234 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 235 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 236 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 237 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 238 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 239 DEALINGS IN THE SOFTWARE.
 240
 241
 242 ==============================================================================
 243 -- Jean-Claude Wippler <jcw@equi4.com>