bozo 0.3.8 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZGUwMTRlYmExMGUzY2FhMGMxMGI1YWRhOTE1Njg4ZTQ2NDk2MzM4NA==
+    MTZhNmM4OTA4NjQwZDI3NTUxN2I0MDE4NmYyNTJmOTg0OGViOGZmMA==
   data.tar.gz: !binary |-
-    OGY3NmY1ZmI2MmVlMjg4NjhlY2NiYjU0ZjZkYjJjNTM2YjYwZWVhYw==
+    N2EwMGFlOTJhZTFmMjI5MzQ2MjQzMzQ4OTAxZGQ2NTU1OGQwMTQxYg==
 SHA512:
   metadata.gz: !binary |-
-    NTU5Y2UxZjRiOGY0ZjNmMGRjMjlmYjI2NmEwYWVmYWYxY2YwNTFjOWY3NTNj
-    Mjc4NGM1OWRkNWJmYmQ3MDgxMjJlNmU0NGYwYjcxMjRiZDE0Y2Y1NjRlZjVl
-    MmJhYTZhOTJhNzkyODkyMDVkZDQ0MjJmYjg3NjY3OWI3NjUzMDk=
+    ZmM1YzhiZmEwYjE3YWJiMGE1MTMzNTU3NWUyNjdiZjU0NGRiZTk5MGRmNjI1
+    MThiZWY5ODI2ZDZjZjQwNjg3NGY1ZGNjZWY3ZGRjMjdiNGVjZWQ3NDRjNmRl
+    YjY3Nzk4ODYxYTFmMzBkMGU3MTFkYTRhMGU5NTFkMmMzMjMxNTk=
   data.tar.gz: !binary |-
-    YjIwODU3NjQ4YmU5OTc2ZTJhMzZhYTc2ZDExNWE0OWFlY2M1MGE4ZmMzMjM1
-    ZWE1MDUwYmI0YTJiNGVmODY3YWE4NmZlNDBiYjYwOTQ4MDMyZWE4NjY4MDg1
-    NDk0NTg4YWE2ZTRjMTFjMDVjMDUyNmRhYjBlODI1MGVlZGI0YWE=
+    OTJmNmFmYWJkY2M0Y2I4MWY3ODU2MjY0ZWQ3Mjg5YmQyM2MxYTYwNmY2Y2Rj
+    MDc0YTY2NzQ1YTM1NWRkMDgwOGI5YTkwMmRmNDY1MjU2ZTZlNTU0YjcyMDli
+    YTg5MWJjZTNkMWMwOTdlZmFhZTUxNGI0ZDdhNWQwZWU2MzMxYzk=

data/README.md

@@ -1,427 +1,444 @@
-# Bozo
-
-Bozo is a build system written in Ruby. It is designed to be rigid yet
-extensible.
-
-## Steps
-
-There is a fixed set of steps, they are currently:
-
- 1. Clean
- 2. Resolve dependencies
- 3. Prepare
- 4. Compile
- 5. Test
- 6. Package
- 7. Publish
-
-The steps are sequential but you can run up to any of them. For example `bozo
-compile` executes the `clean`, `dependencies`, `prepare` and `compile` steps
-whereas `bozo dependencies` only executes the `clean` and `dependencies`
-steps.
-
-Bozo is a framework that provides a skeleton which can be populated by custom
-runners and hooks. Bozo itself provides no runners or hooks a reference
-project for runners and hooks can be found in the [bozo-scripts
-project](https://github.com/zopaUK/bozo-scripts/).
-
-Each step allows several runners to execute, for example you may run RSpec
-unit tests followed by Cucumber integration tests within the scope of the
-`test` step. Each step, along with the entire build, also expose pre- and
-post-step hooks.
-
-## Configuration
-
-A bozo build is configured through a single Ruby file, by convention this
-should be `bozorc.rb` located at the root of your project.
-
-Bozo makes use of a VERSION file in the root directory of the project. Versions can be specified in whatever format
-is required but a string in the format [major].[minor].[point] is generally expected.
-
-### Conventions
-
-Dependency resolvers must be defined within the `Bozo::DependencyResolvers`
-module, project preparers must be defined within the `Bozo::Preparers`
-module, compilers must be defined within the `Bozo::Compilers` module, test
-runners must be defined within the `Bozo::TestRunners` module, packagers must
-be defined within the `Bozo::Packagers`, publishers must be defined within
-the `Bozo::Publishers` module and hooks, regardless of the steps they relate
-to, must be defined within the `Bozo::Hooks` module.
-
-Runners are specified by convention with the relevant module being inspected
-for a matching class definition. For example, the configuration `compile_with
-:msbuild` will resolve to the class definition `Bozo::Compilers::Msbuild`.
-The symbol provided will be converted to Pascal Case prior to resolution. For
-example, the configuration `pre_compile :common_assembly_info` will resolve
-to the class definition `Bozo::Hooks::CommonAssemblyInfo`.
-
-Each runner and hook must provide a parameterless constructor and Bozo will
-invoke that constructor before registering and passing the instance to any
-block provided as part of the configuration. A runner or hook should be able
-to run with the default configuration whenever possible with customizations
-being provided through the block:
-
-```ruby
-test_with :nunit do |n|          # Creates and registers a new Bozo::TestRunners::Nunit instance
-  n.project 'Project.Tests'      # Adds additonal configuration to the instance
-end
-```
-
-If there are several runners for the same step then they will be executed in
-the order the are specified within the configuration.
-
-As soon as one runner or hook raises an error through either failing to
-execute a command successfully or some custom condition then the build is
-aborted.
-
-### Configuration example
-
-The exact syntax is still a work in progress though the concepts will remain
-the same.
-
-```ruby
-require 'bozo_scripts'            # Makes custom runners and hooks available
-
-prepare :common_assembly_info     # Defines that the common assembly info should be prepared for the project
-
-compile_with :msbuild             # Defines that the project should be compiled with the `msbuild` compiler
-
-test_with :nunit do |n|           # Defines that the project should be tested with the `nunit` test runner
-  n.project 'Project.Tests'       # Runner specific configuration - in this case defining the assemblies to run
-end
-
-package_with :nuget do |p|        # Defines that the project should be packaged with `nuget`
-  p.project 'Project'             # Runner specific configuration - in this case the projects to package
-  p.project 'Project.Testing'
-end
-
-resolve_dependencies_with :nuget  # Defines that project dependencies should be resolved with `nuget`
-
-with_hook :git_commit_hashes      # Defines that the `git_commit_hashes` hook should be executed with the build
-with_hook :timing                 # Defines that the `timing` hook should be executed with the build
-
-build_tools_location '//SERVER/network/path' # Defines the location build tools can be copied from
-```
-
-## Creating step runners and hooks
-
-Both step runners and hooks have their nuances which are covered in their
-dedicated sections. However, both are extended by the `Bozo::Runner` module
-that makes a collection of methods available to them.
-
-### build_configuration
-
-Returns the `Bozo::Configuration` of the build.
-
-### build_server?
-
-Returns `true` when the build is being run with the `--build-server` switch,
-otherwise `false`.
-
-This is a shortcut for `global_params[:build_server]`.
-
-### pre_release?
-
-Returns `true` when the build is being run with the `--pre-release` switch,
-otherwise `false`.
-
-This is a shortcut for `params[:pre_release]`.
-
-### env
-
-Returns the hash of environment variables. Initially populated by calling
-`ENV.to_hash` this may be added to by runners and hooks to enable lightweight
-communication and to cache the result of expensive calls.
-
-### environment
-
-Returns the name of the environment that the build is running in, eg.
-`'development'`.
-
-This is a shortcut for `global_params[:environment]`.
-
-### execute_command(tool, args)
-
-Executes a command line tool.
-
-Raises a `Bozo::ExecutionError` if the command responds with a non-zero exit
-code.
-
-#### Parameters
-
- * __tool [Symbol]__ A friendly identifier for the tool
- * __args [Array]__ An array of arguments making up the command to execute
-
-### global_params
-
-Returns the hash of global parameters passed to bozo. All key symbols are
-converted from the CLI style of `:'multi-word'` to `:multi_word` to be more
-idiomatic for Ruby.
-
-### log_debug(msg)
-
-Records an `debug` log message.
-
-#### Parameters
-
- * __msg [String]__ The message to log
-
-### log_fatal(msg)
-
-Records an `fatal` log message.
-
-#### Parameters
-
- * __msg [String]__ The message to log
-
-### log_info(msg)
-
-Records an `info` log message.
-
-#### Parameters
-
- * __msg [String]__ The message to log
-
-### log_warn(msg)
-
-Records an `warn` log message.
-
-#### Parameters
-
- * __msg [String]__ The message to log
-
-### params
-
-Returns the hash of command parameters passed to bozo. All key symbols are
-converted from the CLI style of `:'multi-word'` to `:multi_word` to be more
-idiomatic for Ruby.
-
-### version
-
-Returns the version of the build.
-
-This is a shortcut for `build_configuration.version`.
-
-## Creating step runners
-
-The structure of all runners is the same. They must be defined within the
-appropriate module, dependency resolvers in the `Bozo::DependencyResolvers`
-module, project preparers must be defined within the `Bozo::Preparers`
-module, compilers in the`Bozo::Compilers` module, test runners in the
-`Bozo::TestRunners` module, packagers in the `Bozo::Packagers` module and
-publishers in the `Bozo::Publishers` module. They must have a parameterless
-constructor and they must expose an `#execute` method which will be invoked
-when they should execute whatever task they are meant to perform. They can
-optionally define a `#required_tools` method which returns the name of any
-build tools it requires that cannot be retrieved through dependency
-resolvers, for example a dependency resolving executable such as `nuget.exe`.
-
-When executing a command line executable they should use the
-`execute_command(tool, args)` method so that the command will be logged in if
-the correct format and if executable completes with an error exit code the
-build will be aborted. They should also use the `log_info(msg)` and
-`log_debug(msg)` methods to ensure their output is formatted correctly and
-the verbosity of the messages can be controlled centrally.
-
-The runner will be passed back to the configuration code via an optional
-block so if further configuration of the runner is possible, or required,
-this should be exposed through public methods on the runner. If required
-configuration is omitted then a `Bozo::ConfigurationError` with a message
-explaining the problem and how to rectify it should be raised when the
-`#execute` method of the runner is called.
-
-### Registration
-
-Runners are registered through step-specific methods:
-
- * `dependency_resolver(identifier, &block)` registers dependency resolvers
- * `prepare(identifier, &block)` registers project preparers
- * `compile_with(identifier, &block)` registers compilers
- * `test_with(identifier, &block)` registers test runners
- * `package_with(identifier, &block)` registers packagers
- * `publish_with(identifier, &block)` registers publishers
-
-### Example
-
-Here is an example of a 'compiler' that logs `"Hello, <name>!"` where name is
-configured from the optional block and a `Bozo::ConfigurationError` is raised
-if no name has been configured:
-
-```ruby
-module Bozo::Compilers
-
-  class HelloWorld
-
-    def name(name)
-      @name = name
-    end
-
-    def execute
-      raise Bozo::ConfigurationError.new('You must specify a name to say "Hello" to') if @name.nil?
-      log_info "Hello, #{@name}!"
-    end
-
-  end
-
-end
-```
-
-This compiler would be added to your build via the configuration:
-
-```ruby
-compile_with :hello_world do |hw|
-  hw.name 'Bozo'
-end
-```
-
-## Creating hooks
-
-The structure of all hooks is the same. The must be defined within the
-`Bozo::Hooks` module and they must have a parameterless constructor. They can
-optionally define a `#required_tools` method which returns the name of any
-build tools it requires that cannot be retrieved through dependency resolvers,
-for example a dependency resolving executable such as `nuget.exe`.
-
-When executing a command line executable they should use the
-`execute_command(tool, args)` method so that the command will be logged in if
-the correct format and if executable completes with an error exit code the
-build will be aborted. They should also use the `log_info(msg)` and
-`log_debug(msg)` methods to ensure their output is formatted correctly and the
-verbosity of the messages can be controlled centrally.
-
-The hook will be passed back to the configuration code via an optional block
-so if further configuration of the hook is possible, or required, this should
-be exposed through public methods on the hook. If required configuration is
-omitted then a `Bozo::ConfigurationError` with a message explaining the
-problem and how to rectify it should be raised when a hook method is called.
-
-A hook can be called several times. In order to hook around a step all that is
-required is that an appropriately named method is defined within the class.
-For example, this hook logs a message both before and after the compile step
-is run:
-
-```ruby
-module Bozo::Hooks
-
-  class CompilingMessages
-
-    def pre_compile
-      log_info 'About to compile'
-    end
-
-    def post_compile
-      log_info 'Finished compiling'
-    end
-
-  end
-
-end
-```
-
-Which steps the hook wants to execute on is determined by checking the
-response to the `#respond_to?` method so if you wish to use `#method_missing`
-to add functionality you need to ensure that the response to `#respond_to?`
-reflects that.
-
-### Registration
-
-As hook instances can listen to one or more pre- or post-stage hooks there are
-multiple ways to register a hook. However, they are all functionally identical
-and are just aliases to the same method so that your configuration can read
-more clearly.
-
-The registration methods are:
-
- * `with_hook(identifier, &block)` (recommended when hooking several stages)
- * `pre_build(identifier, &block)`
- * `post_build(identifier, &block)`
- * `pre_clean(identifier, &block)`
- * `post_clean(identifier, &block)`
- * `pre_dependencies(identifier, &block)`
- * `post_dependencies(identifier, &block)`
- * `pre_prepare(identifier, &block)`
- * `post_prepare(identifier, &block)`
- * `pre_compile(identifier, &block)`
- * `post_compile(identifier, &block)`
- * `pre_test(identifier, &block)`
- * `post_test(identifier, &block)`
- * `pre_package(identifier, &block)`
- * `post_package(identifier, &block)`
- * `pre_publish(identifier, &block)`
- * `post_publish(identifier, &block)`
-
-Failed hooks exist that are called when a stage fails, in these cases the
-relevant `post` hook is not called.
-
- * `failed_build(identifier, &block)`
- * `failed_clean(identifier, &block)`
- * `failed_dependencies(identifier, &block)`
- * `failed_prepare(identifier, &block)`
- * `failed_compile(identifier, &block)`
- * `failed_test(identifier, &block)`
- * `failed_package(identifier, &block)`
- * `failed_publish(identifier, &block)`
-
-## Build tools
-
-Build tools are usually executables that you need to perform a task that are
-not available via some other means.
-
-For example, at Zopa we use in Nuget to resolve our .NET dependencies. This is
-a chicken and egg situation in that you can't use a dependency management
-system like Nuget until you've got a copy of the Nuget executable you can
-call. The build tools function aims to resolve this loop of cyclical dependency.
-
-Your build tools are resolve as the first part of the "resolve dependencies"
-step. When possible you should use real package management systems to retrieve
-dependencies rather than using the build tools function.
-
-### Specifying required build tools
-
-All the runners and hooks you create can optionally specify a `required_tools`
-method which returns the name of one or more required build tools:
-
-```ruby
-module Bozo::DependencyResolvers
-
-  class Nuget
-
-    def required_tools
-      :nuget # or for many [:nuget, :open_wrap]
-    end
-
-  end
-
-end
-```
-
-### How it works
-
-Within the example configuration there is a single line:
-
-```ruby
-build_tools_location '//SERVER/network/path' # Defines the location build tools can be copied from
-```
-
-This specifies the location that build tools should be retrieved from. This
-location is then joined with the name of the build tool to find the directory
-that must be copied into the `./build/tools` directory. For example with a
-`build_tools_location` of `//SERVER/network/path` along with a required
-build tool called `:nuget` will result in the directory
-`//SERVER/network/path/nuget` being copied to `./build/tools/nuget` directory.
-By knowing the contents of this directory you can then invoke the executables
-contained within it:
-
-```ruby
-module Bozo::DependencyResolvers
-
-  class Nuget
-
-    def execute
-      execute_command :nuget, File.join('build', 'tools', 'nuget', 'NuGet.exe')
-    end
-
-  end
-
-end
+# Bozo
+
+Bozo is a build system written in Ruby. It is designed to be rigid yet
+extensible.
+
+## Steps
+
+There is a fixed set of steps, they are currently:
+
+ 1. Clean
+ 2. Resolve dependencies
+ 3. Prepare
+ 4. Compile
+ 5. Test
+ 6. Package
+ 7. Publish
+
+The steps are sequential but you can run up to any of them. For example `bozo
+compile` executes the `clean`, `dependencies`, `prepare` and `compile` steps
+whereas `bozo dependencies` only executes the `clean` and `dependencies`
+steps.
+
+Bozo is a framework that provides a skeleton which can be populated by custom
+runners and hooks. Bozo itself provides no runners or hooks a reference
+project for runners and hooks can be found in the [bozo-scripts
+project](https://github.com/zopaUK/bozo-scripts/).
+
+Each step allows several runners to execute, for example you may run RSpec
+unit tests followed by Cucumber integration tests within the scope of the
+`test` step. Each step, along with the entire build, also expose pre- and
+post-step hooks.
+
+## Configuration
+
+A bozo build is configured through a single Ruby file, by convention this
+should be `bozorc.rb` located at the root of your project.
+
+Bozo makes use of a VERSION file in the root directory of the project. Versions can be specified in whatever format
+is required but a string in the format [major].[minor].[point] is generally expected.
+
+### Conventions
+
+Dependency resolvers must be defined within the `Bozo::DependencyResolvers`
+module, project preparers must be defined within the `Bozo::Preparers`
+module, compilers must be defined within the `Bozo::Compilers` module, test
+runners must be defined within the `Bozo::TestRunners` module, packagers must
+be defined within the `Bozo::Packagers`, publishers must be defined within
+the `Bozo::Publishers` module and hooks, regardless of the steps they relate
+to, must be defined within the `Bozo::Hooks` module.
+
+Runners are specified by convention with the relevant module being inspected
+for a matching class definition. For example, the configuration `compile_with
+:msbuild` will resolve to the class definition `Bozo::Compilers::Msbuild`.
+The symbol provided will be converted to Pascal Case prior to resolution. For
+example, the configuration `pre_compile :common_assembly_info` will resolve
+to the class definition `Bozo::Hooks::CommonAssemblyInfo`.
+
+Each runner and hook must provide a parameterless constructor and Bozo will
+invoke that constructor before registering and passing the instance to any
+block provided as part of the configuration. A runner or hook should be able
+to run with the default configuration whenever possible with customizations
+being provided through the block:
+
+```ruby
+test_with :nunit do |n|          # Creates and registers a new Bozo::TestRunners::Nunit instance
+  n.project 'Project.Tests'      # Adds additonal configuration to the instance
+end
+```
+
+If there are several runners for the same step then they will be executed in
+the order the are specified within the configuration.
+
+As soon as one runner or hook raises an error through either failing to
+execute a command successfully or some custom condition then the build is
+aborted.
+
+### Configuration example
+
+The exact syntax is still a work in progress though the concepts will remain
+the same.
+
+```ruby
+require 'bozo_scripts'            # Makes custom runners and hooks available
+
+prepare :common_assembly_info     # Defines that the common assembly info should be prepared for the project
+
+compile_with :msbuild             # Defines that the project should be compiled with the `msbuild` compiler
+
+test_with :nunit do |n|           # Defines that the project should be tested with the `nunit` test runner
+  n.project 'Project.Tests'       # Runner specific configuration - in this case defining the assemblies to run
+end
+
+package_with :nuget do |p|        # Defines that the project should be packaged with `nuget`
+  p.project 'Project'             # Runner specific configuration - in this case the projects to package
+  p.project 'Project.Testing'
+end
+
+resolve_dependencies_with :nuget  # Defines that project dependencies should be resolved with `nuget`
+
+with_hook :git_commit_hashes      # Defines that the `git_commit_hashes` hook should be executed with the build
+with_hook :timing                 # Defines that the `timing` hook should be executed with the build
+
+build_tools_location '//SERVER/network/path' # Defines the location build tools can be copied from
+```
+
+## Creating step runners and hooks
+
+Both step runners and hooks have their nuances which are covered in their
+dedicated sections. However, both are extended by the `Bozo::Runner` module
+that makes a collection of methods available to them.
+
+### build_configuration
+
+Returns the `Bozo::Configuration` of the build.
+
+### build_server?
+
+Returns `true` when the build is being run with the `--build-server` switch,
+otherwise `false`.
+
+This is a shortcut for `global_params[:build_server]`.
+
+### pre_release?
+
+Returns `true` when the build is being run with the `--pre-release` switch,
+otherwise `false`.
+
+This is a shortcut for `params[:pre_release]`.
+
+### env
+
+Returns the hash of environment variables. Initially populated by calling
+`ENV.to_hash` this may be added to by runners and hooks to enable lightweight
+communication and to cache the result of expensive calls.
+
+### environment
+
+Returns the name of the environment that the build is running in, eg.
+`'development'`.
+
+This is a shortcut for `global_params[:environment]`.
+
+### execute_command(tool, args)
+
+Executes a command line tool.
+
+Raises a `Bozo::ExecutionError` if the command responds with a non-zero exit
+code.
+
+#### Parameters
+
+ * __tool [Symbol]__ A friendly identifier for the tool
+ * __args [Array]__ An array of arguments making up the command to execute
+
+### global_params
+
+Returns the hash of global parameters passed to bozo. All key symbols are
+converted from the CLI style of `:'multi-word'` to `:multi_word` to be more
+idiomatic for Ruby.
+
+### log_debug(msg)
+
+Records an `debug` log message.
+
+#### Parameters
+
+ * __msg [String]__ The message to log
+
+### log_fatal(msg)
+
+Records an `fatal` log message.
+
+#### Parameters
+
+ * __msg [String]__ The message to log
+
+### log_info(msg)
+
+Records an `info` log message.
+
+#### Parameters
+
+ * __msg [String]__ The message to log
+
+### log_warn(msg)
+
+Records an `warn` log message.
+
+#### Parameters
+
+ * __msg [String]__ The message to log
+
+### params
+
+Returns the hash of command parameters passed to bozo. All key symbols are
+converted from the CLI style of `:'multi-word'` to `:multi_word` to be more
+idiomatic for Ruby.
+
+### version
+
+Returns the version of the build.
+
+This is a shortcut for `build_configuration.version`.
+
+## Creating step runners
+
+The structure of all runners is the same. They must be defined within the
+appropriate module, dependency resolvers in the `Bozo::DependencyResolvers`
+module, project preparers must be defined within the `Bozo::Preparers`
+module, compilers in the`Bozo::Compilers` module, test runners in the
+`Bozo::TestRunners` module, packagers in the `Bozo::Packagers` module and
+publishers in the `Bozo::Publishers` module. They must have a parameterless
+constructor and they must expose an `#execute` method which will be invoked
+when they should execute whatever task they are meant to perform. They can
+optionally define a `#required_tools` method which returns the name of any
+build tools it requires that cannot be retrieved through dependency
+resolvers, for example a dependency resolving executable such as `nuget.exe`.
+
+When executing a command line executable they should use the
+`execute_command(tool, args)` method so that the command will be logged in if
+the correct format and if executable completes with an error exit code the
+build will be aborted. They should also use the `log_info(msg)` and
+`log_debug(msg)` methods to ensure their output is formatted correctly and
+the verbosity of the messages can be controlled centrally.
+
+The runner will be passed back to the configuration code via an optional
+block so if further configuration of the runner is possible, or required,
+this should be exposed through public methods on the runner. If required
+configuration is omitted then a `Bozo::ConfigurationError` with a message
+explaining the problem and how to rectify it should be raised when the
+`#execute` method of the runner is called.
+
+### Registration
+
+Runners are registered through step-specific methods:
+
+ * `dependency_resolver(identifier, &block)` registers dependency resolvers
+ * `prepare(identifier, &block)` registers project preparers
+ * `compile_with(identifier, &block)` registers compilers
+ * `test_with(identifier, &block)` registers test runners
+ * `package_with(identifier, &block)` registers packagers
+ * `publish_with(identifier, &block)` registers publishers
+
+### Example
+
+Here is an example of a 'compiler' that logs `"Hello, <name>!"` where name is
+configured from the optional block and a `Bozo::ConfigurationError` is raised
+if no name has been configured:
+
+```ruby
+module Bozo::Compilers
+
+  class HelloWorld
+
+    def name(name)
+      @name = name
+    end
+
+    def execute
+      raise Bozo::ConfigurationError.new('You must specify a name to say "Hello" to') if @name.nil?
+      log_info "Hello, #{@name}!"
+    end
+
+  end
+
+end
+```
+
+This compiler would be added to your build via the configuration:
+
+```ruby
+compile_with :hello_world do |hw|
+  hw.name 'Bozo'
+end
+```
+
+## Creating hooks
+
+The structure of all hooks is the same. The must be defined within the
+`Bozo::Hooks` module and they must have a parameterless constructor. They can
+optionally define a `#required_tools` method which returns the name of any
+build tools it requires that cannot be retrieved through dependency resolvers,
+for example a dependency resolving executable such as `nuget.exe`.
+
+When executing a command line executable they should use the
+`execute_command(tool, args)` method so that the command will be logged in if
+the correct format and if executable completes with an error exit code the
+build will be aborted. They should also use the `log_info(msg)` and
+`log_debug(msg)` methods to ensure their output is formatted correctly and the
+verbosity of the messages can be controlled centrally.
+
+The hook will be passed back to the configuration code via an optional block
+so if further configuration of the hook is possible, or required, this should
+be exposed through public methods on the hook. If required configuration is
+omitted then a `Bozo::ConfigurationError` with a message explaining the
+problem and how to rectify it should be raised when a hook method is called.
+
+A hook can be called several times. In order to hook around a step all that is
+required is that an appropriately named method is defined within the class.
+For example, this hook logs a message both before and after the compile step
+is run:
+
+```ruby
+module Bozo::Hooks
+
+  class CompilingMessages
+
+    def pre_compile
+      log_info 'About to compile'
+    end
+
+    def post_compile
+      log_info 'Finished compiling'
+    end
+
+  end
+
+end
+```
+
+Which steps the hook wants to execute on is determined by checking the
+response to the `#respond_to?` method so if you wish to use `#method_missing`
+to add functionality you need to ensure that the response to `#respond_to?`
+reflects that.
+
+### Registration
+
+As hook instances can listen to one or more pre- or post-stage hooks there are
+multiple ways to register a hook. However, they are all functionally identical
+and are just aliases to the same method so that your configuration can read
+more clearly.
+
+The registration methods are:
+
+ * `with_hook(identifier, &block)` (recommended when hooking several stages)
+ * `pre_build(identifier, &block)`
+ * `post_build(identifier, &block)`
+ * `pre_clean(identifier, &block)`
+ * `post_clean(identifier, &block)`
+ * `pre_dependencies(identifier, &block)`
+ * `post_dependencies(identifier, &block)`
+ * `pre_prepare(identifier, &block)`
+ * `post_prepare(identifier, &block)`
+ * `pre_compile(identifier, &block)`
+ * `post_compile(identifier, &block)`
+ * `pre_test(identifier, &block)`
+ * `post_test(identifier, &block)`
+ * `pre_package(identifier, &block)`
+ * `post_package(identifier, &block)`
+ * `pre_publish(identifier, &block)`
+ * `post_publish(identifier, &block)`
+
+Failed hooks exist that are called when a stage fails, in these cases the
+relevant `post` hook is not called.
+
+ * `failed_build(identifier, &block)`
+ * `failed_clean(identifier, &block)`
+ * `failed_dependencies(identifier, &block)`
+ * `failed_prepare(identifier, &block)`
+ * `failed_compile(identifier, &block)`
+ * `failed_test(identifier, &block)`
+ * `failed_package(identifier, &block)`
+ * `failed_publish(identifier, &block)`
+
+## Build tools
+
+Build tools are usually executables that you need to perform a task that are
+not available via some other means.
+
+For example, at Zopa we use in Nuget to resolve our .NET dependencies. This is
+a chicken and egg situation in that you can't use a dependency management
+system like Nuget until you've got a copy of the Nuget executable you can
+call. The build tools function aims to resolve this loop of cyclical dependency.
+
+Your build tools are resolved as the first part of the "resolve dependencies"
+step. When possible you should use real package management systems to retrieve
+dependencies rather than using the build tools function.
+
+### Specifying required build tools
+
+All the runners and hooks you create can optionally specify a `required_tools`
+method which returns the name of one or more required build tools:
+
+```ruby
+module Bozo::DependencyResolvers
+
+  class Nuget
+
+    def required_tools
+      :nuget # or for many [:nuget, :open_wrap]
+    end
+
+  end
+
+end
+```
+
+Tools that aren't `required_tools` of another runner can be specified using the following:
+
+```ruby
+required_tool :nuget
+
+required_tool :tool_with_configuration do |n|
+  n.tool_version '1.0'
+end
+```
+
+In the case of the configuration `required_tool` method only the `Bozo::Tools` module is used.
+
+### How it works
+
+There are two ways which tools may be resolved when required by another module, either
+from the `build_tools_location` or via a `Bozo::Tool` module class. A class in the `Bozo::Tool` module
+takes priority over the `build_tools_location`, if Bozo fails to find a class with the same name then
+the `build_tools_location` is used.
+
+Within the example configuration there is a single line:
+
+```ruby
+build_tools_location '//SERVER/network/path' # Defines the location build tools can be copied from
+```
+
+This specifies the location that build tools should be retrieved from. This
+location is then joined with the name of the build tool to find the directory
+that must be copied into the `./build/tools` directory. For example with a
+`build_tools_location` of `//SERVER/network/path` along with a required
+build tool called `:nuget` will result in the directory
+`//SERVER/network/path/nuget` being copied to `./build/tools/nuget` directory.
+By knowing the contents of this directory you can then invoke the executables
+contained within it:
+
+```ruby
+module Bozo::DependencyResolvers
+
+  class Nuget
+
+    def execute
+      execute_command :nuget, File.join('build', 'tools', 'nuget', 'NuGet.exe')
+    end
+
+  end
+
+end
 ```