From 5712df850b395510f447de1ca11d0ffadbfa9839 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 9 Jul 2013 14:00:42 +0200 Subject: [PATCH] build type manpages using the Makefile Signed-off-by: Nico Schottelius --- Makefile | 80 +++++++++- bin/build-helper | 62 +------- docs/man/man7/cdist-type.text | 280 ---------------------------------- 3 files changed, 77 insertions(+), 345 deletions(-) delete mode 100644 docs/man/man7/cdist-type.text diff --git a/Makefile b/Makefile index 8929f91d..3c62e8c8 100644 --- a/Makefile +++ b/Makefile @@ -23,11 +23,60 @@ A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8 helper=./bin/build-helper MANDIR=docs/man + MAN1DSTDIR=$(MANDIR)/man1 MAN7DSTDIR=$(MANDIR)/man7 MANREF=$(MAN7DSTDIR)/cdist-reference.text 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 DIST=dist-tag dist-branch-merge @@ -51,12 +100,6 @@ $(RELEASE): $(DIST) $(CHECKS) 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) $(MANREFSH) @@ -75,7 +118,6 @@ link-type-manpages: $(helper) $@ - ################################################################################ # dist code # @@ -109,6 +151,30 @@ release-web: web-doc PKGBUILD: 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 %: diff --git a/bin/build-helper b/bin/build-helper index 94b52f66..39c535df 100755 --- a/bin/build-helper +++ b/bin/build-helper @@ -46,34 +46,6 @@ MAN7DSTDIR=${MANDIR}/man7 SPEECHESDIR=docs/speeches 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) 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) rsync -av "${basedir}/docs/web/" "${WEBTOPDIR}" @@ -268,27 +231,6 @@ eof 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) shift # skip t export PYTHONPATH="$(pwd -P)" @@ -303,6 +245,10 @@ eof echo "VERSION = \"$(git describe)\"" > cdist/version.py ;; + # Targets handled in the makefile + speeches|clean|dist-clean) + ;; + *) echo "Unknown target $@ - aborting" exit 1 diff --git a/docs/man/man7/cdist-type.text b/docs/man/man7/cdist-type.text deleted file mode 100644 index cfb50414..00000000 --- a/docs/man/man7/cdist-type.text +++ /dev/null @@ -1,280 +0,0 @@ -cdist-type(7) -============= -Nico Schottelius - - -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).