Merge remote branch 'nico/master'

HACKERS_README

@@ -3,21 +3,12 @@ cat << eof
 Hey hackers,
 
 this README is for you, for those who want to dig into cdist, hack it or try
-to get a deeper understanding.
+to get a deeper understanding. Please read doc/man/cdist-hacker.text.
-
-A lot of documentation is still missing, but running cdist-quickstart should
-give you an impression of how cdist works.
 
 I hope you have a lot of fun with cdist, because it was also a lot of fun to
 develop it!
 
-   -- Nico, 20110304
+   -- Nico, 20110324
-
-
-## Conventions
-
-- All variables exported by cdist are prefixed with a double underscore (__)
-- All cdist-internal variables are prefixed with __cdist_ and are generally not exported.
 
 ## Running cdist when developing
 

Makefile

@@ -28,6 +28,7 @@ MANSRC=$(MANDIR)/cdist.text						\
    $(MANDIR)/cdist-explorer-run-global.text 	\
    $(MANDIR)/cdist-deploy-to.text 				\
 	$(MANDIR)/cdist-explorer.text					\
+	$(MANDIR)/cdist-hacker.text  					\
 	$(MANDIR)/cdist-manifest.text 				\
 	$(MANDIR)/cdist-manifest-run.text			\
    $(MANDIR)/cdist-manifest-run-all.text	 	\
@@ -62,7 +63,8 @@ all:
 
 man: doc/man/.marker
 
-doc/man/.marker: $(MANDIR)/cdist-reference.text
+# FIXME: also depends on conf/type/*/man.text!
+doc/man/.marker: manmove
 	touch $@
 
 # Manual from core
@@ -74,7 +76,7 @@ mantype:
 	for man in conf/type/*/man.text; do $(A2XM) $$man; $(A2XH) $$man; done
 
 # Move into manpath directories
-manmove: mantype mancore
+manmove: mantype mancore $(MANGENERATED)
 	for manpage in $(MANDIR)/*.[1-9] conf/type/*/*.7; do \
 		cat=$${manpage##*.}; \
 		mandir=$(MANDIR)/man$$cat; \
@@ -90,15 +92,13 @@ manmove: mantype mancore
 	done
 
 # Reference depends on conf/type/*/man.text - HOWTO with posix make?
-$(MANDIR)/cdist-reference.text: manmove $(MANDIR)/cdist-reference.text.sh
+$(MANDIR)/cdist-reference.text: $(MANDIR)/cdist-reference.text.sh
 	$(MANDIR)/cdist-reference.text.sh
 	$(A2XM) $(MANDIR)/cdist-reference.text
 	$(A2XH) $(MANDIR)/cdist-reference.text
-	# Move us to the destination as well
-	make manmove
 	
 clean:
-	rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] $(MANGENERATED)
+	rm -rf doc/man/html/* doc/man/*.[1-9] doc/man/man[1-9] $(MANGENERATED)
 	rm -f conf/type/*/man.html
 	rm -rf doc/html
 
@@ -114,10 +114,11 @@ test:
 	# gentoo
 	.rsync nicosc@ru3.inf.ethz.ch:cdist
 
-#web: manmove
+web: man
-web:
 	cp README $(WEBDIR)/$(WEBPAGE)
+	rm -rf $(WEBDIR)/$(WEBBASE)/man && mkdir $(WEBDIR)/$(WEBBASE)/man
 	cp -r doc/html/* $(WEBDIR)/$(WEBBASE)/man
+	cd $(WEBDIR) && git add $(WEBBASE)/man
 	cd $(WEBDIR) && git commit -m "cdist update" $(WEBBASE) $(WEBPAGE)
 	cd $(WEBDIR) && make pub
 

README

@@ -120,13 +120,14 @@ how to use cdist.
 There are at least the following branches available:
 
  * master: the development branch
- * 1.3: Support for local and remote code execution (current stable)
+ * 1.4: Support for redefiniton of objects (if equal)
 
 Old versions:
 
- * 1.0: First official release
+ * 1.3: Support for local and remote code execution (current stable)
- * 1.1: __file to __file, __directory, __link migration
  * 1.2: Dependencies supported
+ * 1.1: __file to __file, __directory, __link migration
+ * 1.0: First official release
 
 Other branches may be available for features or bugfixes, but they
 may vanish at any point. To select a specific branch use
@@ -156,6 +157,10 @@ If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
 The master branch on the other hand is the development branch and may not be
 working, break your setup or eat the tree in your garden.
 
+### Upgrading from 1.3 to 1.4
+
+No incompatiblities.
+
 ### Upgrading from 1.2 to 1.3
 
 Rename **gencode** of every type to **gencode-remote**.

bin/cdist-code-run

@@ -22,12 +22,9 @@
 # 
 
 . cdist-config
-[ $# -eq 3 ] || __cdist_usage "<object dir> <object> <type>"
+[ $# -eq 2 ] || __cdist_usage "<object> <type>"
 set -ue
 
-# This variable MUST be exactly like this - see __cdist_object_dir
-__cdist_out_object_dir="$1"; shift
-
 object="$1"; shift
 __cdist_gencode_type="$1"; shift
 
@@ -50,7 +47,7 @@ echo "Checking code-${__cdist_gencode_type} for $object ..."
 if [ -f "$require" ]; then
    while read requirement; do
       echo "Requiring  dependency $requirement for $object ..."
-      cdist-code-run "$__cdist_out_object_dir" "$requirement" "$__cdist_gencode_type"
+      cdist-code-run "$requirement" "$__cdist_gencode_type"
    done < "$require"
 fi
 

bin/cdist-code-run-all

@@ -38,14 +38,13 @@ while [ $# -ge 1 ]; do
    object="$1"; shift
 
    # Code local
-   cdist-code-run "$__cdist_out_object_dir" "$object" \
+   export __cdist_out_object_dir="$__cdist_out_object_dir"
-      "${__cdist_name_gencode_local}"                 \
+   cdist-code-run "$object" "${__cdist_name_gencode_local}"                 \
-         || __cdist_exit_err "Remote code failed for $object"
+         || __cdist_exit_err "Local code failed for $object"
 
    # Code remote
-   cdist-run-remote "$__cdist_target_host"                                 \
+   cdist-run-remote "$__cdist_target_host"                                       \
-      "__cdist_out_object_dir=\"$__cdist_remote_out_object_base_dir\""     \
+      "export __cdist_out_object_dir=\"$__cdist_remote_out_object_base_dir\";"   \
-      "cdist-code-run" "${__cdist_remote_out_object_base_dir}" "$object"   \
+      "cdist-code-run" "$object" "${__cdist_name_gencode_remote}"                \
-      "${__cdist_name_gencode_remote}"                                     \
       || __cdist_exit_err "Remote code failed for $object"
 done < "$__cdist_tmp_file"

bin/cdist-manifest-run-all

@@ -64,6 +64,7 @@ while [ "$__cdist_new_objects_created" = "y"  ]; do
                export $__cdist_name_var_type="$(__cdist_type_dir "$__cdist_type")"
 
                cdist-manifest-run "$__cdist_target_host" "$__cdist_manifest"
+               __cdist_new_objects_created=y
             else
                __cdist_exit_err "${__cdist_manifest} needs to be executable."
             fi

bin/cdist-run-remote

@@ -28,4 +28,4 @@ set -ue
 __cdist_target_host="$1"; shift
 
 ssh "${__cdist_remote_user}@${__cdist_target_host}"   \
-   "PATH=\"${__cdist_remote_bin_dir}:\$PATH\"" "$@"
+   "export PATH=\"${__cdist_remote_bin_dir}:\$PATH\";" "$@"

bin/cdist-type-emulator

@@ -71,11 +71,10 @@ __cdist_out_object_dir_orig="$__cdist_out_object_dir"
 # Store to tmp now
 __cdist_out_object_dir="$__cdist_tmp_dir"
 
-__cdist_object_dir="$(__cdist_object_dir "$__cdist_object_self")"
+__cdist_new_object_dir="$(__cdist_object_dir "$__cdist_object_self")"
 
-# Record source
+# Initialise object
-mkdir -p "${__cdist_object_dir}"
+mkdir -p "${__cdist_new_object_dir}"
-__cdist_object_source_add "${__cdist_object_dir}"
 
 # Record parameter
 __cdist_parameter_dir="$(__cdist_object_parameter_dir "$__cdist_object_self")"
@@ -147,15 +146,16 @@ done
 # Restore original destination
 __cdist_out_object_dir="$__cdist_out_object_dir_orig"
 
-__cdist_new_object_dir="$(__cdist_object_dir "$__cdist_object_self")"
+__cdist_object_dir="$(__cdist_object_dir "$__cdist_object_self")"
 
 #
 # If the object already exists and is exactly the same, merge it. Otherwise fail.
 #
-if [ -e "${__cdist_new_object_dir}" ]; then
+if [ -e "${__cdist_object_dir}" ]; then
    # Allow diff to fail
    set +e
-   diff -ru "${__cdist_object_dir}" "${__cdist_new_object_dir}" \
+   diff -ru "${__cdist_new_object_dir}/${__cdist_name_parameter}" \
+      "${__cdist_object_dir}/${__cdist_name_parameter}" \
       > "$__cdist_tmp_file"; ret=$?
    set -e
    
@@ -164,14 +164,11 @@ if [ -e "${__cdist_new_object_dir}" ]; then
       exec >&2
       echo "${__cdist_object_self} already exists differently."
       echo "Recorded source(s):"
-      __cdist_object_source "${__cdist_new_object_dir}"
+      __cdist_object_source "${__cdist_object_dir}"
       echo "Differences:"
       cat "$__cdist_tmp_file"
       __cdist_exit_err "Aborting due to object conflict."
    fi
-
-   # Add ourselves, if we're compatible
-   __cdist_object_source_add "${__cdist_new_object_dir}"
 else
    #
    # Move object into tree:
@@ -179,5 +176,8 @@ else
    #
    __cdist_new_object_base_dir="$(__cdist_object_base_dir "$__cdist_object_self")"
    mkdir -p "$__cdist_new_object_base_dir"
-   mv "$__cdist_object_dir"  "$__cdist_new_object_base_dir"
+   mv "$__cdist_new_object_dir"  "$__cdist_new_object_base_dir"
 fi
+
+# Add "I was here message"
+__cdist_object_source_add "${__cdist_object_dir}"

conf/type/__apt_ppa/man.text

@@ -1,5 +1,5 @@
 cdist-type__apt_ppa(7)
-==========================
+======================
 Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 

conf/type/__apt_ppa/manifest

@@ -27,8 +27,3 @@ require="__package/python-software-properties" \
    --source "$__type/files/remove-apt-repository" \
    --mode 0755
 
-# FIXME: rewrite to use $__self once that exists
-# FIXME: only run if something changed. currently working arround this in
-#    __apt_update_index/gencode-remote
-require="__apt_ppa/$__object_id" __apt_update_index
-

conf/type/__apt_update_index/gencode-remote

@@ -1,35 +0,0 @@
-#!/bin/sh
-#
-# 2011 Steven Armstrong (steven-cdist at armstrong.cc)
-#
-# 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 <http://www.gnu.org/licenses/>.
-#
-
-# BIG FAT FIXME: there must be a better way to do this!
-tmpdir=$(mktemp -d)
-cleanup() {
-   rm -rf "$tmpdir"
-}
-trap cleanup EXIT
-
-should="$tmpdir/should"
-is="$tmpdir/is"
-
-find "$__global/object/__apt_ppa" -path "*.cdist/parameter/state" | xargs cat > "$should"
-find "$__global/object/__apt_ppa" -path "*.cdist/explorer/state" | xargs cat > "$is"
-
-diff -ru "$is" "$should" || echo apt-get update
-

conf/type/__apt_update_index/man.text

@@ -1,44 +0,0 @@
-cdist-type__apt_update_index(7)
-==========================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
-
-NAME
-----
-cdist-type__apt_update_index - resynchronize the apt package index
-
-
-DESCRIPTION
------------
-This cdist type allows you to resynchronize the package index files from their
-sources. In other words, it runs `apt-get update`.
-
-FIXME: currently hard coded to work together with the __apt_ppa type
-
-
-REQUIRED PARAMETERS
--------------------
-None.
-
-OPTIONAL PARAMETERS
--------------------
-None.
-
-
-EXAMPLES
---------
-
---------------------------------------------------------------------------------
-__apt_update_index
---------------------------------------------------------------------------------
-
-
-SEE ALSO
---------
-- cdist-type(7)
-
-
-COPYING
--------
-Copyright \(C) 2011 Steven Armstrong. Free use of this software is
-granted under the terms of the GNU General Public License version 3 (GPLv3).

doc/changelog

@@ -1,6 +1,6 @@
-1.4.0:
+1.4.0: 2011-03-24
 	* Add --recursive to __directory
-	* Move cdist generated stuff to .cdist of object
+	* Move cdist generated stuff to .cdist of an object
 	* Allow objects to be redefined
 
 1.3.2: 2011-03-21

doc/dev/todo/TAKEME

@@ -0,0 +1,12 @@
+The following list of todos has not been assigned to any developer.
+
+Feel free to pick one:
+
+Types to be written/extended:
+   - __ssh-keys (host/user)
+   - Think about __service - necessary?
+   - __file_edit
+      - regexp replace (can probably cover all?)
+         -> aka sed.
+   - __cron
+

doc/dev/todo/niconext

@@ -1,3 +1,23 @@
-Document redefine behaviour
+Core:
-release cdist 1.4.0
+   - support $__self = relative_type/object_id
-   perhaps include __self
+   - cache
+
+Cache:
+   Assume you want to configure stuff one host ("monitor node"),
+   depending on the configuration of other hosts ("cluster nodes").
+
+   For instance, the monitor host would like to know,
+   which hosts are configured with the provider
+   "apache" and option --start true.
+
+   This requires the monitor node to be able to
+   query all other configured nodes. It can't
+   ask for all hosts, because cdist does not
+   know which hosts are configured or may exist.
+
+   Example implementation
+
+   If cdist keeps ("caches") the configuration of every
+   node it configures, each new node can query the
+   cache for existing nodes that acquired the given
+   configuration.

doc/dev/todo/post-1.3

@@ -1,35 +0,0 @@
-Core:
-   - allow redefine object, if everything same
-   - support $__self = relative_type/object_id
-   - .cdist
-   - cache
-   - display changes if object cannot be merged to user
-
-Cache:
-   Assume you want to configure stuff one host ("monitor node"),
-   depending on the configuration of other hosts ("cluster nodes").
-
-   For instance, the monitor host would like to know,
-   which hosts are configured with the provider
-   "apache" and option --start true.
-
-   This requires the monitor node to be able to
-   query all other configured nodes. It can't
-   ask for all hosts, because cdist does not
-   know which hosts are configured or may exist.
-
-   Example implementation
-
-   If cdist keeps ("caches") the configuration of every
-   node it configures, each new node can query the
-   cache for existing nodes that acquired the given
-   configuration.
-
-Types to be written/extended:
-   - __ssh-keys (host/user)
-   - __service
-   - __file_edit
-      - regexp replace (can probably cover all?)
-         -> aka sed.
-   - __cron
-

doc/man/cdist-env.text

@@ -32,7 +32,7 @@ in csh variants (csh, tcsh):
 eval `./bin/cdist-env`
 --------------------------------------------------------------------------------
 
-For bourne shell, the is also a shorter version:
+For bourne shell, there is also a shorter version:
 --------------------------------------------------------------------------------
 . ./bin/cdist-env
 --------------------------------------------------------------------------------

doc/man/cdist-hacker.text

@@ -0,0 +1,73 @@
+cdist-hacker(7)
+===============
+Nico Schottelius <nico-cdist--@--schottelius.org>
+
+
+NAME
+----
+cdist-hacker - How to get (stuff) into cdist
+
+
+WELCOME
+-------
+Welcome dear hacker! I invite you to a tour of pointers to
+get into the usable configuration mangament system, cdist.
+
+The first thing to know is probably that cdist is brought to
+you by people who care about how code looks like and who think
+twice before merging or implementing a feature: Less features
+with good usability are far better than the opposite.
+
+
+UNDERSTANDING CDIST INTERNALS
+-----------------------------
+IF you are interested in how cdist internally works, you can open
+bin/cdist-config and bin/cdist-deploy-to in your favorite editor and
+read the scripts bin/cdist-deploy-to calls. The magnificent HACKERS_README
+may be of great help as well.
+
+
+CODING CONVENTIONS (CORE)
+-------------------------
+- All variables exported by cdist are prefixed with a double underscore (__)
+- All cdist-internal variables are prefixed with __cdist_ and are generally not exported.
+
+
+HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST
+-----------------------------------------------------
+If you did some cool changes to cdist, which you value as a benefit for
+everybody using cdist, you're welcome to propose inclusion into upstream.
+
+There are though some requirements to ensure your changes don't break others
+work nor kill the authors brain:
+
+- Code submission must be done via git
+- Code to be included should be branched of the upstream "master" branch
+   - Exception: Bugfixes to a version branch
+- Code submissions must be in your master branch
+   - Exception: If you only want a comment on your code, but not an inclusion.
+- Do not add conf/manifest/init - This file should only be touched in your
+  private branch!
+
+As soon as your work meets these requirements, you can contact me
+(IRC, Mailinglist, Phone, RFC 1149) and I'll check your code before
+including it.
+
+
+HOW TO SUBMIT A NEW TYPE
+------------------------
+Submitting a type works as described above, with the additional requirement
+that a corresponding manpage named man.text in asciidoc format with
+the manpage-name "cdist-type__NAME" is included in the type directory
+AND asciidoc is able to compile it.
+
+
+SEE ALSO
+--------
+- cdist(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).

doc/man/cdist-manifest.text

@@ -15,8 +15,8 @@ host as well as to define which configurations should be applied within a
 type. Manifests are executed locally and the resulting objects are stored in
 an internal database.
 
-The same object can be redefined in multiple different manifests as long as it is
+The same object can be redefined in multiple different manifests as long as
-exactly the same, that is, all its parameters are equal.
+the parameters are exactly the same.
 
 In general, manifests are used to define which types are used depending
 on given conditions.

doc/man/cdist.text

@@ -32,6 +32,7 @@ SEE ALSO
 - Website: http://www.nico.schottelius.org/cdist/[]
 - cdist-best-practise(7)
 - cdist-deploy-to(1)
+- cdist-hacker(7)
 - cdist-manifest(7)
 - cdist-quickstart(1)
 - cdist-type(7)