1The Metakit Library 2.4.9.7 Jun 2007
2==============================================================================
3
4
5WHAT IT IS - Metakit is an embeddable database which runs on Unix, Windows,
6 Macintosh, and other platforms. It lets you build applications which
7 store their data efficiently, in a portable way, and which will not need a
8 complex runtime installation. In terms of the data model, Metakit takes
9 the middle ground between RDBMS, OODBMS, and flat-file databases - yet it
10 is quite different from each of them.
11
12TECHNOLOGY - Everything is stored variable-sized yet with efficient positional
13 row access. Changing an existing datafile structure is as simple as re-
14 opening it with that new structure. All changes are transacted, including
15 restructuring. You can mix and match software written in C++, Python,
16 and Tcl. Things can't get much more flexible...
17
18CORE - The Metakit core library is written in C++. It has a code footprint of
19 just over 100 Kb on Windows. It can be used as DLL, or linked statically.
20 Debug builds include extensive assertion checks to catch problems early.
21
22PYTHON - The binding for Python is called "Mk4py". It uses SCXX by Gordon
23 McMillan as C++ glue interface. The source is in directory "python/".
24
25TCL/TK - The MK extension for Tcl is called "Mk4tcl". It is being used in a
26 number of commercial projects. The source is in directory "tcl/".
27
28LICENSE AND SUPPORT - Metakit is distributed as open source software (see the
29 X/MIT-style license at the end of this document). Commercial support is
30 available through an Enterprise License, see the URL mentioned below.
31
32DOCUMENTATION - All documentation uses HTML. The main page is "Metakit.html",
33 which leads to the rest of the documentation in the "doc/" directory.
34 The C++ API Reference is extracted from the source code using Doxygen.
35
36WEBSITE URLS - The main pages on the world wide web, for news and downloads:
37 Homepage: http://www.equi4.com/metakit.html
38 Python news: http://www.equi4.com/metakit/python.html
39 Tcl/Tk news: http://www.equi4.com/metakit/tcl.html
40 License info: http://www.equi4.com/metakit/license.html
41 Contact info: http://www.equi4.com/about/contact.html
42
43ACKNOWLEDGEMENTS - Thanks to everyone who has helped shape and extend Metakit,
44 including Kyrill Denisenko, Mark Roseman, Gordon McMillan, Matt Newman,
45 Christian Tismer, John Bushakra, Steve Landers, Jacob Levy, John Barnard,
46 Nicholas Riley, Brian Kelley, and many more people who have reported bugs
47 and helped fix them. Last but not least, many thanks to all enterprise
48 license customers and all my clients for funding Metakit work.
49
50
51INSTALLATION
52============
53
54All platform builds and language bindings are designed to work from a single
55common "builds/" directory. Where possible, that is - it turns out to be
56impossible to keep build side-effects limited to *just* this directory
57(CodeWarrior can't be told where to place its temp data, and Visual C++ still
58alters a few files next to the project ".dsw" file, to name two offenders).
59
60PYTHON - Nov 2006
61
62 There is a --with-python option in unix/configure, but it does not always
63 seem to work. One problem is python version numbers being hard-wired into
64 the configure/make files (2.5 right now). This worked for me on Mac OS X:
65 cd builds
66 ../unix/configure \
67 --with-python=/Library/Frameworks/Python.framework/Versions/2.5
68 ln -s Mk4py.dylib Mk4py.so
69 Note that the arg to --with-python is the path *upto* include/python2.5
70
71 There is also a python/setup.py script which should simplify building for
72 Python. Unfortunately, it does things in a somewhat tricky way in that
73 it uses MK's .o files from the builds/ directory. This in turn means
74 that on Mac OS X, you'll need to hack things a bit to make these .o's end
75 up as "fat" (ppc+i386) binaries since setup.py needs them that way.
76
77 Here's how a non-macosx build should work:
78 cd builds
79 sh ../unix/configure
80 make test
81 cd ../python
82 python setup.py clean build
83 The result will be left in ../builds/lib.*/{Mk4py.so,metakit.py}
84
85 For Mac OS X, you need to hack ../builds/Makefile after running configure:
86 * change "CXXFLAGS = $(CXX_FLAGS)" to "CXXFLAGS = $(CXX_FLAGS) \
87 -arch ppc -arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk"
88 * change "SHLIB_LD = g++" to "SHLIB_LD = g++ -dynamiclib \
89 -flat_namespace -undefined suppress -arch ppc -arch"
90 Then do the rest, using "make" i.s.o. "make test" because the changes to
91 the flags don't seem to create proper executables. That's ok though, the
92 .o files are fat, which is all setup.py needs.
93
94TCL - Jun 2007
95
96 The Tcl build has been converted to use the TEA3-based configure script
97 in the tcl/ directory. The way to build Mk4tcl is now as follows:
98
99 mkdir tbuild # can be anywhere, really...
100 cd tbuild
101 CC=g++ sh ../tcl/configure
102 make
103 make test
104 make install
105
106 This build configuration has not yet been tested with non-gcc compilers.
107 There are no dependencies on the C++ build process, nor the builds/ dir.
108
109 Note: for Windows CE, an older version of the tcl.configure script was
110 successfully used with MS EVC3. One trick is that in tcl/configure.in,
111 "TEA_ADD_CFLAGS([])" has to be changed to "TEA_ADD_CFLAGS([-Dq4_WINCE])".
112
113UNIX (ALSO MAC OS X)
114
115 It is no longer advised to build the Unix code in the "unix/" directory.
116 Instead, you should perform the following steps:
117 cd builds
118 sh ../unix/configure
119 make
120 make test
121 And optionally (this only installs the core lib, not script extensions):
122 make install
123
124 By switching to the "builds/" directory, you will keep the distribution
125 directory tree 100% unaltered. All changes are made in this subdir, and
126 all final build results are left behind in this same subdir.
127
128 To build with STL containers and strings, you can do the following:
129 make CXXFLAGS='-Dq4_STD' test # add -O3 etc, as needed
130
131 OLD: to build the Mk4tcl extension on Unix, change the configure to:
132 ../unix/configure --with-tcl=<dir-where-tcl.h-is>
133 OLD: to build the Mk4py extension on Unix, change the configure to:
134 ../unix/configure --with-python=<dir-where-include/-is>
135 E.g.
136 ../unix/configure --with-tcl=/usr/include --with-python=/usr
137
138 Use "../unix/configure --help" to find out about other variants, when the
139 include & lib dirs are completely different, and for other build options.
140
141WINDOWS
142
143 There is a "win/" directory which contains subdirectories for a number of
144 compiler systems. Metakit has been built with many different compilers
145 in the past (Microsoft, Borland, Watcom, Symantec, Metrowerks, Optima),
146 only a few are maintained (there are 12 configurations for MSVC6 alone!).
147
148 The MS Visual C++ 6.0 project is "win/msvc60/mksrc.dsw", with subprojects
149 for the C++ demo (mkdemo), building dll's (mkdll), static libs (mklib),
150 regression tests (mktest), as well as Tcl (mktcl) and Python (mkpython).
151 It has been set up to place all intermediate files and final results in
152 the "builds/" subdirectory, even though you'll launch it from "win/".
153
154 An MSVC 7.0 project by David Van Maren is in win/msvc70/mksrc.sln.
155
156 To build with STL containers and strings under MSVC, define "q4_STD".
157 To build with MFC containers and strings under MSVC, define "q4_MFC".
158
159 The Metrowerks Codewarrior project is in the "mac/" directory, and can be
160 used to build both Mac and Windows versions (on either Mac *or* Windows).
161 The core libraries are built with "mac/cw5.mcp", demos / tests are built
162 with "cw5apps.mcp", Tcl is "cw5tcl.mcp", and Python is "cw5python.mcp".
163
164 The Borland C++ Builder projects have not yet been incorporated in this
165 release, but the "KitViewer" application is an example of how to use BCB.
166
167 The Cygwin build (B20.1 / gcc 2.95.2) is different, because it uses the
168 unix autoconf system, and must be launched as described above for UNIX.
169 I have upgraded to the latest development of libtool to be able to build
170 DLL's with Cygwin. You can build the "-mno-cygwin" version by editing
171 the Makefile by hand and adding that option to CXXFLAGS.
172
173 Rob Bloodgood adds that the following GCC options are for maximum code
174 efficiency on x86 hardware: "-O2 -m486 -malign-loops=2 -malign-jumps=2".
175 I have not yet tried this myself, but am passing on the tip.
176
177
178LICENSE AND COPYRIGHT STATEMENT
179===============================
180
181Copyright (c) 1996-2007 Jean-Claude Wippler
182
183Permission is hereby granted, free of charge, to any person obtaining a
184copy of this software and associated documentation files (the "Software"),
185to deal in the Software without restriction, including without limitation
186the rights to use, copy, modify, merge, publish, distribute, sublicense,
187and/or sell copies of the Software, and to permit persons to whom the
188Software is furnished to do so, subject to the following conditions:
189
190The above copyright notice and this permission notice shall be included
191in all copies or substantial portions of the Software.
192
193THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
194OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
195FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
196THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
197LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
198FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
199DEALINGS IN THE SOFTWARE.
200
201
202==============================================================================
203-- Jean-Claude Wippler <jcw@equi4.com>
204