From 20b50ea19fd04d66e153fc4a34fa4d73842a9ace Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 12:18:26 +0100 Subject: [PATCH 1/4] prepend new path, so running HACKERS_README in biased environment works Signed-off-by: Nico Schottelius --- HACKERS_README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HACKERS_README b/HACKERS_README index fa01666f..0ae1bdcd 100755 --- a/HACKERS_README +++ b/HACKERS_README @@ -33,7 +33,7 @@ set -x # Tell the user what we do, so this script makes sense during execution # prepare use (only from top level directory) -export PATH="$PATH:$(pwd -P)/bin" +export PATH="$(pwd -P)/bin:$PATH" export __cdist_conf_dir="$(pwd -P)/conf" # Allow user to supply hostname From 1b3aef7ea35e2e4510817534f9c05acefed80701 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 12:36:59 +0100 Subject: [PATCH 2/4] how to use a type, how to define parameters Signed-off-by: Nico Schottelius --- doc/man/to_check/cdist-type.text | 38 +++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text index 9e9642a1..26706ae4 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/to_check/cdist-type.text @@ -53,11 +53,29 @@ Every time a type is used, a new object is created of the specific type, with a type specific unique id that stores the parameters +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 (required) +- parameter (optional) - manifest (optional) - gencode (optional) - explorer (optional) @@ -66,14 +84,26 @@ 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 to conf/type/__NAME. +and cd conf/type/__NAME. DEFINING PARAMETERS ------------------- -Every type consists of optional and +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 +-------------------- + HOW TO WRITE A NEW TYPE (TODO) ------------------------------ Assume you want to create the new type named "coffee", which creates @@ -104,6 +134,8 @@ SEE ALSO cdist-config-layout(7), cdist-type-manifest(7), cdist-type-explorer(7), cdist-type-gencode(7) +- cdist-manifest-run(1) + COPYING ------- From cc28d4ddbb439138f82fe6331a8a30b5e86ef00f Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 12:39:05 +0100 Subject: [PATCH 3/4] do not exit 0 if __package_$type does not exit 0 Signed-off-by: Nico Schottelius --- conf/type/__package/manifest | 2 -- 1 file changed, 2 deletions(-) diff --git a/conf/type/__package/manifest b/conf/type/__package/manifest index cf085e2f..d8b55814 100755 --- a/conf/type/__package/manifest +++ b/conf/type/__package/manifest @@ -49,5 +49,3 @@ for property in $(ls .); do done __package_$type "$@" - -exit 0 From bc436c6c5cb0658b53f12f718d11a88cb1789742 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 12:47:51 +0100 Subject: [PATCH 4/4] describe how to submit a new cdist type for inclusion Signed-off-by: Nico Schottelius --- doc/man/to_check/cdist-type.text | 53 +++++++++++++++++++------------- 1 file changed, 31 insertions(+), 22 deletions(-) diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text index 26706ae4..cd06463e 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/to_check/cdist-type.text @@ -103,37 +103,46 @@ 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: -HOW TO WRITE A NEW TYPE (TODO) ------------------------------- -Assume you want to create the new type named "coffee", which creates -files which contain the word "c0ffee". +-------------------------------------------------------------------------------- +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 "$@" +-------------------------------------------------------------------------------- -Create the directory conf/type/coffee/. -Create the file /etc/cdist/types/coffee/README containing a description of the -type. -If your type supports attributes, create the directory /etc/cdist/types/coffee/ -attributes. -For each attribute, create the file - /etc/cdist/types/coffee/attributes/$attribute_name which contains +As you can see, the type can reference different environment variables, +which are documented in cdist-environment-variables(7). - a short description on the first line - then a blank line - then a long description (probably over several lines) +Always ensure the manifest is executable, otherwise cdist will not be able +to execute it. -If you think your type may be useful for others, submit it for inclusion -into cdist at cdist -- at -- l.schottelius.org. +WRITING THE GENCODE SCRIPT +-------------------------- -Create /etc/cdist/types/coffee/init which reads $configinput -(either via cconfig or via environment) and outputs a block of -shell code suitable for running on the client. +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 there is a corresponding manpage named cdist-type-NAME (without +underscores) included. SEE ALSO -------- -cdist-config-layout(7), cdist-type-manifest(7), cdist-type-explorer(7), -cdist-type-gencode(7) - - cdist-manifest-run(1)