2005/5/10

     
 

ACDK projects directory layout

artefaktur

Description of the common directory layout of an ACDK project.


Content of this chapter:

   Overview
     ACDK Home
     Package
     Sources
     MetaInfo
     Unit Tests
     Configuration
     Includes
     Binaries


 Overview


[acdkhome] ->  the root of acdk
    |
    |--[acdk_core] ->  package root, also refered as [acdk_package]
    |        |
    |        |-- build.csf -> build file used via acdkmake
    |        |-- [acdk_core].lsp -> workspace/project lisp configuration
    |        |                     used to generate platform make files
    |        |-- Makefile  -> Platform make file. Starts [acdk_core].[platform]
    |        |-- [acdk_core].linux -> linux platform make file 
    |        |                       generated from [acdk_core].lsp
    |        |-- [acdk_core].dsw   -> MS Visual Studio workplace
    |        |                       generated from [acdk_core].lsp
    |        |-- [acdk_core].[platform]      -> other platform makes generated from [acdk_core].lsp
    |        |
    |        |-- [acdk_core_metainf].[lsp|platform] ->  extended metainfo for acdk_core.
    |        |
    |        |-- index.html -> start of the HTML package docs
    |        |-- index.htxt -> start of the package docs (source)
    |        |-- index.txt  -> start of the TXT docs
    |        |-- Changelog  -> Changelog generated from CVS repository
    |        |
    |        |- docs
    |        |    |
    |        |    |- images
    |        |    |       |-  *.gif -> local gifs used by the HTML files
    |        |    |       |-  *.css -> local style sheet
    |        |    |
    |        |    |- *.htxt -> documentation source
    |        |    |- *.html -> HTML documentation generated from the *.htxt files
    |        |    |- *.txt  -> text documentation generated from the *.htxt files
    |        |    |- package.xml -> description of the package
    |        |  
    |        |--src -> contains the Sources of this package, excluding test and samples
    |        |    |
    |        |    |-- [acdk_core].lsp  -> library/executable lisp configuration
    |        |    |                       used to generated platform make files
    |        |    |-- [acdk_core].dsp   -> MS Visual Studio Project
    |        |    |-- [acdk_core].[platform]  -> other platform makes generated from [acdk_core].lsp
    |        |    |
    |        |    |-- [acdk_cfgscript].[*] -> another package
    |        |    |
    |        |    |- [acdk]
    |        |         |
    |        |         |-- *.h *.cpp -> headers and source
    |        |         | 
    |        |         |--[lang]
    |        |         |     |
    |        |         |     |-- *.h *.cpp -> headers and source
    |        |         |     |-- [lang_metainf]_base.cpp ->  basic meta info for classes of this namespace.
    |        |         |     |
    |        |         |     |-- [lang_metainf]
    |        |         |     |          |
    |        |         |     |          |-- [lang_metainf_ext]*.cpp ->  extended meta info 
    |        |         |     |
    |        |         |     |
    |        |         |     |--dmi
    |        |         |     |    |
    |        |         |     |  [...]
    |        |         |   [...]
    |        |         |
    |        |         |--[io]
    |        |         |     |  
    |        |         |   [...]   -> more sources 
    |        |        [...]
    |        |             
    |        |--tests -> contains the  unit tests for this package
    |        |    |
    |        |    |--[acdk]
    |        |          |
    |        |          |--[lang] -> contains the unit tests for acdk::lang
    |        |          |    |
    |        |          |    |-- [acdk_lang_Test].lsp -> test executable lisp configuration
    |        |          |    |-- [acdk_lang_Test].cpp -> main of the unit Test
    |        |          |    |-- [acdk_lang_Test].[package] -> latform makes generated from [acdk_lang_Test].lsp
    |        |          |    |-- [acdk_lang_ClassLoader_Test.cpp] -> Test for acdk::lang::ClassLoader class.
    |        |          |    |-- *.cpp   -> other tests
    |        |          |
    |        |          |--[io] 
    |        |          |     |
    |        |          |   [...]
    |        |        [...]
    |        |
    |        |--cfg ->  package related configuration files.
    |        |
    |        |--tobj -> the intermediate object files
    |              |
    |              |--[acdk_core] -> object files from the library acdk_core
    |              |        |
    |              |        |--[platform] -> name of the platform
    |              |                |
    |              |                |--[debug]  -> object file from debug build
    |              |                |      |
    |              |              [...]    |-- *.[o|obj] -> the object files
    |              |
    |            [...] -> other library/executables
    |
    |--[acdk_text] -> antoher acdk package
    |       |
    |     [...]
    |
  [...] -> other packages
    |
    |--include ->  include files.
    |      |
    |      |--[acdk] -> all sources from the packages below the src directory
    |      |     |
    |      |     |--[lang]
    |      |     |      |
    |      |     |      |-- *.h *.cpp
    |      |     |      |
    |      |     |    [...]
    |      |   [...]
    |      |
    |      |--tests -> source of the unit tests
    |           |
    |           |--[acdk]
    |           |     |
    |         [...]   |--lang
    |               [...]
    |
    |--bin -> the compiled libraries and binaries.
    |
    |-- acdk_all.[platform] -> compile all standard ACDK packages
    |-- acdk_globals.[platform] -> platform make, which will be included by 
                                   package platform make files.
    
   
    
    
    

 ACDK Home

acdkhome is the root of the ACDK development tree. in normal case it just named acdk.

If you use acdkmake to build the ACDK sources, the environment variable ACDKHOME has to be set to this directory.

 Package

A package is collection of libraries, executables, unit tests, configuration and documentation.

 Sources

The sources of an acdk library executable should be organized in namespaces / unit, where every namespace is directory in the directory layout.

All sources will be installed into [acdkhome]/include directory.

For the organization of the sources with namespaces followign rules should be regarded:
  • Suffix .h for headers
  • Suffix .cpp for ACDK/C++ sources
  • Suffix .c for c sources.
  • Inside one library/executable a single Source file must not have the same name, also not, if they stay in different units. Otherwise linking the library/executable will fail.
  • Inside one library/executable a namespace name must not have the same name, otherwise linking the library/executable will fail.
  • Different ACDK package should not have sources in the same unit hierarchy.
  • The name of a loadable library should reflect the unit/namespace hierarchy.
    acdk_text contains classes of the acdk::text namespace.
    See  ClassLoader.

 MetaInfo


If a unit (namespace) contains ACDK classes with meta info, the meta compiler  man acdkmc generates [acdkhome]/[acdk_package]/src/[parentunit]/[unit]/[unit]_metainf_base.cpp and in the subdirectory the extended meta info [acdkhome]/[acdk_package]/src/[parentunit]/[unit]/[unit]_metainf/[unit]_metainf_ext.cpp.
If the extended meta info for the classes becomes to large, acdkmc split into multiple files.

The extended meta info can be linked into the library or linked to an extra library which will be loaded if requested.

See  Metainfo.


 Unit Tests

For a unit a unit test should be created. These tests are organized in the tests subdirectory.
The [acdk_package]/tests/* sources will be installed into [acdkhome]/include/tests directory.

The executable should be named reflecting the unit.
A unit test for acdk::lang::dmi should be named acdk_lang_dmi_Test.

See  ACDK Unit Tests.

 Configuration

Each package can provide configuration files.
The [acdk_package]/cfg/* sources will be installed into [acdkhome]/cfg/cfg directory.

A package should organized the configuration files in subdirectories reflecting the affected units.

 Includes


All sources of the packages are copied into the [acdkhome]/include directory with the same unit hierarchy.

The .cpp sources are also copied into the include directory, because this include will also used for documentation generations.

 Binaries

The linked libraries and executable, and also the unit test executable are stored in the [acdkhome]/bin directory.