//This is documentation, not code - the main page in doxygen output .. /*! \mainpage WORM - ORM framework * * \section intro_sec Introduction * * 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. * * At this writing the framework only supports SQlite3 and MySQL databases. * and the default output supports Wt's (Web Toolkit http://webtoolkit.eu) Dbo * library. It generates header files that (with a little adjustment sometimes) * will work with Wt::Dbo for existing database schemata. * * The output is configurable using the WORM template system which uses * google's ctemplate for output templating. * * 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. * * 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 :). * * \section install_sec Installation * * \subsection step1 Step 1: Requirements * NOTE: THIS IS UNTESTED ON WINDOWS or MAC AND NOT LIKELY TO WORK CURRENTLY.. * linux or Unices should be ok. * * \li cmake, make, gcc, libstdc++, stl * \li Boost - basic, header only (algorithm/string, lexical_cast) * \li SQlite3 libraries - you may comment out the sqlite driver in src/CMakeLists.txt * if you don't want SQlite3 support * \li libmysqlclient - same applies, you may comment this out * \li ctemplate 1.0; libctemplate (currently the no threads version - this can be changed in the cmake files) * * \subsection step2 Step 2: Obtaining the sources * Using git(1) clone the repository thus: *\code * git clone https://github.com/erikwinn/worm.git worm * \endcode * This will create a sources directory called "worm" - alternately you can * download a tarball and unpack it. * * \subsection step3 Step 3: Building * \code * cd worm/build * cmake ../ * make * \endcode * 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 ..) * * libraries: libworm.so libworm.a * binary: wormgen * * Installation(optional): * \code * make install * ldconfig * \endcode * * 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/ * \note 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): * \code export LD_LIBRARY_PATH=./build/src ./build/src/wormgen -h * \endcode * * Uninstall: * \code * rm /usr/local/bin/wormgen * rm /usr/local/lib/libworm* * rm -rf /usr/local/share/worm * \endcode * Alternately you can do: * \code * cat install_manifest.txt | xargs rm * \endcode * * \note You can also use wormgen \em without installing by doing something like this if * it was built with the shared libraries: * (use a full path to work outside this directory): * \code * export LD_LIBRARY_PATH=./build/src * ./build/src/wormgen * \endcode * * \section usage Using WORM * \subsection codegen Generating code: * wormgen Usage: * \code * wormgen -h * \endcode * gives a description of the available options. * * 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: * * \code * wormgen -D sqlite -d ./examples/blog.db * \endcode * * This will generate files in the current directory - to specify a different output * directory use -o /path/to/output, for example: * * \code * wormgen -D sqlite -d ./examples/blog.db -o /tmp * \endcode * * will place the generated files under /tmp * * 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 .. * * \subsection customizing Customizing the output * 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. * * The default template directory is /usr/local/share/worm - the option [-t DIRECTORY] * will tell wormgen to look in DIRECTORY for templates, eg: * \code * wormgen -D sqlite -d ./examples/blog.db -o /tmp -t $HOME/my_worm_templates/ * \endcode * 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. * * These are the currently supported template types: * * \li base class header - generates FooBase.h:
* ClassDeclarationBase, //class_declaration_base.tpl * \li base class source - generates FooBase.cpp:
* ClassDefinitionBase, //class_definition_base.tpl * \li class header - generates Foo.h:
* ClassDeclaration, //class_declaration.tpl * \li class source - generates Foo.cpp:
* ClassDefinition, //class_definition.tpl * * 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. * * 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. * * \section library Using the library * * Note that the library API is still unstable and may change. * * wormgen.cpp 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. * * 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. * */