MacroScope, as a software component, consists of 2 DLLs: MacroScope and Glaze (the confusing naming is due, as usual, to historical reasons). MacroScope DLL is the base, doing SQL parsing and defining the object model, while Glaze DLL implements an ADO.NET provider on top of it.
MacroScope code is C#, using .NET 2.0 and tested only on Windows (lately Vista, but it did work on XP and there's no technical reason it couldn't be maintained there; other platforms - Mono, or Windows CE
- are untested and probably more complicated).
SQL parsing in MacroScope is based on an ANTLR (http://www.antlr.org/) grammar. That leads to compact, high-level, easily extendable (after you learn ANTLR) definition of the SQL variety parsed by MacroScope, which is otherwise hard to document precisely - it's a subset of SQL 92 definitions of the basic CRUD commands, but also includes many non-standard constructions taken from the supported backends. Negative consequences of a code generator include build complications and a run time dependency on an ANTLR DLL. The ANTLR project, including especially the ANTLR C# target and runtime, has been undergoing radical changes, so when building MacroScope, it's important to use compatible versions. This release has been tested with ANTLR 3.1; it is incompatible with earlier versions of ANTLR and later ANTLR versions may also require fixing the grammar.
ANTLR, which is a Java program, isn't actually necessary to build MacroScope, as long as the SQL grammar (file MacroScope\MacroScope.g) doesn't change - the generated files as well as ANTLR runtime DLL are included in the distribution. When rebuilding the generated files, it's necessary to be able to run
java org.antlr.Tool
from your command line - in other words, all ANTLR jars should be in the CLASSPATH. For details about which jars these might be, see the ANTLR installation documentation.
MacroScope build is automated using NAnt (http://nant.sourceforge.net/). The build structure is a bit unusual in that it's controlled by the top-level build script (file MacroScope.build), but all other NAnt scripts needed by the build are generated by XSL transformations, using Visual Studio project files as input. This allows the use of Visual Studio IDE for all development (including adding source files to the projects, i.e. when extending the object model) except grammar changes and running unit tests. The default build target of the top-level build script compiles both MacroScope and Glaze DLLs.
MacroScope unit tests are implemented with NUnit (http://www.nunit.org/index.php). Testing the actual database usage is a bit complicated: some people - the maintainer, for example - will want to test all the supported database backends while others won't even have them installed, so testing Glaze is disabled by default. This release uses NUnit version 2.2.6, which is compatible with NAnt 0.85. Newer versions of NUnit are not entirely compatible and require some additional configuration to make them work - if you have a problem running tests, google for details. MacroScope tests are in the TestMacroScope project and are run by executing
nant test
in the top-level distribution directory.
To make the test target interact with a database backend, create a config file TestGlaze.exe.config in the TestGlaze\bin\Debug directory with database configuration. An example TestGlaze.exe.config is available in the schema directory, but you'll have to remove the keys for backends you don't have from appSettings and change the remaining values to the connection strings correct for your setup. Databases specified by these connection strings must also be created manually, with the tables described in files in the schema directory - more-or-less machine-readable scripts for MySQL, MS SQL Server and Oracle, with the MS SQL Server commands doubling as instructions for how to create a MS Access test database by point-and-click.
Glaze has some logging statements, implemented using log4net (http://logging.apache.org/log4net/), so applications that depend on it should configure the framework to get the level and direction of logging they prefer - see log4net documentation for details. MacroScope DLL doesn't have any logging and can be used independently of log4net. For logging facility names, Glaze logging uses (as is conventional with log4net) class names of classes containing the logging statements, for example "Glaze.GlazeParameterCollection", with the exception of class GlazeCommand, which has 2 facilities: "Glaze.GlazeCommand", logging the commands which update the backend database, and "Glaze.GlazeCommand select", logging read accesses.
Questions and problems about building, using and improving MacroScope should be addressed to the mailing list [email protected]. Note that you must subscribe to the list before you can send messages to it
- you can do that either by sending an e-mail to [email protected], or at http://www.mangrove.cz/lists/macroscope . Some basic usage examples (which aren't supposed to do anything, and don't even work because they miss a database) are available in the Expo directory.