Working Contexts

The working set of modules, manifests, etc for a developer is logically grouped in a 'working context' (a.k.a. workset). A working context is used by Karma to check out modules and manage manifests within a logical context. Suppose you work for two different clients. For each client, you can easily configure a working context and separate every client-specific setting from the other.

The first thing that Karma does, when starting up, is locate the current working context. When Karma is started with the -w <working-context> option, the working-context is stored as a Java preference karma.working-context in .java/.userPrefs/prefs.xml. Having set a working context, the next time you use Karma, it can simply be started with karma.

Configuration Items

The working context requires a number of configuration items. All of these items are configured in working-context.xml, located in ${user.home}/.karma/working-contexts/<working-context>.

The following file shows such a configuration file: 

  
<?xml version="1.0"?>
<wc:working-context
  xmlns:wc="http://www.toolforge.org/specifications/working-context"
  xmlns:loc="http://www.toolforge.org/specifications/location">
  <wc:properties>
    <wc:property name="project.basedir" value="/home/asmedes/karma/toolforge"/>
    <wc:property name="manifest-store.module" value="manifests"/>
    <wc:property name="location-store.module" value="locations"/>
  </wc:properties>

  <loc:locations>
    <loc:location type="cvs" id="manifest-store">
      <loc:protocol>pserver</loc:protocol>
      <loc:host>127.0.0.1</loc:host>
      <loc:port>2401</loc:port>
      <loc:repository>/cvs/om-admin</loc:repository>
      <loc:module-offset></loc:module-offset>
    </loc:location>
    <loc:location type="cvs" id="location-store">
      <loc:protocol>pserver</loc:protocol>
      <loc:host>127.0.0.1</loc:host>
      <loc:port>2401</loc:port>
      <loc:repository>/cvs/om-admin</loc:repository>
      <loc:module-offset></loc:module-offset>
    </loc:location>
  </loc:locations>

</wc:working-context>
project.basedir Specifies the directory where your project work is stored. Modules are checked out in this directory (grouped by manifest) and all other project related work is performed in this directory.
manifest-store.module Manifests are version controlled xml files containing all modules for a software application or component. They are stored in a version control system (currently, only CVS is supported) in a module. The module can be specified with this property. Examples of module names are: manifests or admin/manifests. When manifests are checked out of the repository, they will be stored in ${project.basedir}/.admin/manifest-store/${manifest-store.module}.
location-store.module Locations are version controlled xml files containing definitions of locations where modules are located (a CVS repository, for example). They are stored in a version control system (currently, only CVS is supported) in a module. The module can be specified with this property. Examples of module names are: locations or admin/locations. When locations are checked out of the repository, they will be stored in ${project.basedir}/.admin/location-store/${location-store.module}.

Location configuration is required to specify where manifests and locations can be found. This is done through the <loc:location>-elements. Check the example. It should be sufficient to configure your manifest and location stores.

Authentication data for a CVS repository can be found in ${user.home}/.karma/authenticators.xml, which will contain a mapping for the manifest-store and location-store for the current working context.

Best Practices

Working contexts are ideal to group software development projects together on a per-client basis. You are free to collect all your project work together in one working context, but for clarity, it is good practice to have several working contexts. You don't need to restart the command shell to get access to another working context. There's a command to quickly change to another working context.