Karma works with manifests and modules. Manifests consist of a certain amount of modules.
A manifests is defined in an XML file, which defines the properties of the manifest and the
modules the manifest contains. Modules are stored in a
version control system, and identified by a
attribute in the manifest file (see below). This attribute is used by
Karma to locate the correct version control system (its location).
The manifest and location configuration is stored in a version control repository as well. The so-called `manifest-store` and `location-store`. Both of these will have to be present for Karma to actually do something usefull.
In the case of CVS you have to create a manifests and
locations module in your repository. It is also possible
to create one module (say karma) and create a manifests
and locations module under that.
Next to the manifests and locations module you have to define a modules module. In this module the actual modules are stored. I.e. :
CVSROOT/ manifests/ locations/ modules/
CVSROOT/ karma/ manifests/ locations/ modules/
Software modules are grouped in a so-called manifest. These manifests are xml files, following the `http://www.toolforge.org/specifications/karma/manifest.dtd` definition. Karma is capable of checking out these manifest files from a (CVS) repository. The local checkout of this module (which must be named : manifests) is called the 'manifest-store'. During startup of Karma, the manifest-store configuration will be checked and asked for if missing (see getting started).
See the Reference Documentation for more information on the configuration aspects of the manifest store.
Create a file
helloworld.xml and add it to your manifest store
(check it in into your manifest store module in a CVS repository:
<?xml version="1.0"?> <manifest type="development" version="1-0"> <modules> <module name="helloworld" location="local"/> </modules> </manifest>
Each module has a location. Right now, all modules have a location
identifying a CVS repository. Locations are configured in xml files,
following the http://www.toolforge.org/specifications/karma/location.dtd
definition. Karma is capable of checking out these location files from a
(CVS) repository. The local checkout of this module (which must be named
: locations) is called the 'location-store'. During startup of Karma, the
location-store configuration will be checked and asked for if
missing. You have to provide these properties to Karma which will be
See the reference documentation for more information on the configuration aspects of the location store.
The following could be your starter location. Create a file
locations.xml and add it to your location store in the CVS
<?xml version="1.0"?> <loc:locations> <loc:location type="cvs-repository" id="local"> <loc:protocol>local</loc:protocol> <loc:host>localhost</loc:host> <loc:port>2401</loc:port> <loc:repository>/home/cvs</loc:repository> <loc:module-offset></loc:module-offset> </loc:location> </loc:locations>
The mapping between the manifest and the location is made via
Version control repositories, such as CVS, can be behind an authentication
layer. If so, you will need a username and password. Karma maps each
location to authentication data. This authentication data is (Karma R1.0)
required to be in a file called
$USER_HOME/.cvspass. If you
have ever used CVS command-line tools, you might have it on your system
already. For each location (a CVS location will create a CVSROOT from it),
a line should be created in the
.cvspass file. This includes
the location configuration for the manifest-store and the
location-store. A general
.cvspass file looks like:
/1 :pserver:firstname.lastname@example.org:2401/cvs/karma B$#H er_9 /1 :pserver:email@example.com:2418/cvs/cli B$^G er_9
The scrambled password is stored in this file as well. Ask your administrator (or send us an email firstname.lastname@example.org for more info if you haven't got a clue...).
The authentication data that Karma requires has to be available in
$USER_HOME/.karma, in a file called
authenticators.xml. The following snippet shows the
authenticators.xml that maps to the location you configured
<?xml version="1.0"?> <authenticators> <authenticator working-context="default" id="local" username="asmedes"/> </authenticators>
asmedes is the username in the CVS repository,
although it is not required for a CVS repository that is local (the
:local: protocol), Karma still needs it to keep track of who
did what (history).