bozo 0.3.2 → 0.3.3

data/lib/bozo/bozo_configuration.rb

@@ -0,0 +1,300 @@
+module Bozo
+
+  # Class used for defining the configuration of a build.
+  class BozoConfiguration
+
+    include Bozo::ClassNameHelpers
+    
+    # Creates a new instance
+    def initialize
+      @build_tools_location = nil
+      @compilers = []
+      @dependency_resolvers = []
+      @hooks = []
+      @packagers = []
+      @preparers = []
+      @publishers = []
+      @test_runners = []
+      @version = nil
+    end
+    
+    # Loads the configuration from the specified file.
+    # 
+    # @param [String] path
+    #     The path to the configuration file.    
+    def load(path)
+      instance_eval IO.read(path), path
+    end
+
+    # The version of the project to build.
+    def version
+      @version ||= Versioning::Version.load_from_file
+    end
+
+    # The location of the base build tools.
+    #
+    # Sets and returns the location if a value is provided, otherwise returns
+    # the current value.
+    #
+    # It is expected the build tools will be in sub-directory of this location
+    # according to the name of the tool and that the runner will be able to
+    # copy the contents of the sub-directory to a local directory via the
+    # `FileUtils.cp_r` method.
+    #
+    # @param [String] location
+    #     The path to set as the build tools location.
+    def build_tools_location(location = nil)
+      @build_tools_location = location if location
+      @build_tools_location
+    end
+
+    # Returns the all the build tools required by the specified compilers,
+    # dependency resolvers, hooks, packagers, publishers and test runners.
+    def build_tools
+      build_tools = get_build_tools @compilers
+      build_tools |= get_build_tools @dependency_resolvers
+      build_tools |= get_build_tools @hooks
+      build_tools |= get_build_tools @packagers
+      build_tools |= get_build_tools @preparers
+      build_tools |= get_build_tools @publishers
+      build_tools | (get_build_tools @test_runners)
+    end
+
+    # Returns the configured dependency resolvers.
+    attr_reader :dependency_resolvers
+
+    # Adds an instance of the named preparer to the preparer collection and
+    # yields it to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the preparer.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the preparer.
+    def prepare(type, &block) # :yields: preparer
+      add_instance @preparers, Bozo::Preparers, type, block
+    end
+
+    # Returns the configured preparers.
+    attr_reader :preparers
+
+    # Adds an instance of the named dependency resolver to the dependency
+    # resolver collection and yields it to the configuration block when one
+    # is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the dependency resolver.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the dependency
+    #     resolver.
+    def resolve_dependencies_with(type, &block) # :yields: dependency_resolver
+      add_instance @dependency_resolvers, Bozo::DependencyResolvers, type, block
+    end
+
+    # Returns the configured compilers.
+    attr_reader :compilers
+
+    # Adds an instance of the named compiler to the compiler collection and
+    # yields it to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the compiler.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the compiler.
+    def compile_with(type, &block) # :yields: compiler
+      add_instance @compilers, Bozo::Compilers, type, block
+    end
+
+    # Returns the configured test runners.
+    attr_reader :test_runners
+
+    # Adds an instance of the named test runner to the test runner collection
+    # and yields it to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the test runner.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the test runner.
+    def test_with(type, &block) # :yields: test_runner
+      add_instance @test_runners, Bozo::TestRunners, type, block
+    end
+
+    # Returns the configured packagers.
+    attr_reader :packagers
+
+    # Adds an instance of the named packager to the packager collection and
+    # yields it to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the packager.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the packager.
+    def package_with(type, &block) # :yields: packager
+      add_instance @packagers, Bozo::Packagers, type, block
+    end
+
+    # Returns the configured publishers.
+    attr_reader :publishers
+
+    # Adds an instance of the named publisher to the publisher collection and
+    # yields it to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the publisher.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the publisher.
+    def publish_with(type, &block) # :yields: publisher
+      add_instance @publishers, Bozo::Publishers, type, block
+    end
+
+    # Returns the configured hooks.
+    attr_reader :hooks
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    #
+    # @param [Symbol] type
+    #     The name of the hook.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the hook.
+    def with_hook(type, &block) # :yields: hook
+      add_instance @hooks, Bozo::Hooks, type, block
+    end
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_build :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_clean :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_clean :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_uninstall :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_uninstall :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_dependencies :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_dependencies :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_prepare :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_prepare :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_compile :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_compile :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_test :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_test :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_package :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_package :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :pre_publish :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_publish :with_hook
+
+    # Adds an instance of the named hook to the hook collection and yields it
+    # to the configuration block when one is specified.
+    alias :post_build :with_hook
+    
+    private
+
+    # Resolves the named class within the given namespace and then created an
+    # instance of the class before adding it to the given collection and
+    # yielding it to the configuration block when one is provided.
+    #
+    # @param [Array] collection
+    #     The collection the step executor should be added to once created.
+    # @param [Module] namespace
+    #     The module the named step executor should be found in.
+    # @param [Symbol] type
+    #     The name of the step executor.
+    # @param [Proc] block
+    #     Optional block to refine the configuration of the step executor.
+    def add_instance(collection, namespace, type, block)
+      instance = namespace.const_get(to_class_name(type)).new
+      instance.extend Bozo::Runner
+      collection << instance
+      block.call instance if block
+    end
+
+    # Returns the collection of build tools required for the configuration.
+    #
+    # Sourced from the required tools of compilers, dependency resolvers,
+    # hooks, publishers and test runners.
+    #
+    # @param [Array] providers
+    #     Collection of providers that can define required tools.
+    def get_build_tools(providers)
+      providers.
+          select{|p| p.respond_to? :required_tools}.
+          map{|p| p.required_tools}.
+          flatten
+    end
+  
+  end
+
+  # Module containing all dependency resolvers.
+  module DependencyResolvers
+  end
+
+  # Module containing all compilers.
+  module Compilers
+  end
+
+  # Module containing all test runners.
+  module TestRunners
+  end
+
+  # Module containing all packagers.
+  module Packagers
+  end
+
+  # Module containing all preparers.
+  module Preparers
+  end
+
+  # Module containing all publishers.
+  module Publishers
+  end
+
+  # Module containing all hooks.
+  module Hooks
+  end
+
+end

data/lib/bozo/class_name_helpers.rb

@@ -0,0 +1,17 @@
+module Bozo
+
+  module ClassNameHelpers
+
+    # Converts a symbol into a Pascal Case class name.
+    #
+    # eg. `:single` => `"Single"`, `:two_words` => `"TwoWords"`.
+    #
+    # @param [Symbol] type
+    #     The name of a step executor.
+    def to_class_name(type)
+      type.to_s.split('_').map{|word| word.capitalize}.join
+    end
+
+  end
+
+end

data/lib/bozo/configuration_error.rb

@@ -0,0 +1,30 @@
+module Bozo
+
+  # Error raised when a runner or hook finds the configuration or build in an
+  # unexpected state.
+  class ConfigurationError < StandardError
+
+    # The code the program should exit with upon handling this error.
+    attr_reader :exit_code
+
+    # A message explaining the corrective actions someone can take to avoid the
+    # error.
+    attr_reader :message
+
+    # Creates a new instance.
+    #
+    # @param [String] message
+    #     A message explaining the corrective actions someone can take to avoid
+    #     the error.
+    def initialize(message)
+      @message = message
+      @exit_code = -1
+    end
+    
+    def inspect
+      "Configuration error: #{message}"
+    end
+    
+  end
+  
+end

data/lib/bozo/execution_error.rb

@@ -0,0 +1,36 @@
+module Bozo
+
+  # Error raised when a command line executable does not return an exit code of
+  # zero.
+  class ExecutionError < StandardError
+
+    # The array of parameters that made up the call.
+    attr_reader :command
+
+    # The exit code returned by the command.
+    attr_reader :exit_code
+
+    # The friendly name of the tool that failed.
+    attr_reader :tool
+
+    # Create a new instance.
+    #
+    # @param [Symbol] tool
+    #     The friendly name of the tool that failed.
+    # @param [Array] command
+    #     The array of parameters that made up the call.
+    # @param [Integer] exit_code
+    #     The exit code returned by the command
+    def initialize(tool, command, exit_code)
+      @tool = tool
+      @command = command
+      @exit_code = exit_code
+    end
+    
+    def inspect
+      "Execution error: Exit code of #{exit_code} returned from: #{tool} #{command[1..-1].join(' ')}"
+    end
+    
+  end
+  
+end

data/lib/bozo/executor.rb

@@ -0,0 +1,282 @@
+module Bozo
+  
+  # Class defining the structure of the build and responsible for executing
+  # tasks and their dependencies.
+  class Executor
+    include Runner
+    
+    # Create a new instance.
+    #
+    # @param [Configuration] build_configuration
+    #     The build configuration.
+    # @param [Hash] global_params
+    #     The global parameters
+    def initialize(build_configuration, global_params)
+      @build_configuration = build_configuration
+      @global_params = cli_keys_to_ruby global_params
+    end
+    
+    # Executes the command using the given parameters and environment.
+    #
+    # @param [Symbol] command
+    #     The name of the command to execute.
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def execute(command, params, env)
+      with_hooks :build, params, env do
+        send command, params, env
+      end
+    end
+
+    # Runs the clean task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def clean(params, env)
+      with_hooks :clean, params, env do
+        log_info 'Cleaning project'
+        clear_directory 'temp'
+        clear_directory 'dist'
+      end
+    end
+    
+    # Runs the uninstall task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def uninstall(params, env)
+      clean params, env
+      with_hooks :uninstall, params, env do
+        log_info 'Uninstalling project'
+        clear_directory 'packages'
+        clear_directory 'build'
+      end
+    end
+
+    # Runs the dependency retrieval task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def dependencies(params, env)
+      clean params, env
+      retrieve_build_dependencies
+      execute_with_hooks :dependencies, params, env
+    end
+
+    # Runs the prepare task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def prepare(params, env)
+      dependencies params, env
+      execute_with_hooks :prepare, params, env
+    end
+
+    # Runs the compile task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def compile(params, env)
+      prepare params, env
+      execute_with_hooks :compile, params, env
+    end
+
+    # Runs the test task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def test(params, env)
+      compile params, env
+      execute_with_hooks :test, params, env
+    end
+
+    # Runs the package task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def package(params, env)
+      test params, env
+      execute_with_hooks :package, params, env
+    end
+
+    # Runs the publish task.
+    #
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def publish(params, env)
+      if build_server?
+        package params, env
+        execute_with_hooks :publish, params, env
+      else
+        log_warn 'You can only publish a package from build server.'
+        log_warn ''
+        log_warn 'If you really need to publish the package then provide the --build-server switch but you should only be doing that as a last resort.'
+      end
+    end
+    
+    private
+
+    # Executes the executors for the given stage logging all messages with the
+    # given action.
+    #
+    # @param [Symbol] stage
+    #     The name of the stage to execute.
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def execute_with_hooks(stage, params, env)
+      action, executors = stage_definition stage
+      with_hooks stage, params, env do
+        log_info '' # blank line for aesthetics
+        log_info action
+        log_debug 'No executors' if executors.empty?
+        executors.each do |executor|
+          log_debug "#{action} with #{executor.class}"
+          set_parameters executor, params, env
+          executor.execute
+        end
+      end
+    end
+    
+    # Gets the description and runners associated with the given stage.
+    #
+    # @params [Symbol] stage
+    #     The name of the stage.
+    def stage_definition(stage)
+      case stage
+      when :dependencies
+        return 'Resolving dependencies', @build_configuration.dependency_resolvers
+      when :compile
+        return 'Compiling', @build_configuration.compilers
+      when :test
+        return 'Running tests', @build_configuration.test_runners
+      when :package
+        return 'Packaging', @build_configuration.packagers
+      when :prepare
+        return 'Preparing', @build_configuration.preparers
+      when :publish
+        return 'Publishing', @build_configuration.publishers
+      else
+        raise "Unrecognized stage: #{stage}"
+      end
+    end
+
+    # Runs the given code block surrounding it with the hooks for the named
+    # stage.
+    #
+    # @param [Symbol] stage
+    #     The name of the stage being run.
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def with_hooks(stage, params, env)
+      call_receiving_hooks "pre_#{stage}".to_sym, params, env
+      yield
+      call_receiving_hooks "post_#{stage}".to_sym, params, env
+    end
+    
+    # Invokes the method for the hook for all hook objects that define a 
+    # method for it.
+    #
+    # @param [Symbol] stage
+    #     The name of the hook to call the methods for.
+    # @param [Hash] params
+    #     The parameters for the command.
+    # @param [Hash] env
+    #     The environment that the command is run within.
+    def call_receiving_hooks(stage, params, env)
+      @build_configuration.hooks.each do |hook|
+        if hook.respond_to? stage
+          set_parameters hook, params, env
+          hook.send stage
+        end
+      end
+    end
+    
+    # Assigns the state of the build system to the runner.
+    #
+    # @param [Runner] runner
+    #     The runner to assign the state to.
+    # @param [Hash] params
+    #     The parameters for the step.
+    # @param [Hash] env
+    #     The environment that the step is run within.
+    def set_parameters(runner, params, env)
+      runner.build_configuration = @build_configuration
+      runner.global_params = @global_params
+      runner.params = cli_keys_to_ruby params
+      runner.env = env
+    end
+
+    # Removes the named directory from the root directory.
+    #
+    # @param [String] dir
+    #     The name of the directory to remove.
+    def clear_directory(dir)
+      full_path = File.expand_path(dir)
+      log_debug "Clearing directory #{full_path}"
+      FileUtils.rm_rf full_path
+    end
+
+    # Retrieves the required build tools from the configured build tools
+    # location.
+    def retrieve_build_dependencies
+      tools_location = @build_configuration.build_tools_location
+      required_tools = @build_configuration.build_tools
+      tools_path = File.expand_path(File.join('build', 'tools'))
+
+      log_info 'Retrieving build tools'
+
+      required_tools.each do |tool|
+        tool_name = tool.to_s
+        tool_path = File.join(tools_location, tool_name)
+        tool_destination = File.join(tools_path, tool_name)
+
+        if File.exist? tool_destination
+          log_debug "#{tool_name.capitalize} already present"
+        else
+          log_debug "Retrieving #{tool_name.capitalize}"
+          FileUtils.mkdir_p tool_destination
+          FileUtils.cp_r tool_path, tools_path
+          log_debug "#{tool_name.capitalize} retrieved"
+        end
+      end
+    end
+    
+    # Converts a hash containing CLI-style keys (:'multi-word') and converts 
+    # them into Ruby-style symbols (:multi_word).
+    #
+    # @param [Hash] hash
+    #     A hash containing CLI-style keys.
+    def cli_keys_to_ruby(hash)
+      hash.keys.to_a.each do |key|
+        new_key = key.to_s.gsub('-', '_').to_sym
+        hash[new_key] = hash[key] unless hash.has_key? new_key
+      end
+
+      hash
+    end
+    
+  end
+  
+end

data/lib/bozo/logging.rb

@@ -0,0 +1,40 @@
+module Bozo
+
+  # Module that provides functionality for logging.
+  module Logging
+
+    # Records a `debug` log message.
+    #
+    # @param [String] msg
+    #   The message to log.
+    def log_debug(msg)
+      puts "  #{msg.bright.color(:black)}"
+    end
+
+    # Records a `fatal` log message.
+    #
+    # @param [String] msg
+    #   The message to log.
+    def log_fatal(msg)
+      puts msg.color(:red).bright
+    end
+
+    # Records an `info` log message.
+    #
+    # @param [String] msg
+    #   The message to log.
+    def log_info(msg)
+      puts msg.color(:cyan).bright
+    end
+
+    # Records a `warn` log message.
+    #
+    # @param [String] msg
+    #   The message to log.
+    def log_warn(msg)
+      puts msg.color(:yellow).bright
+    end
+
+  end
+
+end