module Bundler::Plugin::API::Source

This shall check if two source object represent the same source.

The comparison shall take place only on the attribute that can be inferred from the options passed from Gemfile and not on attributes that are used to pin down the gem to specific version (e.g. Git sources should compare on branch and tag but not on commit hash)

The sources objects are constructed from Gemfile as well as from lockfile. To converge the sources, it is necessary that they match.

The same applies for ‘eql?` and `hash`

# File bundler/plugin/api/source.rb, line 213
def ==(other)
  other.is_a?(self.class) && uri == other.uri
end

Used by definition.

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 258
def add_dependency_names(names)
  @dependencies |= Array(names)
end

Name of directory where plugin the is expected to cache the gems when cache is called.

Also this name is matched against the directories in cache for pruning

This is used by ‘app_cache_path`

# File bundler/plugin/api/source.rb, line 178
def app_cache_dirname
  base_name = File.basename(Gem::URI.parse(uri).normalize.path)
  "#{base_name}-#{uri_hash}"
end

The full path where the plugin should cache the gem so that it can be installed latter.

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 237
def app_cache_path(custom_path = nil)
  @app_cache_path ||= Bundler.app_cache(custom_path).join(app_cache_dirname)
end

This method is called while caching to save copy of the gems that the source can resolve to path provided by ‘app_cache_app`so that they can be reinstalled from the cache without querying the remote (i.e. an alternative to remote)

This is stored with the app and source plugins should try to provide specs and install only from this cache when ‘cached!` is called.

This cache is different from the internal caching that can be done at sub paths of ‘cache_path` (from API). This can be though as caching by bundler.

# File bundler/plugin/api/source.rb, line 194
def cache(spec, custom_path = nil)
  new_cache_path = app_cache_path(custom_path)

  FileUtils.rm_rf(new_cache_path)
  FileUtils.cp_r(install_path, new_cache_path)
  FileUtils.touch(app_cache_path.join(".bundlecache"))
end

Set internal representation to fetch the gems/specs from app cache.

When this is called, the source should try to fetch the specs and install from the path provided by ‘app_cache_path`.

# File bundler/plugin/api/source.rb, line 162
def cached!
end

NOTE: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 263
def can_lock?(spec)
  spec.source == self
end

@private This API on source might not be stable, and for now we expect plugins to download all specs in ‘#specs`, so we implement the method for compatibility purposes and leave it undocumented (and don’t support) overriding it)

# File bundler/plugin/api/source.rb, line 317
def double_check_for(*); end

This is used by the default ‘spec` method to constructs the Specification objects for the gems and versions that can be installed by this source plugin.

Note: If the spec method is overridden, this function is not necessary

@return [Array<String>] paths of the gemspec files for gems that can

be installed

# File bundler/plugin/api/source.rb, line 62
def fetch_gemspec_files
  []
end

NOTE: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 299
def gem_install_dir
  Bundler.install_path
end

When overriding ‘hash` please preserve the behaviour as mentioned in docstring for `==` method, i.e. two methods equal by above comparison should have same hash.

# File bundler/plugin/api/source.rb, line 224
def hash
  [self.class, uri].hash
end

NOTE: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 290
def include?(other)
  other == self
end

Install the gem specified by the spec at appropriate path. ‘install_path` provides a sufficient default, if the source can only satisfy one gem, but is not binding.

@return [String] post installation message (if any)

# File bundler/plugin/api/source.rb, line 82
def install(spec, opts)
  raise MalformattedPlugin, "Source plugins need to override the install method."
end

A default installation path to install a single gem. If the source servers multiple gems, it’s not of much use and the source should one of its own.

# File bundler/plugin/api/source.rb, line 107
def install_path
  @install_path ||=
    begin
      base_name = File.basename(Gem::URI.parse(uri).normalize.path)

      gem_install_dir.join("#{base_name}-#{uri_hash[0..11]}")
    end
end

A helper method, not necessary if not used internally.

# File bundler/plugin/api/source.rb, line 229
def installed?
  File.directory?(install_path)
end

Set internal representation to fetch the gems/specs locally.

When this is called, the source should try to fetch the specs and install from the local system.

# File bundler/plugin/api/source.rb, line 148
def local!
end

Options to be saved in the lockfile so that the source plugin is able to check out same version of gem later.

There options are passed when the source plugin is created from the lock file.

@return [Hash]

# File bundler/plugin/api/source.rb, line 73
def options_to_lock
  {}
end

It builds extensions, generates bins and installs them for the spec provided.

It depends on ‘spec.loaded_from` to get full_gem_path. The source plugins should set that.

It should be called in ‘install` after the plugin is done placing the gem at correct install location.

It also runs Gem hooks ‘pre_install`, `post_build` and `post_install`

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 98
def post_install(spec, disable_exts = false)
  opts = { env_shebang: false, disable_extensions: disable_exts }
  installer = Bundler::Source::Path::Installer.new(spec, opts)
  installer.post_install
end

Set internal representation to fetch the gems/specs from remote.

When this is called, the source should try to fetch the specs and install from remote path.

# File bundler/plugin/api/source.rb, line 155
def remote!
end

It is used to obtain the full_gem_path.

spec’s loaded_from path is expanded against this to get full_gem_path

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 308
def root
  Bundler.root
end

Used by definition.

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 251
def spec_names
  specs.spec_names
end

Parses the gemspec files to find the specs for the gems that can be satisfied by the source.

Few important points to keep in mind:

- If the gems are not installed then it shall return specs for all
the gems it can satisfy
- If gem is installed (that is to be detected by the plugin itself)
then it shall return at least the specs that are installed.
- The `loaded_from` for each of the specs shall be correct (it is
used to find the load path)

@return [Bundler::Index] index containing the specs

# File bundler/plugin/api/source.rb, line 128
def specs
  files = fetch_gemspec_files

  Bundler::Index.build do |index|
    files.each do |file|
      next unless spec = Bundler.load_gemspec(file)
      Bundler.rubygems.set_installed_by_version(spec)

      spec.source = self
      Bundler.rubygems.validate(spec)

      index << spec
    end
  end
end

Generates the content to be entered into the lockfile. Saves type and remote and also calls to ‘options_to_lock`.

Plugin should use ‘options_to_lock` to save information in lockfile and not override this.

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 274
def to_lock
  out = String.new("#{LockfileParser::PLUGIN}\n")
  out << "  remote: #{@uri}\n"
  out << "  type: #{@type}\n"
  options_to_lock.each do |opt, value|
    out << "  #{opt}: #{value}\n"
  end
  out << "  specs:\n"
end

This is called to update the spec and installation.

If the source plugin is loaded from lockfile or otherwise, it shall refresh the cache/specs (e.g. git sources can make a fresh clone).

# File bundler/plugin/api/source.rb, line 169
def unlock!
end

Used by definition.

Note: Do not override if you don’t know what you are doing.

# File bundler/plugin/api/source.rb, line 244
def unmet_deps
  specs.unmet_dependency_names
end