Added manual (perldoc) to cronbuilder.
authorStanislaw Klekot <dozzie@jarowit.net>
Tue, 5 Apr 2011 16:40:57 +0000 (18:40 +0200)
committerStanislaw Klekot <dozzie@jarowit.net>
Wed, 6 Apr 2011 12:28:13 +0000 (14:28 +0200)
Makefile
cronbuilder
redhat/cronbuilder.spec
sample-env/cronbuilder.yaml

index de0f1d4..8f950d0 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -9,12 +9,14 @@ PREFIX = /usr/local
 BINDIR = $(PREFIX)/bin
 DOCDIR = $(PREFIX)/share/doc/cronbuilder
 EXAMPLES = $(DOCDIR)/examples
+MANDIR = $(PREFIX)/share/man
 
-all: modules.make
+all: modules.make cronbuilder.1
        ${MAKE} -f modules.make
 
 install: all
        install -D -m 755 cronbuilder $(DESTDIR)$(BINDIR)/cronbuilder
+       install -D -m 644 cronbuilder.1 $(DESTDIR)$(MANDIR)/man1/cronbuilder.1
        install -d $(DESTDIR)$(EXAMPLES)
        cp -R sample-env $(DESTDIR)$(EXAMPLES)
        ${MAKE} -f modules.make install
@@ -22,9 +24,13 @@ install: all
 modules.make: Makefile.PL
        perl Makefile.PL PREFIX='$(PREFIX)' INSTALLDIRS=$(INSTALLDIRS)
 
+cronbuilder.1: cronbuilder
+       perldoc -MPod::Man $^ > $@
+
 clean:
        if [ -f modules.make ]; then ${MAKE} -f modules.make clean; fi
        rm -f modules.make.old
+       rm -f *.1
 
 srpm: VERSION=$(shell awk '$$1 == "%define" && $$2 == "_version" {print $$3}' redhat/cronbuilder.spec)
 srpm:
index bc5452c..68b267d 100755 (executable)
@@ -237,4 +237,246 @@ if (true $config{build}{inform}) {
 }
 
 #-----------------------------------------------------------------------------
+
+__END__
+
+=head1 NAME
+
+cronbuilder - generic cron-based repository builder
+
+=head1 SYNOPSIS
+
+cronbuilder [options] working-directory
+
+cronbuilder --help
+
+=head1 DESCRIPTION
+
+=head2 Options
+
+=over
+
+=item --inform
+
+This option works exactly as setting C<build.inform> option to C<true> (see
+L</Build related options>).
+
+=item --rebuild
+
+This option works exactly as setting C<build.rebuild> option to C<true> (see
+L</Build related options>).
+
+=item --no-build
+
+Option makes L<cronbuilder> skip building. This is useful when you want to
+check correctness of checking-out sources and destination.
+
+=item --no-checkout
+
+Option makes L<cronbuilder> skip updating source and destination working
+copies, but if one of them is missing, will still get checked-out.
+
+Useful when you are preparing build scripts that will be committed to
+repository along with sources (updating sources working copy can remove all
+local changes, depending on repository type).
+
+=item --no-commit
+
+Option causes L<cronbuilder> to skip committing changes to destination
+repository. Especially useful for developing build command, when you are not
+sure about the resulting files.
+
+=item --no-clean
+
+Option causes L<cronbuilder> to skip cleaning source working copy after
+building and to skip cleaning destination working copy after failed build.
+
+Useful when you are preparing build scripts that will be committed to
+repository along with sources.
+
+=item --debug
+
+Alias for C<--no-commit --no-clean --inform>.
+
+=back
+
+=head2 Tool Rationale
+
+In sysadmin's life there is often a need for fetch-generate-save task running
+from crontab. Such task is composed of three steps:
+
+=over
+
+=item 1. fetch
+
+Sources (templates of some kind, possibly with parameters) are taken out of
+some repository. Generally it's a good idea to have sources in a repository of
+versioning system of some kind, e.g. L<svn(1)> or L<git(1)>.
+
+You can think of this as of configuration templates for a set of servers.
+
+=item 2. generate
+
+Sources are used for producing some other files. You can think of this step as
+of generating configuration files for specific server from templates.
+
+=item 3. save
+
+Files produced in step 2. should be saved somewhere. Again, it's a good idea
+to have them in a repository (not necessarily in the same as in step 1.,
+though).
+
+=back
+
+L<cronbuilder> is designed for making tasks like this easier to set up. Not
+that the task is difficult. It's just annoying to re-implement fetching from
+one repository and saving in another repository, especially generating useful
+commit messages, handling repository access credentials or I<not sending> an
+e-mail when everything went fine, but nothing was generated.
+
+L<cronbuilder> takes care of pretty much everything. The only things you need
+to specify, are a) where to get sources (URL + credentials), b) where to save
+generator output (URL + credentials) and c) how to produce output from sources
+(build command).
+
+You don't need to bother with not producing output in build command -- quite
+the opposite! This output will be useful in case of build error.
+
+L<cronbuilder> will send you an e-mail (well, L<cron(8)> will) each time when
+a problem appears and each time when changes were saved in destination
+repository (this one is configurable). If nothing new was generated,
+I<you won't get an e-mail>. As quiet as possible, but not more.
+
+=head2 Working Directory
+
+Initially, working directory contains a single file: F<cronbuilder.yaml>. This
+contains necessary information for all the three steps. Example configuration:
+
+  source:
+    type: git
+    url: https://sources.example.net/policy
+    user: policy-building-service
+    password: 12345
+  destination:
+    type: svn
+    url: https://policy.example.net/generated
+    user: polbusvc
+    password: 53421
+  build:
+    command: "make -C $SOURCE generate DESTDIR=$DESTINATION"
+    inform: true
+    rebuild: false
+
+Working copies of sources and destination will be checked-out as necessary, so
+no action on your side is needed. Just make sure that appropriate users can
+read and write to repositories.
+
+In case of password change for either repository, you'll need to re-initialize
+build directory. Just remove subdirectories (that is, F<.../source>,
+F<.../source-state>, F<.../dest> and F<.../dest-state>).
+
+Build command is a command that will be passed to C</bin/sh -c>. It will get
+source and destination paths in environment variables C<$SOURCE> and
+C<$DESTINATION>. Both paths are absolute.
+
+=head2 Options In F<cronbuilder.yaml>
+
+=head3 Build related options
+
+These options should be set in C<build> section.
+
+=over
+
+=item C<command> (string)
+
+This is a shell command that will be used by L<cronbuilder> to turn sources
+into output.
+
+It will be passed to C</bin/sh -c>, so you can use any valid shell construct
+(including builtins and loops).
+
+Command will be provided with environment variables C<$SOURCE> and
+C<$DESTINATION> (absolute paths).
+
+=item C<inform> (I<true>/I<false>; default: I<false>)
+
+If build was successful but no changes were saved in destination repository,
+you don't want to get a message. But if there were changes, you can choose
+whether a message should or should not be sent.
+
+=item C<rebuild> (I<true>/I<false>; default: I<false>)
+
+If result of your build command only depends on sources, rebuilding is
+unnecessary if there were no changes in source repository. But build could
+depend on, say, some DNS records, which are outside of the source repository.
+In this case you may want to force build even if no changes were detected.
+
+=back
+
+=head3 Source and destination related options
+
+Following options should be set in C<source> or C<destination> section, as
+appropriate.
+
+=over
+
+=item C<type>
+
+This option tells what kind of repository is this. Valid values: C<svn> and
+C<git>.
+
+=item options for Subversion
+
+=over
+
+=item C<url>
+
+URL that will be passed to C<svn checkout>. Basically, URL of your repository.
+This can be local repository, too (no C<user> or C<password> is necessary
+then).
+
+=item C<user>
+
+=item C<password>
+
+Credentials that will be used by L<cronbuilder> to access the repository.
+
+=back
+
+=item Options for git
+
+=over
+
+=item C<url>
+
+URL that will be passed to C<git clone>. Basically, URL of your repository.
+This can be local repository, too (no C<user> or C<password> is necessary
+then).
+
+=item C<user>
+
+=item C<password>
+
+Credentials that will be used by L<cronbuilder> to access the repository.
+
+=back
+
+=back
+
+=head2 Commit Messages
+
+For utilizing L<cronbuilder> fully, you need to properly comment your commits
+in source repository. What cronbuilder expects from you, is to format commit
+messages according to commonly established way: first line is a (very) short
+description of what was done in this revision, all the rest -- if any -- is
+a longer description.
+
+If you follow this guideline, L<cronbuilder> will give you quite useful
+automatic commit messages and e-mails. In each you will get nice description
+of incorporated changes. In becoming aware of changes, this helps much better
+than just raw commit identifiers.
+
+=cut
+
+#-----------------------------------------------------------------------------
 # vim:ft=perl
index e21c306..e3eed94 100644 (file)
@@ -58,6 +58,7 @@ find $RPM_BUILD_ROOT%{perl_vendorarch}/auto -name .packlist -print0 | xargs -0 r
 %files
 %{_bindir}/cronbuilder
 %{_prefix}/share/doc/cronbuilder
+%{_mandir}/man1
 %{_mandir}/man3
 %{perl_vendorlib}/Cron/Builder.pm
 %{perl_vendorlib}/Cron/Builder
index b0dfb3b..ccf701c 100644 (file)
@@ -9,6 +9,17 @@ source:
   #user: xx
   #password: yy
 
+destination:
+  # type: svn, git
+  # necessary to determine last commit submitted by cronbuilder and how to add
+  # new files or search for changes
+  type: git
+
+  # if provided, cronbuilder can prepare initial check-out on its own
+  #url: "https://.../..."
+  #user: xx
+  #password: yy
+
 build:
   # specify how to produce destination data from source data
   # this command is guaranteed to be passed to /bin/sh
@@ -24,14 +35,3 @@ build:
   # want to be informed (building is performed rarely), and sometimes you
   # could want to omit this and only be informed about problems
   inform: true
-
-destination:
-  # type: svn, git
-  # necessary to determine last commit submitted by cronbuilder and how to add
-  # new files or search for changes
-  type: git
-
-  # if provided, cronbuilder can prepare initial check-out on its own
-  #url: "https://.../..."
-  #user: xx
-  #password: yy