forked from ungleich-public/cdist
integrate the first type manpage into cdist
Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
This commit is contained in:
Nico Schottelius
parent
0e52bfcc40
commit
7a4ab2efd8
4 changed files with 34 additions and 142 deletions
11
Makefile
11
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 \
|
||||
|
|
@ -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]
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
1
doc/man/.gitignore
vendored
1
doc/man/.gitignore
vendored
|
|
@ -1,3 +1,4 @@
|
|||
cdist.7
|
||||
*.html
|
||||
cdist-design.7
|
||||
cdist-type-listing.text
|
||||
|
|
|
|||
160
doc/man/cdist-type-listing.text.sh
Normal file → Executable file
160
doc/man/cdist-type-listing.text.sh
Normal file → Executable file
|
|
@ -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 <nico-cdist--@--schottelius.org>
|
||||
|
|
@ -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 <<eof
|
||||
|
||||
COPYING
|
||||
-------
|
||||
|
|
|
|||
Loading…
Reference in a new issue