Merge remote branch 'nico/master'

Makefile

@@ -36,3 +36,4 @@ pub:
 man:
 	echo $(MANSRC)
 	a2x -f manpage --no-xmllint doc/man/cdist-stages.text
+	echo man ./doc/man/cdist-stages.7

REAL_README

@@ -13,7 +13,6 @@ it ticks differently:
  * cdist sticks completly to the KISS (keep it simple and stupid) paradigma
   * cdist's core is very small (currently around 400 lines of code)
   * There is only one type to extend cdist called ***type***.
-  * 
  * cdist is UNIX
   * It reuses existing tools like cat, find, mv, ...
   * cdist's documentation is bundled as manpages

TODO-1.0

@@ -11,7 +11,7 @@ x run initial manifest (stage 2)
    x Create configuration tree from manifest
       x write binaries, which create the tree when called from manifest (cdist_tree_wrapper)
 
-- be able to run manifest of types (stage 3)
+x be able to run manifest of types (stage 3)
    x Parse configuration tree/objects recursively
       x can/may types modify tree?
          -> yes, of everything a type created itself!
@@ -22,13 +22,6 @@ x run initial manifest (stage 2)
    x rename $__object_dir to $__object_base_dir
    x use $type/manifest instead of $type/init
    x find $object_id in recursive runner (before merge)
-   - DOC document "cd $__object_dir, before running manifest" in doc/man/cdist-types.text
-   - DOC document that $type/manifest is executed for every object/instance
-   - DOC: types can always access
-      __cdist_out_objects, __cdist_out_explorers, 
-      __cdist_out_execs
-
-      --> create cdist-variables document?
 
 x generate code to be executed on clients (stage 4)
    x for one object
@@ -41,6 +34,7 @@ x execute code on client (stage 5)
       - file (with directory)
       - package
    - doc cleanup for 1.0:
+      - ensure every file in bin/ has a correspondent manpage
       - cdist manpage (main manpage)
          - cleanup following man + their tree:
             - cdist-language        [CLEANUP AND REMOVE]
@@ -72,3 +66,11 @@ x execute code on client (stage 5)
       - create doc/dev/HACKERS_README
    - Add install target to Makefile
    - create cdist-config-init to create basic tree
+   - cdist-type integration!
+   - DOC document "cd $__object_dir, before running manifest" in doc/man/cdist-types.text
+   - DOC document that $type/manifest is executed for every object/instance
+   - DOC: types can always access __cdist_out_objects, __cdist_out_explorers, __cdist_out_execs
+      --> create cdist-variables document?
+
+   - include generation in makefile
+

bin/cdist-config

@@ -21,8 +21,6 @@
 # Print configuration directories - helper for all other scripts
 #
 
-echo teeeeeeeeeeeeeeeeeees
-
 # Fail if something bogus is going on
 set -u
 
@@ -181,6 +179,13 @@ __cdist_object_source()
    cat "${object_dir}/$__cdist_name_object_source"
 }
 
+__cdist_exec_fail_on_error()
+{
+   sh -e "$@"
+   [ "$?" -eq 0 ] || __cdist_exit_err "Error: $1 exited non-zero."
+}
+
+
 __cdist_tmp_removal()
 {
    rm -rf "${__cdist_tmp_dir}"

bin/cdist-manifest-run

@@ -41,17 +41,6 @@ if [ ! -x "${__cdist_manifest}" ]; then
    __cdist_exit_err "${__cdist_manifest} needs to be executable."
 fi
 
-mkdir -p "${__cdist_output_dir}"
+mkdir -p "${__cdist_output_dir}" || __cdist_exit_err "Cannot create output dir ${__cdist_output_dir}"
 
-# Catch errors ourselves now
+__cdist_exec_fail_on_error "${__cdist_manifest}"
-set +e
-
-# Ensure manifest fails if any error exists - FIXME: redundant, cdist-object-codegen
-(
-   set -e
-   . "${__cdist_manifest}"
-); ret=$?
-
-if [ "$ret" -ne 0 ]; then
-   __cdist_exit_err "Error: ${__cdist_manifest} exited non-zero."
-fi

bin/cdist-object-codegen

@@ -54,19 +54,5 @@ if [ -x "$gencode" ]; then
 
 eof
 
-   # Catch errors ourself now
+   __cdist_exec_fail_on_error "$gencode"
-   set +e
-   (
-      # Ensure manifest fails if something within manifest fails
-      # And not all manifests need to include set -e themselves
-      set -e
-      . "$gencode"
-   ); ret=$?
-
-else
-   ret=0
-fi
-
-if [ "$ret" -ne 0 ]; then
-   __cdist_exit_err "Error: $gencode exited non-zero"
 fi

bin/cdist-quickstart

@@ -0,0 +1,40 @@
+#!/bin/sh
+#
+# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org)
+#
+# 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/>.
+#
+#
+# Give the user an introduction into cdist
+#
+
+. cdist-config
+set -eu
+
+__prompt()
+{
+   echo "Press enter to continue or ctrl-c to abort"
+   echo "[Enter]"
+   read answer
+}
+
+cat << eof
+
+Welcome to cdist-quickstart, the interactive guide to cdist!
+
+After you press enter, I'll create the basic directories for you.
+
+eof

doc/dev/logs/README

@@ -0,0 +1 @@
+Logfiles of discussions

doc/man/cdist-quickstart.text

@@ -1,5 +1,42 @@
-## How to use cdist?
+cdist-quickstart(1)
+===================
+Nico Schottelius <nico-cdist--@--schottelius.org>
 
+NAME
+----
+cdist-quickstart - Make use of cinit in 5 minutes
+
+
+DESCRIPTION
+-----------
+This document helps you to take the first steps with cdist.
+We'll begin to configure the host "localhost" to have two files
+in place, /etc/DO-NOT-CHANGE and /root/CDIST-ENABLED-HOST, which
+both are used to warn other sysadmins that this system is managed
+by configuration management and manual changes may get overwritten.
+
+Begin to execute cdist-quickstart, it will show you the steps it
+takes and explains what it does:
+
+% cdist-quickstart
+
+mkdir -p /etc/cdist/manifests
+
+# Create 
+
+Cdist uses 
+kgives you an impression of 
  0. Create a host specification (/etc/cdist/hosts/**hostname**)
   0. Add functionalilty to add
    0. Run ***cdist-apply***
+
+SEE ALSO
+--------
+cdist-config-layout(7)
+
+
+COPYING
+-------
+Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
+## How to use cdist?

doc/man/cdist-stages.text

@@ -5,76 +5,82 @@ Nico Schottelius <nico-cdist--@--schottelius.org>
 
 NAME
 ----
-cdist-stages - How the configuration is built
+cdist-stages - Stages used during configuration deployment
 
 
 DESCRIPTION
 -----------
-Starting the execution of deployment with cdist-deploy-to(1),
+Starting the execution of deployment with cdist-deploy-to(1), cdist passes
-cdist passes through different stages, each can be triggered
+through different stages, each can be triggered and debugged on its own.
-and debugged on its own. Reading the source of the
+Reading the source of the cdist-deploy-to executable shous the scripts
-cdist-deploy-to script shous the binaries being responsible
+responsible for each stage.
-for each stage.
+
 
 STAGE 1: TARGET INFORMATION RETRIEVAL
 --------------------------------------
-In this stage information is collected about target using
+In this stage information is collected about target using so called explorers.
-so called explorers.
+Every existing explorer is run on the target and the output of all explorers
-Every existing explorer is run on the target and the output
+are copied back into the local cache. The results can be used by manifests and
-of all explorers are copied back into the local cache.
+types.
-The results can be used by manifests and types.
 
 Related manpages are cdist-explorers(7) and cdist-cache(7).
 
 
 STAGE 2: RUN THE INITIAL MANIFEST
 ---------------------------------
-The initial manifest, which should be used for mappings
+The initial manifest, which should be used for mappings of hosts to types,
-of hosts to types, is executed.
+is executed. This stage creates objects in a cconfig database that contains
-
+the objects as defined in the manifest for the specific host. In this stage,
-This stage creates objects in a cconfig database that
+no conflicts may occur, i.e. no object of the same type with the same id may
-contains as defined in the manifest for the specific host.
+be created.
-
-In this stage, no conflicts may occur, i.e. no object of
-the same type with the same id may be created.
 
 Related manpages are cdist-manifest-init(1), cdist-manifests(7) and
 cdist-config-layout(7).
 
+
 STAGE 3: EXECUTION OF TYPES
 ---------------------------
-   Every object is checked whether its type has an init
+Every object is checked whether its type has a manifest file. If the type has
-   script (see cdist-types(7)). If the type of the object
+a manifest file and it is executable, it will be executed. The manifest script
-   has an init script, it is run. This init script may
+may generate and change the created objects. In other words, one type can reuse
-   generate additional objects.
+other types.
 
-   For instance the object __apache/www.test.ch is of
+For instance the object __apache/www.test.ch is of type __apache, which may 
-   type __apache, which may contain an init script, which
+contain an manifest script, which creates new objects of type __file.
-   creates new objects of type __file.
+
+The newly created objects are merged back into the existing tree. No conflicts
+may occur during the merge. A conflict would mean that two different objects
+try to create the same object, which indicates a broken configuration.
+
+Related manpage are cdist-types(7) and cdist-manifest-run-all(1).
 
-   The newly created objects are merged back into
-   the existing tree. No conflicts may occur during
-   the merge. A conflict would mean that two different
-   objects try to create the same object, which indicates a
-   broken configuration.
 
 STAGE 4: CODE GENERATION
 ------------------------
-   The "gencode" binary of the types for every existing object is
+In this stage for every created objects its type is checked whether it has a
-   called to generate code that will be executed on the target host.
+gencode script. If the type has a gencode script and it is executable it will
+be executed. This executable should create code to be executed on the target
+on stdout. If the gencode executable fails, it must print diagnostic messages
+on stderr and exit non-zero.
 
-   This binary should create code to be executed on the target on stdout.
+Related manpages are cdist-types-gencode(7), cdist-gencode(1) and
+cdist-gencode-all(1).
 
-   If the gencode binary fails, it must print diagnostic messages on stderr
-   and exit non-zero.
-
-   A description of what the generated code may/must/should
-   do can be found in cdist-types-gencode(7).
 
 STAGE 5: CODE EXECUTION
 -----------------------
-   The resulting code is transferred to the target host and executed,
+The resulting code from the previous stage is transferred to the target host
-   the run of cdist-deploy-to(1) ends.
+and executed there to apply the configuration changes,
+
+Related manpages are cdist-exec-transfer(1) and cdist-exec-run(1).
+
+
+SUMMARY
+-------
+If, and only if, all the stages complete without an errors, the configuration
+will be applied to the target. Each stage can also be run individually, though
+dependencies for each stage must be fulfilled and thus the stages must be run
+in correct order.
 
 
 SEE ALSO