From 4bb7fb5c59c412d34503a295b78a294a2365d58f Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:27:57 +0100 Subject: [PATCH] add template for manpage of __file type Signed-off-by: Nico Schottelius --- doc/man/cdist-type__file.text | 166 ++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 doc/man/cdist-type__file.text diff --git a/doc/man/cdist-type__file.text b/doc/man/cdist-type__file.text new file mode 100644 index 00000000..3c7a1317 --- /dev/null +++ b/doc/man/cdist-type__file.text @@ -0,0 +1,166 @@ +cdist-type(7) +============= +Nico Schottelius + + +NAME +---- +cdist-type - Functionality bundled + + +SYNOPSIS +-------- +Other languages name this module or class + + +DESCRIPTION +----------- +Types are the main component of cdist and define functionality. If you +use cdist, you'll write a type for every functionality you would like +to use. + + +HOW TO USE A TYPE +----------------- +You can use types from the initial manifest or the type manifest like a +normal command: + +-------------------------------------------------------------------------------- +# Creates empty file /etc/cdist-configured +__file /etc/cdist-configured --type file + +# Ensure tree is installed +__package tree --state installed +-------------------------------------------------------------------------------- + +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). + + +HOW TO WRITE A NEW TYPE +----------------------- +A type consists of + +- parameter (optional) +- manifest (optional) +- explorer (optional) +- gencode (optional) + +Types are stored below conf/type/. Their name should always be prefixed with +two underscores (__) to prevent collisions with other binaries in $PATH. + +To begin a new type from a template, execute "cdist-type-template __NAME" +and cd conf/type/__NAME. + + +DEFINING PARAMETERS +------------------- +Every type consists of optional and required parameters, which must +be created in a newline seperated file in parameters/required and +parameters/optional. If either or both missing, the type will have +no required, no optional or no parameters at all. + +Example: +-------------------------------------------------------------------------------- +echo servername >> conf/type/__nginx_vhost/parameter/required +echo logdirectory >> conf/type/__nginx_vhost/parameter/optional +-------------------------------------------------------------------------------- + + +WRITING THE MANIFEST +-------------------- +In the manifest of a type you can use other types, so your type extends +their functionality. A good example is the __package type, which in +a shortened version looks like this: + +-------------------------------------------------------------------------------- +os="$(cat "$__global/explorer/os")" +case "$os" in + archlinux) type="pacman" ;; + debian|ubuntu) type="apt" ;; + gentoo) type="emerge" ;; + *) + echo "Don't know how to manage packages on: $os" >&2 + exit 1 + ;; +esac + +__package_$type "$@" +-------------------------------------------------------------------------------- + +As you can see, the type can reference different environment variables, +which are documented in cdist-environment-variables(7). + +Always ensure the manifest is executable, otherwise cdist will not be able +to execute it. + + +THE TYPE EXPLORERS +------------------ +If a type needs to explore specific details, it can provide type specific +explorers, which will be executed on the target for every created object. + +The explorers are stored under the "explorer" directory below the type. +It could for instance contain code to check the md5sum of a file on the +client, like this (shortened version from real type __file): + +-------------------------------------------------------------------------------- +if [ -f "$__object/parameter/destination" ]; then + destination="$(cat "$__object/parameter/destination")" +else + destination="/$__object_id" +fi + +if [ -e "$destination" ]; then + md5sum < "$destination" +fi +-------------------------------------------------------------------------------- + + +WRITING THE GENCODE SCRIPT +-------------------------- +The gencode script can make use of the parameters, the global explorers +and the type specific explorers. The output (stdout) of this script is +saved by cdist and will be executed on the target. + +If the gencode script encounters an error, it should print diagnostic +messages to stderr and exit non-zero. If you need to debug the gencode +script, you can write to stderr: + +-------------------------------------------------------------------------------- +# Debug output to stderr +echo "My fancy debug line" >&2 + +# Output to be saved by cdist for execution on the target +echo "touch /etc/cdist-configured" +-------------------------------------------------------------------------------- + + +HINTS FOR TYPEWRITERS +---------------------- +It must be assumed that the target is pretty dumb and thus does not have high +level tools like ruby installed. If a type requires specific tools to be present +on the target, there must be another type that provides this tool and the first +type should create an object of the specific type. + + +HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST +----------------------------------------- +If you think your type may be useful for others, ensure it works with the +current master branch of cdist and submit the git url containing the type for +inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**. + +Ensure a corresponding manpage named cdist-type__NAME is included. + + +SEE ALSO +-------- +- cdist-manifest-run(1) +- cdist-stages(7) + + +COPYING +------- +Copyright \(C) 2011 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3).