Class: Homebrew::Bundle::Extension Abstract Private

Inherits:
PackageType show all
Extended by:
T::Helpers, Utils::Output::Mixin
Defined in:
bundle/extensions/extension.rb

Overview

This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.

This class is abstract.

It cannot be directly instantiated. Subclasses must implement the abstract methods below.

Direct Known Subclasses

Cargo, Flatpak, Go, Krew, MacAppStore, Npm, Uv, VscodeExtension, Winget

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils::Output::Mixin

issue_reporting_message, odebug, odeprecated, odie, odisabled, ofail, oh1, oh1_title, ohai, ohai_title, onoe, opoo, opoo_once, opoo_outside_github_actions, opoo_without_github_actions_annotation, pretty_cannot_install, pretty_deprecated, pretty_disabled, pretty_duration, pretty_install_status, pretty_installed, pretty_removed, pretty_uninstalled, pretty_unmarked, pretty_upgradable, pretty_warning

Methods inherited from PackageType

batch_installable?, check_label, #checkable_entries, #exit_early_check, #find_actionable, #format_checkable, #full_check, install_batch!, type

Class Method Details

.add_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


140
141
142
 
# File 'bundle/extensions/extension.rb', line 140

def self.add_supported?
  true
end

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method is abstract.

Returns:



35
 
# File 'bundle/extensions/extension.rb', line 35

def self.banner_name; end

.check(entries, exit_on_first_error: false, no_upgrade: false, verbose: false) ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • entries (Array<Dsl::Entry>)
  • exit_on_first_error (Boolean) (defaults to: false)
  • no_upgrade (Boolean) (defaults to: false)
  • verbose (Boolean) (defaults to: false)

Returns:



224
225
226
 
# File 'bundle/extensions/extension.rb', line 224

def self.check(entries, exit_on_first_error: false, no_upgrade: false, verbose: false)
  new.find_actionable(entries, exit_on_first_error:, no_upgrade:, verbose:)
end

.cleanup!(items) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'bundle/extensions/extension.rb', line 253

def self.cleanup!(items)
  executable = package_manager_executable
  if executable.nil?
    ofail "Failed to uninstall #{banner_name}: executable not found" unless items.empty?
    return
  end

  successes = with_env(package_manager_env(executable)) do
    items.count do |item|
      success = uninstall_package!(item, executable:)
      ofail "Failed to uninstall #{banner_name}: #{cleanup_item_name(item)}" unless success
      success
    end
  end
  puts "Uninstalled #{Utils.pluralize(package_description, successes, include_count: true)}"
end

.cleanup_disable_description ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



125
126
127
 
# File 'bundle/extensions/extension.rb', line 125

def self.cleanup_disable_description
  "`cleanup` without #{banner_name}."
end

.cleanup_disable_env ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



115
116
117
 
# File 'bundle/extensions/extension.rb', line 115

def self.cleanup_disable_env
  :"bundle_cleanup_no_#{type}"
end

.cleanup_heading ⇒ String?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



160
161
162
 
# File 'bundle/extensions/extension.rb', line 160

def self.cleanup_heading
  nil
end

.cleanup_item_name(item) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



243
244
245
 
# File 'bundle/extensions/extension.rb', line 243

def self.cleanup_item_name(item)
  item
end

.cleanup_items(entries) ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'bundle/extensions/extension.rb', line 229

def self.cleanup_items(entries)
  return [].freeze unless package_manager_installed?

  kept_packages = entries.filter_map do |entry|
    entry.name if entry.type == type
  end

  return [].freeze if kept_packages.empty?

  installed_names = packages.map { |pkg| dump_name(pkg) }
  installed_names - kept_packages
end

.cleanup_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


165
166
167
 
# File 'bundle/extensions/extension.rb', line 165

def self.cleanup_supported?
  !cleanup_heading.nil?
end

.disable_predicate_method ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



135
136
137
 
# File 'bundle/extensions/extension.rb', line 135

def self.disable_predicate_method
  :"no_#{type}?"
end

.dump ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



204
205
206
 
# File 'bundle/extensions/extension.rb', line 204

def self.dump
  packages.map { |package| dump_entry(package) }.join("\n")
end

.dump_disable_description ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



105
106
107
 
# File 'bundle/extensions/extension.rb', line 105

def self.dump_disable_description
  "`dump` without #{banner_name}."
end

.dump_disable_env ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



110
111
112
 
# File 'bundle/extensions/extension.rb', line 110

def self.dump_disable_env
  :"bundle_dump_no_#{type}"
end

.dump_disable_predicate_method ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



130
131
132
 
# File 'bundle/extensions/extension.rb', line 130

def self.dump_disable_predicate_method
  disable_predicate_method
end

.dump_disable_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


120
121
122
 
# File 'bundle/extensions/extension.rb', line 120

def self.dump_disable_supported?
  true
end

.dump_entry(package) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



179
180
181
182
183
184
185
186
 
# File 'bundle/extensions/extension.rb', line 179

def self.dump_entry(package)
  line = "#{type} #{quote(dump_name(package))}"
  with = dump_with(package)
  return line if with.blank?

  formatted_with = with.map { |requirement| quote(requirement) }.join(", ")
  "#{line}, with: [#{formatted_with}]"
end

.dump_name(package) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



194
195
196
 
# File 'bundle/extensions/extension.rb', line 194

def self.dump_name(package)
  package.to_s
end

.dump_output(describe: false, no_restart: false) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • describe (Boolean) (defaults to: false)
  • no_restart (Boolean) (defaults to: false)

Returns:



209
210
211
212
213
214
 
# File 'bundle/extensions/extension.rb', line 209

def self.dump_output(describe: false, no_restart: false)
  _ = describe
  _ = no_restart

  dump
end

.dump_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


100
101
102
 
# File 'bundle/extensions/extension.rb', line 100

def self.dump_supported?
  true
end

.dump_with(_package) ⇒ Array<String>?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



199
200
201
 
# File 'bundle/extensions/extension.rb', line 199

def self.dump_with(_package)
  nil
end

.ensure_package_manager_installed!(name, verbose: false) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:

  • name (String)
  • verbose (Boolean) (defaults to: false) 


318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'bundle/extensions/extension.rb', line 318

def self.ensure_package_manager_installed!(name, verbose: false)
  return if package_manager_installed?

  puts "Installing #{package_manager_name}. It is not currently installed." if verbose
  Bundle.system(HOMEBREW_BREW_FILE, "install", "--formula", package_manager_name, verbose:)
  # `formula_versions_from_env` consumes the env vars once at startup, so
  # keep the cached values across reset when bootstrapping a manager.
  formula_versions_from_env = T.let(
    Bundle.formula_versions_from_env_cache,
    T.nilable(T::Hash[String, String]),
  )
  upgrade_formulae = Bundle.upgrade_formulae
  Bundle.reset!
  Bundle.formula_versions_from_env_cache = formula_versions_from_env
  Bundle.upgrade_formulae = upgrade_formulae.join(",")
  reset!
  return if package_manager_installed?

  raise "Unable to install #{name} #{package_description}. " \
        "#{package_manager_name} installation failed."
end

.entry(name, options = {}) ⇒ Dsl::Entry

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



43
44
45
46
47
 
# File 'bundle/extensions/extension.rb', line 43

def self.entry(name, options = {})
  raise "unknown options(#{options.keys.inspect}) for #{type}" if options.present?

  Dsl::Entry.new(type, name)
end

.flag ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



50
51
52
 
# File 'bundle/extensions/extension.rb', line 50

def self.flag
  type.to_s.tr("_", "-")
end

.inherited(subclass) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



17
18
19
20
 
# File 'bundle/extensions/extension.rb', line 17

def self.inherited(subclass)
  super
  Homebrew::Bundle.register_extension(T.cast(subclass, T.class_of(Homebrew::Bundle::Extension)))
end

.install!(name, with: nil, preinstall: true, no_upgrade: false, verbose: false, force: false, **_options) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • name (String)
  • with (Array<String>, nil) (defaults to: nil)
  • preinstall (Boolean) (defaults to: true)
  • no_upgrade (Boolean) (defaults to: false)
  • verbose (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • _options (Homebrew::Bundle::EntryOption)

Returns:

  • (Boolean) 


351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'bundle/extensions/extension.rb', line 351

def self.install!(name, with: nil, preinstall: true, no_upgrade: false, verbose: false, force: false,
                  **_options)
  _ = no_upgrade
  _ = force

  return true unless preinstall

  puts "Installing #{name} #{package_description}." if verbose
  return false unless install_package!(name, with:, verbose:)

  package = package_record(name, with:)
  installed_packages << package unless installed_packages.include?(package)
  packages << package unless packages.include?(package)
  true
end

.install_package!(name, with: nil, verbose: false) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • name (String)
  • with (Array<String>, nil) (defaults to: nil)
  • verbose (Boolean) (defaults to: false)

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


387
388
389
390
391
392
393
 
# File 'bundle/extensions/extension.rb', line 387

def self.install_package!(name, with: nil, verbose: false)
  _ = name
  _ = with
  _ = verbose

  raise NotImplementedError, "#{self} must override `install_package!` or `install!`."
end

.install_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


150
151
152
 
# File 'bundle/extensions/extension.rb', line 150

def self.install_supported?
  true
end

.install_verb(_name = "", _options = {}) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



155
156
157
 
# File 'bundle/extensions/extension.rb', line 155

def self.install_verb(_name = "", _options = {})
  "Installing"
end

.installed_packages ⇒ Array<T.untyped>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method is abstract.

Returns:



176
 
# File 'bundle/extensions/extension.rb', line 176

def self.installed_packages; end

.legacy_check_step ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



248
249
250
 
# File 'bundle/extensions/extension.rb', line 248

def self.legacy_check_step
  :registered_extensions_to_install
end

.package_description ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



95
96
97
 
# File 'bundle/extensions/extension.rb', line 95

def self.package_description
  check_label.downcase
end

.package_installed?(name, with: nil) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


291
292
293
 
# File 'bundle/extensions/extension.rb', line 291

def self.package_installed?(name, with: nil)
  installed_packages.include?(package_record(name, with:))
end

.package_manager_env(_executable) ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



80
81
82
 
# File 'bundle/extensions/extension.rb', line 80

def self.package_manager_env(_executable)
  {}
end

.package_manager_executable ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



70
71
72
 
# File 'bundle/extensions/extension.rb', line 70

def self.package_manager_executable
  which(package_manager_name, ORIGINAL_PATHS)
end

.package_manager_executable! ⇒ Pathname

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



75
76
77
 
# File 'bundle/extensions/extension.rb', line 75

def self.package_manager_executable!
  package_manager_executable || raise("#{package_manager_name} is not installed")
end

.package_manager_installed? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


65
66
67
 
# File 'bundle/extensions/extension.rb', line 65

def self.package_manager_installed?
  package_manager_executable.present?
end

.package_manager_name ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



60
61
62
 
# File 'bundle/extensions/extension.rb', line 60

def self.package_manager_name
  flag
end

.package_outdated?(_name, with: nil, source: nil) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Whether an installed package has an available upgrade.

Parameters:

Returns:

  • (Boolean) 


279
280
281
 
# File 'bundle/extensions/extension.rb', line 279

def self.package_outdated?(_name, with: nil, source: nil)
  false
end

.package_record(name, with: nil) ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



284
285
286
287
288
 
# File 'bundle/extensions/extension.rb', line 284

def self.package_record(name, with: nil)
  _ = with

  name
end

.packages ⇒ Array<T.untyped>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method is abstract.

Returns:



173
 
# File 'bundle/extensions/extension.rb', line 173

def self.packages; end

.predicate_method ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



55
56
57
 
# File 'bundle/extensions/extension.rb', line 55

def self.predicate_method
  :"#{type}?"
end

.preinstall!(name, with: nil, no_upgrade: false, verbose: false, **_options) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'bundle/extensions/extension.rb', line 304

def self.preinstall!(name, with: nil, no_upgrade: false, verbose: false, **_options)
  ensure_package_manager_installed!(name, verbose:)

  if package_installed?(name, with:)
    return true if !no_upgrade && package_outdated?(name, with:)

    puts "Skipping install of #{name} #{package_description}. It is already installed." if verbose
    return false
  end

  true
end

.quote(value) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



189
190
191
 
# File 'bundle/extensions/extension.rb', line 189

def self.quote(value)
  value.inspect
end

.remove_supported? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


145
146
147
 
# File 'bundle/extensions/extension.rb', line 145

def self.remove_supported?
  true
end

.reset! ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method is abstract.

This method returns an undefined value.



170
 
# File 'bundle/extensions/extension.rb', line 170

def self.reset!; end

.switch_description(description) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



38
39
40
 
# File 'bundle/extensions/extension.rb', line 38

def self.switch_description(description)
  description
end

.uninstall_package!(name, executable: Pathname.new("")) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


271
272
273
 
# File 'bundle/extensions/extension.rb', line 271

def self.uninstall_package!(name, executable: Pathname.new(""))
  raise NotImplementedError, "#{self} must override `uninstall_package!` or `cleanup!`."
end

.with_package_manager_env(&_blk) ⇒ T.type_parameter(:U)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • _blk (T.proc.params(executable: Pathname).returns(T.type_parameter(:U)))

Returns:

  • (T.type_parameter(:U)) 


89
90
91
92
 
# File 'bundle/extensions/extension.rb', line 89

def self.with_package_manager_env(&_blk)
  executable = package_manager_executable!
  with_env(package_manager_env(executable)) { yield executable }
end

Instance Method Details

#failure_reason(package, no_upgrade:) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • package (Object)
  • no_upgrade (Boolean)

Returns:



368
369
370
371
 
# File 'bundle/extensions/extension.rb', line 368

def failure_reason(package, no_upgrade:)
  "#{self.class.check_label} #{self.class.dump_name(package)} needs to be " \
    "#{(!no_upgrade && installed_and_up_to_date?(package, no_upgrade: true)) ? "upgraded" : "installed"}."
end

#installed_and_up_to_date?(package, no_upgrade: false) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • package (Object)
  • no_upgrade (Boolean) (defaults to: false)

Returns:

  • (Boolean) 


374
375
376
377
378
 
# File 'bundle/extensions/extension.rb', line 374

def installed_and_up_to_date?(package, no_upgrade: false)
  self.class.package_installed?(self.class.dump_name(package), with: self.class.dump_with(package)) &&
    (no_upgrade || !self.class.package_outdated?(self.class.dump_name(package),
                                                 with: self.class.dump_with(package)))
end