[DOC] document singleton behaviour in type manpage

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
This commit is contained in:
Nico Schottelius 2011-03-11 19:09:36 +01:00
parent 783c4b12ca
commit 19c7317cbb
3 changed files with 46 additions and 9 deletions

View file

@ -19,7 +19,7 @@
#
#
# Fail if something bogus is going on and export all variables
# Fail if something bogus is going on
set -u
################################################################################

View file

@ -1,7 +1,11 @@
- Support singletons (see types/issue for a good reason)
- add documentation!
- think about splitting __file:
__file --source
__directory --recursive yes|no --source
__link --type symbolic|hard
__file
source
mode
owner
__directory
parents
mode
owner
__link
type symbolic | hard

View file

@ -10,7 +10,9 @@ cdist-type - Functionality bundled
SYNOPSIS
--------
Other languages name this module or class
__TYPE ID --parameter value [--parameter value ...]
__TYPE --parameter value [--parameter value ...] (for singletons)
DESCRIPTION
@ -37,7 +39,23 @@ Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to
save the given parameters into a cconfig database, so they can be accessed by
the manifest and gencode scripts of the type (see below).
A list of supported types can be found in the cdist-type-listing(7) manpage.
A list of supported types can be found in the cdist-reference(7) manpage.
SINGLETON TYPES
---------------
If a type is flagged as a singleton, it may me used only once. This
is useful for types which can be used only once on a system. If a type
can only be used once, it does not take an
Example:
--------------------------------------------------------------------------------
# __issue type manages /etc/issue
__issue
# Probably your own type - singletons may use parameters
__myfancysingleton --colour green
--------------------------------------------------------------------------------
HOW TO WRITE A NEW TYPE
@ -46,6 +64,7 @@ A type consists of
- parameter (optional)
- manifest (optional)
- singleton (optional)
- explorer (optional)
- gencode (optional)
@ -98,6 +117,20 @@ Always ensure the manifest is executable, otherwise cdist will not be able
to execute it.
SINGLETON - ONLY INSTANCE ONLY
------------------------------
If you want to ensure that a type can only be used once per target, you can
mark it as a singleton: Just create the (empty) file "singleton" in your type
directory. This will also change the way your type must be called:
--------------------------------------------------------------------------------
__YOURTYPE --parameter value
--------------------------------------------------------------------------------
As you can see, the ID is omitted, because it does not make any sense, if your
type can be used only once.
THE TYPE EXPLORERS
------------------
If a type needs to explore specific details, it can provide type specific