omnibus 3.1.1 → 3.2.0.rc.1

data/lib/omnibus/software.rb

@@ -14,438 +14,815 @@
 # limitations under the License.
 #
 
-require 'digest/md5'
-require 'net/ftp'
-require 'net/http'
-require 'net/https'
-require 'uri'
-
 require 'fileutils'
+require 'uri'
 
 module Omnibus
   # Omnibus software DSL reader
   class Software
-    include Logging
-
-    NULL_ARG = Object.new
-    UNINITIALIZED = Object.new
-
-    # It appears that this is not used
-    attr_reader :builder
-
-    # @todo Why do we apparently use two different ways of
-    #   implementing what are effectively the same DSL methods?  Compare
-    #   with Omnibus::Project.
-    attr_reader :description
-
-    # @todo This doesn't appear to be used at all
-    attr_reader :fetcher
-
-    attr_reader :project
-
-    attr_reader :version
+    class << self
+      #
+      # @param [Project] project
+      #   the project that loaded this software definition
+      # @param [String] filepath
+      #   the path to the software definition to load from disk
+      # @param [hash] overrides
+      #   a list of software overrides
+      #
+      # @return [Software]
+      #
+      def load(project, filepath, overrides = {})
+        instance = new(project, overrides, filepath)
+        instance.evaluate_file(filepath)
+        instance
+      end
+    end
 
-    attr_reader :overrides
+    include Cleanroom
+    include Digestable
+    include Logging
+    include NullArgumentable
+    include Sugarable
 
-    attr_reader :whitelist_files
+    #
+    # Create a new software object.
+    #
+    # @param [String] NullBuilder.new(self)
+    # @param [Project] project
+    #   the Omnibus project that instantiated this software definition
+    # @param [Hash] repo_overrides
+    #   @see Omnibus::Overrides
+    # @param [String] filepath
+    #   the path to where this software definition lives on disk
+    #
+    # @return [Software]
+    #
+    def initialize(project, repo_overrides = {}, filepath = nil)
+      unless project.is_a?(Project)
+        raise ArgumentError,
+          "`project' must be a kind of `Omnibus::Project', but was `#{project.class.inspect}'!"
+      end
 
-    attr_reader :source_config
+      # Magical methods
+      @filepath = filepath
+      @project  = project
 
-    def self.load(filename, project, repo_overrides = {})
-      new(IO.read(filename), filename, project, repo_overrides)
+      # Overrides
+      @overrides      = NULL
+      @repo_overrides = repo_overrides
     end
 
-    # @param io [String]
-    # @param filename [String]
-    # @param project [???] Is this a string or an Omnibus::Project?
-    # @param repo_overrides [Hash]
     #
-    # @see Omnibus::Overrides
+    # The builder for this softare. This defaults to a {NullBuilder}, but
+    # can be specified using the {#build} DSL method.
     #
-    # @todo See comment on {Omnibus::NullBuilder}
-    # @todo does `filename` need to be absolute, or does it matter?
-    # @ @todo Any reason to not have this just take a filename,
-    #   project, and override hash directly?  That is, why io AND a
-    #   filename, if the filename can always get you the contents you
-    #   need anyway?
-    def initialize(io, filename, project, repo_overrides = {})
-      @version          = nil
-      @overrides        = UNINITIALIZED
-      @name             = nil
-      @description      = nil
-      @source           = nil
-      @relative_path    = nil
-      @source_uri       = nil
-      @source_config    = filename
-      @project          = project
-      @always_build     = false
-      @repo_overrides   = repo_overrides
-
-      # Seems like this should just be Builder.new(self) instead
-      @builder = NullBuilder.new(self)
-
-      @dependencies = []
-      @whitelist_files = []
-      instance_eval(io, filename)
+    # @return [Builder]
+    #
+    def builder
+      @builder ||= NullBuilder.new(self)
     end
 
+    #
+    # Compare two software projects (by name).
+    #
+    # @return [1, 0, -1]
+    #
     def <=>(other)
       self.name <=> other.name
     end
 
-    # Retrieves the override_version
+    #
+    # @!group DSL methods
+    #
+    # The following DSL methods are available from within software definitions.
+    # --------------------------------------------------
+
+    #
+    # The project that created this software.
+    #
+    # @return [Project]
+    #
+    def project
+      @project
+    end
+    expose :project
+
+    #
+    # Retrieves the overriden version.
+    #
+    # @deprecated Use {#version} or test with {#overridden?} instead.
     #
     # @return [Hash]
     #
-    # @todo: can't we just use #version here or are we testing this against nil? somewhere and
-    #        not using #overridden?
     def override_version
       log.deprecated(log_key) do
         'Software#override_version. Please use #version or ' \
-        'test  with #overridden?'
+        'test with #overridden?'
       end
 
       overrides[:version]
     end
+    expose :override_version
 
-    # Retrieves the repo-level and project-level overrides for the software.
     #
-    # @return [Hash]
-    def overrides
-      # deliberately not providing a setter since that feels like a shotgun pointed at a foot
-      if @overrides == UNINITIALIZED
-        # lazily initialized because we need the 'name' to be parsed first
-        @overrides = {}
-        @overrides = project.overrides[name.to_sym].dup if project.overrides[name.to_sym]
-        if @repo_overrides[name]
-          @overrides[:version] = @repo_overrides[name]
-        end
+    # **[Required]** Sets or retreives the name of the software.
+    #
+    # @example
+    #   name 'libxslt'
+    #
+    # @param [String] val
+    #   name of the Software
+    #
+    # @return [String]
+    #
+    def name(val = NULL)
+      if null?(val)
+        @name || raise(MissingSoftwareConfiguration.new(name, 'name', 'libxslt'))
+      else
+        @name = val
       end
-      @overrides
     end
+    expose :name
 
-    # Sets or retreives the name of the software
     #
-    # @param val [String] name of the Software
+    # Sets the description of the software.
+    #
+    # @example
+    #   description 'Installs libxslt'
+    #
+    # @param [String] val
+    #   the description of the software
+    #
     # @return [String]
-    def name(val = NULL_ARG)
-      @name = val unless val.equal?(NULL_ARG)
-      @name || raise(MissingSoftwareConfiguration.new(name, 'name', 'libxslt'))
-    end
-
-    # Sets the description of the software
     #
-    # @param val [String] description of the Software
-    # @return [void]
-    def description(val)
-      @description = val
+    def description(val = NULL)
+      if null?(val)
+        @description
+      else
+        @description = val
+      end
     end
+    expose :description
 
-    # Add an Omnibus software dependency.
     #
-    # @param val [String] the name of a Software dependency
-    # @return [void]
-    def dependency(val)
-      @dependencies << val
+    # Always build the given software definition.
+    #
+    # @param [true, false] val
+    #
+    # @return [true, false]
+    #
+    def always_build(val)
+      @always_build = val
+      @always_build
     end
+    expose :always_build
 
-    # Set or retrieve the list of software dependencies for this
-    # project.  As this is a DSL method, only pass the names of
-    # software components, not {Omnibus::Software} objects.
     #
-    # These is the software that comprises your project, and is
-    # distinct from runtime dependencies.
+    # Add a software dependency to this software.
+    #
+    # @example
+    #   dependency 'libxml2'
+    #   dependency 'libpng'
     #
-    # @note This will reinitialize the internal depdencies Array
-    #   and overwrite any dependencies that may have been set using
-    #   {#dependency}.
+    # @param [String] val
+    #   the name of a software dependency
     #
-    # @param val [Array<String>] a list of names of Software components
     # @return [Array<String>]
-    def dependencies(val = NULL_ARG)
-      @dependencies = val unless val.equal?(NULL_ARG)
-      @dependencies
-    end
-
-    # Set or retrieve the source for the software
+    #   the list of current dependencies
+    #
+    def dependency(val)
+      dependencies << val
+      dependencies.dup
+    end
+    expose :dependency
+
+    #
+    # Set or retrieve the source for the software.
+    #
+    # @raise [InvalidValue]
+    #   if the parameter is not a Hash
+    # @raise [InvalidValue]
+    #   if the hash includes extraneous keys
+    # @raise [InvalidValue]
+    #   if the hash declares keys that cannot work together
+    #   (like +:git+ and +:path+)
+    #
+    # @example
+    #   source url: 'http://ftp.gnu.org/gnu/autoconf/autoconf-2.68.tar.gz',
+    #          md5: 'c3b5247592ce694f7097873aa07d66fe'
+    #
+    # @param [Hash<Symbol, String>] val
+    #   a single key/pair that defines the kind of source and a path specifier
+    #
+    # @option val [String] :git (nil)
+    #   a git URL
+    # @option val [String] :url (nil)
+    #   general URL
+    # @option val [String] :path (nil)
+    #   a fully-qualified local file system path
+    # @option val [String] :md5 (nil)
+    #   the checksum of the downloaded artifact
+    # @option val [String] :cookie (nil)
+    #   a cookie to set
+    # @option val [String] :warning (nil)
+    #   a warning message to print when downloading
     #
-    # @param val [Hash<Symbol, String>] a single key/pair that defines
-    #   the kind of source and a path specifier
-    # @option val [String] :git (nil) a Git URL
-    # @option val [String] :url (nil) a general URL
-    # @option val [String] :path (nil) a fully-qualified local file system path
+    # @return [Hash]
     #
-    # @todo Consider changing this to accept two arguments instead
-    # @todo This should throw an error if an invalid key is given, or
-    #   if more than one pair is given
-    def source(val = NULL_ARG)
-      unless val.equal?(NULL_ARG)
+    def source(val = NULL)
+      unless null?(val)
+        unless val.is_a?(Hash)
+          raise InvalidValue.new(:source,
+            "be a kind of `Hash', but was `#{val.class.inspect}'")
+        end
+
+        extra_keys = val.keys - [:git, :path, :url, :md5, :cookie, :warning]
+        unless extra_keys.empty?
+          raise InvalidValue.new(:source,
+            "only include valid keys. Invalid keys: #{extra_keys.inspect}")
+        end
+
+        duplicate_keys = val.keys & [:git, :path, :url]
+        unless duplicate_keys.size < 2
+          raise InvalidValue.new(:source,
+            "not include duplicate keys. Duplicate keys: #{duplicate_keys.inspect}")
+        end
+
         @source ||= {}
         @source.merge!(val)
       end
+
       apply_overrides(:source)
     end
+    expose :source
 
-    # Retieve the default_version of the software
+    #
+    # Set or retieve the {#default_version} of the software to build.
+    #
+    # @example
+    #   default_version '1.2.3'
+    #
+    # @param [String] val
+    #   the default version to set for the software
     #
     # @return [String]
     #
-    # @todo: remove this in favor of default_version
-    def given_version
-      log.deprecated(log_key) do
-        'Software#given_version. Please use #default_version instead.'
+    def default_version(val = NULL)
+      if null?(val)
+        @version
+      else
+        @version = val
       end
-
-      default_version
     end
+    expose :default_version
 
-    # Set or retieve the default_version of the software to build
     #
-    # @param val [String]
-    # @return [String]
-    def default_version(val = NULL_ARG)
-      @version = val unless val.equal?(NULL_ARG)
-      @version
-    end
-
     # Evaluate a block only if the version matches.
     #
-    # Note that passing only a string without a block will set the default_version but this
-    # behavior is deprecated and will be removed, use the default_version method instead.
+    # @example
+    #   version '1.2.3' do
+    #     source path: '/local/path/to/software-1.2.3'
+    #   end
+    #
+    # @deprecated passing only a string without a block to set the version is
+    #   deprecated. Please use {#default_version} instead.
+    #
+    # @param [String] val
+    #   the version of the software
+    #
+    # @param [Proc] block
+    #   the block to run if the version we are building matches the argument
     #
-    # @param val [String] version of the software.
-    # @param block [Proc] block to run if the version we are building matches the argument.
-    # @return [void]
+    # @return [String, Proc]
     #
-    # @todo remove deprecated setting of version
-    def version(val = NULL_ARG)
+    def version(val = NULL)
       if block_given?
-        if val.equal?(NULL_ARG)
-          raise 'block needs a version argument to apply against'
+        if val.equal?(NULL)
+          raise InvalidValue.new(:version,
+            'pass a block when given a version argument')
         else
           if val == apply_overrides(:version)
             yield
           end
         end
       else
-        unless val.equal?(NULL_ARG)
+        unless val.equal?(NULL)
           log.deprecated(log_key) do
             'Software#version. Please use #default_version instead.'
           end
           @version = val
         end
       end
+
       apply_overrides(:version)
     end
+    expose :version
 
-    # Add an Omnibus software dependency.
     #
-    # @param file [String, Regexp] the name of a file to ignore in the healthcheck
-    # @return [void]
+    # Add a file to the healthcheck whitelist.
+    #
+    # @example
+    #   whitelist_file '/path/to/file'
+    #
+    # @param [String, Regexp] file
+    #   the name of a file to ignore in the healthcheck
+    #
+    # @return [Array<String>]
+    #   the list of currently whitelisted files
+    #
     def whitelist_file(file)
       file = Regexp.new(file) unless file.kind_of?(Regexp)
-      @whitelist_files << file
+      whitelist_files << file
+      whitelist_files.dup
     end
+    expose :whitelist_file
 
-    # Was this software version overridden externally, relative to the
-    # version declared within the software DSL file?
     #
-    # @return [Boolean]
-    def overridden?
-      # note: using instance variables to bypass accessors that enforce overrides
-      @overrides.key?(:version) && (@overrides[:version] != @version)
+    # The relative path inside the extracted tarball.
+    #
+    # @example
+    #   relative_path 'example-1.2.3'
+    #
+    # @param [String] relative_path
+    #   the relative path inside the tarball
+    #
+    # @return [String]
+    #
+    def relative_path(val = NULL)
+      if null?(val)
+        @relative_path ||= name
+      else
+        @relative_path = val
+      end
     end
+    expose :relative_path
 
-    # @todo see comments on {Omnibus::Fetcher#without_caching_for}
-    def version_guid
-      Fetcher.for(self).version_guid
+    #
+    # The path where the extracted software lives.
+    #
+    # @return [String]
+    #
+    def project_dir
+      @project_dir ||= File.join(Config.source_dir, relative_path)
     end
+    expose :project_dir
 
-    # @todo Define as a delegator
-    def build_version
-      @project.build_version
+    #
+    # The path where the software will be built.
+    #
+    # @return [String]
+    #
+    def build_dir
+      "#{Config.build_dir}/#{project.name}"
     end
+    expose :build_dir
 
-    # Returns the version to be used in cache.
-    def version_for_cache
-      if fetcher
-        fetcher.version_for_cache || version
-      else
-        version
-      end
+    #
+    # The directory where this software is installed on disk.
+    #
+    # @example
+    #   { 'PATH' => "#{install_dir}/embedded/bin:#{ENV["PATH"]}", }
+    #
+    # @return [String]
+    #
+    def install_dir
+      @project.install_dir
     end
+    expose :install_dir
 
-    # @todo Judging by existing usage, this should sensibly default to
-    #   the name of the software, since that's what it effectively does down in #project_dir
-    def relative_path(val)
-      @relative_path = val
-    end
+    #
+    # The path where this software is installed on disk.
+    #
+    # @deprecated Use {#install_dir} instead
+    #
+    # @return (see #install_dir)
+    #
+    def install_path
+      log.deprecated(log_key) do
+        'install_path (DSL). Please use install_dir instead.'
+      end
 
-    # @todo Code smell... this only has meaning if the software was
-    #   defined with a :uri, and this is only used in
-    #   {Omnibus::NetFetcher}.  This responsibility is distributed
-    #   across two classes, one of which is a specific interface
-    #   implementation
-    # @todo Why the caching of the URI?
-    def source_uri
-      @source_uri ||= URI(source[:url])
+      install_dir
     end
+    expose :install_path
 
-    # @param val [Boolean]
-    # @return void
     #
-    # @todo Doesn't necessarily need to be a Boolean if #always_build?
-    #   uses !! operator
-    def always_build(val)
-      @always_build = val
+    # Returns the platform of the machine on which Omnibus is running, as
+    # determined by Ohai.
+    #
+    # @deprecated Use +Ohai['platform']+ instead.
+    #
+    # @return [String]
+    #
+    def platform
+      log.deprecated(log_key) do
+        "Software#platform. Please use Ohai['platform'] instead."
+      end
+
+      Ohai['platform']
     end
+    expose :platform
 
-    # @return [Boolean]
-    def always_build?
-      return true if project.dirty_cache
-      # Should do !!(@always_build)
-      @always_build
+    #
+    # Return the architecture of the machine, as determined by Ohai.
+    #
+    # @deprecated Will not be replaced.
+    #
+    # @return [String]
+    #   Either "sparc" or "intel", as appropriate
+    #
+    def architecture
+      log.deprecated(log_key) do
+        "Software#architecture. Please use Ohai['kernel']['machine'] instead."
+      end
+
+      Ohai['kernel']['machine'] =~ /sun/ ? 'sparc' : 'intel'
     end
+    expose :architecture
 
-    # @todo Code smell... this only has meaning if the software was
-    #   defined with a :uri, and this is only used in
-    #   {Omnibus::NetFetcher}.  This responsibility is distributed
-    #   across two classes, one of which is a specific interface
-    #   implementation
-    def checksum
-      source[:md5]
+    #
+    # Define a series of {Builder} DSL commands that are required to build the
+    # software.
+    #
+    # @see Builder
+    #
+    # @param [Proc] block
+    #   a block of build commands
+    #
+    # @return [Builder]
+    #   the builder instance
+    #
+    # @todo Seems like this renders the setting of @builder in the initializer
+    #   moot
+    #
+    def build(&block)
+      @builder = Builder.new(self, &block)
+      @builder
     end
+    expose :build
 
-    # @todo Should this ever be legitimately used in the DSL?  It
-    #   seems that that facility shouldn't be provided, and thus this
-    #   should be made a private function (if it even really needs to
-    #   exist at all).
-    def config
-      Omnibus.config
+    #
+    # Add standard compiler flags to the environment hash to produce omnibus
+    # binaries (correct RPATH, etc).
+    #
+    # Supported options:
+    #    :aix => :use_gcc    force using gcc/g++ compilers on aix
+    #
+    # @params [Hash] env
+    # @params [Hash] opts
+    #
+    # @return [Hash]
+    #
+    def with_standard_compiler_flags(env = {}, opts = {})
+      env ||= {}
+      opts ||= {}
+      compiler_flags =
+        case Ohai['platform']
+        when "aix"
+          cc_flags =
+            if opts[:aix] && opts[:aix][:use_gcc]
+              {
+                "CC" => "gcc -maix64",
+                "CXX" => "g++ -maix64",
+                "CFLAGS" => "-maix64 -O -I#{install_dir}/embedded/include",
+                "LDFLAGS" => "-L#{install_dir}/embedded/lib -Wl,-blibpath:#{install_dir}/embedded/lib:/usr/lib:/lib",
+              }
+            else
+              {
+                "CC" => "xlc -q64",
+                "CXX" => "xlC -q64",
+                "CFLAGS" => "-q64 -I#{install_dir}/embedded/include -O",
+                "LDFLAGS" => "-q64 -L#{install_dir}/embedded/lib -Wl,-blibpath:#{install_dir}/embedded/lib:/usr/lib:/lib",
+              }
+            end
+          cc_flags.merge({
+            "LD" => "ld -b64",
+            "OBJECT_MODE" => "64",
+            "ARFLAGS" => "-X64 cru",
+          })
+        when "mac_os_x"
+          {
+            "LDFLAGS" => "-L#{install_dir}/embedded/lib",
+            "CFLAGS" => "-I#{install_dir}/embedded/include",
+          }
+        when "solaris2"
+          {
+            "LDFLAGS" => "-R#{install_dir}/embedded/lib -L#{install_dir}/embedded/lib -static-libgcc",
+            "CFLAGS" => "-I#{install_dir}/embedded/include",
+          }
+        else
+          {
+            "LDFLAGS" => "-Wl,-rpath,#{install_dir}/embedded/lib -L#{install_dir}/embedded/lib",
+            "CFLAGS" => "-I#{install_dir}/embedded/include",
+          }
+        end
+
+      # merge LD_RUN_PATH into the environment.  most unix distros will fall
+      # back to this if there is no LDFLAGS passed to the linker that sets
+      # the rpath.  the LDFLAGS -R or -Wl,-rpath will override this, but in
+      # some cases software may drop our LDFLAGS or think it knows better
+      # and edit them, and we *really* want the rpath setting and do know
+      # better.  in that case LD_RUN_PATH will probably survive whatever
+      # edits the configure script does
+      extra_linker_flags = {
+        "LD_RUN_PATH" => "#{install_dir}/embedded/lib"
+      }
+      # solaris linker can also use LD_OPTIONS, so we throw the kitchen sink against
+      # the linker, to find every way to make it use our rpath.
+      extra_linker_flags.merge!(
+        {
+          "LD_OPTIONS" => "-R#{install_dir}/embedded/lib"
+        }
+      ) if Ohai['platform'] == "solaris2"
+      env.merge(compiler_flags).
+        merge(extra_linker_flags).
+        # always want to favor pkg-config from embedded location to not hose
+        # configure scripts which try to be too clever and ignore our explicit
+        # CFLAGS and LDFLAGS in favor of pkg-config info
+        merge({"PKG_CONFIG_PATH" => "#{install_dir}/embedded/lib/pkgconfig"})
+    end
+    expose :with_standard_compiler_flags
+
+    #
+    # A PATH variable format string representing the current PATH with the
+    # project's embedded/bin directory prepended. The correct path separator
+    # for the platform is used to join the paths.
+    #
+    # @params [Hash] env
+    #
+    # @return [Hash]
+    #
+    def with_embedded_path(env = {})
+      path_value = prepend_path("#{install_dir}/bin", "#{install_dir}/embedded/bin")
+      env.merge(path_key => path_value)
     end
+    expose :with_embedded_path
 
-    # @!group Directory Accessors
+    #
+    # A PATH variable format string representing the current PATH with the
+    # given path prepended. The correct path separator
+    # for the platform is used to join the paths.
+    #
+    # @param [Array<String>] paths
+    #
+    # @return [String]
+    #
+    def prepend_path(*paths)
+      path_values = Array(paths)
+      path_values << ENV[path_key]
 
+      separator = File::PATH_SEPARATOR || ':'
+      path_values.join(separator)
+    end
+    expose :prepend_path
+
+    #
+    # The source directory.
+    #
+    # @deprecated Use {Config.source_dir} instead
+    #
+    # @return [String]
+    #
     def source_dir
-      config.source_dir
+      log.deprecated(log_key) do
+        'source_dir (DSL). Please use Config.source_dir instead.'
+      end
+
+      Config.source_dir
     end
+    expose :source_dir
 
+    #
+    # The cache directory.
+    #
+    # @deprecated Use {Config.cache_dir} instead
+    #
+    # @return [String]
+    #
     def cache_dir
-      config.cache_dir
+      log.deprecated(log_key) do
+        'cache_dir (DSL). Please use Config.cache_dir instead.'
+      end
+
+      Config.cache_dir
     end
+    expose :cache_dir
 
-    # The directory that the software will be built in
     #
-    # @return [String] an absolute filesystem path
-    def build_dir
-      "#{config.build_dir}/#{@project.name}"
-    end
+    # Convenience method for accessing the global Omnibus configuration object.
+    #
+    # @deprecated Use {Config} instead
+    #
+    # @return Config
+    #
+    # @see Config
+    #
+    def config
+      log.deprecated(log_key) do
+        'config (DSL). Please use Config.(thing) instead (capital C).'
+      end
 
-    # @todo Why the different name (i.e. *_dir instead of *_path, or
-    #   vice versa?)  Given the patterns that are being set up
-    #   elsewhere, this is just confusing inconsistency.
-    def install_dir
-      @project.install_path
+      Config
     end
+    expose :config
 
-    # @!endgroup
+    #
+    # The list of software dependencies for this software. These is the software
+    # that comprises your software, and is distinct from runtime dependencies.
+    #
+    # @deprecated Use {#dependency} instead (as a setter; the getter will stay)
+    #
+    # @todo Remove the "setter" part of this method and unexpose it as part of
+    # the DSL in the next major release
+    #
+    # @see #dependency
+    #
+    # @param [Array<String>]
+    #
+    # @return [Array<String>]
+    #
+    def dependencies(*args)
+      @dependencies ||= []
+
+      # Handle the case where an array or list of args were given
+      flattened_args = Array(args).flatten
 
-    # @todo It seems like this isn't used, and if it were, it should
-    # probably be part of Opscode::Builder instead
-    def max_build_jobs
-      if Ohai.cpu && Ohai.cpu[:total] && Ohai.cpu[:total].to_s =~ /^\d+$/
-        Ohai.cpu[:total].to_i + 1
+      if flattened_args.empty?
+        @dependencies
       else
-        3
+        log.deprecated(log_key) do
+          "dependencies (DSL). Please specify each dependency on its own " \
+          "line like `dependency '#{flattened_args.first}'`."
+        end
+
+        @dependencies = flattened_args
       end
     end
+    expose :dependencies
 
-    # @todo See comments for {#source_uri}... same applies here.  If
-    #   this is called in a non-source-software context, bad things will
-    #   happen.
-    def project_file
-      filename = source_uri.path.split('/').last
-      "#{cache_dir}/#{filename}"
+    #
+    # @!endgroup
+    # --------------------------------------------------
+
+    #
+    # @!group Public API
+    #
+    # In addition to the DSL methods, the following methods are considered to
+    # be the "public API" for a software.
+    # --------------------------------------------------
+
+    #
+    # Fetch the software definition using the appropriate fetcher. This may
+    # fetch the software from a local path location, git location, or download
+    # the software from a remote URL (HTTP(s)/FTP)
+    #
+    # @return [true, false]
+    #   true if the software was fetched, false if it was cached
+    #
+    def fetch
+      # Create the directories we need
+      [build_dir, Config.source_dir, Config.cache_dir, project_dir].each do |dir|
+        FileUtils.mkdir_p(dir)
+      end
+
+      if fetcher.fetch_required?
+        fetcher.fetch
+        true
+      else
+        false
+      end
     end
 
-    # @todo this would be simplified and clarified if @relative_path
-    #   defaulted to @name... see the @todo tag for #relative_path
-    # @todo Move this up with the other *_dir methods for better
-    #   logical grouping
-    def project_dir
-      @relative_path ? "#{source_dir}/#{@relative_path}" : "#{source_dir}/#{@name}"
+    #
+    # The list of files to ignore in the healthcheck.
+    #
+    # @return [Array<String>]
+    #
+    def whitelist_files
+      @whitelist_files ||= []
     end
 
-    # The name of the sentinel file that marks the most recent fetch
-    # time of the software
     #
-    # @return [String] an absolute path
+    # The path (on disk) where this software came from. Warning: this can be
+    # +nil+ if a software was dynamically created!
+    #
+    # @return [String, nil]
     #
-    # @see Omnibus::Fetcher
-    # @todo seems like this should be a private
-    #   method, since it's an implementation detail.
-    def fetch_file
-      "#{build_dir}/#{@name}.fetch"
+    def filepath
+      @filepath
     end
 
-    # @todo This is actually "snake case", not camel case
-    # @todo this should be a private method
-    def camel_case_path(project_path)
-      path = project_path.dup
-      # split the path and remmove and empty strings
-      if platform == 'windows'
-        path.sub!(':', '')
-        parts = path.split('\\') - ['']
-        parts.join('_')
-      else
-        parts = path.split('/') - ['']
-        parts.join('_')
+    #
+    # The repo-level and project-level overrides for the software.
+    #
+    # @return [Hash]
+    #
+    def overrides
+      if null?(@overrides)
+        # lazily initialized because we need the 'name' to be parsed first
+        @overrides = {}
+        @overrides = project.overrides[name.to_sym].dup if project.overrides[name.to_sym]
+        if @repo_overrides[name]
+          @overrides[:version] = @repo_overrides[name]
+        end
       end
+
+      @overrides
     end
 
-    # Define a series of {Omnibus::Builder} DSL commands that are
-    # required to successfully build the software.
     #
-    # @param block [block] a block of build commands
-    # @return void
+    # Determine if this software version overridden externally, relative to the
+    # version declared within the software DSL file?
     #
-    # @see Omnibus::Builder
+    # @return [true, false]
     #
-    # @todo Not quite sure the proper way to document a "block"
-    #   parameter in Yard
-    # @todo Seems like this renders the setting of @builder in the
-    #   initializer moot
-    # @todo Rename this to something like "build_commands", since it
-    #   doesn't actually do any building
-    def build(&block)
-      @builder = Builder.new(self, &block)
+    def overridden?
+      # NOTE: using instance variables to bypass accessors that enforce overrides
+      @overrides.key?(:version) && (@overrides[:version] != @version)
     end
 
-    # Returns the platform of the machine on which Omnibus is running,
-    # as determined by Ohai.
+    #
+    # @!endgroup
+    # --------------------------------------------------
+
+    #
+    # Retieve the {#default_version} of the software.
+    #
+    # @deprecated Use {#default_version} instead.
     #
     # @return [String]
-    def platform
-      Ohai.platform
+    #
+    def given_version
+      log.deprecated(log_key) do
+        'Software#given_version. Please use #default_version instead.'
+      end
+
+      default_version
     end
 
-    # Return the architecture of the machine, as determined by Ohai.
-    # @return [String] Either "sparc" or "intel", as appropriate
-    # @todo Is this used?  Doesn't appear to be...
-    def architecture
-      Ohai.kernel['machine'] =~ /sun/ ? 'sparc' : 'intel'
+    # @todo see comments on {Omnibus::Fetcher#without_caching_for}
+    def version_guid
+      Fetcher.for(self).version_guid
+    end
+
+    # Returns the version to be used in cache.
+    def version_for_cache
+      @version_for_cache ||= if fetcher.version_for_cache
+        fetcher.version_for_cache
+      elsif version
+        version
+      else
+        log.warn(log_key) do
+          "No version given! This is probably a bad thing. I am going to " \
+          "assume the version `0.0.0', but that is most certainly not your " \
+          "desired behavior. If git caching seems off, this is probably why."
+        end
+
+        '0.0.0'
+      end
+    end
+
+    # @todo Code smell... this only has meaning if the software was
+    #   defined with a :uri, and this is only used in
+    #   {Omnibus::NetFetcher}.  This responsibility is distributed
+    #   across two classes, one of which is a specific interface
+    #   implementation
+    # @todo Why the caching of the URI?
+    def source_uri
+      @source_uri ||= URI(source[:url])
+    end
+
+    # @todo Code smell... this only has meaning if the software was
+    #   defined with a :uri, and this is only used in
+    #   {Omnibus::NetFetcher}.  This responsibility is distributed
+    #   across two classes, one of which is a specific interface
+    #   implementation
+    def checksum
+      source[:md5]
+    end
+
+    # @todo See comments for {#source_uri}... same applies here.  If
+    #   this is called in a non-source-software context, bad things will
+    #   happen.
+    def project_file
+      filename = source_uri.path.split('/').last
+      "#{Config.cache_dir}/#{filename}"
+    end
+
+    # The fetcher for this software.
+    #
+    # @return [Fetcher]
+    def fetcher
+      @fetcher ||= Fetcher.for(self)
     end
 
     # Actually build the software package
     def build_me
-      # Fetch the source
-      @fetcher = fetch_me
-
       # Build if we need to
       if always_build?
         execute_build(fetcher)
       else
-        if Omnibus::InstallPathCache.new(install_dir, self).restore
+        if GitCache.new(self).restore
           true
         else
           execute_build(fetcher)
@@ -456,50 +833,103 @@ module Omnibus
       true
     end
 
-    # Fetch the software
-    def fetch_me
-      # Create the directories we need
-      [build_dir, source_dir, cache_dir, project_dir].each do |dir|
-        FileUtils.mkdir_p dir
-      end
-
-      fetcher = Fetcher.for(self)
-
-      if !File.exist?(fetch_file) || fetcher.fetch_required?
-        # force build to run if we need to do an updated fetch
-        fetcher.fetch
-        touch fetch_file
-      end
-
-      fetcher
+    #
+    # The unique "hash" for this software.
+    #
+    # @see (#shasum)
+    #
+    # @return [Fixnum]
+    #
+    def hash
+      shasum.hash
     end
 
-    # A PATH variable format string representing the current PATH with the
-    # project's embedded/bin directory prepended. The correct path separator
-    # for the platform is used to join the paths.
     #
-    # @return [String]
-    def path_with_embedded
-      prepend_path("#{install_dir}/bin", "#{install_dir}/embedded/bin")
+    # Determine if two softwares are identical.
+    #
+    # @param [Software] other
+    #
+    # @return [true, false]
+    #
+    def ==(other)
+      self.hash == other.hash
     end
+    alias_method :eql?, :==
 
-    # A PATH variable format string representing the current PATH with the
-    # given path prepended. The correct path separator
-    # for the platform is used to join the paths.
     #
-    # @param paths [String]
-    # @param paths [Array<String>]
+    # The unique SHA256 for this sofware definition.
+    #
+    # A software is defined by its parent project's shasum, its own name, its
+    # version_for_cache, and any overrides (as JSON). Additionally, if provided,
+    # the actual file contents are included in the SHA to ensure uniqueness.
+    #
     # @return [String]
-    def prepend_path(*paths)
-      path_values = Array(paths)
-      path_values << ENV['PATH']
+    #
+    def shasum
+      @shasum ||= begin
+        digest = Digest::SHA256.new
 
-      separator = File::PATH_SEPARATOR || ':'
-      path_values.join(separator)
+        log.debug(log_key) { "project (SHA): #{project.shasum.inspect}" }
+        log.debug(log_key) { "name: #{name.inspect}" }
+        log.debug(log_key) { "version_for_cache: #{version_for_cache.inspect}" }
+        log.debug(log_key) { "overrides: #{overrides.inspect}" }
+
+        update_with_string(digest, project.shasum)
+        update_with_string(digest, name)
+        update_with_string(digest, version_for_cache)
+        update_with_string(digest, JSON.fast_generate(overrides))
+
+        if filepath && File.exist?(filepath)
+          log.debug(log_key) { "filepath: #{filepath.inspect}" }
+          update_with_file_contents(digest, filepath)
+        else
+          log.debug(log_key) { "filepath: <DYNAMIC>" }
+          update_with_string(digest, '<DYNAMIC>')
+        end
+
+        shasum = digest.hexdigest
+
+        log.debug(log_key) { "shasum: #{shasum.inspect}" }
+
+        shasum
+      end
     end
 
     private
 
+    #
+    # Determine if this software should always be built. A software should
+    # always be built if git caching is disabled ({Config#use_git_caching}) or
+    # if the parent project has dirtied the cache.
+    #
+    # @return [true, false]
+    #
+    def always_build?
+      unless Config.use_git_caching
+        return true
+      end
+
+      if project.dirty?
+        return true
+      end
+
+      !!@always_build
+    end
+
+    #
+    # The proper platform-specific "$PATH" key.
+    #
+    # @return [String]
+    #
+    def path_key
+      # The ruby devkit needs ENV['Path'] set instead of ENV['PATH'] because
+      # $WINDOWSRAGE, and if you don't set that your native gem compiles
+      # will fail because the magic fixup it does to add the mingw compiler
+      # stuff won't work.
+      Ohai['platform'] == 'windows' ? 'Path' : 'PATH'
+    end
+
+    #
     # Apply overrides in the @overrides hash that mask instance variables
     # that are set by parsing the DSL
     #
@@ -526,16 +956,14 @@ module Omnibus
     def execute_build(fetcher)
       fetcher.clean
       @builder.build
-      log.info(log_key) { 'Caching build' }
-      Omnibus::InstallPathCache.new(install_dir, self).incremental
-      log.info(log_key) { 'Dirtied the cache!' }
-      project.dirty_cache = true
-    end
 
-    def touch(file)
-      File.open(file, 'w') do |f|
-        f.print ''
+      if Config.use_git_caching
+        log.info(log_key) { 'Caching build' }
+        GitCache.new(self).incremental
+        log.info(log_key) { 'Dirtied the cache!' }
       end
+
+      project.dirty!
     end
 
     def log_key