diff --git a/HACKERS_README b/HACKERS_README index 0ae1bdcd..66103acc 100755 --- a/HACKERS_README +++ b/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. - -A lot of documentation is still missing, but running cdist-quickstart should -give you an impression of how cdist works. +to get a deeper understanding. Please read doc/man/cdist-hacker.text. I hope you have a lot of fun with cdist, because it was also a lot of fun to develop it! - -- Nico, 20110304 - - -## 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. + -- Nico, 20110324 ## Running cdist when developing diff --git a/Makefile b/Makefile index 29d86c67..1023d541 100644 --- a/Makefile +++ b/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: +web: man 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 diff --git a/README b/README index e7345a78..feca4bc4 100644 --- a/README +++ b/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.1: __file to __file, __directory, __link migration + * 1.3: Support for local and remote code execution (current stable) * 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**. diff --git a/bin/cdist-code-run b/bin/cdist-code-run index 229d4d1d..a6a9137f 100755 --- a/bin/cdist-code-run +++ b/bin/cdist-code-run @@ -22,12 +22,9 @@ # . cdist-config -[ $# -eq 3 ] || __cdist_usage " " +[ $# -eq 2 ] || __cdist_usage " " 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 diff --git a/bin/cdist-code-run-all b/bin/cdist-code-run-all index 90ef6443..1486cc46 100755 --- a/bin/cdist-code-run-all +++ b/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" \ - "${__cdist_name_gencode_local}" \ - || __cdist_exit_err "Remote code failed for $object" + export __cdist_out_object_dir="$__cdist_out_object_dir" + cdist-code-run "$object" "${__cdist_name_gencode_local}" \ + || __cdist_exit_err "Local code failed for $object" # Code remote - cdist-run-remote "$__cdist_target_host" \ - "__cdist_out_object_dir=\"$__cdist_remote_out_object_base_dir\"" \ - "cdist-code-run" "${__cdist_remote_out_object_base_dir}" "$object" \ - "${__cdist_name_gencode_remote}" \ + cdist-run-remote "$__cdist_target_host" \ + "export __cdist_out_object_dir=\"$__cdist_remote_out_object_base_dir\";" \ + "cdist-code-run" "$object" "${__cdist_name_gencode_remote}" \ || __cdist_exit_err "Remote code failed for $object" done < "$__cdist_tmp_file" diff --git a/bin/cdist-manifest-run-all b/bin/cdist-manifest-run-all index ee15273c..a431576d 100755 --- a/bin/cdist-manifest-run-all +++ b/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 diff --git a/bin/cdist-run-remote b/bin/cdist-run-remote index 87af8459..93cf9062 100755 --- a/bin/cdist-run-remote +++ b/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\";" "$@" diff --git a/bin/cdist-type-emulator b/bin/cdist-type-emulator index 18069b44..6294870a 100755 --- a/bin/cdist-type-emulator +++ b/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 -mkdir -p "${__cdist_object_dir}" -__cdist_object_source_add "${__cdist_object_dir}" +# Initialise object +mkdir -p "${__cdist_new_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}" diff --git a/conf/type/__apt_ppa/man.text b/conf/type/__apt_ppa/man.text index 73fabc7f..5423a1a2 100644 --- a/conf/type/__apt_ppa/man.text +++ b/conf/type/__apt_ppa/man.text @@ -1,5 +1,5 @@ cdist-type__apt_ppa(7) -========================== +====================== Steven Armstrong diff --git a/conf/type/__apt_ppa/manifest b/conf/type/__apt_ppa/manifest index ad6ee614..d5df9e23 100755 --- a/conf/type/__apt_ppa/manifest +++ b/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 - diff --git a/conf/type/__apt_update_index/gencode-remote b/conf/type/__apt_update_index/gencode-remote deleted file mode 100755 index ad2296df..00000000 --- a/conf/type/__apt_update_index/gencode-remote +++ /dev/null @@ -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 . -# - -# 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 - diff --git a/conf/type/__apt_update_index/man.text b/conf/type/__apt_update_index/man.text deleted file mode 100644 index dffba372..00000000 --- a/conf/type/__apt_update_index/man.text +++ /dev/null @@ -1,44 +0,0 @@ -cdist-type__apt_update_index(7) -========================== -Steven Armstrong - - -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). diff --git a/conf/type/__apt_update_index/singleton b/conf/type/__apt_update_index/singleton deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/changelog b/doc/changelog index f7241150..f78b1660 100644 --- a/doc/changelog +++ b/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 diff --git a/doc/dev/todo/TAKEME b/doc/dev/todo/TAKEME new file mode 100644 index 00000000..9fa083cc --- /dev/null +++ b/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 + diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index bf13881e..3556f371 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,3 +1,23 @@ -Document redefine behaviour -release cdist 1.4.0 - perhaps include __self +Core: + - support $__self = relative_type/object_id + - 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. diff --git a/doc/dev/todo/post-1.3 b/doc/dev/todo/post-1.3 deleted file mode 100644 index ec186d3a..00000000 --- a/doc/dev/todo/post-1.3 +++ /dev/null @@ -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 - diff --git a/doc/man/cdist-env.text b/doc/man/cdist-env.text index cf54d363..9a736133 100644 --- a/doc/man/cdist-env.text +++ b/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 -------------------------------------------------------------------------------- diff --git a/doc/man/cdist-hacker.text b/doc/man/cdist-hacker.text new file mode 100644 index 00000000..d55f1c2f --- /dev/null +++ b/doc/man/cdist-hacker.text @@ -0,0 +1,73 @@ +cdist-hacker(7) +=============== +Nico Schottelius + + +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). diff --git a/doc/man/cdist-manifest.text b/doc/man/cdist-manifest.text index 701c8b98..04f1c56c 100644 --- a/doc/man/cdist-manifest.text +++ b/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 -exactly the same, that is, all its parameters are equal. +The same object can be redefined in multiple different manifests as long as +the parameters are exactly the same. In general, manifests are used to define which types are used depending on given conditions. diff --git a/doc/man/cdist.text b/doc/man/cdist.text index 957e7cb4..44be52b1 100644 --- a/doc/man/cdist.text +++ b/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)