README.metakit

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