forked from ungleich-public/cdist
build type manpages using the Makefile
Signed-off-by: Nico Schottelius <nico@bento.schottelius.org>
This commit is contained in:
Nico Schottelius
parent
067af56cd8
commit
5712df850b
3 changed files with 77 additions and 345 deletions
80
Makefile
80
Makefile
|
|
@ -23,11 +23,60 @@ A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8
|
||||||
helper=./bin/build-helper
|
helper=./bin/build-helper
|
||||||
|
|
||||||
MANDIR=docs/man
|
MANDIR=docs/man
|
||||||
|
|
||||||
MAN1DSTDIR=$(MANDIR)/man1
|
MAN1DSTDIR=$(MANDIR)/man1
|
||||||
MAN7DSTDIR=$(MANDIR)/man7
|
MAN7DSTDIR=$(MANDIR)/man7
|
||||||
MANREF=$(MAN7DSTDIR)/cdist-reference.text
|
MANREF=$(MAN7DSTDIR)/cdist-reference.text
|
||||||
MANREFSH=$(MANDIR)/cdist-reference.text.sh
|
MANREFSH=$(MANDIR)/cdist-reference.text.sh
|
||||||
|
|
||||||
|
SPEECHDIR=docs/speeches
|
||||||
|
|
||||||
|
TYPEDIR=cdist/conf/type
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Manpages for types
|
||||||
|
#
|
||||||
|
# Use shell / ls to get complete list - $(TYPEDIR)/*/man.text does not work
|
||||||
|
TYPEMANSRC=$(shell ls $(TYPEDIR)/*/man.text)
|
||||||
|
|
||||||
|
# replace first path component
|
||||||
|
TYPEMANPREFIX=$(subst cdist/conf/type/,docs/man/man7/cdist-type,$(TYPEMANSRC))
|
||||||
|
|
||||||
|
# replace man.text with .7 or .html
|
||||||
|
TYPEMANPAGES=$(subst /man.text,.7,$(TYPEMANPREFIX))
|
||||||
|
TYPEMANHTML=$(subst /man.text,.html,$(TYPEMANPREFIX))
|
||||||
|
|
||||||
|
|
||||||
|
# Link manpage so A2XH does not create man.html but correct named file
|
||||||
|
$(MAN7DSTDIR)/cdist-type%.text: $(TYPEDIR)/%/man.text
|
||||||
|
ln -sf "../../../$^" $@
|
||||||
|
|
||||||
|
# Creating the type manpage
|
||||||
|
$(MAN7DSTDIR)/cdist-type%.7: $(MAN7DSTDIR)/cdist-type%.text
|
||||||
|
$(A2XM) $^
|
||||||
|
|
||||||
|
# Creating the type html page
|
||||||
|
$(MAN7DSTDIR)/cdist-type%.html: $(MAN7DSTDIR)/cdist-type%.text
|
||||||
|
$(A2XH) $^
|
||||||
|
|
||||||
|
typemanpage: $(TYPEMANPAGES)
|
||||||
|
typemanhtml: $(TYPEMANHTML)
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Speeches
|
||||||
|
#
|
||||||
|
SPEECHESOURCES=$(SPEECHDIR)/*.tex
|
||||||
|
SPEECHES=$(SPEECHESOURCES:.tex=.pdf)
|
||||||
|
|
||||||
|
# Create speeches and ensure Toc is up-to-date
|
||||||
|
$(SPEECHDIR)/%.pdf: $(SPEECHDIR)/%.tex
|
||||||
|
pdflatex -output-directory $(SPEECHDIR) $^
|
||||||
|
pdflatex -output-directory $(SPEECHDIR) $^
|
||||||
|
pdflatex -output-directory $(SPEECHDIR) $^
|
||||||
|
|
||||||
|
speeches: $(SPEECHES)
|
||||||
|
|
||||||
|
################################################################################
|
||||||
CHECKS=check-version check-date
|
CHECKS=check-version check-date
|
||||||
|
|
||||||
DIST=dist-tag dist-branch-merge
|
DIST=dist-tag dist-branch-merge
|
||||||
|
|
@ -51,12 +100,6 @@ $(RELEASE): $(DIST) $(CHECKS)
|
||||||
|
|
||||||
man: $(MANREF) mantype manbuild
|
man: $(MANREF) mantype manbuild
|
||||||
|
|
||||||
$(MAN7DSTDIR)/cdist-type__motd.7: $(MAN7DSTDIR)/cdist-type__motd.text
|
|
||||||
$(A2XM) $^
|
|
||||||
|
|
||||||
$(MAN7DSTDIR)/cdist-type__motd.text: cdist/conf/type/__motd/man.text
|
|
||||||
echo ln -sf $@ $^
|
|
||||||
|
|
||||||
$(MANREF): $(MANREFSH)
|
$(MANREF): $(MANREFSH)
|
||||||
$(MANREFSH)
|
$(MANREFSH)
|
||||||
|
|
||||||
|
|
@ -75,7 +118,6 @@ link-type-manpages:
|
||||||
$(helper) $@
|
$(helper) $@
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
################################################################################
|
################################################################################
|
||||||
# dist code
|
# dist code
|
||||||
#
|
#
|
||||||
|
|
@ -109,6 +151,30 @@ release-web: web-doc
|
||||||
PKGBUILD: PKGBUILD.in
|
PKGBUILD: PKGBUILD.in
|
||||||
./PKGBUILD.in
|
./PKGBUILD.in
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Cleanup
|
||||||
|
|
||||||
|
clean:
|
||||||
|
rm -f $(MAN7DSTDIR)/cdist-reference.text
|
||||||
|
|
||||||
|
find "$(MANDIR)" -mindepth 2 -type l \
|
||||||
|
-o -name "*.1" \
|
||||||
|
-o -name "*.7" \
|
||||||
|
-o -name "*.html" \
|
||||||
|
-o -name "*.xml" \
|
||||||
|
| xargs rm -f
|
||||||
|
|
||||||
|
find * -name __pycache__ | xargs rm -rf
|
||||||
|
|
||||||
|
distclean:
|
||||||
|
rm -f cdist/version.py MANIFEST PKGBUILD
|
||||||
|
rm -rf cache/ dist/
|
||||||
|
|
||||||
|
# Archlinux
|
||||||
|
rm -f cdist-*.pkg.tar.xz cdist-*.tar.gz
|
||||||
|
rm -rf pkg/ src/
|
||||||
|
|
||||||
|
|
||||||
################################################################################
|
################################################################################
|
||||||
# generic call
|
# generic call
|
||||||
%:
|
%:
|
||||||
|
|
|
||||||
|
|
@ -46,34 +46,6 @@ MAN7DSTDIR=${MANDIR}/man7
|
||||||
SPEECHESDIR=docs/speeches
|
SPEECHESDIR=docs/speeches
|
||||||
|
|
||||||
case "$1" in
|
case "$1" in
|
||||||
manbuild)
|
|
||||||
trap abort INT
|
|
||||||
abort() {
|
|
||||||
kill 0
|
|
||||||
}
|
|
||||||
for section in 1 7; do
|
|
||||||
for src in ${MANDIR}/man${section}/*.text; do
|
|
||||||
manpage="${src%.text}.$section"
|
|
||||||
if [ ! -f "$manpage" -o "$manpage" -ot "$src" ]; then
|
|
||||||
echo "Compiling man page for $src"
|
|
||||||
$A2XM "$src"
|
|
||||||
fi
|
|
||||||
htmlpage="${src%.text}.html"
|
|
||||||
if [ ! -f "$htmlpage" -o "$htmlpage" -ot "$src" ]; then
|
|
||||||
echo "Compiling html page for $src"
|
|
||||||
$A2XH "$src"
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
done
|
|
||||||
;;
|
|
||||||
|
|
||||||
link-type-manpages)
|
|
||||||
for mansrc in cdist/conf/type/*/man.text; do
|
|
||||||
dst="$(echo $mansrc | sed -e 's;cdist/conf/;cdist-;' -e 's;/;;' -e 's;/man;;' -e 's;^;docs/man/man7/;')"
|
|
||||||
ln -sf "../../../$mansrc" "$dst"
|
|
||||||
done
|
|
||||||
;;
|
|
||||||
|
|
||||||
release-man)
|
release-man)
|
||||||
version=$($0 changelog-version)
|
version=$($0 changelog-version)
|
||||||
|
|
||||||
|
|
@ -236,15 +208,6 @@ eof
|
||||||
|
|
||||||
;;
|
;;
|
||||||
|
|
||||||
dist-speeches)
|
|
||||||
cd "$SPEECHESDIR"
|
|
||||||
for speech in *tex; do
|
|
||||||
pdflatex "$speech"
|
|
||||||
pdflatex "$speech"
|
|
||||||
pdflatex "$speech"
|
|
||||||
done
|
|
||||||
;;
|
|
||||||
|
|
||||||
web-doc)
|
web-doc)
|
||||||
rsync -av "${basedir}/docs/web/" "${WEBTOPDIR}"
|
rsync -av "${basedir}/docs/web/" "${WEBTOPDIR}"
|
||||||
|
|
||||||
|
|
@ -268,27 +231,6 @@ eof
|
||||||
done
|
done
|
||||||
;;
|
;;
|
||||||
|
|
||||||
clean)
|
|
||||||
rm -f ${MAN7DSTDIR}/cdist-reference.text
|
|
||||||
|
|
||||||
find "${MANDIR}" -mindepth 2 -type l \
|
|
||||||
-o -name "*.1" \
|
|
||||||
-o -name "*.7" \
|
|
||||||
-o -name "*.html" \
|
|
||||||
-o -name "*.xml" \
|
|
||||||
| xargs rm -f
|
|
||||||
|
|
||||||
find * -name __pycache__ | xargs rm -rf
|
|
||||||
;;
|
|
||||||
distclean)
|
|
||||||
rm -f cdist/version.py MANIFEST PKGBUILD
|
|
||||||
rm -rf cache/ dist/
|
|
||||||
|
|
||||||
# Archlinux
|
|
||||||
rm -f cdist-*.pkg.tar.xz cdist-*.tar.gz
|
|
||||||
rm -rf pkg/ src/
|
|
||||||
;;
|
|
||||||
|
|
||||||
test)
|
test)
|
||||||
shift # skip t
|
shift # skip t
|
||||||
export PYTHONPATH="$(pwd -P)"
|
export PYTHONPATH="$(pwd -P)"
|
||||||
|
|
@ -303,6 +245,10 @@ eof
|
||||||
echo "VERSION = \"$(git describe)\"" > cdist/version.py
|
echo "VERSION = \"$(git describe)\"" > cdist/version.py
|
||||||
;;
|
;;
|
||||||
|
|
||||||
|
# Targets handled in the makefile
|
||||||
|
speeches|clean|dist-clean)
|
||||||
|
;;
|
||||||
|
|
||||||
*)
|
*)
|
||||||
echo "Unknown target $@ - aborting"
|
echo "Unknown target $@ - aborting"
|
||||||
exit 1
|
exit 1
|
||||||
|
|
|
||||||
|
|
@ -1,280 +0,0 @@
|
||||||
cdist-type(7)
|
|
||||||
=============
|
|
||||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
|
||||||
|
|
||||||
|
|
||||||
NAME
|
|
||||||
----
|
|
||||||
cdist-type - Functionality bundled
|
|
||||||
|
|
||||||
|
|
||||||
SYNOPSIS
|
|
||||||
--------
|
|
||||||
__TYPE ID --parameter value [--parameter value ...]
|
|
||||||
|
|
||||||
__TYPE --parameter value [--parameter value ...] (for singletons)
|
|
||||||
|
|
||||||
|
|
||||||
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
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
A list of supported types can be found in the cdist-reference(7) manpage.
|
|
||||||
|
|
||||||
|
|
||||||
SINGLETON TYPES
|
|
||||||
---------------
|
|
||||||
If a type is flagged as a singleton, it may be used only
|
|
||||||
once per host. This is useful for types which can be used only once on a
|
|
||||||
system. Singleton types do not take an object name as argument.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
# __issue type manages /etc/issue
|
|
||||||
__issue
|
|
||||||
|
|
||||||
# Probably your own type - singletons may use parameters
|
|
||||||
__myfancysingleton --colour green
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
|
|
||||||
HOW TO WRITE A NEW TYPE
|
|
||||||
-----------------------
|
|
||||||
A type consists of
|
|
||||||
|
|
||||||
- parameter (optional)
|
|
||||||
- manifest (optional)
|
|
||||||
- singleton (optional)
|
|
||||||
- explorer (optional)
|
|
||||||
- gencode (optional)
|
|
||||||
|
|
||||||
Types are stored below cdist/conf/type/. Their name should always be prefixed with
|
|
||||||
two underscores (__) to prevent collisions with other executables in $PATH.
|
|
||||||
|
|
||||||
To implement a new type, create the directory **cdist/conf/type/__NAME**.
|
|
||||||
|
|
||||||
|
|
||||||
DEFINING PARAMETERS
|
|
||||||
-------------------
|
|
||||||
Every type consists of required, optional and boolean parameters, which must
|
|
||||||
each be declared in a newline separated file in ***parameter/required***,
|
|
||||||
***parameter/required_multiple***, ***parameter/optional***,
|
|
||||||
***parameter/optional_multiple*** and ***parameter/boolean***.
|
|
||||||
Parameters which are allowed multiple times should be listed in
|
|
||||||
required_multiple or optional_multiple respectively. All other parameters
|
|
||||||
follow the standard unix behaviour "the last given wins".
|
|
||||||
If either is missing, the type will have no required, no optional, no boolean
|
|
||||||
or no parameters at all.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
echo servername >> cdist/conf/type/__nginx_vhost/parameter/required
|
|
||||||
echo logdirectory >> cdist/conf/type/__nginx_vhost/parameter/optional
|
|
||||||
echo server_alias >> cdist/conf/type/__nginx_vhost/parameter/optional_multiple
|
|
||||||
echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
|
|
||||||
USING PARAMETERS
|
|
||||||
----------------
|
|
||||||
The parameters given to a type can be accessed and used in all type scripts
|
|
||||||
(e.g manifest, gencode-*, explorer/*). Note that boolean parameters are
|
|
||||||
represented by file existence. File exists -> True,
|
|
||||||
file does not exist -> False
|
|
||||||
|
|
||||||
Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
# required parameter
|
|
||||||
servername="$(cat "$__object/parameter/servername")"
|
|
||||||
|
|
||||||
# optional parameter
|
|
||||||
if [ -f "$__object/parameter/logdirectory" ]; then
|
|
||||||
logdirectory="$(cat "$__object/parameter/logdirectory")"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# boolean parameter
|
|
||||||
if [ -f "$__object/parameter/use_ssl" ]; then
|
|
||||||
# file exists -> True
|
|
||||||
# do some fancy ssl stuff
|
|
||||||
fi
|
|
||||||
|
|
||||||
# parameter with multiple values
|
|
||||||
if [ -f "$__object/parameter/server_alias" ]; then
|
|
||||||
for alias in $(cat "$__object/parameter/server_alias"); do
|
|
||||||
echo $alias > /some/where/usefull
|
|
||||||
done
|
|
||||||
fi
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
|
|
||||||
INPUT FROM STDIN
|
|
||||||
----------------
|
|
||||||
Every type can access what has been written on stdin when it has been called.
|
|
||||||
The result is saved into the ***stdin*** file in the object directory.
|
|
||||||
|
|
||||||
Example use of a type: (e.g. in cdist/conf/type/__archlinux_hostname)
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
__file /etc/rc.conf --source - << eof
|
|
||||||
...
|
|
||||||
HOSTNAME="$__target_host"
|
|
||||||
...
|
|
||||||
eof
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
If you have not seen this syntax (<< eof) before, it may help you to read
|
|
||||||
about "here documents".
|
|
||||||
|
|
||||||
In the __file type, stdin is used as source for the file, if - is used for source:
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
if [ -f "$__object/parameter/source" ]; then
|
|
||||||
source="$(cat "$__object/parameter/source")"
|
|
||||||
if [ "$source" = "-" ]; then
|
|
||||||
source="$__object/stdin"
|
|
||||||
fi
|
|
||||||
....
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
|
|
||||||
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-reference(7).
|
|
||||||
|
|
||||||
Always ensure the manifest is executable, otherwise cdist will not be able
|
|
||||||
to execute it. For more information about manifests see cdist-manifest(7).
|
|
||||||
|
|
||||||
|
|
||||||
SINGLETON - ONE INSTANCE ONLY
|
|
||||||
-----------------------------
|
|
||||||
If you want to ensure that a type can only be used once per target, you can
|
|
||||||
mark it as a singleton: Just create the (empty) file "singleton" in your type
|
|
||||||
directory:
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
touch cdist/conf/type/__NAME/singleton
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
This will also change the way your type must be called:
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
__YOURTYPE --parameter value
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
As you can see, the object ID is omitted, because it does not make any sense,
|
|
||||||
if your type can be used only once.
|
|
||||||
|
|
||||||
|
|
||||||
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 the 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
|
|
||||||
--------------------------
|
|
||||||
There are two gencode scripts: ***gencode-local*** and ***gencode-remote***.
|
|
||||||
The output of gencode-local is executed locally, whereas
|
|
||||||
the output of gencode-remote is executed on the target.
|
|
||||||
The gencode scripts can make use of the parameters, the global explorers
|
|
||||||
and the type specific explorers.
|
|
||||||
|
|
||||||
If the gencode scripts 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.
|
|
||||||
|
|
||||||
If your type wants to save temporary data, that may be used by other types
|
|
||||||
later on (for instance __file), you can save them in the subdirectory
|
|
||||||
"files" below $__object (but you must create it yourself).
|
|
||||||
cdist will not touch this directory.
|
|
||||||
|
|
||||||
If your type contains static files, it's also recommended to place them in
|
|
||||||
a folder named "files" within the type (again, because cdist guarantees to
|
|
||||||
never ever touch this folder).
|
|
||||||
|
|
||||||
|
|
||||||
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 have a look at cdist-hacker(7) on
|
|
||||||
how to submit it.
|
|
||||||
|
|
||||||
SEE ALSO
|
|
||||||
--------
|
|
||||||
- cdist-explorer(7)
|
|
||||||
- cdist-hacker(7)
|
|
||||||
- cdist-stages(7)
|
|
||||||
- cdist-tutorial(7)
|
|
||||||
|
|
||||||
|
|
||||||
COPYING
|
|
||||||
-------
|
|
||||||
Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is
|
|
||||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
|
||||||
Loading…
Reference in a new issue