1 For your convenience (and with the author's permission) a copy of the
2 MetaKit source is bundled with SimGear. You must have metakit
3 installed before you can build SimGear.
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.
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.
15 Once metakit is installed you can return to configuring and building
18 =============================================================================
20 Potentially important build note:
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
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
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
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
43 Now we return you to the official metakit readme ... :-)
46 The MetaKit Library 2.01 March 2000
47 ==============================================================================
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.
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.
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
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.
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/".
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/".
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.
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.
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
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).
103 It is no longer advised to build the Unix code in the "unix/" directory.
104 Instead, you should perform the following steps:
109 And optionally (this only installs the core lib, not script extensions):
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.
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.
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.
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.
128 See below for some platform-specific build notes.
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.
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/".
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".
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".
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.
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.
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.
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.
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).
177 PLATFORM-SPECIFIC NOTES
178 =======================
180 * Linux RH 5.2 / gcc 2.95.2
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.
187 The core MK libs end up as ".libs/libmk4.a" and ".libs/libmk4.so.0.0.0".
189 * Solaris 2.6 / gcc 2.8.1
191 The Solaris builds are nasty for several reasons:
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.
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.
208 No further notes, though many systems will build fine out of the box.
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).
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.
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.
230 MWCW 5 builds PPC shared libs, PPC static libs, and 68K static libraries.
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.
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%).
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.
246 No news yet, please report your findings with any other platform builds.
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 :)
260 LICENSE AND COPYRIGHT STATEMENT
261 ===============================
263 Copyright (c) 1996-2000 Jean-Claude Wippler
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:
272 The above copyright notice and this permission notice shall be included
273 in all copies or substantial portions of the Software.
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.
284 ==============================================================================
285 -- Jean-Claude Wippler <jcw@equi4.com>