From 844862846196e0db4edff020af9513fe92142009 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 19:58:35 +0100 Subject: [PATCH 01/13] add a new section Signed-off-by: Nico Schottelius --- doc/man/to_check/cdist-type.text | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text index cd06463e..bd154813 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/to_check/cdist-type.text @@ -77,8 +77,8 @@ A type consists of - parameter (optional) - manifest (optional) -- gencode (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. @@ -128,8 +128,12 @@ 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 +------------------ + WRITING THE GENCODE SCRIPT -------------------------- +The gencode script can make use HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST ----------------------------------------- From 5d62370ff147e7a7dd327332bf1310c4ec00427c Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 20:00:11 +0100 Subject: [PATCH 02/13] [DOC] begin documentation of environment variables Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 1 + doc/dev/todo/post-1.0 | 13 ------------- doc/man/to_check/cdist-environment-variables.text | 14 ++++++++++++++ 3 files changed, 15 insertions(+), 13 deletions(-) create mode 100644 doc/man/to_check/cdist-environment-variables.text diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 4f8f033d..52bc8041 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,5 +1,6 @@ Documentation cleanup - to_check/cdist-type.text + - document environment variables - cdist-type-integration - Ensure available types are documented (!) - define how to in cdist-type-integration diff --git a/doc/dev/todo/post-1.0 b/doc/dev/todo/post-1.0 index de8919f0..9d6031b4 100644 --- a/doc/dev/todo/post-1.0 +++ b/doc/dev/todo/post-1.0 @@ -38,12 +38,6 @@ Documentation: - via version control - Define how to raise errors in types - - = todo - + = in progress -> S|N - x = done - - - x remove old documentation from doc/man/! - Check all references in manpages, ensure all manpages exist, generic ones: + cdist + cdist-deploy-to @@ -53,13 +47,6 @@ Documentation: - install packages only if not existent - copy file only if different - DOC document that $type/manifest is executed for every object/instance - - exported variables: - - general explorer: __explorer # cdist-explorer - - initial manifest: __manifest, __global # cdist-manifest - - type manifests __object, __object_id, __global # cdist-type - - type explorers: __object, __object_id, __type_explorers # cdist-type - - type codegen: __object, __object_id, __global # cdist-type - - type code: - # cdist-code - category 7: - cdist-manifest(7) - cdist-explorer diff --git a/doc/man/to_check/cdist-environment-variables.text b/doc/man/to_check/cdist-environment-variables.text new file mode 100644 index 00000000..c91a2ae0 --- /dev/null +++ b/doc/man/to_check/cdist-environment-variables.text @@ -0,0 +1,14 @@ +Update on env: + + general explorer: __explorer + initial manifest: __manifest, __global + type manifests __object, __object_id, __global + type explorers: __object, __object_id, __type_explorers, __global + type codegen: __object, __object_id, __global + type code: - + + +- __object: Path to the object that we are working on +- __object_id: type unique object id +- __global: contains global information (see cdist-env + From 7b2e815830718622371b3b3e470bff5d908a8043 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 20:26:44 +0100 Subject: [PATCH 03/13] begin to cleanup cdist-type Signed-off-by: Nico Schottelius --- doc/man/to_check/cdist-type.text | 62 ++++++++++++++------------------ 1 file changed, 27 insertions(+), 35 deletions(-) diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text index bd154813..b4df77d7 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/to_check/cdist-type.text @@ -1,5 +1,5 @@ cdist-type(7) -============== +============= Nico Schottelius @@ -20,39 +20,6 @@ use cdist, you'll write a type for every functionality you would like to use. - -Was man mit cdist type machen kann..... - -A cdist type describes some kind of functionality, starting from simple stuff -like copying files until complex user auth/ldap/ kerberos infrastructure -designs. The name of every type is prefixed with two underscores (__) by convention. - - -, because -types will be executed and the two underscores prevent collisions with real -binaries (like "file"). -In general, types should be written independent of hosts (as in reusable -code), but may be used implement functionality only needed on one host -as well. -It must be assumed that the clients are pretty dumb and thus do 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 must create an object of the specific type. -If the generated code fails on the client, it must print diagnostistic messages on -stderr and exit non-zero, so the configuration is aborted. -Types may make use of other types to realise a new type or may implement some -functionality on their own. - -Types may consist of -- a number of required and optional parameters they accept, -- a manifest script that makes use of the parameters and may create other objects -- explorers that explore type specific information on the target -- a gencode script, that may generate code to be executed on the target - -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 @@ -128,12 +95,36 @@ 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 ------------------ WRITING THE GENCODE SCRIPT -------------------------- -The gencode script can make use +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 ----------------------------------------- @@ -148,6 +139,7 @@ underscores) included. SEE ALSO -------- - cdist-manifest-run(1) +- cdist-stages(7) COPYING From 45737ce452ca99cdd9c29b660399f2352abd163f Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 20:35:21 +0100 Subject: [PATCH 04/13] [DOC] add cdist-type manpage Signed-off-by: Nico Schottelius --- Makefile | 2 +- doc/man/{to_check => }/cdist-type.text | 25 ++++++++++++++++++++++--- 2 files changed, 23 insertions(+), 4 deletions(-) rename doc/man/{to_check => }/cdist-type.text (83%) diff --git a/Makefile b/Makefile index ddada4c3..95507337 100644 --- a/Makefile +++ b/Makefile @@ -15,13 +15,13 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-quickstart.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ - $(MANDIR)/cdist-type.text MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ $(MANDIR)/cdist-manifest.text \ $(MANDIR)/cdist-stages.text \ + $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ diff --git a/doc/man/to_check/cdist-type.text b/doc/man/cdist-type.text similarity index 83% rename from doc/man/to_check/cdist-type.text rename to doc/man/cdist-type.text index b4df77d7..ad051585 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/cdist-type.text @@ -98,6 +98,25 @@ 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 -------------------------- @@ -132,8 +151,8 @@ 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. +Ensure a corresponding manpage named cdist-type-NAME (without +underscores) is included. SEE ALSO @@ -144,5 +163,5 @@ SEE ALSO COPYING ------- -Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is +Copyright \(C) 2011 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). From a138f2ec965464a12a0b42cdeba9bba0779a8ccc Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 20:36:18 +0100 Subject: [PATCH 05/13] less todo for nico Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 52bc8041..636cd561 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,9 +1,4 @@ Documentation cleanup - - to_check/cdist-type.text - document environment variables - - cdist-type-integration - - Ensure available types are documented (!) - - define how to in cdist-type-integration - - referenced on the webpage via cdist-type(7)! - - - how to debug explorer and codegen + - Reference all types somewhere (on the webpage?) + - how to debug explorer From ed92a7d6fd51a7445eeeaeeb33072003e6c2c679 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 20:37:52 +0100 Subject: [PATCH 06/13] upcoming changes for 1.0.2 Signed-off-by: Nico Schottelius --- doc/changelog | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/changelog b/doc/changelog index 179afd8d..b0087c36 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,3 +1,7 @@ +1.0.2: upcoming + * Add manpages: cdist-type + * Make doc/man/ usable as MANPATH entry + 1.0.1: 2011-03-08 * Added cdist-type-template including manpage * Fix manpage building From 2dbb289fc3f665efb66e1cd277ff6d25f0d609b0 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:23:44 +0100 Subject: [PATCH 07/13] remove all generated/moved manpages Signed-off-by: Nico Schottelius --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 95507337..deefbafd 100644 --- a/Makefile +++ b/Makefile @@ -48,7 +48,7 @@ doc/man/.marker: $(MANSRC) touch $@ clean: - rm -f doc/man/*.html doc/man/*.[1-9] + rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] ################################################################################ # Developer targets From 8549e74f45d631b3e5627b4f2527839601163a07 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:25:35 +0100 Subject: [PATCH 08/13] name type manpages differently Signed-off-by: Nico Schottelius --- doc/man/cdist-type.text | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/man/cdist-type.text b/doc/man/cdist-type.text index ad051585..3c7a1317 100644 --- a/doc/man/cdist-type.text +++ b/doc/man/cdist-type.text @@ -151,8 +151,7 @@ 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 (without -underscores) is included. +Ensure a corresponding manpage named cdist-type__NAME is included. SEE ALSO From 4bb7fb5c59c412d34503a295b78a294a2365d58f Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:27:57 +0100 Subject: [PATCH 09/13] 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). From a095b1a3c323b7a58db4bc999e2cffeb13785ded Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:47:08 +0100 Subject: [PATCH 10/13] finish manpage for cdist-type__file Signed-off-by: Nico Schottelius --- Makefile | 1 + doc/man/cdist-type__file.text | 173 +++++++--------------------------- 2 files changed, 34 insertions(+), 140 deletions(-) diff --git a/Makefile b/Makefile index deefbafd..e003c0c6 100644 --- a/Makefile +++ b/Makefile @@ -23,6 +23,7 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ + $(MANDIR)/cdist-type__file.text \ ################################################################################ diff --git a/doc/man/cdist-type__file.text b/doc/man/cdist-type__file.text index 3c7a1317..04e0ffc3 100644 --- a/doc/man/cdist-type__file.text +++ b/doc/man/cdist-type__file.text @@ -1,163 +1,56 @@ -cdist-type(7) -============= +cdist-type__file(7) +=================== Nico Schottelius NAME ---- -cdist-type - Functionality bundled - - -SYNOPSIS --------- -Other languages name this module or class +cdist-type__file - Create files 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. +This cdist type allows you to create files on the target. -HOW TO USE A TYPE ------------------ -You can use types from the initial manifest or the type manifest like a -normal command: +REQUIRED PARAMETERS +------------------- +type:: + Specifies the type of file to be created. Either "directory" or "file" + + +OPTIONAL PARAMETERS +------------------- +destination:: + If supplied, use this as the destination on the target. Otherwise the + object_id is used. + +mode:: + Unix permissions, suitable for chmod. + +source:: + If supplied, copy this file from the host running cdist to the target. + If not supplied, an empty file or directory will be created. + + +EXAMPLES +-------- -------------------------------------------------------------------------------- -# Creates empty file /etc/cdist-configured +# Create /etc/cdist-configured as an empty file __file /etc/cdist-configured --type file -# Ensure tree is installed -__package tree --state installed +# Same but with a different object id +__file cdist-marker --type file --destination /etc/cdist-configured + +# Use __file from another type +__file /etc/issue --source "$__type/files/archlinux" --type file -------------------------------------------------------------------------------- -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) +- cdist-type(7) COPYING From 43a4dd49ca87581404a85ee7fdd83bb9c27d5280 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 21:51:58 +0100 Subject: [PATCH 11/13] define how to use manpages Signed-off-by: Nico Schottelius --- REAL_README | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/REAL_README b/REAL_README index 10b1b812..ab070b38 100644 --- a/REAL_README +++ b/REAL_README @@ -79,6 +79,10 @@ To install cdist, execute the following commands: cd cdist export PATH=$PATH:$(pwd -P)/bin + # If you want the manpages + make man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + Afterwards you can run ***cdist-quickstart*** to get an impression on how to use cdist. @@ -105,6 +109,11 @@ To upgrade cdist in the current branch use git pull + # Also update the manpages + make man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + + The version branches are designed to change if there are incompatibilities. Or the other way round: As long as you stay on 1.0 and do git pull, nothing should break. From 4c5069e0cdfe14c2bc87ecd2baad4587863d6183 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 22:04:32 +0100 Subject: [PATCH 12/13] begin manpage to include all types Signed-off-by: Nico Schottelius --- doc/man/cdist-type-supported.text.sh | 203 +++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 doc/man/cdist-type-supported.text.sh diff --git a/doc/man/cdist-type-supported.text.sh b/doc/man/cdist-type-supported.text.sh new file mode 100644 index 00000000..78c04a43 --- /dev/null +++ b/doc/man/cdist-type-supported.text.sh @@ -0,0 +1,203 @@ +#!/bin/sh +# +# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org) +# +# This file is part of cdist. +# +# cdist is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# cdist is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with cdist. If not, see . +# +# +# Generate manpage that lists available types +# + +__cdist_pwd="$(pwd -P)" +__cdist_mydir="${0%/*}"; +__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)" +__cdist_myname=${0##*/}; +__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" + +filename="${__cdist_myname%.sh}" +dest="$__cdist_abs_mydir/$filename" + +exit 0 + +cat << eof > "$dest" +cdist-type-listing(7) +===================== +Nico Schottelius + + +NAME +---- +cdist-type-listing - Available types in cdist + + +SYNOPSIS +-------- +Types that are included in cdist $(git describe). + + +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-$(date +%Y) Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). + +eof From 0e52bfcc4032477b8d152e0fa7683c26b6355992 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 8 Mar 2011 22:04:49 +0100 Subject: [PATCH 13/13] and name it type-listing Signed-off-by: Nico Schottelius --- .../{cdist-type-supported.text.sh => cdist-type-listing.text.sh} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/man/{cdist-type-supported.text.sh => cdist-type-listing.text.sh} (100%) diff --git a/doc/man/cdist-type-supported.text.sh b/doc/man/cdist-type-listing.text.sh similarity index 100% rename from doc/man/cdist-type-supported.text.sh rename to doc/man/cdist-type-listing.text.sh