Application Standard Components Library (ASCL) last update 10.4.2007

• Application Standard Components Library (ASCL)
  • Introduction
  • Available and Planned Library Units
  • Development Environment
    • Overview
    • Library Units
    • Quality ensurance
    • Documentation Process
    • Release Mechanism and Configuration Management
    • Structure of the packages
    • Usage of the ASCL libraries and the ASCL based infrastrcture
  • Personal Software Process
    • Overview
  • Work Plan
  • Status
  • Contact
  • Related Activities
  • Accessing the Source Code

Introduction

This projects represents an idea i am going along for a long time. While writing application is Ada 95 i am always coming along components which have the potential to be reused, which is fine but where to put it? In the past i have put these packages into a package hierarchy Util.X.Y.Z for each project. The Util packages have been reused and further developed during the next project. Consequently during the cause of several projects a library of commonly used components has formed. As you can imaging this approach has some major deficiencies. 

• There is no compatitibility build into this approach
• Bugs fixes found in a later projects are not automatically available in previous projects

Since i am using Linux and Windows in paralell the question of the build environment, tools and embedment within CVS and Subversion has become a constant issue where a considerable effort has to be spend.

Additionally besides of the above issues, issues like documentation and quality ensurance are some important issues which should be addressed with reasonable effort.

Adressing these topics is the primary objective of this project. The objective is to provide for Linux and Windows platforms to address the following topics by providing either software or a reasonable collection of references to components from the net.

• A set of reusable packages as most of the libraries you find on the net, but the focus are not light weighted components but larger components as e.g. a configuration manager, an cli application environment which does all the argument parsing etc.
• A build environment for Linux which can be updated and maintained idenpendantly of the actual source code. 
• Support of the personal software process.

The licensing for ASCL components will follow the commonly used GPL with the exception:

"... As a special exception, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.."

Under all circumstances, as a general working principle, the bazaar style will be applied which means "..release early and often ..." (Eric Steven Raymond)

Available and Planned Library Units

ASCL currently provides the following library units:

Development Environment

Overview

 The development environment is using the following tools:

The ASCL environment for Linux is based on libary units. A library unit is a package hirarchy which will be compiled into a library using GNAT project files. The targets of the build environment are:

• Libraries and the corresponding include files
• Documentation files.

Library Units

A library unit consists of a hirarchy of packages with the same top level package and a GNAT makefile which assumes that the directories include and lib are used during the build. A typical sample is shown below:

with "../util/util.gpr"
project Tam is
   for Languages use ("Ada", "Makefile");
   for Library_Name use "tam";
   for Library_Dir use "../lib";
   for Library_Ali_Dir use "../include";
   for Library_Kind use "dynamic";
end Tam;

A library unit is expected to export the object code and a documentation module for docbook. In order to keep the build environement simple, for each library unit a common makefile (Makefile.unit) is called. This makefile includes the file makefile.local. This file is expected to set two variables as shown below: 

project=tam
userdoc=tam
title=Transaction Manager for Ada 95 Objects

The variable project specifies the name of the top level compilation unit of this library unit. The project name given here is used to locate the project file and to name the documentation unit. The title is used to give the package a working title which will popup in the userguide documentation. The contents of a typical library package (e.g. TAM)  looks like this:

ascl@hal:~/ascl/tam> ls -l
total 116
-rw-r--r-- 1 ascl users  3172 2007-04-07 17:35 makefile.local
-rwxr-xr-x 1 ascl users  2984 2007-03-26 17:21 tam.ads
-rwxr-xr-x 1 ascl users   235 2007-03-26 17:22 tam.gpr
-rw-r--r-- 1 ascl users 10601 2007-04-06 10:36 tam-storage_pool.adb
-rw-r--r-- 1 ascl users  4612 2007-04-04 19:02 tam-storage_pool.ads
-rwxr-xr-x 1 ascl users 16353 2007-04-08 09:17 tam-transaction.adb
-rwxr-xr-x 1 ascl users  6289 2007-04-06 10:10 tam-transaction.ads
-rwxr-xr-x 1 ascl users  6671 2007-04-08 09:17 tam-transaction_element.adb
-rwxr-xr-x 1 ascl users  9389 2007-04-06 15:43 tam-transaction_element.ads
drwxr-xr-x 3 ascl users   110 2007-03-26 19:27 test

Quality ensurance

Each libary unit also provides an set of testcases which can be executed automatically in order to ensure the quality over time. For automatic  testing AUnit and a modifed version of tg is used. The tool TG is a preprocessor which simplyfies the writing of test cases.  A typical test case is shown below:

-------------------------------------------------------------------------------
***** [TAM003] Conseq. Transaction_Begin_Or_Join without cancel/commit
define
        TID1,TID2 : TID_Type ;
test

        TID1 := Transaction.Begin_Or_Join;
        TID2 := Transaction.Begin_Or_Join;

pass exception Already_In_Transaction;

cleanup
        Commit;

The first line defines the name of the test case and the descriptive text for the test case. 

In the define section two transaction variables are defined. 

The test section contains the actual test code.

The testcase is successfull if the excetpion Already_In_Trasnaction is thrown by the second Begin_Or_Join method. At the end of the test case under all circumstances the Commit has to be executed in order to remove the open transaction.

All test suites are located in the directory regression. A regression is stared by means of the command:

$ make test

As a result a logfile called test.log is stored in the directory. This file is also managed via subversion in order to commit  the regression result together with any other code change.

Documentation Process

The documentation of the ASCL library is intended to be code centric, which means there is only a minimum of documentation which is not part of the source code. This allows by means of the adadoc utility the extraction of the user manual relevant information and conversion into docbook format.

The user manual of the ASCL project is made using docbook and the output of adadoc will be included automatically.

In order to create reasonably structured documentation the following overall rules have to be taken into account:

• All Comments starting on the first column, before the package <name> is statement, are understood as general package description.
• Within the same module the description of the procedures and functions are either all comments before a procedure or after each procedure. It is not possible to mix the style in the same module.

In case of the general description section the following formatting rules will be applied by the documentation generator:

• A line of text underlined by '-' or '=' characters is understood as a headline which will be visible in the table of contents of the documentation.
• A line of text ending with a ':' is understood as an item list. All paragraphs beginning with a '-' character or and indentation level deeper then the starting line are assumed as item elements.
• A text line with a length lower then 2/3 of the max. block width is assumed as an end of paragraph and a new paragraph is started.

The description of procedures and functions may be structured in the same way. But in order to enforce a useful description scheme, the usage of the following keywords is enforced:

• Description
• Precondition
• Postcondition
• Excpetions
• Notes

If one of these keywords appears in a comment followed by a ':' character, the adadoc facility will place a headline in the description which is not visible in the TOC.

The adadoc utility is a Ada 95 program which translates Ada 95 package specifications into docbook units.

Release Mechanism and Configuration Management

The ASCL environment provides ans explicit release meachnism by means of the target release in the main Makefile. This target perform the following steps:

1. Create a package with the name ascl-<version>-src.tar.gz. The package contains the source code and a version of the documentation in postscript, PDF and HTML format. 
2. Create a label in the version management.
3. Extract the package; compile it and run the regression test. If the regression test is not successfull step the process.
4. Create a branch for the release version.

After a release (e.g. Version 0.2.0) of ASCL you will find the structure in the CM System (e.g. sub version) as shown below:

The branch ASCL_X_Y_0 is intended for later correction (e.g. patches) which are needed for this release. Patches will NOT be released by means of a release.

Structure of the packages

ASCL comes in two package. The core package which contains the basic infrastructure for the ASCL library and the ascl package is self.  The idea is that the infrastructure of an project can be updated independant of the project it self. The concept is based on the concept of units. A unit is a set of package which are belonging to the same package hirarchy (e.g. TAM) which will end up in the same library.

1. The file ./UNITS contain list of package to be hosted by the ASCL infrastructure.
2. The code for a unit is completly contained in a subdirectory of the installation directory (e.g. where the file UNITS  is located).
3. The directory of a unit contains the file makefile.local which contains variable settings for the makefile Makefile.unit (see previous chapters)
4. The directory of a unit contains the file MANIFEST.local which contains the list of all source files which have to be added to the source distribution. The file pathes are specified relative to the installation directory.
   

Usage of the ASCL libraries and the ASCL based infrastrcture

There are basically two use case:

1. You want to extend the ASCL by additional components.
2. You want to reuse the ASCL core environment for further developement.

In the first case, the best is to to join  the teams and checkout the svn tree and start working on this. But alternatively you may also download the core and the ascl software and perform your changes locally.

In the second case i propose the following:

1. Get the core and ascl source, compile is and install it on your system for common usage. After installing ASCL system wide on you system, ASCL provides for each library a wrapper project files. In order to use them correctly with GPS and the gnatmake compiler please add the directory /usr/local/ascl to your project file path (ADA_PROJECT_PATH).
2. Create a directory and extract the core release into this directory. Create a subdirectory in this directory for your own library unit. Then you need to update the UNITS file and create a makefile.local and and MANIFEST.local file. 

The picture below shows the deployment. The ASCL library is system wide installed, the development environemt of the local developer contains a copy of the core where he developes his library unit in.

The ASCL library is installed system wide and the core is installed in the environment of the library project you want to realize. The core part can always be replaced by a new version of it.

Personal Software Process

Overview

No yet supported by ASCL. 

Work Plan

The release time schedule is shown below:

Status

Currently the project is under construction. 

Contact

The table below does summarize the contact points of the ASCL project.

Related Activities

This section contains to my best knowlege a list of related activies in the Ada 95 community. I guess there a probly a lot more.

Accessing the Source Code

The source code is can be downloaded from the download area or accessed via the subversion archive.

© 2007 Michael Erdmann - $Revision: 1.9 $ / $Date: 2002/07/08 12:58:30 $