[Instantobjects-cvscommit] Docs Source_Tree_Structure.txt,NONE,1.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/instantobjects/Docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14327

Added Files:
	Source_Tree_Structure.txt 
Log Message:
source tree documentation for IO developers

--- NEW FILE: Source_Tree_Structure.txt ---
Structure of the InstantObjects source tree
===========================================
Nando Dessena, 02/2005

Abstract
--------
The following notes document the structure of the InstantObjects tree as stored in CVS, explaining what each folder is for.

Modules
-------
Currently IO is made up of 4 (mostly independent) modules; future versions might be organized differently. Here is a list of the 4 modules:

Demos: contains demo projects aimed at the IO newbie. There is a subfolder for each applciation:

- Intro: the bare bones demo application, whose building process is shown in the famous IO introductory video.

- PrimerCross: the cross-platform version of the more juicy Primer example. This folder also contains a PrimerExternal.dpr project that makes use of external storage.

- Pump: a straightforward application that shows how to use the InstantPump component.

- Test: in a subfolder called BuildPrimerDatabase you'll find a console application that demonstrates building and populating an InstantObjects database.

The Demos folder must be a sibling of the Source folder (they're not completely independent).

Docs: Here you'll find some developer and user docs, mostly in the form of txt files. User docs here are in their primal form, not intended for direct user consumption but rather as the basis for the help maintainers and docs for testers. This folder might use a restructure.

Help: sources for the IO user docs/help.

Source: here is where all the IO code is stored. The Source folder has a number of subfolders each containing a different part of the code base. I'll document the inner structure of the folders in later sections, but here is a summary:

- Brokers: base folder for all the persistence brokers (one subfolder each).

- Core: the core run time stuff, or the heart of IO.

- Design: the design-time companion (Model Explorer, etc.).

- ObjectFoundry: ModelMaker integration expert/add-in.

- Tests: holds the IO automated unit test infrastructure and the actual test code.

The Source\Brokers folder
-------------------------
Here we have a subfolder for each supported broker. A broker is a means for IO to use as storage a particular database engine through a particular middleware. There are two main kinds of IO object brokers: dataset-based and SQL-based; the latter offer better performance and additional features (like external storage) when you use a SQL-enabled database engine. Here is a list of the currently supported brokers:

ADO: for MS Access (table-based) and MS SQL Server (SQL-based) through ADO/OLEDB. Makes use of the Delphi support for ADO (ADOExpress/dbGo).

ADS: a dataset-based broker for Advantage Database Server. Makes use of the ADS library for Delphi (commercial - not available out of the box).

BDE: a dataset-based broker that uses the Borland Database Engine. Although it might work with SQL databases, its use is highly discouraged for other than the Paradox engine.

DBISAM: a dataset-based broker for the DBISAM database and Delphi components (commercial - not available out of the box).

DBX: a SQL-based broker to use Borland dbExpress (dbX). Available out of the box in Delphi 6 and Delphi 7.

FlashFiler: a dataset-based broker to use the open source (formerly TurboPower) FlashFiler database components. Not available out of the box; still available (although AFAIK no longer actively maintained) through SourceForge.

IBX: a SQL-based broker for the open source Delphi IBX components (for InterBase and, if you're daring, Firebird). Generally requires the latest IBX update. IBX is available out of the box, updates from Borland CodeCentral.

NexusDb & NexusDbSQL: dataset-based and SQL-based version of the NexusDb (commercial, not available out of the box) broker. AFAIU the two might be merged into a single broker in the future.

UIB: a SQL-based broker for the high-performance open source UIB (Unified InterBase) components, good for both InterBase and Firebird and part of the JVCL. Not available out of the box.

XML: a lightweight XML-based broker which uses plain XML files as storage. Currently it does not support filtering.

Template: an example do-nothing dataset-based broker to use as template to build your own. My own advice, if you want to develop a new broker, is to rather clone & modify a real (possibly similar) broker than starting from the template.

Each broker's subfolder contains the common source files plus a subfolder for each supported platform (D5, D6, D7, K3...). This subfolder contains the package source files plus any additional platform specific files. Not all brokers are supported on all platforms. If a platform is missing, the reason might be one of these:

- Not applicable (for example, the DBX broker does not exist in D5 because dbExpress itself is a D6+ thing).
- Missing maintainer: we haven't found anyone to maintain and keep the broker up-to-date on that particular platform. This is where you can help! Have a look at the Docs\Maintainers.html list to see what holes we have currently.

The Source\Core folder
----------------------
This is the core (IOCore.dpk) of InstantObjects; it is used by all the brokers and by the design time stuff. The subfolders here have the same meaning as those in the brokers folders.

The Source\Design folder
------------------------
This is where the IO design time stuff (DclIOCore.dpk) lives. The subfolders here have the same meaning as those in the brokers folders.

The Source\ObjectFoundry folder
-------------------------------
ObjectFoundry is a tool that joins InstantObjects and ModelMaker. See the OF_readme.txt file to know more.

The Source\Tests folder
-----------------------
The IO test infrastructure makes use of the open source ubmock unit test framework (from our own Uberto Barbini). This folder contains the IO specific unit test stuff. Currently the unit testing effort has just started, so we have just a handful of tests. Additions (in the form of new tests) are very welcome.