From 21ddd6a2a404657583fb82f6907cb612496d0da0 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 01:47:10 +0100 Subject: [PATCH 1/6] begin to integrate manpage generation in Makefile Signed-off-by: Nico Schottelius --- Makefile | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Makefile b/Makefile index 81d59325..63d35407 100644 --- a/Makefile +++ b/Makefile @@ -3,6 +3,15 @@ BINDIR=$(PREFIX}/bin WEBDIR=$$HOME/niconetz WEBPAGE=software/cdist.mdwn +MANSRC=doc/man/cdist-config-layout.text doc/man/cdist-config.text \ + doc/man/cdist-deploy-to.text doc/man/cdist-design.text \ + doc/man/cdist-environment.text doc/man/cdist-explorers.text \ + doc/man/cdist-language.text doc/man/cdist-manifests.text \ + doc/man/cdist-quickstart.text doc/man/cdist-stages.text \ + doc/man/cdist-terms.text doc/man/cdist.text \ + doc/man/cdist-types.text + + # FIXME: some distro nerd, can you make this more beautiful? # I'm just a hacker, I don't really care... install: @@ -23,3 +32,6 @@ web: pub: git push --mirror + +man: + echo $(MANSRC) From c3245348b4fd16ccb8fa28d98f36bc169fa87c44 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 01:48:43 +0100 Subject: [PATCH 2/6] -todo in cdist-stages Signed-off-by: Nico Schottelius --- doc/man/cdist-stages.text | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/man/cdist-stages.text b/doc/man/cdist-stages.text index b48fcb44..29db1d9b 100644 --- a/doc/man/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -34,7 +34,7 @@ cdist passes through different stages: You can trigger the first stage part using cdist-manifest-init(1). -- Third stage: Execution of types [TODO] +- Third stage: Execution of types Every object is checked whether its type has an init script (see cdist-types(7)). If the type of the object has an init script, it is run. This init script may @@ -50,7 +50,7 @@ cdist passes through different stages: objects try to create the same object, which indicates a broken configuration. -- Fourth stage: Code generation [TODO] +- Fourth stage: Code generation The "gencode" binary of the types for every existing object is called to generate code that will be executed on the target host. @@ -62,7 +62,7 @@ cdist passes through different stages: A description of what the generated code may/must/should do can be found in cdist-types-gencode(7). -- Fifth stage: [TODO] +- Fifth stage: The resulting code is transferred to the target host and executed, the run of cdist-deploy-to(1) ends. From 6fb75395bc668580ad8b4720b8106f29b53f44ff Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 01:52:32 +0100 Subject: [PATCH 3/6] ignore generated manpages Signed-off-by: Nico Schottelius --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index a01ee289..b4ec3d44 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .*.swp +doc/man/*.[1-9] From f3600bc5ddb584882d9cce07d2f1a7a4af263d52 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 01:52:46 +0100 Subject: [PATCH 4/6] generate first manpage Signed-off-by: Nico Schottelius --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 63d35407..341f2eb5 100644 --- a/Makefile +++ b/Makefile @@ -35,3 +35,4 @@ pub: man: echo $(MANSRC) + a2x -f manpage --no-xmllint doc/man/cdist-stages.text From 0e71028b4bd06d095cf51cc966cd20effdb834bd Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 01:53:06 +0100 Subject: [PATCH 5/6] begin to create sections in cdist-stages manpage Signed-off-by: Nico Schottelius --- doc/man/cdist-stages.text | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/man/cdist-stages.text b/doc/man/cdist-stages.text index 29db1d9b..7fda6b7e 100644 --- a/doc/man/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -11,13 +11,17 @@ cdist-stages - How the configuration is built DESCRIPTION ----------- Starting the execution of deployment with cdist-deploy-to(1), -cdist passes through different stages: +cdist passes through different stages, each can be triggered +and debugged on its own. -- First stage: Get information about target - Every existing explorer is run on the target and the results - are copied back into the local cache. - The results can be used by manifests and types. - See cdist-explorers(7) and see cdist-cache(7). +STAGE 1: TARGET INFORMATION RETRIEVAL +-------------------------------------- +In this stage information is collected about target using +so called explorers. +Every existing explorer is run on the target and the output +of all explorers are copied back into the local cache. +The results can be used by manifests and types. +See cdist-explorers(7) and see cdist-cache(7). - Second stage: Initial manifest run The initial manifest (see cdist-manifests(7) is run, From fa1764598e5b57512eb8b7525e070712dee8195f Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 19 Feb 2011 02:00:32 +0100 Subject: [PATCH 6/6] +sections Signed-off-by: Nico Schottelius --- doc/man/cdist-stages.text | 42 ++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/doc/man/cdist-stages.text b/doc/man/cdist-stages.text index 7fda6b7e..98e42ece 100644 --- a/doc/man/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -12,7 +12,9 @@ DESCRIPTION ----------- Starting the execution of deployment with cdist-deploy-to(1), cdist passes through different stages, each can be triggered -and debugged on its own. +and debugged on its own. Reading the source of the +cdist-deploy-to script shous the binaries being responsible +for each stage. STAGE 1: TARGET INFORMATION RETRIEVAL -------------------------------------- @@ -21,24 +23,26 @@ so called explorers. Every existing explorer is run on the target and the output of all explorers are copied back into the local cache. The results can be used by manifests and types. -See cdist-explorers(7) and see cdist-cache(7). -- Second stage: Initial manifest run - The initial manifest (see cdist-manifests(7) is run, - which is done by cdist-manifest-init(1). - - This run creates an internal database in cconfig - format (see cdist-config-layout(7), that contains all - objects configured for the specific host. +Related manpages are cdist-explorers(7) and cdist-cache(7). - In this stage, no conflicts may occur, i.e. no - object of the same type with the same id may - be created. - - You can trigger the first stage part using - cdist-manifest-init(1). -- Third stage: Execution of types +STAGE 2: RUN THE INITIAL MANIFEST +--------------------------------- +The initial manifest, which should be used for mappings +of hosts to types, is executed. + +This stage creates objects in a cconfig database that +contains as defined in the manifest for the specific host. + +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 script (see cdist-types(7)). If the type of the object has an init script, it is run. This init script may @@ -54,7 +58,8 @@ See cdist-explorers(7) and see cdist-cache(7). objects try to create the same object, which indicates a broken configuration. -- Fourth stage: Code generation +STAGE 4: CODE GENERATION +------------------------ The "gencode" binary of the types for every existing object is called to generate code that will be executed on the target host. @@ -66,7 +71,8 @@ See cdist-explorers(7) and see cdist-cache(7). A description of what the generated code may/must/should do can be found in cdist-types-gencode(7). -- Fifth stage: +STAGE 5: CODE EXECUTION +----------------------- The resulting code is transferred to the target host and executed, the run of cdist-deploy-to(1) ends.