You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
202 lines
14 KiB
202 lines
14 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<title>WORM: WORM - ORM framework</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body onload='searchBox.OnSelectItem(0);'>
|
|
<!-- Generated by Doxygen 1.7.3 -->
|
|
<script type="text/javascript"><!--
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
--></script>
|
|
<script type="text/javascript">
|
|
function hasClass(ele,cls) {
|
|
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
|
|
}
|
|
|
|
function addClass(ele,cls) {
|
|
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
|
|
}
|
|
|
|
function removeClass(ele,cls) {
|
|
if (hasClass(ele,cls)) {
|
|
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
|
|
ele.className=ele.className.replace(reg,' ');
|
|
}
|
|
}
|
|
|
|
function toggleVisibility(linkObj) {
|
|
var base = linkObj.getAttribute('id');
|
|
var summary = document.getElementById(base + '-summary');
|
|
var content = document.getElementById(base + '-content');
|
|
var trigger = document.getElementById(base + '-trigger');
|
|
if ( hasClass(linkObj,'closed') ) {
|
|
summary.style.display = 'none';
|
|
content.style.display = 'block';
|
|
trigger.src = 'open.png';
|
|
removeClass(linkObj,'closed');
|
|
addClass(linkObj,'opened');
|
|
} else if ( hasClass(linkObj,'opened') ) {
|
|
summary.style.display = 'block';
|
|
content.style.display = 'none';
|
|
trigger.src = 'closed.png';
|
|
removeClass(linkObj,'opened');
|
|
addClass(linkObj,'closed');
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
<div id="top">
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectlogo"><img alt="Logo" src="worm_sm.png"></td>
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectname">WORM <span id="projectnumber">0.2</span></div>
|
|
<div id="projectbrief">A C++ DAL/ORM code generation framework</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div id="navrow1" class="tabs">
|
|
<ul class="tablist">
|
|
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
|
|
<li><a href="pages.html"><span>Related Pages</span></a></li>
|
|
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
|
|
<li><a href="annotated.html"><span>Classes</span></a></li>
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
|
<li id="searchli">
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
alt=""/>
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<h1>WORM - ORM framework </h1> </div>
|
|
</div>
|
|
<div class="contents">
|
|
<div class="textblock"><h2><a class="anchor" id="intro_sec"></a>
|
|
Introduction</h2>
|
|
<p>WORM is a Data Abstraction Layer for access to database servers and an Object Relational Mapping system. It consists of libraries providing a generic API for database access and database metadata mapping of schema structure. On top of this there is a tool to generate C++ class files for a given arbitrary database schema called "wormgen". wormgen accepts a few arguments setting the database to use and optionally username, password, output directory, etc. - "wormgen -h" shows usage. See below for more information.</p>
|
|
<p>At this writing the framework only supports SQlite3 and MySQL databases. and the default output supports Wt's (Web Toolkit <a href="http://webtoolkit.eu">http://webtoolkit.eu</a>) Dbo library. It generates header files that (with a little adjustment sometimes) will work with Wt::Dbo for existing database schemata.</p>
|
|
<p>The output is configurable using the WORM template system which uses google's ctemplate for output templating.</p>
|
|
<p>Additionally the libraries provide a general API for basic database access including query execution with structured result sets and runtime metadata including column information such as name, data type, defaults, extras, etc.</p>
|
|
<p>NOTE: This API is not fully stable! I expect there to be some changes and do not yet recommend building off the API for anything serious. wormgen is functional (if simple) and changes there should not cause problems but the libraries are under heavy development. There may be modifications and these should be expected until this message is removed. You have been warned :).</p>
|
|
<h2><a class="anchor" id="install_sec"></a>
|
|
Installation</h2>
|
|
<h3><a class="anchor" id="step1"></a>
|
|
Step 1: Requirements</h3>
|
|
<p>NOTE: THIS IS UNTESTED ON WINDOWS or MAC AND NOT LIKELY TO WORK CURRENTLY.. linux or Unices should be ok.</p>
|
|
<ul>
|
|
<li>cmake, make, gcc, libstdc++, stl </li>
|
|
<li>Boost - basic, header only (algorithm/string, lexical_cast) </li>
|
|
<li>SQlite3 libraries - you may comment out the sqlite driver in src/CMakeLists.txt if you don't want SQlite3 support </li>
|
|
<li>libmysqlclient - same applies, you may comment this out </li>
|
|
<li>ctemplate 1.0; libctemplate (currently the no threads version - this can be changed in the cmake files)</li>
|
|
</ul>
|
|
<h3><a class="anchor" id="step2"></a>
|
|
Step 2: Obtaining the sources</h3>
|
|
<p>Using git(1) clone the repository thus: </p>
|
|
<div class="fragment"><pre class="fragment"> git clone https:<span class="comment">//github.com/erikwinn/worm.git worm</span>
|
|
</pre></div><p> This will create a sources directory called "worm" - alternately you can download a tarball and unpack it.</p>
|
|
<h3><a class="anchor" id="step3"></a>
|
|
Step 3: Building</h3>
|
|
<div class="fragment"><pre class="fragment"> cd worm/build
|
|
cmake ../
|
|
make
|
|
</pre></div><p> This will build the libraries and wormgen in ./build/src. By default the static library is built - uncomment the shared library in src/CMakeLists.txt and comment out the static library to change this (todo: add a configure script ..)</p>
|
|
<p>libraries: libworm.so libworm.a binary: wormgen</p>
|
|
<p>Installation(optional): </p>
|
|
<div class="fragment"><pre class="fragment"> make install
|
|
ldconfig
|
|
</pre></div><p>This will install the libraries to /usr/local/lib/libworm.* and the binary to /usr/local/bin/wormgen. Code generation templates will be installed to /usr/local/share/worm/</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>You can also use wormgen without installing by doing something like this if it was built with the shared libraries: (use a full path to work outside this directory): <div class="fragment"><pre class="fragment"> export LD_LIBRARY_PATH=./build/src
|
|
./build/src/wormgen -h
|
|
</pre></div></dd></dl>
|
|
<p>Uninstall: </p>
|
|
<div class="fragment"><pre class="fragment"> rm /usr/local/bin/wormgen
|
|
rm /usr/local/lib/libworm*
|
|
rm -rf /usr/local/share/worm
|
|
</pre></div><p> Alternately you can do: </p>
|
|
<div class="fragment"><pre class="fragment"> cat install_manifest.txt | xargs rm
|
|
</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>You can also use wormgen <em>without</em> installing by doing something like this if it was built with the shared libraries: (use a full path to work outside this directory): <div class="fragment"><pre class="fragment"> export LD_LIBRARY_PATH=./build/src
|
|
./build/src/wormgen
|
|
</pre></div></dd></dl>
|
|
<h2><a class="anchor" id="usage"></a>
|
|
Using WORM</h2>
|
|
<h3><a class="anchor" id="codegen"></a>
|
|
Generating code:</h3>
|
|
<p>wormgen Usage: </p>
|
|
<div class="fragment"><pre class="fragment"> wormgen -h
|
|
</pre></div><p> gives a description of the available options.</p>
|
|
<p>The database (-d) argument is the only required argument - you must have a database already set up and access to it. By default it assumes the username is root with no password - for an SQlite3 database pass the filename as the argument for -d database; for example, from within the source directory you can generate files from the sample Sqlite3 database thus:</p>
|
|
<div class="fragment"><pre class="fragment"> wormgen -D sqlite -d ./examples/blog.db
|
|
</pre></div><p>This will generate files in the current directory - to specify a different output directory use -o /path/to/output, for example:</p>
|
|
<div class="fragment"><pre class="fragment"> wormgen -D sqlite -d ./examples/blog.db -o /tmp
|
|
</pre></div><p>will place the generated files under /tmp</p>
|
|
<p>Other commandline arguments include: -D driver ([default]mysql or sqlite) -t template directory (default /usr/local/share/worm/ or ./src/orm/templates) -u username -p password -h help - use this to see all the arguments ..</p>
|
|
<h3><a class="anchor" id="customizing"></a>
|
|
Customizing the output</h3>
|
|
<p>The output can be configured by editing or creating new template files in the template directory - any files in this directory named with the extension ".tpl" are assumed to be templates to use. Note that there is a naming convention for each type of template - see the list of supported template types below.</p>
|
|
<p>The default template directory is /usr/local/share/worm - the option [-t DIRECTORY] will tell wormgen to look in DIRECTORY for templates, eg: </p>
|
|
<div class="fragment"><pre class="fragment"> wormgen -D sqlite -d ./examples/blog.db -o /tmp -t $HOME/my_worm_templates/
|
|
</pre></div><p> This means that you can copy the default template to my_worm_templates/ and experiment with it or create other templates. Each template must have a filename like the one of the ones listed below - the filename will tell wormgen what kind of template it is and how to name the output files for that template.</p>
|
|
<p>These are the currently supported template types:</p>
|
|
<ul>
|
|
<li>base class header - generates FooBase.h:<br/>
|
|
ClassDeclarationBase, //class_declaration_base.tpl </li>
|
|
<li>base class source - generates FooBase.cpp:<br/>
|
|
ClassDefinitionBase, //class_definition_base.tpl </li>
|
|
<li>class header - generates Foo.h:<br/>
|
|
ClassDeclaration, //class_declaration.tpl </li>
|
|
<li>class source - generates Foo.cpp:<br/>
|
|
ClassDefinition, //class_definition.tpl</li>
|
|
</ul>
|
|
<p>Database and class naming conventions: A table in the database should be named in lowercase with underscores for best results (Note: this is optional but will avoid naming conflicts - wormgen will still generate files for camel case naming schema). Ex: some_persons will be transformed to a class SomePerson. Columns like first_name will transform to firstName. Underscores for private variables, accessors, etc can be established in the templates. Table names should be plural and will be transformed to singular.</p>
|
|
<p>Templates: The templates use ctemplate and currently support only the tags in the default template (which generates Wt::Dbo object headers). A decent introduction to ctemplate syntax is available at the ctemplate website. The supported tags are quite simple and self-explanatory - see the default template for more.</p>
|
|
<h2><a class="anchor" id="library"></a>
|
|
Using the library</h2>
|
|
<p>Note that the library API is still unstable and may change.</p>
|
|
<p><a class="el" href="wormgen_8cpp.html">wormgen.cpp</a> itself is quite simple and provides a quick example of using the library - additionally, WormClassGenerator shows usage of the metadata aspects of the library. libworm can also be used for basic database access, queries and generic result sets - but it is currently intended primarily for the ORM generator. The library does not support transactions, and all results are cached locally in one call.</p>
|
|
<p>There are also some small example programs under examples/ - I recommend starting with these. Also, the library code is heavily commented -and there is HTML documentation under doc/html. Until the API is stablized and "real" documentation written the best course is experimentation and "reading the
|
|
source, Luke!" - the DAL functions available are documented in comments but not yet stable so your mileage may vary. </p>
|
|
</div></div>
|
|
<!--- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Defines</a></div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<hr class="footer"/><address class="footer"><small>Generated on Fri Nov 18 2011 21:01:45 for WORM by 
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
|
|
</body>
|
|
</html>
|