[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 set -u
################################################################################ ################################################################################

View file

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

View file

@ -10,7 +10,9 @@ cdist-type - Functionality bundled
SYNOPSIS SYNOPSIS
-------- --------
Other languages name this module or class __TYPE ID --parameter value [--parameter value ...]
__TYPE --parameter value [--parameter value ...] (for singletons)
DESCRIPTION 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 save the given parameters into a cconfig database, so they can be accessed by
the manifest and gencode scripts of the type (see below). 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 HOW TO WRITE A NEW TYPE
@ -46,6 +64,7 @@ A type consists of
- parameter (optional) - parameter (optional)
- manifest (optional) - manifest (optional)
- singleton (optional)
- explorer (optional) - explorer (optional)
- gencode (optional) - gencode (optional)
@ -98,6 +117,20 @@ Always ensure the manifest is executable, otherwise cdist will not be able
to execute it. 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 THE TYPE EXPLORERS
------------------ ------------------
If a type needs to explore specific details, it can provide type specific If a type needs to explore specific details, it can provide type specific