From 7a4ab2efd8ea6e42a46177c85220ae0ca6f8804a Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 08:53:19 +0100 Subject: [PATCH] integrate the first type manpage into cdist Signed-off-by: Nico Schottelius --- Makefile | 13 ++- doc/changelog | 2 +- doc/man/.gitignore | 1 + doc/man/cdist-type-listing.text.sh | 160 ++++------------------------- 4 files changed, 34 insertions(+), 142 deletions(-) mode change 100644 => 100755 doc/man/cdist-type-listing.text.sh diff --git a/Makefile b/Makefile index e003c0c6..5d099260 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,8 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ +MANGENERATED=$(MANDIR)/cdist-type-listing.text + MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ @@ -23,7 +25,7 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ - $(MANDIR)/cdist-type__file.text \ + $(MANDIR)/cdist-type__file.text \ ################################################################################ @@ -43,11 +45,16 @@ all: man: doc/man/.marker -doc/man/.marker: $(MANSRC) - for mansrc in $(MANSRC); do $(A2X) $$mansrc; done +doc/man/.marker: $(MANSRC) $(MANGENERATED) + for mansrc in $^; do $(A2X) $$mansrc; done for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done touch $@ +# Only depends on cdist-type__*.text in reality +$(MANDIR)/cdist-type-listing.text: $(MANSRC) $(MANDIR)/cdist-type-listing.text.sh + $(MANDIR)/cdist-type-listing.text.sh + + clean: rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] diff --git a/doc/changelog b/doc/changelog index b0087c36..528b7e86 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ 1.0.2: upcoming - * Add manpages: cdist-type + * Add manpages: cdist-type, cdist-type__file * Make doc/man/ usable as MANPATH entry 1.0.1: 2011-03-08 diff --git a/doc/man/.gitignore b/doc/man/.gitignore index 22d0a62d..299485e8 100644 --- a/doc/man/.gitignore +++ b/doc/man/.gitignore @@ -1,3 +1,4 @@ cdist.7 *.html cdist-design.7 +cdist-type-listing.text diff --git a/doc/man/cdist-type-listing.text.sh b/doc/man/cdist-type-listing.text.sh old mode 100644 new mode 100755 index 78c04a43..d1da1477 --- a/doc/man/cdist-type-listing.text.sh +++ b/doc/man/cdist-type-listing.text.sh @@ -30,9 +30,11 @@ __cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" filename="${__cdist_myname%.sh}" dest="$__cdist_abs_mydir/$filename" -exit 0 +cd "$__cdist_abs_mydir" -cat << eof > "$dest" +exec > "$dest" + +cat << eof cdist-type-listing(7) ===================== Nico Schottelius @@ -50,150 +52,32 @@ 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. +The following types are available: +eof +for type in cdist-type__*.text; do + name_1="${type#cdist-type}" + name_2="${name_1%.text}" -HOW TO USE A TYPE ------------------ -You can use types from the initial manifest or the type manifest like a -normal command: + name="$name_2" + echo "- $name" +done --------------------------------------------------------------------------------- -# 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. +cat << eof SEE ALSO -------- -- cdist-manifest-run(1) -- cdist-stages(7) +- cdist-type(7) +eof +for type in cdist-type__*.text; do + name_2="${type%.text}" + name="$name_2" + echo "- ${name}(7)" +done + +cat <