Dynamo - stcarrez/dynamo GitHub Wiki

dynamo - Ada Application Generator

dynamo [ -v ] [ -o directory ] [ -t templates ] [ -c config-dir ] command

dynamo is a command to help developers write an Ada Application using the ASF , ADO , AWA or Gtk libraries. dynamo provides several commands to perform one specific task in the development process.

First the create-project command will be used to initiate a new project. The project name is used at this stage to configure the name of the root Ada package for the application.

The add-model command will be used to create a database table mapping file. The database mapping file describes how to map a database table into an Ada record type for the ADO framework. The generate command is then used to build the Ada model files from the database mapping files or from a UML model. At the same time, it generates the SQL database creation schemas for MySQL and SQLite databases.

The add-page command is then used to add web pages for the application. When a new application layout is necessary, the add-layout command can be used.

To deploy an application on a production server, the dist command can be used to prepare the distribution tree, merge various files and directories, perform CSS and Javascript compression by using the yui-compressor, closure or other tools.

dynamo uses the dynamo.xml file to get information on the project and customize the generation. It scans the GNAT project files to obtain the dependencies between several dynamo components.

The following options are recognized by dynamo:

-v Prints the dynamo version as well as various installation and configuration paths.

-o directory

Specifies the directory where result files are created. The default is the current directory.

-c directory

Specifies the configuration directory which contains dynamo configuration files as well as template files.

-t directory

Specifies the templates directory. This option can be used to override the templates provided by dynamo.

dynamo create-project [-l {apache|gpl|bsd3|mit|proprietary}] [--web] [--gtk] [--lib] [--tool] [--ado] name author email

Create a new project in the current working directory or in the directory specified by the -o option. The project name should be a valid Ada identifier. It represents the Ada root package name for the project. The command creates a set of Ada files, a configure script, a Makefile as well as a gprbuild build file. The application can be immediately compiled to obtain a web server that is ready to run. The -l option allows to choose the license headers. The tool supports the generation of Apache, the GNU license or a proprietary license. The author's name and email address can be specified in the command line so that the license headers integrates them correctly.

The project type is controlled by one of the --web , --lib , --tool , --gtk or --ado option. When --ado is specified, a command line project using Ada Database Objects is generated. This type of project does not use Ada Server Faces nor Ada Web Application. When --web option is specified, a full web application based on ASF and AWA is created. The --web is the default if no other option is specified. The --lib option is helpful to generate a simple library with static or shared library support. The --gtk option generates a Gtk Ada application.

dynamo dist target-dir [package.xml]

After a web project is compiled, this command allows to build the distribution files that must be installed on the server. The dist command reads a package.xml file which describes how to make such distribution by specifying the files that must be copied. For some files, it is possible to execute an external application that will do some transformation on the source file and prepare it for the installation. For example the package.xml description can compress the Javascript and CSS files by using the yui-compressor, or closure tool. Images can be optimized by using pngcrush or jpegtran.

dynamo create-database model [connection] admin-user [admin-password]

The create-database command creates the database used by the application. The database schema file is stored in the directory identified by model and is generated by the generate command. The database connection string is optional. The default database connection string is read from the database property in the dynamo.xml configuration file. The connection string has the following form:

driver://host:port/database

The command will connect to the database server specified by the connection string. It will use the admin user for this connection. The database is created if it does not yet exist. If a user is specified in the connection string, a grant command is issued to create that user and allow him to access the new database.

Example of connection string for MySQL database:

mysql://localhost:3306/my_db?user=joe&password=admin

The MySQL server is running on localhost and TCP/IP port 3306. The database name is my_db and the user joe is created for the application with the password admin. The database tables are created by using the create-name-driver.sql script where name represents the Dynamo project name.

dynamo create-plugin name [ada | web]

Create a new plugin for the current project. The plugin sources are created in the plugins/name directory. The optional last argument controls whether the new plugin contains Ada sources or is a Web plugin. The plugin can be seen as a separate small Dynamo project that is used by a project. Once create, the other Dynamo commands can be executed in the new plugin.

dynamo add-layout name

Create a new XHTML layout file. The layout file is an XHTML facelet template which can be used by a web page to provide a common presentation layout. When the project is created, at least one layout is proposed. By adding a new layout, the application can provide different presentation styles. The layout files are stored in the web/WEB-INF/layouts directory.

dynamo add-page name

Create a new presentation page. The presentation page is an XHTML facelet file which contains HTML code as well as ASF facelet components. The presentation pages are stored in the web directory.

dynamo add-model [module] name

Create a new database table model mapping. The model mapping is an XML file that describes how to map a database table into an Ada type. The model mappings are stored in the db directory. The database table is mapped to an Ada tagged record in the package project-name.module.Model\fR if a module name is passed otherwise the package will have the name project-name.Model. The Ada record will have the name _name__Ref.

dynamo add-module name

Add a new module to the project. The module is composed of a set of Ada files and a set of XHTML presentation files. The name parameter is the name of the Ada child package that represents the module. This is also the name of the directory that will contain the specific XHTML files used for the module. The following Ada packages are generated:

package project.module;

package project.module.Beans;

package project.module.Modules;

where project is the project name (defined by the create-project command) and module is the new module name.

The Module package defines the main module data type with the initialization steps. The Beans package defines the Ada bean types which are specific to the module. Each Ada bean type must be registered in the Module package. The generated files are intended to be modified to implement the module functionality.

dynamo add-module-operation module entity operation

Add an operation in a module to perform some action on a database entity. The module is the name of the module in the application and entity is the name of the database table. The operation is the name of the Ada procedure and must be a valid Ada identifier. The generated operation has the following signature:

  procedure <operation>
    (Module : in <module>_Module;

     Entity : in out <project>.<module>.Models.<entity>_Ref'Class);

where project is the project name. The command modifies the module package specification to add the necessary Ada with clauses and declare the new operation. It modifies the module package body to add some other necessary Ada with clauses and implement the new operation. The default implementation creates a database transaction, saves the entity and commits the transaction.

dynamo add-permission module entity

This command adds several permissions for the a new module in the application. The module is the name of the module in the application and entity is the name of the entity or database table. Three permissions are created for the entity. It creates the following permissions by instantiating the Security.Permissions.Definition package:

  entity-create
  entity-delete
  entity-update

dynamo build-doc [-markdown|-google] directory

Extract the documentation from the project source files and generate the project documentation. The Ada specification files are scanned and the package specification header comment is used as the main structure for the project documentation. The XML files are also scanned and the documentation is extracted from these files. It can be merged together with other documentation to build up the final project user documentation.

The -markdown option generates the documentation using the Markdown Wiki syntax and the -google option generates a Google Code Wiki syntax.

While extracting the documentation from Ada source files, a set of pre-defined tags are recognized:

@include {name}.ads can be used to include the documentation from the Ada source file.

@include-doc {path}.md can be used to include the external documentation by reading the file. The file is read and included without changes.

The @include-bean {path}.xml is dedicated to the inclusion of the managed-bean documentation from the XML configuration files.

The @include-permission {path}.xml is dedicated to the inclusion of the permission documentation from the XML configuration files.

The @include-config {path}.xml is dedicated to the inclusion of the context-param documentation from the XML configuration files.

The @include-query {path}.xml is dedicated to the inclusion of the SQL query documentation from the XML configuration files.

dynamo info

Report information about the current project. This command scans the GNAT projects to find the dynamo components dependencies. It then lists the GNAT projects and the dynamo components that are used by the current project.

dynamo help name

Give an help description about a command.

dynamo generate [--package name] [model ... ]

Generate the Ada model implementation from the XML model mappings or from a UML model. The Ada model files are generated in the src/model directory. Developers should not modify these files by themselves. When no file is specified, the generate command will read all the XML and XMI files stored in the db directory. It will generate all the models found in those files.

At the same time, the command generates the SQL files to create the database tables for the supported drivers (MySQL and SQLite). For each project, it generates a set of SQL files that can be used to create or delete the database tables.

The generate command is able to read XMI 1.2 model files (UML 1.4) as well as ArgoUML files (.zargo). The UML model must use the Dynamo UML profile and assign the Table , PK and Bean stereotypes to the model element for the generation to be activated. For large or complex UML models, the --package option allows to activate the generation for the package specified by the option. In that case, other packages defined by the model are not generated although they could be referenced and used.

dynamo propset name value

Set a project property to configure some commands provided by dynamo. The property is composed of a name and a value. It is saved in the dynamo.xml file. The following properties are recognized:

The dynamo.xml file defines several configuration properties which are used to customize several commands. These properties can be modified with the propset command.

This property defines the author name inserted in file headers.

The author email address inserted in file headers.

The GNAT project file name which is used to build the project. By default, the GNAT project file name is the same as the dynamo project name. This property allows to specify a different name when the dynamo project name contains characters not allowed in GNAT project names.

This property controls the license header in file headers. The following license names are recognized: gpl apache mit bsd3

This property is generated automatically by dynamo from the GNAT project paths. It indicates the search paths that the Ada Web Application should use to search configuration files, resource bundles and XHTML presentation files.

The default database connection string.

For the generated documentation, the property indicates the path of a file that contains links to external documentation. The syntax of the file is very basic: each line describes a link with the text of the link followed by the link itself.

This configuration file is read by dynamo to configure various installation parameters necessary for the generation.

These XML files define the type mapping used in the dynamo model files. These mapping indicate for each basic type used in the XML model files, what is the target Ada, MySQL or SQLite type name.

This directory contains XML files that describe additional template commands.

This directory contains the template files associated with dynamo commands.

This directory contains the UML profiles that dynamo reads to obtain global definitions.

gprbuild(1), gcc(1), yui-compressor(1), pngcrush(1), jpegtran(1)

Written by Stephane Carrez.