Modules

The smallest unit that is managed by Karma is a module. A module is a directory structure, containing source code, unit tests, documentation, configuration and the like.

Karma manages modules by putting them under version control. For a high level overview of the version control Karma offers see the page about version management. For detailed information see module versions.

Modules optionally also can be build, tested and packaged. See build management for a high level overview.

Module name

A module name must be composed from the characters: A-Z, a-z, -, 0-9. Valid examples are:

  • A
  • -
  • 4
  • karma-core
  • log4j
Not valid are, e.g.:
  • karma_core ('_' is not allowed)
  • karma core (' ' is not allowed)
  • karma-core! ('!' is not allowed)

Karma system files

A module must have a least one file in the root of the module:

FileDescription
module-descriptor.xml This file serves two purposes.

The first is to specify the type of the module. See module types.

The second purpose is that of version storage. Speaking in CVS terminology: everytime a module is promoted to a higher version, a version tag is placed on its files. Karma uses the version tags on this file to retrieve the module's available versions. See module versions for more information.
Optional, but important files are:
FileDescription
history.xml The history.xml stores all history information of a module. When the module is created using Karma a 'module creation' event is logged. When promoting a module a 'promote module' event is logged.

A module's history is used for generating release notes, determining whether to upgrade to a newer version of a module, etc.

See module history for more information.
dependencies.xml A module can have dependencies on other modules and on external libraries. These dependencies are used when building, testing or packaging a module. See dependency management for more information.

Module creation

Modules are best created by using the create-module command: 

Usage of `create-module`:
----------------------------
create-module (crm)
   -m, --module <module-name>        The module name
   -c, --comment <comment>           The developers comment
   -t, --type <module-type>          Type of the module (see documentation!)
   -l, --location <location-alias>   The location alias
An example is: 
create-module -m karma-core -c "The core of Karma" -t JAVA-SOURCE-MODULE -l karma-sf
This command will create a module with the name karma-core and type JAVA-SOURCE-MODULE in the location karma-sf. This location represents the karma cvs repository on SourceForge, e.g. Module creation is logged in the history of a module by means of a module creation event. The comment is stored as an attribute of this event.

Although not recommended, and much more work, it is possible to create a module by hand. Be sure to add all the necessary files to your module.