Module: Homebrew::Install Private

Extended by:
Utils::Output::Mixin
Included in:
Cmd::GistLogs
Defined in:
install.rb,
install/check.rb

Overview

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

Helper module for performing (pre-)install checks.

Constant Summary collapse

DependencySummary =

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

T.type_alias { T::Hash[Symbol, T::Array[VersionChange]] }

Class 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

Class Method Details

.ask(action: "installation") ⇒ 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:

  • action (String) (defaults to: "installation") 


671
672
673
 
# File 'install.rb', line 671

def ask(action: "installation")
  ask_input(action:)
end

.ask_casks(casks, action: "installation", prompt: true, skip_cask_deps: 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:

  • casks (Array<Cask::Cask>)
  • action (String) (defaults to: "installation")
  • prompt (Boolean) (defaults to: true)
  • skip_cask_deps (Boolean) (defaults to: false) 


540
541
542
543
544
545
546
547
548
549
550
551
 
# File 'install.rb', line 540

def ask_casks(casks, action: "installation", prompt: true, skip_cask_deps: false)
  return if casks.empty?

  cask_names = casks.map(&:full_name)
  dependency_names = print_dry_run_casks(casks, action: dry_run_action(action), skip_cask_deps:,
                                              only_if_prompt_needed: prompt)

  ask_input(action:) if prompt && ask_prompt_needed?(
    planned_names:   cask_names + dependency_names,
    requested_names: cask_names,
  )
end

.ask_formulae(formulae_installer, dependants, flags: [], force_bottle: false, build_from_source_formulae: [], interactive: false, keep_tmp: false, debug_symbols: false, force: false, debug: false, quiet: false, verbose: false, prompt: true, action: "installation") ⇒ 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.

If asking the user is enabled, show dry-run information.

Parameters:

  • formulae_installer (Array<FormulaInstaller>)
  • dependants (Homebrew::Upgrade::Dependents)
  • flags (Array<String>) (defaults to: [])
  • force_bottle (Boolean) (defaults to: false)
  • build_from_source_formulae (Array<String>) (defaults to: [])
  • interactive (Boolean) (defaults to: false)
  • keep_tmp (Boolean) (defaults to: false)
  • debug_symbols (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • debug (Boolean) (defaults to: false)
  • quiet (Boolean) (defaults to: false)
  • verbose (Boolean) (defaults to: false)
  • prompt (Boolean) (defaults to: true)
  • action (String) (defaults to: "installation") 


491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'install.rb', line 491

def ask_formulae(formulae_installer, dependants,
                 flags: [],
                 force_bottle: false,
                 build_from_source_formulae: [],
                 interactive: false,
                 keep_tmp: false,
                 debug_symbols: false,
                 force: false,
                 debug: false,
                 quiet: false,
                 verbose: false,
                 prompt: true,
                 action: "installation")
  return if formulae_installer.empty?
  return if prompt && !formulae_ask_prompt_needed?(formulae_installer, dependants)

  install_formulae(formulae_installer, dry_run: true, dry_run_action: dry_run_action(action))

  Upgrade.upgrade_dependents(
    Homebrew::Upgrade::Dependents.new(
      upgradeable: dependants.upgradeable.dup,
      pinned:      dependants.pinned.dup,
      skipped:     dependants.skipped.dup,
    ),
    formulae_installer.map(&:formula),
    flags:,
    dry_run:                    true,
    force_bottle:,
    build_from_source_formulae:,
    interactive:,
    keep_tmp:,
    debug_symbols:,
    force:,
    debug:,
    quiet:,
    verbose:,
  )

  ask_input(action:) if prompt
end

.ask_prompt_needed?(planned_names:, requested_names:, force: false, named: true) ⇒ 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:

  • planned_names (Array<String>)
  • requested_names (Array<String>)
  • force (Boolean) (defaults to: false)
  • named (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


614
615
616
617
618
619
620
 
# File 'install.rb', line 614

def ask_prompt_needed?(planned_names:, requested_names:, force: false, named: true)
  return false if planned_names.empty?
  return true if force
  return true unless named

  planned_names.any? { |planned_name| requested_names.exclude?(planned_name) }
end

.check_cc_argv(cc) ⇒ 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:



40
41
42
43
44
45
 
# File 'install.rb', line 40

def check_cc_argv(cc)
  return unless cc

  opoo "You passed `--cc=#{cc}`."
  Diagnostic.support_tiers << 3
end

.check_prefix ⇒ 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.



57
 
# File 'install.rb', line 57

def check_prefix; end

.combined_fetch_downloads_heading(formula_names: [], cask_names: []) ⇒ 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:



273
274
275
276
277
278
279
 
# File 'install.rb', line 273

def combined_fetch_downloads_heading(formula_names: [], cask_names: [])
  combined_fetch_targets = formula_names.map { |name| Formatter.identifier(name) } +
                           cask_names.map { |name| Formatter.identifier(name) }
  return if combined_fetch_targets.empty?

  "Fetching downloads for: #{Utils::Text.to_sentence(combined_fetch_targets)}"
end

.enqueue_cask_installers(cask_installers) ⇒ Array<Cask::Installer>

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.

Leave the cask downloads queued so the caller fetches them alongside any formula bottles under one heading instead of draining them first.

Parameters:

Returns:



284
285
286
287
288
289
290
291
292
 
# File 'install.rb', line 284

def enqueue_cask_installers(cask_installers)
  cask_installers.select do |cask_installer|
    cask_installer.enqueue_downloads
    true
  rescue => e
    ofail "#{cask_installer.cask}: #{e}"
    false
  end
end

.enqueue_formulae(formula_installers, download_queue:) ⇒ Array<FormulaInstaller>

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:



262
263
264
265
266
267
268
269
270
 
# File 'install.rb', line 262

def enqueue_formulae(formula_installers, download_queue:)
  fetch_formulae(
    formula_installers,
    download_queue:,
    fetch_after_enqueue:     false,
    shutdown_download_queue: false,
    show_downloads_heading:  false,
  )
end

.fetch_cask_dependencies(cask_installers, download_queue:) ⇒ 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.

Cask dependencies are resolved from the downloaded container, so they can only be queued once the cask downloads above have been fetched.

Parameters:



297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'install.rb', line 297

def fetch_cask_dependencies(cask_installers, download_queue:)
  return if cask_installers.empty?

  mark_failed_cask_downloads(cask_installers, download_queue:)
  cask_installers.each do |cask_installer|
    cask_installer.enqueue_dependency_downloads
  rescue => e
    ofail "#{cask_installer.cask}: #{e}"
  end
  download_queue.fetch(heading: "Fetching dependency downloads")
  mark_failed_cask_downloads(cask_installers, download_queue:)
end

.fetch_formulae(formula_installers, download_queue: nil, fetch_after_enqueue: true, shutdown_download_queue: true, show_downloads_heading: true) ⇒ Array<FormulaInstaller>

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:

  • formula_installers (Array<FormulaInstaller>)
  • download_queue (Homebrew::DownloadQueue, nil) (defaults to: nil)
  • fetch_after_enqueue (Boolean) (defaults to: true)
  • shutdown_download_queue (Boolean) (defaults to: true)
  • show_downloads_heading (Boolean) (defaults to: true)

Returns:



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'install.rb', line 133

def fetch_formulae(
  formula_installers,
  download_queue: nil,
  fetch_after_enqueue: true,
  shutdown_download_queue: true,
  show_downloads_heading: true
)
  return formula_installers if formula_installers.empty?

  download_queue = T.let(download_queue || Homebrew::DownloadQueue.new(pour: true), Homebrew::DownloadQueue)

  begin
    valid_formula_installers = prelude_fetch_formulae(formula_installers, download_queue:)
    # Wait on just the bottle manifests dependency resolution needs so
    # in-flight bottles are only reported under the downloads heading.
    download_queue.fetch(only: Resource::BottleManifest, heading: "Downloading bottle manifests",
                         allow_failures: true)

    [:prelude, :enqueue_fetch].each do |step|
      valid_formula_installers = select_formula_installers(valid_formula_installers, step:)
      next if step == :enqueue_fetch && !fetch_after_enqueue

      if step == :prelude
        # List dependency attestations before `enqueue_fetch` starts the downloads that verify them.
        dependencies = valid_formula_installers.reject(&:ignore_deps?).flat_map do |fi|
          fi.compute_dependencies.map(&:to_formula)
        end
        Homebrew::Attestation.prefetch(dependencies)
        download_queue.fetch(only: Resource::BottleManifest, heading: "Downloading bottle manifests",
                             allow_failures: true)
      else
        heading = if show_downloads_heading
          combined_fetch_downloads_heading(formula_names: valid_formula_installers.map { |fi| fi.formula.name })
        end
        download_queue.fetch(heading:)
        valid_formula_installers = reject_failed_downloads(valid_formula_installers, download_queue:)
      end
    end
  ensure
    download_queue.shutdown if shutdown_download_queue
  end

  valid_formula_installers
end

.finish_installation(formulae:, casks:, dry_run: false, display_times: 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:

  • formulae (Array<Formula>)
  • casks (Array<Cask::Cask>)
  • dry_run (Boolean) (defaults to: false)
  • display_times (Boolean) (defaults to: false) 


334
335
336
337
338
 
# File 'install.rb', line 334

def finish_installation(formulae:, casks:, dry_run: false, display_times: false)
  Cleanup.install_clean!(formulae:, casks:) unless dry_run
  Cleanup.periodic_clean!(dry_run:)
  Homebrew.messages.display_messages(force_caveats: true, display_times:)
end

.formula_installers(formulae_to_install, installed_on_request: true, build_bottle: false, force_bottle: false, bottle_arch: nil, ignore_deps: false, only_deps: false, include_test_formulae: [], build_from_source_formulae: [], cc: nil, git: false, interactive: false, keep_tmp: false, debug_symbols: false, force: false, overwrite: false, debug: false, quiet: false, verbose: false, dry_run: false, skip_post_install: false, skip_link: false) ⇒ Array<FormulaInstaller>

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:

  • formulae_to_install (Array<Formula>)
  • installed_on_request (Boolean) (defaults to: true)
  • build_bottle (Boolean) (defaults to: false)
  • force_bottle (Boolean) (defaults to: false)
  • bottle_arch (String, nil) (defaults to: nil)
  • ignore_deps (Boolean) (defaults to: false)
  • only_deps (Boolean) (defaults to: false)
  • include_test_formulae (Array<String>) (defaults to: [])
  • build_from_source_formulae (Array<String>) (defaults to: [])
  • cc (String, nil) (defaults to: nil)
  • git (Boolean) (defaults to: false)
  • interactive (Boolean) (defaults to: false)
  • keep_tmp (Boolean) (defaults to: false)
  • debug_symbols (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • overwrite (Boolean) (defaults to: false)
  • debug (Boolean) (defaults to: false)
  • quiet (Boolean) (defaults to: false)
  • verbose (Boolean) (defaults to: false)
  • dry_run (Boolean) (defaults to: false)
  • skip_post_install (Boolean) (defaults to: false)
  • skip_link (Boolean) (defaults to: false)

Returns:



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'install.rb', line 69

def formula_installers(
  formulae_to_install,
  installed_on_request: true,
  build_bottle: false,
  force_bottle: false,
  bottle_arch: nil,
  ignore_deps: false,
  only_deps: false,
  include_test_formulae: [],
  build_from_source_formulae: [],
  cc: nil,
  git: false,
  interactive: false,
  keep_tmp: false,
  debug_symbols: false,
  force: false,
  overwrite: false,
  debug: false,
  quiet: false,
  verbose: false,
  dry_run: false,
  skip_post_install: false,
  skip_link: false
)
  formulae_to_install.filter_map do |formula|
    Migrator.migrate_if_needed(formula, force:, dry_run:)
    build_options = formula.build

    FormulaInstaller.new(
      formula,
      options:                    build_options.used_options,
      installed_on_request:       installed_on_request || Tab.for_formula(formula).installed_on_request,
      build_bottle:,
      force_bottle:,
      bottle_arch:,
      ignore_deps:,
      only_deps:,
      include_test_formulae:,
      build_from_source_formulae:,
      cc:,
      git:,
      interactive:,
      keep_tmp:,
      debug_symbols:,
      force:,
      overwrite:,
      debug:,
      quiet:,
      verbose:,
      skip_post_install:,
      skip_link:,
    )
  end
end

.formulae_ask_prompt_needed?(formulae_installer, dependants) ⇒ 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) 


628
629
630
631
632
633
 
# File 'install.rb', line 628

def formulae_ask_prompt_needed?(formulae_installer, dependants)
  formulae_installer.any? do |formula_installer|
    !formula_installer.ignore_deps? && formula_installer.compute_dependencies.present?
  end ||
    dependants.upgradeable.present?
end

.global_post_install ⇒ 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.



54
 
# File 'install.rb', line 54

def global_post_install; end

.install_formula(formula_installer, upgrade:) ⇒ 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:



636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
 
# File 'install.rb', line 636

def install_formula(formula_installer, upgrade:)
  formula = formula_installer.formula

  formula_installer.check_installation_already_attempted

  if upgrade
    Upgrade.print_upgrade_message(formula, formula_installer.options)

    kegs = Upgrade.outdated_kegs(formula)
    linked_kegs = kegs.select(&:linked?)
  else
    formula.print_tap_action
  end

  # first we unlink the currently active keg for this formula otherwise it is
  # possible for the existing build to interfere with the build we are about to
  # do! Seriously, it happens!
  kegs.each(&:unlink) if kegs.present?

  formula_installer.install
  formula_installer.finish
rescue FormulaInstallationAlreadyAttemptedError
  # We already attempted to upgrade f as part of the dependency tree of
  # another formula. In that case, don't generate an error, just move on.
  nil
ensure
  # restore previous installation state if build failed
  begin
    linked_kegs&.each(&:link) unless formula&.latest_version_installed?
  rescue
    nil
  end
end

.install_formula?(formula, head: false, fetch_head: false, only_dependencies: false, force: false, quiet: false, skip_link: false, overwrite: false, installed_on_request: true) ⇒ 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:

  • formula (Formula)
  • head (Boolean) (defaults to: false)
  • fetch_head (Boolean) (defaults to: false)
  • only_dependencies (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • quiet (Boolean) (defaults to: false)
  • skip_link (Boolean) (defaults to: false)
  • overwrite (Boolean) (defaults to: false)
  • installed_on_request (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'install/check.rb', line 17

def install_formula?(
  formula,
  head: false,
  fetch_head: false,
  only_dependencies: false,
  force: false,
  quiet: false,
  skip_link: false,
  overwrite: false,
  installed_on_request: true
)
  # HEAD-only without --HEAD is an error
  if !head && formula.stable.nil?
    odie <<~EOS
      #{formula.full_name} is a HEAD-only formula.
      To install it, run:
        brew install --HEAD #{formula.full_name}
    EOS
  end

  # --HEAD, fail with no head defined
  odie "No head is defined for #{formula.full_name}" if head && formula.head.nil?

  installed_head_version = formula.latest_head_version
  if installed_head_version &&
     !formula.head_version_outdated?(installed_head_version, fetch_head:)
    new_head_installed = true
  end
  prefix_installed = formula.prefix.exist? && !formula.prefix.empty?

  # Check if the installed formula is from a different tap
  if formula.any_version_installed? &&
     (current_tap_name = formula.tap&.name.presence) &&
     (installed_keg_tab = formula.any_installed_keg&.tab.presence) &&
     (installed_tap_name = installed_keg_tab.tap&.name.presence) &&
     installed_tap_name != current_tap_name
    odie <<~EOS
      #{formula.name} was installed from the #{Formatter.identifier(installed_tap_name)} tap
      but you are trying to install it from the #{Formatter.identifier(current_tap_name)} tap.
      Formulae with the same name from different taps cannot be installed at the same time.

      To install this version, you must first uninstall the existing formula:
        brew uninstall #{formula.name}
      Then you can install the desired version:
        brew install #{formula.full_name}
    EOS
  end

  if formula.keg_only? && formula.any_version_installed? && formula.optlinked? && !force
    # keg-only install is only possible when no other version is
    # linked to opt, because installing without any warnings can break
    # dependencies. Therefore before performing other checks we need to be
    # sure the --force switch is passed.
    if formula.outdated?
      if !Homebrew::EnvConfig.no_install_upgrade? && !formula.pinned?
        name = formula.name
        version = formula.linked_version
        puts "#{name} #{version} is already installed but outdated (so it will be upgraded)."
        return true
      end

      unpin_cmd_if_needed = ("brew unpin #{formula.full_name} && " if formula.pinned?)
      optlinked_version = Keg.for(formula.opt_prefix).version
      onoe <<~EOS
        #{formula.full_name} #{optlinked_version} is already installed.
        To upgrade to #{formula.version}, run:
          #{unpin_cmd_if_needed}brew upgrade #{formula.full_name}
      EOS
    elsif only_dependencies
      return true
    elsif !quiet
      opoo_without_github_actions_annotation <<~EOS
        #{formula.full_name} #{formula.pkg_version} is already installed and up-to-date.
        To reinstall #{formula.pkg_version}, run:
          brew reinstall #{formula.name}
      EOS
    end
  elsif (head && new_head_installed) || prefix_installed
    # After we're sure the --force switch was passed for linking to opt
    # keg-only we need to be sure that the version we're attempting to
    # install is not already installed.

    installed_version = if head
      formula.latest_head_version
    else
      formula.pkg_version
    end

    msg = "#{formula.full_name} #{installed_version} is already installed"
    linked_not_equals_installed = formula.linked_version != installed_version
    if formula.linked? && linked_not_equals_installed
      msg = if quiet
        nil
      else
        <<~EOS
          #{msg}.
          The currently linked version is: #{formula.linked_version}
        EOS
      end
    elsif only_dependencies || (!formula.linked? && overwrite)
      msg = nil
      return true
    elsif !formula.linked? || formula.keg_only?
      msg = <<~EOS
        #{msg}, it's just not linked.
        To link this version, run:
          brew link #{formula.full_name}
      EOS
    else
      unless quiet
        opoo_without_github_actions_annotation <<~EOS
          #{msg} and up-to-date.
          To reinstall #{formula.pkg_version}, run:
            brew reinstall #{formula.name}
        EOS
      end
      msg = nil
    end
    opoo msg if msg
  elsif !formula.any_version_installed? && (old_formula = formula.old_installed_formulae.first)
    msg = "#{old_formula.full_name} #{old_formula.any_installed_version} already installed"
    msg = if !old_formula.linked? && !old_formula.keg_only?
      <<~EOS
        #{msg}, it's just not linked.
        To link this version, run:
          brew link #{old_formula.full_name}
      EOS
    elsif quiet
      nil
    else
      "#{msg}."
    end
    opoo msg if msg
  elsif formula.migration_needed? && !force
    # Check if the formula we try to install is the same as installed
    # but not migrated one. If --force is passed then install anyway.
    opoo <<~EOS
      #{formula.oldnames_to_migrate.first} is already installed, it's just not migrated.
      To migrate this formula, run:
        brew migrate #{formula}
      Or to force-install it, run:
        brew install #{formula} --force
    EOS
  elsif formula.linked?
    message = "#{formula.name} #{formula.linked_version} is already installed"
    if formula.outdated? && !head
      if !Homebrew::EnvConfig.no_install_upgrade? && !formula.pinned?
        puts "#{message} but outdated (so it will be upgraded)."
        return true
      end

      unpin_cmd_if_needed = ("brew unpin #{formula.full_name} && " if formula.pinned?)
      onoe <<~EOS
        #{message}
        To upgrade to #{formula.pkg_version}, run:
          #{unpin_cmd_if_needed}brew upgrade #{formula.full_name}
      EOS
    elsif only_dependencies || skip_link
      return true
    else
      onoe <<~EOS
        #{message}
        To install #{formula.pkg_version}, first run:
          brew unlink #{formula.name}
      EOS
    end
  else
    # If none of the above is true and the formula is linked, then
    # FormulaInstaller will handle this case.
    return true
  end

  # Even if we don't install this formula, mark it as requested when appropriate.
  return false if !installed_on_request || !formula.opt_prefix.directory?

  keg = Keg.new(Utils::Path.resolved_path(formula.opt_prefix))
  tab = keg.tab
  unless tab.installed_on_request
    tab.installed_on_request = true
    tab.write
  end

  false
end

.install_formulae(formula_installers, installed_on_request: true, build_bottle: false, force_bottle: false, bottle_arch: nil, ignore_deps: false, only_deps: false, include_test_formulae: [], build_from_source_formulae: [], cc: nil, git: false, interactive: false, keep_tmp: false, debug_symbols: false, force: false, overwrite: false, debug: false, quiet: false, verbose: false, dry_run: false, dry_run_action: "install", skip_post_install: false, skip_link: false, cleanup: true) ⇒ Array<Formula>

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:

  • formula_installers (Array<FormulaInstaller>)
  • installed_on_request (Boolean) (defaults to: true)
  • build_bottle (Boolean) (defaults to: false)
  • force_bottle (Boolean) (defaults to: false)
  • bottle_arch (String, nil) (defaults to: nil)
  • ignore_deps (Boolean) (defaults to: false)
  • only_deps (Boolean) (defaults to: false)
  • include_test_formulae (Array<String>) (defaults to: [])
  • build_from_source_formulae (Array<String>) (defaults to: [])
  • cc (String, nil) (defaults to: nil)
  • git (Boolean) (defaults to: false)
  • interactive (Boolean) (defaults to: false)
  • keep_tmp (Boolean) (defaults to: false)
  • debug_symbols (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • overwrite (Boolean) (defaults to: false)
  • debug (Boolean) (defaults to: false)
  • quiet (Boolean) (defaults to: false)
  • verbose (Boolean) (defaults to: false)
  • dry_run (Boolean) (defaults to: false)
  • dry_run_action (String) (defaults to: "install")
  • skip_post_install (Boolean) (defaults to: false)
  • skip_link (Boolean) (defaults to: false)
  • cleanup (Boolean) (defaults to: true)

Returns:



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'install.rb', line 351

def install_formulae(
  formula_installers,
  installed_on_request: true,
  build_bottle: false,
  force_bottle: false,
  bottle_arch: nil,
  ignore_deps: false,
  only_deps: false,
  include_test_formulae: [],
  build_from_source_formulae: [],
  cc: nil,
  git: false,
  interactive: false,
  keep_tmp: false,
  debug_symbols: false,
  force: false,
  overwrite: false,
  debug: false,
  quiet: false,
  verbose: false,
  dry_run: false,
  dry_run_action: "install",
  skip_post_install: false,
  skip_link: false,
  cleanup: true
)
  return [] if formula_installers.empty?

  if dry_run
    groups = formula_installers.reject(&:only_deps?).map(&:formula).group_by do |formula|
      installed_version = Upgrade.installed_version(formula) if dry_run_action == "install"
      if installed_version && installed_version != formula.pkg_version
        "upgrade"
      else
        dry_run_action
      end
    end
    groups.keys.sort.each do |action|
      group = groups.fetch(action)
      ohai "Would #{action} #{Utils.pluralize("formula", group.count, include_count: true)}:"
      puts Formatter.version_changes(group.map do |formula|
        if action == "upgrade"
          Upgrade.formula_version_change(formula)
        else
          VersionChange.new(name: formula.full_specified_name, new_version: formula.pkg_version.to_s)
        end
      end)
    end

    formula_installers.each do |fi|
      next if fi.ignore_deps?

      print_dry_run_dependencies(fi.formula, fi.compute_dependencies) do |dependency|
        Upgrade.formula_version_change(dependency)
      end
    end
    return []
  end

  installed_formulae = T.let([], T::Array[Formula])
  formula_installers.each do |fi|
    formula = fi.formula
    upgrade = formula.linked? && formula.outdated? && !formula.head? && !Homebrew::EnvConfig.no_install_upgrade?
    install_formula(fi, upgrade:)
    Cleanup.install_formula_clean!(formula) if cleanup
    installed_formulae << formula
  rescue BuildError => e
    require "utils/analytics"

    Utils::Analytics.report_build_error(e)
    e.dump(verbose:)
    puts
    Homebrew.failed = true
  rescue => e
    # Keep a single failed install (e.g. a bottle that fails to extract)
    # from aborting the rest of the batch while still failing the run.
    ofail "#{fi.formula.full_specified_name}: #{e}"
  end
  installed_formulae
end

.mark_failed_cask_downloads(cask_installers, download_queue:) ⇒ 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:



311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'install.rb', line 311

def mark_failed_cask_downloads(cask_installers, download_queue:)
  failed_downloads = download_queue.failed_downloads
  return if failed_downloads.empty?

  cask_installers.each do |cask_installer|
    next if cask_installer.download_failed?

    if failed_downloads.include?(cask_installer.downloader)
      cask_installer.download_failed!
    else
      mark_failed_cask_downloads(cask_installer.dependency_cask_installers, download_queue:)
    end
  end
end

.perform_build_from_source_checks(all_fatal: 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:

  • all_fatal (Boolean) (defaults to: false) 


48
49
50
51
 
# File 'install.rb', line 48

def perform_build_from_source_checks(all_fatal: false)
  Diagnostic.checks(:fatal_build_from_source_checks)
  Diagnostic.checks(:build_from_source_checks, fatal: all_fatal)
end

.perform_preinstall_checks(all_fatal: 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:

  • all_fatal (Boolean) (defaults to: false) 


676
677
678
679
680
681
682
683
 
# File 'install.rb', line 676

def perform_preinstall_checks(all_fatal: false)
  check_prefix
  check_cpu
  attempt_directory_creation
  Diagnostic.checks(:supported_configuration_checks, fatal: all_fatal)
  Diagnostic.checks(:preinstall_checks, fatal: false)
  Diagnostic.checks(:fatal_preinstall_checks)
end

.perform_preinstall_checks_once(all_fatal: 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:

  • all_fatal (Boolean) (defaults to: false) 


31
32
33
34
35
36
37
 
# File 'install.rb', line 31

def perform_preinstall_checks_once(all_fatal: false)
  @perform_preinstall_checks_once ||= T.let({}, T.nilable(T::Hash[T::Boolean, TrueClass]))
  @perform_preinstall_checks_once[all_fatal] ||= begin
    perform_preinstall_checks(all_fatal:)
    true
  end
end

.prelude_fetch_formulae(formula_installers, download_queue:, metadata_only: false) ⇒ Array<FormulaInstaller>

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:



223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'install.rb', line 223

def prelude_fetch_formulae(formula_installers, download_queue:, metadata_only: false)
  formula_installers.each do |fi|
    fi.download_queue = download_queue
  end

  # List attestations before the bottle downloads below start verifying them.
  Homebrew::Attestation.prefetch(formula_installers.map(&:formula)) unless metadata_only

  # Only pass the keyword when limiting the fetch so mocks and
  # overrides expecting the historical no-argument call keep working.
  action = ->(fi) { metadata_only ? fi.prelude_fetch(metadata_only: true) : fi.prelude_fetch }
  select_formula_installers(formula_installers, action:)
end

.print_dry_run_casks(casks, action: "install", skip_cask_deps: false, include_installed: true, only_if_prompt_needed: 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:

  • casks (Array<Cask::Cask>)
  • action (String) (defaults to: "install")
  • skip_cask_deps (Boolean) (defaults to: false)
  • include_installed (Boolean) (defaults to: true)
  • only_if_prompt_needed (Boolean) (defaults to: false)

Returns:



562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
 
# File 'install.rb', line 562

def print_dry_run_casks(casks, action: "install", skip_cask_deps: false, include_installed: true,
                        only_if_prompt_needed: false)
  dependencies = casks.to_h do |cask|
    dep_names = T.let([], T::Array[String])
    unless skip_cask_deps
      dep_names.concat(
        ::Utils::TopologicalHash.graph_package_dependencies([cask]).tsort.grep(Cask::Cask).filter_map do |dep|
          next if dep.full_name == cask.full_name
          next if dep.installed?

          dep.full_name
        end,
      )
    end
    dep_names.concat(
      CaskDependent.new(cask)
                   .runtime_dependencies(read_from_tab: false, undeclared: false)
                   .reject(&:installed?)
                   .map(&:name),
    )
    dep_names.uniq!
    [cask, dep_names]
  end
  cask_names = casks.map(&:full_name)
  return [] if only_if_prompt_needed && !ask_prompt_needed?(
    planned_names:   cask_names + dependencies.values.flatten,
    requested_names: cask_names,
  )

  if (casks_to_print = (include_installed ? casks : casks.reject(&:installed?)).presence)
    ohai "Would #{action} #{::Utils.pluralize("cask", casks_to_print.count, include_count: true)}:"
    puts casks_to_print.map(&:full_name).join(" ")
  end

  dependencies.flat_map do |cask, dep_names|
    next [] if dep_names.blank?

    ohai "Would install #{::Utils.pluralize("dependency", dep_names.count, include_count: true)} " \
         "for #{cask.full_name}:"
    puts dep_names.join(" ")
    dep_names
  end
end

.print_dry_run_dependencies(formula, dependencies, skip_formula_names: [], dependency_summary: nil, &_block) ⇒ 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:



441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'install.rb', line 441

def print_dry_run_dependencies(formula, dependencies, skip_formula_names: [], dependency_summary: nil, &_block)
  return if dependencies.empty?

  entries = dependencies.filter_map do |dep|
    dependency = dep.to_formula
    next if skip_formula_names.include?(dependency.full_name)

    [dependency.any_version_installed?, yield(dependency)]
  end

  upgrade, install = entries.partition(&:first)
  summary = { install: install.map(&:last), upgrade: upgrade.map(&:last) }
  if dependency_summary
    summary.each { |verb, group| dependency_summary.fetch(verb).concat(group) }
  else
    print_dry_run_dependency_summary(summary, formula:)
  end
end

.print_dry_run_dependency_summary(summary, formula: nil) ⇒ 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:



461
462
463
464
465
466
467
468
469
470
 
# File 'install.rb', line 461

def print_dry_run_dependency_summary(summary, formula: nil)
  { install: summary.fetch(:install), upgrade: summary.fetch(:upgrade) }.each do |verb, group|
    group = group.uniq
    next if group.empty?

    ohai "Would #{verb} #{Utils.pluralize("dependency", group.count, include_count: true)}" \
         "#{" for #{formula.name}" if formula}:"
    puts Formatter.version_changes(group)
  end
end

.reject_failed_downloads(formula_installers, download_queue:) ⇒ Array<FormulaInstaller>

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.

A failed download has already been reported, so skip installing its formula rather than failing a second time on the missing or known-bad download, while still installing everything else.

Parameters:

Returns:



185
186
187
188
189
190
 
# File 'install.rb', line 185

def reject_failed_downloads(formula_installers, download_queue:)
  failed_full_names = unmark_failed_formulae(download_queue.failed_downloads)
  return formula_installers if failed_full_names.empty?

  formula_installers.reject { |fi| failed_full_names.include?(fi.formula.full_name) }
end

.select_formula_installers(formula_installers, step: nil, action: nil) ⇒ Array<FormulaInstaller>

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:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'install.rb', line 244

def select_formula_installers(formula_installers, step: nil, action: nil)
  formula_installers.select do |fi|
    if action
      action.call(fi)
    elsif step
      fi.public_send(step)
    end
    true
  rescue CannotInstallFormulaError => e
    ofail e.message
    false
  rescue => e
    ofail "#{fi.formula}: #{e}"
    false
  end
end

.unmark_failed_formulae(downloadables) ⇒ 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.

A formula whose download failed must not stay marked as fetched: FormulaInstaller#enqueue_fetch marks formulae as fetched when their downloads are enqueued, so a later retry pass would otherwise skip fetching entirely and install from a known-bad cached download without any checksum verification (issue 23714).

Parameters:

Returns:



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'install.rb', line 198

def unmark_failed_formulae(downloadables)
  failed_full_names = downloadables.filter_map do |downloadable|
    owner = case downloadable
    when Bottle
      downloadable.resource.owner
    when Resource
      downloadable.owner
    when Homebrew::API::SourceDownload
      downloadable.formula
    end
    owner = owner.owner if owner.is_a?(SoftwareSpec)
    owner.full_name if owner.is_a?(Formula)
  end

  FormulaInstaller.fetched.delete_if { |formula| failed_full_names.include?(formula.full_name) }
  failed_full_names
end