module Bundler::Plugin
This is the interfacing class represents the API that we intend to provide the plugins to use.
For plugins to be independent of the Bundler internals they shall limit their interactions to methods of this class only. This will save them from breaking when some internal change.
Currently we are delegating the methods defined in Bundler class to itself. So, this class acts as a buffer.
If there is some change in the Bundler class that is incompatible to its previous behavior or if otherwise desired, we can reimplement(or implement) the method to preserve compatibility.
To use this, either the class can inherit this class or use it directly. For example of both types of use, refer the file `spec/plugins/command.rb`
To use it without inheriting, you will have to create an object of this to use the functions (except for declaration functions like command, source, and hooks).
Manages which plugins are installed and their sources. This also is supposed to map which plugin does what (currently the features are not implemented so this class is now a stub class).
Handles the installation of plugin in appropriate directories.
This class is supposed to be wrapper over the existing gem installation infra but currently it itself handles everything as the Source's subclasses (e.g. Source::RubyGems) are heavily dependent on the Gemfile.
SourceList object to be used while parsing the Gemfile, setting the approptiate options to be used with Source classes for plugin installation
Constants
- PLUGIN_FILE_NAME
Public Instance Methods
To be called via the API to register to handle a command
# File lib/bundler/plugin.rb, line 107 def add_command(command, cls) @commands[command] = cls end
To be called via the API to register a hooks and corresponding block that will be called to handle the hook
# File lib/bundler/plugin.rb, line 156 def add_hook(event, &block) @hooks_by_event[event.to_s] << block end
To be called via the API to register to handle a source plugin
# File lib/bundler/plugin.rb, line 127 def add_source(source, cls) @sources[source] = cls end
# File lib/bundler/plugin.rb, line 271 def add_to_load_path(load_paths) if insert_index = Bundler.rubygems.load_path_insert_index $LOAD_PATH.insert(insert_index, *load_paths) else $LOAD_PATH.unshift(*load_paths) end end
The cache directory for plugin stuffs
# File lib/bundler/plugin.rb, line 102 def cache @cache ||= root.join("cache") end
Checks if any plugin handles the command
# File lib/bundler/plugin.rb, line 112 def command?(command) !index.command_plugin(command).nil? end
To be called from Cli class to pass the command and argument to approriate plugin class
# File lib/bundler/plugin.rb, line 118 def exec_command(command, args) raise UndefinedCommandError, "Command `#{command}` not found" unless command? command load_plugin index.command_plugin(command) unless @commands.key? command @commands[command].new.exec(command, args) end
Evaluates the Gemfile with a limited DSL and installs the plugins specified by plugin method
@param [Pathname] gemfile path @param [Proc] block that can be evaluated for (inline) Gemfile
# File lib/bundler/plugin.rb, line 53 def gemfile_install(gemfile = nil, &inline) builder = DSL.new if block_given? builder.instance_eval(&inline) else builder.eval_gemfile(gemfile) end definition = builder.to_definition(nil, true) return if definition.dependencies.empty? plugins = definition.dependencies.map(&:name).reject {|p| index.installed? p } installed_specs = Installer.new.install_definition(definition) save_plugins plugins, installed_specs, builder.inferred_plugins rescue => e unless e.is_a?(GemfileError) Bundler.ui.error "Failed to install plugin: #{e.message}\n #{e.backtrace[0]}" end raise end
The global directory root for all plugin related data
# File lib/bundler/plugin.rb, line 97 def global_root Bundler.user_bundle_path.join("plugin") end
Runs all the hooks that are registered for the passed event
It passes the passed arguments and block to the block registered with the api.
@param [String] event
# File lib/bundler/plugin.rb, line 166 def hook(event, *args, &arg_blk) return unless Bundler.feature_flag.plugins? plugins = index.hook_plugins(event) return unless plugins.any? (plugins - @loaded_plugin_names).each {|name| load_plugin(name) } @hooks_by_event[event].each {|blk| blk.call(*args, &arg_blk) } end
The index object used to store the details about the plugin
# File lib/bundler/plugin.rb, line 76 def index @index ||= Index.new end
Installs a new plugin by the given name
@param [Array<String>] names the name of plugin to be installed @param [Hash] options various parameters as described in description.
Refer to cli/plugin for available options
# File lib/bundler/plugin.rb, line 35 def install(names, options) specs = Installer.new.install(names, options) save_plugins names, specs rescue PluginError => e if specs specs_to_delete = Hash[specs.select {|k, _v| names.include?(k) && !index.commands.values.include?(k) }] specs_to_delete.values.each {|spec| Bundler.rm_rf(spec.full_gem_path) } end Bundler.ui.error "Failed to install plugin #{name}: #{e.message}\n #{e.backtrace.join("\n ")}" end
currently only intended for specs
@return [String, nil] installed path
# File lib/bundler/plugin.rb, line 180 def installed?(plugin) Index.new.installed?(plugin) end
Executes the plugins.rb file
@param [String] name of the plugin
# File lib/bundler/plugin.rb, line 255 def load_plugin(name) # Need to ensure before this that plugin root where the rest of gems # are installed to be on load path to support plugin deps. Currently not # done to avoid conflicts path = index.plugin_path(name) add_to_load_path(index.load_paths(name)) load path.join(PLUGIN_FILE_NAME) @loaded_plugin_names << name rescue => e Bundler.ui.error "Failed loading plugin #{name}: #{e.message}" raise end
# File lib/bundler/plugin.rb, line 92 def local_root Bundler.app_config_path.join("plugin") end
Runs the plugins.rb file in an isolated namespace, records the plugin actions it registers for and then passes the data to index to be stored.
@param [String] name the name of the plugin @param [Specification] spec of installed plugin @param [Boolean] optional_plugin, removed if there is conflict with any
other plugin (used for default source plugins)
@raise [MalformattedPlugin] if plugins.rb raises any error
# File lib/bundler/plugin.rb, line 219 def register_plugin(name, spec, optional_plugin = false) commands = @commands sources = @sources hooks = @hooks_by_event @commands = {} @sources = {} @hooks_by_event = Hash.new {|h, k| h[k] = [] } load_paths = spec.load_paths add_to_load_path(load_paths) path = Pathname.new spec.full_gem_path begin load path.join(PLUGIN_FILE_NAME), true rescue StandardError => e raise MalformattedPlugin, "#{e.class}: #{e.message}" end if optional_plugin && @sources.keys.any? {|s| source? s } Bundler.rm_rf(path) false else index.register_plugin(name, path.to_s, load_paths, @commands.keys, @sources.keys, @hooks_by_event.keys) true end ensure @commands = commands @sources = sources @hooks_by_event = hooks end
# File lib/bundler/plugin.rb, line 19 def reset! instance_variables.each {|i| remove_instance_variable(i) } @sources = {} @commands = {} @hooks_by_event = Hash.new {|h, k| h[k] = [] } @loaded_plugin_names = [] end
The directory root for all plugin related data
Points to root in app_config_path if ran in an app else points to the one in user_bundle_path
# File lib/bundler/plugin.rb, line 84 def root @root ||= if SharedHelpers.in_bundle? local_root else global_root end end
Post installation processing and registering with index
@param [Array<String>] plugins list to be installed @param [Hash] specs of plugins mapped to installation path (currently they
contain all the installed specs, including plugins)
@param [Array<String>] names of inferred source plugins that can be ignored
# File lib/bundler/plugin.rb, line 190 def save_plugins(plugins, specs, optional_plugins = []) plugins.each do |name| spec = specs[name] validate_plugin! Pathname.new(spec.full_gem_path) installed = register_plugin(name, spec, optional_plugins.include?(name)) Bundler.ui.info "Installed plugin #{name}" if installed end end
@return [Class] that handles the source. The calss includes API::Source
# File lib/bundler/plugin.rb, line 137 def source(name) raise UnknownSourceError, "Source #{name} not found" unless source? name load_plugin(index.source_plugin(name)) unless @sources.key? name @sources[name] end
Checks if any plugin declares the source
# File lib/bundler/plugin.rb, line 132 def source?(name) !index.source_plugin(name.to_s).nil? end
@param [Hash] The options that are present in the lock file @return [API::Source] the instance of the class that handles the source
type passed in locked_opts
# File lib/bundler/plugin.rb, line 148 def source_from_lock(locked_opts) src = source(locked_opts["type"]) src.new(locked_opts.merge("uri" => locked_opts["remote"])) end
Checks if the gem is good to be a plugin
At present it only checks whether it contains plugins.rb file
@param [Pathname] plugin_path the path plugin is installed at @raise [MalformattedPlugin] if plugins.rb file is not found
# File lib/bundler/plugin.rb, line 205 def validate_plugin!(plugin_path) plugin_file = plugin_path.join(PLUGIN_FILE_NAME) raise MalformattedPlugin, "#{PLUGIN_FILE_NAME} was not found in the plugin." unless plugin_file.file? end