README.metakit

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