omnibus 3.2.0.rc.1 → 3.2.0.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4812c396c2ec933378d32542df7c8245700ecf52
-  data.tar.gz: 51791434059dcada2197bf2bb8693e6c080669f2
+  metadata.gz: 713b0a1bd3b7ac7ea05f5d7b40eb80824c24477e
+  data.tar.gz: b0d7e0927ed88cd196966be1891268e62a0ce5f7
 SHA512:
-  metadata.gz: 805e85738934c39e9d849fa6dd93d0877b17c60aab484e788616e1e143bd72df59971a8fce9c02cc15f2c3402717a565883425058a6fba20c0e3231c4508a6c8
-  data.tar.gz: 9351cf29fb353525d4e705bd0fdde1884ccaac3d393c3c78b96ed88f6963467a92ed32b40f5aad9e8ef7ccda0e460df0a8ed0954b39818e2d0a715d96261aca6
+  metadata.gz: 8289bda18635035acc08431683e4444c24bf2759bdcbe15aa3c69537458c4c1d0718562e45faa789832b0710a5b96e75eb55be4910b4f17ecb3108287ed9ce9c
+  data.tar.gz: f524d6d38c6f328a408b2531c6eabd9853462c3b020a5e10de9b84bf3c5e3bb8d50318c04763bfcf8e69056e66ff768e7882a06c3896439f17e4dbd7560fdeff

data/CHANGELOG.md

@@ -1,8 +1,8 @@
 Omnibus Ruby CHANGELOG
 ======================
 
-v3.2.0.rc.1 (July 14, 2014)
------------==--------------
+v3.2.0.rc.2 (July 17, 2014)
+---------------------------
 - Make build commands output during `log.info` instead of `log.debug`
 - Refactor Chef Sugar into an includable module, permitting DSL methods in both Software and Project definitions
 - Refactor `omnibus release` into a non-S3-specific backend "publisher"
@@ -21,6 +21,8 @@ v3.2.0.rc.1 (July 14, 2014)
 - Add publish APIs for dirtying the git cache
 - Add test coverage for the "public" API
 - Add validation to `source` in software DSL
+- Add logging to the Packager class
+- Add functional tests for builders
 - Update generator templates to use the new APIs
 - Upgrade to Ohai 7.2
 - Improve YARDoc
@@ -40,11 +42,13 @@ v3.2.0.rc.1 (July 14, 2014)
 - Deprecate `Project#install_path` in favor of `Project.install_dir`
 - Deprecate [DSL] `install_path` in favor of `install_dir`
 - Rename `Config.install_path_cache_dir` to `git_cache_dir`
+- Fix a bug in the deprecations where a hardcoded output was used instead of a dynamic variable
 
 ### DSL Changes
 - Add `with_embedded_path` to software
 - Add `with_standard_compiler_flags` to software
 - Add `package_scripts_path` to project
+- Add builder DSL methods for `mkdir`, `touch`, `delete`, `copy`, `move`, and `link`
 
 ### Bug fixes
 - Fix a small typo in the project generator (come -> some)
@@ -63,6 +67,9 @@ v3.2.0.rc.1 (July 14, 2014)
 - Intelligently parse the project's homepage because Ruby's native URI implementation is buggy
 - Fetch all software at the start of the build - this fixes a bug where a build would fail halfway through because of a tiny typo of GitHub outage. Now, all required software is downloaded **before** the build starts, lowering the feedback time for a failure due to networking issues
 - Use the fetcher's `version_for_cache` method directly, falling back to `0.0.0` (and a warining) if no version is given
+- Require `net/http`, `net/https`, and `net/ftp` in the base fetcher module
+- Use -R, not -W1 on FreeBSD's compile flags
+- Expand all paths relative to the project_root
 
 ### Potentially breaking changes
 - Merged `Package` and `Artifact` into the same class and updated API - this was considered an **internal** API so it is not a violation of semver
@@ -70,6 +77,8 @@ v3.2.0.rc.1 (July 14, 2014)
 - Use a cleanroom object when evaluating the DSL - prior to this release, Omnibus did not declare a public API. Project and software definitions had unrestricted access to the entire project.rb and software.rb methods respectively. This poses two problems - first, it makes it impossible to guarantee a public DSL API over a public (code) API. Second, it permits a developer to change the behavior of project.rb or software.rb accidentially, simply by defining a new method. The introducing of a cleanroom fixes both these bugs, however, it was impossible to know what was formerly considered a public API. Thus, it is possible that a previously-relied-on method is now unavaiable using the cleanroom. Please open an issue if you encounter such a case.
 - Remove mixlib-config - if you were relying on mixlib-config as a transitive dependency, it is no longer available
 - Remove the ability to use an overrides file - this was for internal use only and was never exposed as a public API. However, if you dug into the code and found it, it has now been removed. For BC purposes, the value still exists in the configuration object, but is essentially a no-op
+- Move project loading from INFO to DEBUG
+- Truncate platforms to short versions
 
 
 v3.1.1 (May 20, 2014)

data/Rakefile

@@ -1,7 +1,7 @@
 require 'bundler/gem_tasks'
 
 require 'rspec/core/rake_task'
-[:unit, :functional].each do |type|
+[:unit, :functional, :integration].each do |type|
   RSpec::Core::RakeTask.new(type) do |t|
     t.pattern = "spec/#{type}/**/*_spec.rb"
     t.rspec_opts = [].tap do |a|
@@ -22,7 +22,7 @@ end
 
 namespace :travis do
   desc 'Run tests on Travis'
-  task ci: %w(unit acceptance)
+  task ci: %w(unit functional acceptance)
 end
 
 task default: %w(travis:ci)

data/lib/omnibus.rb

@@ -40,6 +40,7 @@ module Omnibus
   autoload :Generator,        'omnibus/generator'
   autoload :GitCache,         'omnibus/git_cache'
   autoload :HealthCheck,      'omnibus/health_check'
+  autoload :Instrumentation,  'omnibus/instrumentation'
   autoload :Library,          'omnibus/library'
   autoload :Logger,           'omnibus/logger'
   autoload :Logging,          'omnibus/logging'
@@ -249,13 +250,15 @@ module Omnibus
     # @return [Array<String>]
     #
     def software_dirs
+      return @software_dirs if @software_dirs
+
       directories = [
         paths_from_project_root,
         paths_from_local_software_dirs,
         paths_from_software_gems,
       ].flatten
 
-      directories.inject([]) do |array, directory|
+      @software_dirs = directories.inject([]) do |array, directory|
         softwares_path = File.join(directory, Config.software_dir)
 
         if File.directory?(softwares_path)
@@ -269,6 +272,8 @@ module Omnibus
 
         array
       end
+
+      @software_dirs
     end
 
     #
@@ -283,12 +288,14 @@ module Omnibus
     # @return [Hash<String, String>]
     #
     def software_map
-      software_dirs.inject({}) do |hash, directory|
+      return @software_map if @software_map
+
+      @software_map = software_dirs.inject({}) do |hash, directory|
         Dir.glob("#{directory}/*.rb").each do |path|
           name = File.basename(path, '.rb')
 
           if hash[name].nil?
-            Omnibus.logger.info('Omnibus#software_map') do
+            Omnibus.logger.debug('Omnibus#software_map') do
               "Using software `#{name}' from `#{path}'."
             end
 
@@ -303,6 +310,8 @@ module Omnibus
 
         hash
       end
+
+      @software_map
     end
 
     private
@@ -323,7 +332,7 @@ module Omnibus
         name = File.basename(path, '.rb')
 
         if hash[name].nil?
-          Omnibus.logger.info('Omnibus#projects') do
+          Omnibus.logger.debug('Omnibus#projects') do
             "Using project `#{name}' from `#{path}'."
           end
 

data/lib/omnibus/builder.rb

@@ -14,178 +14,453 @@
 # limitations under the License.
 #
 
-require 'forwardable'
+require 'bundler'
+require 'fileutils'
 require 'ostruct'
+require 'mixlib/shellout'
 
 module Omnibus
   class Builder
+    include Cleanroom
+    include Digestable
+    include Instrumentation
     include Logging
+    include Util
 
-    # Proxies method calls to either a Builder object or the Software that the
-    # builder belongs to. Provides compatibility with our DSL where we never
-    # yield objects to blocks and hopefully hides some of the confusion that
-    # can arise from instance_eval.
-    class DSLProxy
-      extend Forwardable
-
-      def_delegator :@builder, :patch
-      def_delegator :@builder, :erb
-      def_delegator :@builder, :command
-      def_delegator :@builder, :ruby
-      def_delegator :@builder, :gem
-      def_delegator :@builder, :bundle
-      def_delegator :@builder, :rake
-      def_delegator :@builder, :block
-      def_delegator :@builder, :name
-      def_delegator :@builder, :max_build_jobs
-
-      def initialize(builder, software)
-        @builder, @software = builder, software
+    #
+    # Since builder is also a proxy object to software, we dynamically re-define
+    # all the methods that exist on {Software} as proxy methhods here. This
+    # permits developers to use {Software} methods as if they were directly
+    # part of this DSL.
+    #
+    Software.exposed_methods.each do |name, _|
+      define_method(name) do |*args, &block|
+        software.send(name, *args, &block)
       end
+      expose(name)
+    end
 
-      def eval_block(&block)
-        instance_eval(&block)
-      end
+    #
+    # @return [Software]
+    #   the software definition that created this builder
+    #
+    attr_reader :software
 
-      def respond_to?(method)
-        super || @software.respond_to?(method)
-      end
+    #
+    # Create a new builder object for evaluation.
+    #
+    # @param [Software] software
+    #   the software definition that created this builder
+    #
+    def initialize(software)
+      @software = software
+    end
 
-      def methods
-        super | @software.methods
-      end
+    #
+    # @!group System DSL methods
+    #
+    # The following DSL methods are available from within build blocks.
+    # --------------------------------------------------
 
-      def method_missing(method_name, *args, &block)
-        if @software.respond_to?(method_name)
-          @software.send(method_name, *args, &block)
-        else
-          super
-        end
+    #
+    # Execute the given command string or command arguments.
+    #
+    # @example
+    #   command 'make install', env: { 'PATH' => '/my/custom/path' }
+    #
+    # @param [String] command
+    #   the command to execute
+    # @param [Hash] options
+    #   a list of options to pass to the +Mixlib::ShellOut+ instance when it is
+    #   executed
+    #
+    # @return [void]
+    #
+    def command(command, options = {})
+      build_commands << BuildCommand.new("Execute: `#{command}'") do
+        _shellout!(command, options)
       end
     end
+    expose :command
 
-    # @todo code duplication with {Fetcher::ErrorReporter}
-    # @todo make this use the logger
-    class ErrorReporter
-      # @todo fetcher isn't even used
-      def initialize(error, fetcher)
-        @error, @fetcher = error, fetcher
-      end
+    #
+    # Apply the patch by the given name. This method will search all possible
+    # locations for a patch (such as {Config#software_gems}).
+    #
+    # @example
+    #   patch source: 'ncurses-clang.patch'
+    #
+    # @example
+    #   patch source: 'patch-ad', plevel: 0
+    #
+    # @param [Hash] options
+    #   the list of options
+    #
+    # @option options [String] :source
+    #   the name of the patch to apply
+    # @option options [Fixnum] :plevel
+    #   the level to apply the patch
+    # @option options [String] :target
+    #   the destination to apply the patch
+    #
+    # @return (see #command)
+    #
+    def patch(options = {})
+      source = options.delete(:source)
+      plevel = options.delete(:plevel) || 1
+      target = options.delete(:target)
 
-      # @todo this isn't necessary
-      def e
-        @error
+      locations, patch_path = find_file('config/patches', source)
+
+      unless patch_path
+        raise MissingPatch.new(source, locations)
       end
 
-      def explain(why)
-        $stderr.puts '* ' * 40
-        $stderr.puts why
-        $stderr.puts 'Exception:'
-        $stderr.puts indent("#{e.class}: #{e.message.strip}", 2)
-        Array(e.backtrace).each { |l| $stderr.puts indent(l, 4) }
-        $stderr.puts '* ' * 40
+      # Apply patches nicely on Windows
+      patch_path = windows_safe_path(patch_path)
+
+      if target
+        command = "cat #{patch_path} | patch -p#{plevel} #{target}"
+      else
+        command = "patch -d #{software.project_dir} -p#{plevel} -i #{patch_path}"
       end
 
-      private
+      patches << patch_path
 
-      def indent(string, n)
-        string.split("\n").map { |l| ' '.rjust(n) << l }.join("\n")
+      build_commands << BuildCommand.new("Apply patch `#{source}'") do
+        _shellout!(command, options)
       end
     end
+    expose :patch
 
-    # @todo Look at using Bundler.with_clean_env{ ... } instead
-    BUNDLER_BUSTER = {
-      'RUBYOPT'         => nil,
-      'BUNDLE_BIN_PATH' => nil,
-      'BUNDLE_GEMFILE'  => nil,
-      'GEM_PATH'        => nil,
-      'GEM_HOME'        => nil,
-    }
+    #
+    # The maximum number of build jobs, as computed from Ohai data. If the Ohai
+    # data is unavailable, +3+ is used.
+    #
+    # @todo Should this be moved to {Software}?
+    #
+    # @example
+    #   command "make install -j#{max_build_jobs}"
+    #
+    # @return [Fixnum]
+    #
+    def max_build_jobs
+      if Ohai['cpu'] && Ohai['cpu']['total'] && Ohai['cpu']['total'].to_s =~ /^\d+$/
+        Ohai['cpu']['total'].to_i + 1
+      else
+        3
+      end
+    end
+    expose :max_build_jobs
 
-    attr_reader :build_commands
+    #
+    # @!endgroup
+    # --------------------------------------------------
 
-    def initialize(software, &block)
-      @software = software
-      @build_commands = []
-      @dsl_proxy = DSLProxy.new(self, software)
-      @dsl_proxy.eval_block(&block) if block_given?
-    end
+    #
+    # @!group Ruby DSL methods
+    #
+    # The following DSL methods are available from within build blocks and
+    # expose Ruby DSL methods.
+    # --------------------------------------------------
 
-    def name
-      @software.name
+    #
+    # Execute the given Ruby command or script against the embedded Ruby.
+    #
+    # @example
+    #   ruby 'setup.rb'
+    #
+    # @param (see #command)
+    # @return (see #command)
+    #
+    def ruby(command, options = {})
+      build_commands << BuildCommand.new("ruby `#{command}'") do
+        bin = windows_safe_path("#{install_dir}/embedded/bin/ruby")
+        _shellout!("#{bin} #{command}", options)
+      end
     end
+    expose :ruby
 
-    def command(*args)
-      @build_commands << args
+    #
+    # Execute the given Rubygem command against the embedded Rubygems.
+    #
+    # @example
+    #   gem 'install chef'
+    #
+    # @param (see #command)
+    # @return (see #command)
+    #
+    def gem(command, options = {})
+      build_commands << BuildCommand.new("gem `#{command}'") do
+        bin = windows_safe_path("#{install_dir}/embedded/bin/gem")
+        _shellout!("#{bin} #{command}", options)
+      end
     end
+    expose :gem
 
-    def patch(*args)
-      args = args.dup.pop
+    #
+    # Execute the given bundle command against the embedded Ruby's bundler. This
+    # command assumes the +bundler+ gem is installed and in the embedded Ruby.
+    # You should add a dependency on the +bundler+ software definition if you
+    # want to use this command.
+    #
+    # @example
+    #   bundle 'install'
+    #
+    # @param (see #command)
+    # @return (see #command)
+    #
+    def bundle(command, options = {})
+      build_commands << BuildCommand.new("bundle `#{command}'") do
+        bin = windows_safe_path("#{install_dir}/embedded/bin/bundle")
+        _shellout!("#{bin} #{command}", options)
+      end
+    end
+    expose :bundle
 
-      # Search for patches just like we search for software
-      candidate_paths = Omnibus.software_dirs.map do |directory|
-        patches = directory.sub(Config.software_dir, 'config/patches')
-        "#{patches}/#{name}/#{args[:source]}"
+    #
+    # Execute the given Rake command against the embedded Ruby's rake. This
+    # command assumes the +rake+ gem has been installed.
+    #
+    # @example
+    #   rake 'test'
+    #
+    # @param (see #command)
+    # @return (see #command)
+    #
+    def rake(command, options = {})
+      build_commands << BuildCommand.new("rake `#{command}'") do
+        bin = windows_safe_path("#{install_dir}/embedded/bin/rake")
+        _shellout!("#{bin} #{command}", options)
       end
+    end
+    expose :rake
+
+    #
+    # Execute the given Ruby block at runtime. The block is captured as-is and
+    # no validation is performed. As a general rule, you should avoid this
+    # method unless you know what you are doing.
+    #
+    # TODO: the "name" does nothing right now
+    #
+    # @example
+    #   block do
+    #     # Some complex operation
+    #   end
+    #
+    # @example
+    #   block 'Named operation' do
+    #     # The above name can be used in log output to identify the operation
+    #   end
+    #
+    # @param (see #command)
+    # @return (see #command)
+    #
+    def block(name = '<Dynamic Ruby block>', &proc)
+      build_commands << BuildCommand.new(name, &proc)
+    end
+    expose :block
+
+    #
+    # Render the erb template by the given name. This method will search all
+    # possible locations for an erb template (such as {Config#software_gems}).
+    #
+    # @example
+    #   erb source: 'example.erb',
+    #       dest:   '/path/on/disk/to/render'
+    #
+    # @example
+    #   erb source: 'example.erb',
+    #       dest:   '/path/on/disk/to/render',
+    #       vars:   { foo: 'bar' },
+    #       mode:   '0755'
+    #
+    # @param [Hash] options
+    #   the list of options
+    #
+    # @option options [String] :source
+    #   the name of the patch to apply
+    # @option options [String] :dest
+    #   the path on disk where the erb should be rendered
+    # @option options [Hash] :vars
+    #   the list of variables to pass to the ERB rendering
+    # @option options [String] :mode
+    #   the file mode for the rendered template (default varies by system)
+    #
+    # @return (see #command)
+    #
+    def erb(options = {})
+      source = options.delete(:source)
+      dest   = options.delete(:dest)
+      mode   = options.delete(:mode) || 0644
+      vars   = options.delete(:vars) || {}
+
+      raise "Missing required option `:source'!" unless source
+      raise "Missing required option `:dest'!"   unless dest
 
-      source = candidate_paths.find { |path| File.exist?(path) }
+      locations, source_path = find_file('config/templates', source)
 
-      unless source
-        raise MissingPatch.new(args[:source], candidate_paths)
+      unless source_path
+        raise MissingTemplate.new(source, locations)
       end
 
-      plevel = args[:plevel] || 1
-      if args[:target]
-        target = File.expand_path("#{project_dir}/#{args[:target]}")
-        @build_commands <<
-         "cat #{source} | patch -p#{plevel} #{target}"
-      else
-        @build_commands <<
-         "patch -d #{project_dir} -p#{plevel} -i #{source}"
+      erbs << source_path
+
+      block "Render erb `#{source}'" do
+        template = ERB.new(File.read(source_path), nil, '%')
+        struct   = OpenStruct.new(vars)
+        result   = template.result(struct.instance_eval { binding })
+
+        File.open(dest, 'w') do |file|
+          file.write(result)
+        end
+
+        File.chmod(mode, dest)
       end
     end
+    expose :erb
 
-    def erb(*args)
-      args = args.dup.pop
+    #
+    # @!endgroup
+    # --------------------------------------------------
 
-      source_path = File.expand_path("#{Config.project_root}/config/templates/#{name}/#{args[:source]}")
+    #
+    # @!group File system DSL methods
+    #
+    # The following DSL methods are available from within build blocks that
+    # mutate the file system.
+    #
+    # **These commands are run from inside {Software#install_dir}, so exercise
+    # good judgement when using relative paths!**
+    # --------------------------------------------------
 
-      unless File.exist?(source_path)
-        raise MissingTemplate.new(args[:source], "#{Config.project_root}/config/templates/#{name}")
+    #
+    # Make a directory at runtime. This method uses the equivalent of +mkdir -p+
+    # under the covers.
+    #
+    # @param [String] directory
+    #   the name or path of the directory to create
+    # @param [Hash] options
+    #   the list of options to pass to the underlying +FileUtils+ call
+    #
+    # @return (see #command)
+    #
+    def mkdir(directory, options = {})
+      build_commands << BuildCommand.new("mkdir `#{directory}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.mkdir_p(directory, options)
+        end
       end
+    end
+    expose :mkdir
 
-      block do
-        template = ERB.new(File.new(source_path).read, nil, '%')
-        File.open(args[:dest], 'w') do |file|
-          file.write(template.result(OpenStruct.new(args[:vars]).instance_eval { binding }))
+    #
+    # Touch the given filepath at runtime.
+    #
+    # @param [String] file
+    #   the path of the file to touch
+    # @param (see #mkdir)
+    #
+    # @return (see #command)
+    #
+    def touch(file, options = {})
+      build_commands << BuildCommand.new("touch `#{file}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.touch(file, options)
         end
-
-        File.chmod(args[:mode], args[:dest])
       end
     end
+    expose :touch
 
-    # @todo all these ruby commands (ruby, gem, bundle, rake) could
-    #   all be collapsed into a single underlying implementation, since
-    #   they all just differ on the executable being called
-    def ruby(*args)
-      @build_commands << bundle_bust(*prepend_cmd("#{install_dir}/embedded/bin/ruby", *args))
+    #
+    # Delete the given file or directory on the system. This method uses the
+    # equivalent of +rm -rf+.
+    #
+    # @param [String] path
+    #   the path of the file to delete
+    # @param (see #mkdir)
+    #
+    # @return (see #command)
+    #
+    def delete(path, options = {})
+      build_commands << BuildCommand.new("delete `#{path}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.rm_rf(path, options)
+        end
+      end
     end
+    expose :delete
 
-    def gem(*args)
-      @build_commands << bundle_bust(*prepend_cmd("#{install_dir}/embedded/bin/gem", *args))
+    #
+    # Copy the given source to the destination.
+    #
+    # @param [String] source
+    #   the path on disk to copy from
+    # @param [String] destination
+    #   the path on disk to copy to
+    # @param (see #mkdir)
+    #
+    # @return (see #command)
+    #
+    def copy(source, destination, options = {})
+      build_commands << BuildCommand.new("copy `#{source}' to `#{destination}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.cp_r(source, destination, options)
+        end
+      end
     end
+    expose :copy
 
-    def bundle(*args)
-      @build_commands << bundle_bust(*prepend_cmd("#{install_dir}/embedded/bin/bundle", *args))
+    #
+    # Copy the given source to the destination.
+    #
+    # @param [String] source
+    #   the path on disk to move from
+    # @param [String] destination
+    #   the path on disk to move to
+    # @param (see #mkdir)
+    #
+    # @return (see #command)
+    #
+    def move(source, destination, options = {})
+      build_commands << BuildCommand.new("move `#{source}' to `#{destination}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.mv(source, destination, options)
+        end
+      end
     end
+    expose :move
 
-    def rake(*args)
-      @build_commands << bundle_bust(*prepend_cmd("#{install_dir}/embedded/bin/rake", *args))
+    #
+    # Link the given source to the destination.
+    #
+    # @param [String] source
+    #   the path on disk to link from
+    # @param [String] destination
+    #   the path on disk to link to
+    # @param (see #mkdir)
+    #
+    # @return (see #command)
+    #
+    def link(source, destination, options = {})
+      build_commands << BuildCommand.new("link `#{source}' to `#{destination}'") do
+        Dir.chdir(software.install_dir) do
+          FileUtils.ln_s(source, destination, options)
+        end
+      end
     end
+    expose :link
 
-    def block(&rb_block)
-      @build_commands << rb_block
-    end
+    #
+    # @!endgroup
+    # --------------------------------------------------
+
+    #
+    # @!group Deprecated DSL methods
+    #
+    # The following DSL methods are available from within build blocks, but are
+    # deprecated and will be removed in the next major release.
+    # --------------------------------------------------
 
     #
     # @deprecated Use {Config.project_root} instead
@@ -197,177 +472,250 @@ module Omnibus
 
       Config.project_root
     end
+    expose :project_root
 
-    def project_dir
-      @software.project_dir
-    end
+    #
+    # @!endgroup
+    # --------------------------------------------------
 
     #
-    # @deprecated Use {install_path} instead
+    # @!group Public API
     #
-    def install_path
-      log.deprecated(log_key) do
-        'install_path (DSL). Please use install_dir instead.'
-      end
-
-      install_dir
-    end
-
-    def install_dir
-      @software.install_dir
-    end
+    # The following methods are considered part of the public API for a
+    # builder. All DSL methods are also considered part of the public API.
+    # --------------------------------------------------
 
+    #
+    # Execute all the {BuildCommand} instances, in order, for this builder.
+    #
+    # @return [void]
+    #
     def build
-      log.info(log_key) { 'Starting...' }
+      log.info(log_key) { 'Starting build' }
 
-      if @software.overridden?
+      if software.overridden?
         log.info(log_key) do
-          "Version overridden from #{@software.default_version} to "\
-          "#{@software.version}"
+          "Version overridden from #{software.default_version} to "\
+          "#{software.version}"
         end
       end
 
-      time_it('Build') do
-        @build_commands.each do |cmd|
-          execute(cmd)
+      measure("Build #{software.name}") do
+        build_commands.each do |command|
+          execute(command)
         end
       end
-    end
 
-    def execute(cmd)
-      case cmd
-      when Proc
-        execute_proc(cmd)
-      else
-        execute_sh(cmd)
-      end
+      log.info(log_key) { 'Finished build' }
     end
 
-    def max_build_jobs
-      if Ohai['cpu'] && Ohai['cpu']['total'] && Ohai['cpu']['total'].to_s =~ /^\d+$/
-        Ohai['cpu']['total'].to_i + 1
-      else
-        3
+    #
+    # The shasum for this builder object. The shasum is calculated using the
+    # following:
+    #
+    #   - The descriptions of all {BuildCommand} objects
+    #   - The digest of all patch files on disk
+    #   - The digest of all erb files on disk
+    #
+    # @return [String]
+    #
+    def shasum
+      @shasum ||= begin
+        digest = Digest::SHA256.new
+
+        build_commands.each do |build_command|
+          update_with_string(digest, build_command.description)
+        end
+
+        patches.each do |patch_path|
+          update_with_file_contents(digest, patch_path)
+        end
+
+        erbs.each do |erb_path|
+          update_with_file_contents(digest, erb_path)
+        end
+
+        digest.hexdigest
       end
     end
 
+    #
+    # @!endgroup
+    # --------------------------------------------------
+
     private
 
-    def execute_proc(cmd)
-      cmd.call
-    rescue Exception => e
-      # In Ruby 1.9, Procs have a #source_location method with file/line info.
-      # Too bad we can't use it :(
-      ErrorReporter.new(e, self).explain("Failed to build #{name} while running ruby block build step")
-      raise
+    #
+    # The **in-order** list of {BuildCommand} for this builder.
+    #
+    # @return [Array<BuildCommand>]
+    #
+    def build_commands
+      @build_commands ||= []
     end
 
-    def execute_sh(cmd)
-      retries ||= 0
-      shell = nil
-      cmd_args = Array(cmd)
-      options = {
-        cwd: project_dir,
-        timeout: 5400,
-      }
-      options[:live_stream] = log.live_stream(:debug)
-      if cmd_args.last.is_a? Hash
-        cmd_options = cmd_args.last
-        cmd_args[cmd_args.size - 1] = options.merge(cmd_options)
-      else
-        cmd_args << options
-      end
+    #
+    # The list of paths to patch files on disk. This is used in the calculation
+    # of the shasum.
+    #
+    # @return [Array<String>]
+    #
+    def patches
+      @patches ||= []
+    end
 
-      cmd_string = cmd_args[0..-2].join(' ')
-      cmd_opts_for_display = to_kv_str(cmd_args.last)
+    #
+    # The list of paths to erb files on disk. This is used in the calculation
+    # of the shasum.
+    #
+    # @return [Array<String>]
+    #
+    def erbs
+      @erbs ||= []
+    end
 
-      log.info(log_key) do
-        "Executing: `#{cmd_string}` with #{cmd_opts_for_display}"
-      end
+    #
+    # This is a helper method that wraps {Util#shellout!} for the purposes of
+    # setting the +:cwd+ value.
+    #
+    # @see (Util#shellout!)
+    #
+    def _shellout!(command_string, options = {})
+      # Make sure the PWD is set to the correct directory
+      options = { cwd: software.project_dir }.merge(options)
 
-      shell = Mixlib::ShellOut.new(*cmd)
-      shell.environment['HOME'] = '/tmp' unless ENV['HOME']
+      # Use Util's shellout
+      shellout!(command_string, options)
+    end
 
-      cmd_name = cmd_string.split(/\s+/).first
-      time_it("#{cmd_name} command") do
-        shell.run_command
-        shell.error!
-      end
-    rescue Exception => e
-      raise if Config.build_retries.nil? || Config.build_retries == 0
-      # Getting lots of errors from github, particularly with erlang/rebar
-      # projects fetching tons of deps via git all the time. This isn't a
-      # particularly elegant way to solve that problem. But it should work.
-      if retries >= Config.build_retries
-        ErrorReporter.new(e, self).explain("Failed to build #{name} while running `#{cmd_string}` with #{cmd_opts_for_display}")
-        raise
-      else
-        time_to_sleep = 5 * (2**retries)
-        retries += 1
-        log.info(log_key) do
-          "Failed to execute cmd `#{cmd}` #{retries} time(s). " \
-          "Retrying in #{time_to_sleep}s."
+    #
+    # Execute the given command object. This method also wraps the following
+    # operations:
+    #
+    #   - Reset bundler's environment using +Bundler.with_clean_env+
+    #   - Instrument (time/measure) the individual command's execution
+    #   - Retry failed commands in accordance with {Config#build_retries}
+    #
+    # @param [BuildCommand] command
+    #   the command object to build
+    #
+    def execute(command)
+      Bundler.with_clean_env do
+        measure(command.description) do
+          with_retries do
+            command.run(self)
+          end
         end
-        sleep(time_to_sleep)
-        retry
       end
     end
 
-    def prepend_cmd(str, *cmd_args)
-      if cmd_args.size == 1
-        # command as a string, no opts
-        "#{str} #{cmd_args.first}"
-      elsif cmd_args.size == 2 && cmd_args.last.is_a?(Hash)
-        # command as a string w/ opts
-        ["#{str} #{cmd_args.first}", cmd_args.last]
-      elsif cmd_args.size == 0
-        raise ArgumentError, "I don't even"
-      else
-        # cmd given as argv array
-        cmd_args.dup.unshift(str)
+    #
+    # Execute the given block with (n) reties defined by {Config#build_retries}.
+    # This method will only retry for the following exceptions:
+    #
+    #   - +Mixlib::ShellOut::ShellCommandFailed+
+    #   - +Mixlib::ShellOut::CommandTimeout+
+    #
+    # @param [Proc] block
+    #   the block to execute
+    #
+    def with_retries(&block)
+      tries = Config.build_retries
+      delay = 5
+      exceptions = [
+        Mixlib::ShellOut::ShellCommandFailed,
+        Mixlib::ShellOut::CommandTimeout,
+      ]
+
+      begin
+        block.call
+      rescue *exceptions => e
+        if tries <= 0
+          raise e
+        else
+          delay = delay * 2
+
+          log.warn(log_key) do
+            label = "#{(Config.build_retries - tries) + 1}/#{Config.build_retries}"
+            "[#{label}] Failed to execute command. Retrying in #{delay} seconds..."
+          end
+
+          sleep(delay)
+          tries -= 1
+          retry
+        end
       end
     end
 
-    def bundle_bust(*cmd_args)
-      if cmd_args.last.is_a?(Hash)
-        cmd_args = cmd_args.dup
-        cmd_opts = cmd_args.pop.dup
-        cmd_opts[:env] = cmd_opts[:env] ? BUNDLER_BUSTER.merge(cmd_opts[:env]) : BUNDLER_BUSTER
-        cmd_args << cmd_opts
-      else
-        cmd_args << { env: BUNDLER_BUSTER }
+    #
+    # Find a file amonst all local files, "remote" local files, and
+    # {Config#software_gems}.
+    #
+    # @param [String] path
+    #   the path to find the file
+    # @param [String] source
+    #   the source name of the file to find
+    #
+    # @return [Array<Array<String>, String, nil>]
+    #   an array where the first entry is the list of candidate paths searched,
+    #   and the second entry is the first occurence of the matched file (or
+    #   +nil+) if one does not exist.
+    #
+    def find_file(path, source)
+      # Search for patches just like we search for software
+      candidate_paths = Omnibus.software_dirs.map do |directory|
+        full_path = directory.sub(Config.software_dir, path)
+        "#{full_path}/#{software.name}/#{source}"
       end
-    end
 
-    def time_it(what)
-      start = Time.now
-      yield
-    rescue Exception
-      elapsed = Time.now - start
-      log.warn(log_key) { "#{what} failed! (#{elapsed.to_f}s)" }
-      raise
-    else
-      elapsed = Time.now - start
-      log.info(log_key) { "#{what} succeeded! (#{elapsed.to_f}s)" }
-    end
+      file = candidate_paths.find { |path| File.exist?(path) }
 
-    # Convert a hash to a string in the form `key=value`. It should work with
-    # whatever input is given but is designed to make the options to ShellOut
-    # look nice.
-    def to_kv_str(hash, join_str = ',')
-      hash.reduce([]) do |kv_pair_strs, (k, v)|
-        val_str = case v
-                  when Hash
-                    %Q("#{to_kv_str(v, " ") }")
-                  else
-                    v.to_s
-                  end
-        kv_pair_strs << "#{k}=#{val_str}"
-      end.join(join_str)
+      [candidate_paths, file]
     end
 
+    #
+    # The log key for this class, overriden to incorporate the software name.
+    #
+    # @return [String]
+    #
     def log_key
-      @log_key ||= "#{super}: #{name}"
+      @log_key ||= "#{super}: #{software.name}"
+    end
+
+    #
+    # This is an internal wrapper around a command executed on the system. The
+    # block could contain a Ruby command (such as +FileUtils.rm_rf('/')+), or it
+    # could contain a call to shell out to the system.
+    #
+    class BuildCommand
+      attr_reader :description
+
+      #
+      # Create a new BuildCommand object.
+      #
+      # @param [String] description
+      #   a unique identifier for this build command - it will be used for
+      #   logging and timing labels
+      # @param [Proc] block
+      #   the block to capture
+      #
+      def initialize(description, &block)
+        @description, @block = description, block
+      end
+
+      #
+      # Execute the build command against the given object. Because BuildCommand
+      # objects could reference internal DSL methods, this method requires you
+      # pass in an object against which to +instance_eval+ the block. Otherwise,
+      # you would be severly restricted in the commands avaiable to you via the
+      # DSL.
+      #
+      # @param [Builder] builder
+      #   the builder to +instance_eval+ against
+      #
+      def run(builder)
+        builder.instance_eval(&@block)
+      end
     end
   end
 end