Administrative Requirements

Karma manages manifests and modules. Part of the management task is the storage of those manifests and modules. Storing modules in a version control system is common practice in development organizations. Karma uses a 'manifest store' to store manifest files as well.

Please refer to the Administration Guide for further information about the manifest store configuration.

User Environment Configuration

After installation, a little bit of configuration is required:

• Karma requires a KARMA_HOME environment variable, which should point to the same location you used during the installation process (yep, we owe you this one as a default from the installation process itself, but haven't implemented this as yet in the installation script).
• Add $KARMA_HOME/bin (Windows- or Unix-style) to your PATH environment variable.

The remaining configuration is done as needed when Karma is started. The next step is to start Karma. Karma R1.0 comes with two flavours of user interfaces. One is the command-line interface, the other is the console. We'll start with the console

The Karma console

Karma shows its usage information when you enter:

karma

Just using karma without anything means nothing to Karma, as we are not Ant or Maven and for clarity we don't perform a default startup procedure. The output looks like:

usage: karma [options] console | <command> <command options>

Options:
  -u                         Update the location- and manifest store.
  -w <working context>       Load the given working context.

console                      Start the Karma console.
<command> <command options>  Run the given command with the given options.
                             Use the 'help' command for the list of commands.

  

We'll choose for the option of starting the console, which also starts the configuration process.

karma [-u] [-w <working-context>] console

The -u option updates the manifest store and location store (see the Administration guide for in-depth coverage of these two terms). -w specifies the working context. If ommitted, the last used working context is selected.

Note: a working context name must follow the pattern [a-zA-Z0-9_][a-zA-Z0-9_\-]* (don't start with a -).

Just do a karma console for the moment. This starts up the console, which is going to complain about missing configuration:

      _________________________________
      Welcome to Karma (R1.0 BETA6) !!!

      K     A     R        M        A
      .     .     .        .        .
      Karma Ain't Remotely Maven or Ant
      _________________________________

[ console ] Logging will be written to /home/user/Karma/logs.
[ console ] Checking working context configuration for `default`.
[ console ] ** Error in working context configuration : WCC-00001 : Could not load `working-context.xml`.
[ console ] ** Error in working context configuration : Missing configuration for manifest store.
[ console ] ** Error in working context configuration : Missing configuration for location store.
[ console ] Working context not initialized properly, start configurator ? [Y|N] (Y) :

  

Just say Y here, or else you wont get much further. The configurator is going to start to ask you questions. The first one is for your project base directory. This is the directory into which all your project's source code and configuration is stored. Choose your own location or just stick with the default by pressing enter:

[ configurator ] What is your project base directory (/home/user/karma/default) :

Now, you're asked to specify your manifest store. The information needed for this step should be obtained from your Karma administrator, or if you're the Karma administrator yourself you should read the Administration guide for more details.

So, fill in the requested information, e.g. like below:

[ configurator ] Please configure the manifest-store !
[ configurator ] What is your server protocol ? [ local | pserver ] (pserver) : local
[ configurator ] What is your server repository ? (/home/cvs) : /home/user/cvs
[ configurator ] What is the cvs module for the manifest store ? (manifests)
[ configurator ] What is your username ?  : user
    

And do the same for the location store:

[ configurator ] Please configure the location-store !
[ configurator ] What is your server protocol ? [ local | pserver ] (pserver) : local
[ configurator ] What is your server repository ? (/home/cvs) : /home/user/cvs
[ configurator ] What is the cvs module for the location store ? (locations)
[ configurator ] What is your username ?  : user
    

If the information you provided is correct, Karma will reward you with:

[ console ] Configuration complete. Loading working context `default` ...
[ console ] Configuration can be manually updated in `/home/user/.karma/working-contexts/default`

[ console ] Starting up console ...

[ init ] Loading manifest from history ...
[ init ] No manifest stored in history ...
21:40:03 [ default::Karma ] >
    

Now your Karma is up-and-running. You can try some commands (like list-manifests or help ;).

Also, once you have configured your working context via the console, you can start using the command-line interface.

Working Context Configuration

In the Basics section, the working context concept is defined.

Having started Karma, you have configured your first working context. The properties for a working context can be changed in working-context.xml, located in the working context subdirectory of ${user.home}/.karma/working-contexts.

For in-depth information on working contexts, see the Reference Documentation.