- How to create a new item?

Create a directory called "my-new-item" and another called "cm" under it:

  my-new-item/
    cm/

Run "coma.sh generate" in the "cm" directory. This creates three new files:

  my-new-item/
    cm/
      coma.lisp
      coma.sh
      .coma-sources.bundle

Define the item for coma by creating a file called "item.lisp" under
"cm" that looks like:

  (defitem my-new-item
      ((debug nil)
       (emacs t))
    (:rule (:build)
           (member emacs '(t nil)))
    (:rule (:run)
           (member debug '(t nil)))
    (:config-files "out"))

Explanation:

  Name of the item is my-new-item:
    (defitem my-new-item
  Define three slots: debug, emacs (with default value T) and cc:
        (debug
         (emacs t)
         cc)
  Define rules for building:
      (:rule (:build)
             (member emacs '(t nil))
             (or (equal cc "gcc")
                 (equal cc "cc")))
  Define rules for building and running:
      (:rule (:build :run)
             (member debug '(t nil)))
  List configuration files:
      (:config-files "Makefile" "my-new-item.conf"))

Create a file named "Makefile.coma" under "my-new-item" that looks like:

  CC=@cc@
  CFLAGS=@(if debug "-g" "")@

  all:
          $CC $CFLAGS ize.c

"Makefile.coma" is just a template in which when processed the
placeholder lisp forms between the @ characters are evaluated and
their result inserted in their place. For these placeholder forms the
slots of the item are available directly by their names (i.e. cc,
debug, ...).

There is one more file "cm/config.lisp" that contains the current
configuration of the item. It may look like this:
((DEBUG T)
 (EMACS T)
 (CC "gcc"))

- how to validate the configuration of an item?

Run "coma.sh validate" in the cm directory of the item.

- how to force reconfiguration of an item?

By running "coma.sh configure". It processes the configuration
template files.

- How to create a kit?

A kit is a special kind of item and most steps involved in creating
one is the same as for normal items, so only the differences shall be
noted here.

In item definition file "item.lisp" write:
  (defkit my-new-kit)

In most cases it is enough, but kits can also have user defined slots,
rules, config-files. In fact defkit has much the same parameters as
defitem, all of which are omitted here.

We haven't defined new slots here, so we don't create "config.lisp",
but we do create "kit-items.lisp" that lists the items this kit is
made of. Example:

  (MY-NEW-ITEM #S(HOC-MODULE :NAME "my-new-item" :VERSION #v2.0.0)
               ((DEBUG T) (EMACS T) (CC "gcc")))
  (OTHER-ITEM #S(HOC-MODULE :NAME "other-item" :VERSION #v5.0.0)
              ((LIB MY-NEW-ITEM)))

This means that version #v2.0.0 of hoc module "my-new-item" is part of
this kit and can be referenced as MY-NEW-ITEM. We also say that DEBUG
and EMACS slots are to be set to T and CC to "gcc".

Another hoc module "other-item" is specified whose LIB slot is to be
set to MY-NEW-ITEM.

By running "coma.sh configure" the kit does the same template processing an simple item would, but it also looks at "kit-items.lisp":
- checks out "my-new-item" and configures it
- checks out "other-item" and configures it

It also registers itself as a listener at the above hoc modules and
automatically update versions in "kit-items.lisp" when necessary.
