Class: Formula

Inherits:
Object show all
Extended by:
APIHashable, Attrable, BuildEnvironment::DSL, Cachable, Forwardable, OnSystem::MacOSAndLinux
Includes:
Context, FileUtils, Homebrew::Livecheck::Constants, OnSystem::MacOSAndLinux, Utils::Shebang, Utils::Shell
Defined in:
extend/os/mac/formula.rb,
extend/os/linux/formula.rb,
formula.rb,
formula.rbi,
sorbet/rbi/parlour.rbi

Overview

This file provides definitions for Forwardable#delegate, which is currently not supported by Sorbet.

Constant Summary

Constants included from Homebrew::Livecheck::Constants

Homebrew::Livecheck::Constants::LATEST_VERSION

Constants included from Utils::Shell

Utils::Shell::SHELL_PROFILE_MAP, Utils::Shell::UNSAFE_SHELL_CHAR

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from OnSystem::MacOSAndLinux

included

Methods included from BuildEnvironment::DSL

inherited

Methods included from Cachable

cache

Methods included from Attrable

attr_predicate, attr_rw

Methods included from APIHashable

generated_hash!, generating_hash!, generating_hash?

Methods included from Context

current, current=, #debug?, #quiet?, #verbose?, #with_context

Methods included from Utils::Shell

csh_quote, export_value, from_path, parent, preferred, preferred_path, prepend_path_in_profile, profile, set_variable_in_profile, sh_quote

Methods included from Kernel

#disk_usage_readable, #ensure_executable!, #ensure_formula_installed!, #exec_browser, #exec_editor, #ignore_interrupts, #interactive_shell, #number_readable, #odebug, #odeprecated, #odie, #odisabled, #ofail, #oh1, #oh1_title, #ohai, #ohai_title, #onoe, #opoo, #paths, #pretty_duration, #pretty_installed, #pretty_outdated, #pretty_uninstalled, #quiet_system, #redact_secrets, #redirect_stdout, #require?, #safe_system, #tap_and_name_comparison, #truncate_text_to_approximate_size, #which, #which_all, #which_editor, #with_custom_locale, #with_env, #with_homebrew_path

Methods included from Utils::Shebang

rewrite_shebang

Class Attribute Details

.bottle(&block) ⇒ void

This method returns an undefined value.

Adds a bottle SoftwareSpec. This provides a pre-built binary package built by the Homebrew maintainers for you. It will be installed automatically if there is a binary package for your platform and you haven’t passed or previously used any options on this formula.

If you maintain your own repository, you can add your own bottle links. You can ignore this block entirely if submitting to Homebrew/homebrew-core. It’ll be handled for you by the Brew Test Bot.

bottle do
  root_url "https://example.com" # Optional root to calculate bottle URLs.
  rebuild 1 # Marks the old bottle as outdated without bumping the version/revision of the formula.
  # Optionally specify the HOMEBREW_CELLAR in which the bottles were built.
  sha256 cellar: "/brew/Cellar", catalina:    "ef65c759c5097a36323fa9c77756468649e8d1980a3a4e05695c05e39568967c"
  sha256 cellar: :any,           mojave:      "28f4090610946a4eb207df102d841de23ced0d06ba31cb79e040d883906dcd4f"
  sha256                         high_sierra: "91dd0caca9bd3f38c439d5a7b6f68440c4274945615fae035ff0a369264b8a2f"
end

Homebrew maintainers aim to bottle all formulae.

Parameters:

See Also:



3255
3256
3257
 
# File 'formula.rb', line 3255

def bottle(&block)
  stable.bottle(&block)
end

.deprecated_option(hash) ⇒ Object

Deprecated options are used to rename options and migrate users who used them to newer ones. They are mostly used for migrating non-with options (e.g. enable-debug) to with options (e.g. with-debug).

deprecated_option "enable-debug" => "with-debug"


3409
3410
3411
 
# File 'formula.rb', line 3409

def deprecated_option(hash)
  specs.each { |spec| spec.deprecated_option(hash) }
end

.deprecation_date ⇒ Object (readonly)

The date that this Formula was or becomes deprecated. Returns nil if no date is specified.

Returns:

  • Date

See Also:



3673
3674
3675
 
# File 'formula.rb', line 3673

def deprecation_date
  @deprecation_date
end

.deprecation_reason ⇒ nil, ... (readonly)

The reason for deprecation of a Formula.

Returns:

  • (nil) —

    if no reason was provided or the formula is not deprecated.

  • (String, Symbol)

See Also:



3679
3680
3681
 
# File 'formula.rb', line 3679

def deprecation_reason
  @deprecation_reason
end

.desc(arg = T.unsafe(nil)) ⇒ T.untyped

Parameters:

  • arg (T.untyped) (defaults to: T.unsafe(nil))

Returns:

  • (T.untyped) 


165
 
# File 'sorbet/rbi/parlour.rbi', line 165

def self.desc(arg = T.unsafe(nil)); end

.disable_date ⇒ Object (readonly)

The date that this Formula was or becomes disabled. Returns nil if no date is specified.

Returns:

  • Date

See Also:



3713
3714
3715
 
# File 'formula.rb', line 3713

def disable_date
  @disable_date
end

.disable_reason ⇒ String, Symbol (readonly)

The reason this Formula is disabled. Returns nil if no reason was provided or the formula is not disabled.

Returns:

See Also:



3719
3720
3721
 
# File 'formula.rb', line 3719

def disable_reason
  @disable_reason
end

.head(val = nil, specs = {}, &block) ⇒ Object

Adds a head SoftwareSpec. This can be installed by passing the --HEAD option to allow installing software directly from a branch of a version-control repository. If called as a method this provides just the url for the SoftwareSpec. If a block is provided you can also add depends_on and Patches just to the head SoftwareSpec. The download strategies (e.g. :using =>) are the same as for url. master is the default branch and doesn’t need stating with a branch: parameter.

head "https://we.prefer.https.over.git.example.com/.git"
head "https://example.com/.git", branch: "name_of_branch"

or (if autodetect fails):

head "https://hg.is.awesome.but.git.has.won.example.com/", using: :hg


3304
3305
3306
3307
3308
3309
3310
3311
3312
 
# File 'formula.rb', line 3304

def head(val = nil, specs = {}, &block)
  if block
    @head.instance_eval(&block)
  elsif val
    @head.url(val, specs)
  else
    @head
  end
end

.homepage(arg = T.unsafe(nil)) ⇒ T.untyped

Parameters:

  • arg (T.untyped) (defaults to: T.unsafe(nil))

Returns:

  • (T.untyped) 


168
 
# File 'sorbet/rbi/parlour.rbi', line 168

def self.homepage(arg = T.unsafe(nil)); end

.license(args = nil) ⇒ Object

The SPDX ID of the open-source license that the formula uses. Shows when running brew info. Use :any_of, :all_of or :with to describe complex license expressions. :any_of should be used when the user can choose which license to use. :all_of should be used when the user must use all licenses. :with should be used to specify a valid SPDX exception. Add + to an identifier to indicate that the formulae can be licensed under later versions of the same license.

license "BSD-2-Clause"
license "EPL-1.0+"
license any_of: ["MIT", "GPL-2.0-only"]
license all_of: ["MIT", "GPL-2.0-only"]
license "GPL-2.0-only" => { with: "LLVM-exception" }
license :public_domain
license any_of: [
  "MIT",
  :public_domain,
  all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
  "Apache-2.0" => { with: "LLVM-exception" },
]

See Also:



3097
3098
3099
3100
3101
3102
3103
 
# File 'formula.rb', line 3097

def license(args = nil)
  if args.nil?
    @licenses
  else
    @licenses = args
  end
end

.livecheck(&block) ⇒ Object

Livecheck can be used to check for newer versions of the software. This method evaluates the DSL specified in the livecheck block of the Formula (if it exists) and sets the instance variables of a Livecheck object accordingly. This is used by brew livecheck to check for newer versions of the software.

livecheck do
  skip "Not maintained"
  url "https://example.com/foo/releases"
  regex /foo-(\d+(?:\.\d+)+)\.tar/
end


3570
3571
3572
3573
3574
3575
 
# File 'formula.rb', line 3570

def livecheck(&block)
  return @livecheck unless block

  @livecheckable = true
  @livecheck.instance_eval(&block)
end

.mirror(val) ⇒ Object

Additional URLs for the stable version of the formula. These are only used if the url fails to download. It’s optional and there can be more than one. Generally we add them when the main url is unreliable. If url is really unreliable then we may swap the mirror and url.

mirror "https://in.case.the.host.is.down.example.com"
mirror "https://in.case.the.mirror.is.down.example.com


3217
3218
3219
 
# File 'formula.rb', line 3217

def mirror(val)
  stable.mirror(val)
end

.option(name, description = "") ⇒ Object

Options can be used as arguments to brew install. To switch features on/off: "with-something" or "with-otherthing". To use other software: "with-other-software" or "without-foo". Note that for depends_on that are :optional or :recommended, options are generated automatically.

There are also some special options:

  • :universal: build a universal binary/library (e.g. on newer Intel Macs this means a combined x86_64/x86 binary/library).
option "with-spam", "The description goes here without a dot at the end"
option "with-qt", "Text here overwrites what's autogenerated by 'depends_on "qt" => :optional'"
option :universal


3400
3401
3402
 
# File 'formula.rb', line 3400

def option(name, description = "")
  specs.each { |spec| spec.option(name, description) }
end

.revision(arg = T.unsafe(nil)) ⇒ T.untyped

Parameters:

  • arg (T.untyped) (defaults to: T.unsafe(nil))

Returns:

  • (T.untyped) 


171
 
# File 'sorbet/rbi/parlour.rbi', line 171

def self.revision(arg = T.unsafe(nil)); end

.service(&block) ⇒ Object

Service can be used to define services. This method evaluates the DSL specified in the service block of the Formula (if it exists) and sets the instance variables of a Service object accordingly. This is used by brew install to generate a service file.

service do
  run [opt_bin/"foo"]
end


3586
3587
3588
3589
3590
 
# File 'formula.rb', line 3586

def service(&block)
  return @service_block unless block

  @service_block = block
end

.sha256(val) ⇒ Object

To verify the cached download’s integrity and security we verify the SHA-256 hash matches what we’ve declared in the Formula. To quickly fill this value you can leave it blank and run brew fetch --force and it’ll tell you the currently valid value.

sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"


3229
3230
3231
 
# File 'formula.rb', line 3229

def sha256(val)
  stable.sha256(val)
end

.stable(&block) ⇒ Object

Allows adding depends_on and Patches just to the stable SoftwareSpec. This is required instead of using a conditional. It is preferable to also pull the url and sha256 into the block if one is added.

stable do
  url "https://example.com/foo-1.0.tar.gz"
  sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"

  depends_on "libxml2"
  depends_on "libffi"
end


3286
3287
3288
3289
3290
 
# File 'formula.rb', line 3286

def stable(&block)
  return @stable unless block

  @stable.instance_eval(&block)
end

.url(val, specs = {}) ⇒ Object

The URL used to download the source for the stable version of the formula. We prefer https for security and proxy reasons. If not inferable, specify the download strategy with using: ....

  • :git, :hg, :svn, :bzr, :fossil, :cvs,
  • :curl (normal file download, will also extract)
  • :nounzip (without extracting)
  • :post (download via an HTTP POST)
url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
url "https://some.dont.provide.archives.example.com",
    using:    :git,
    tag:      "1.2.3",
    revision: "db8e4de5b2d6653f66aea53094624468caad15d2"


3194
3195
3196
 
# File 'formula.rb', line 3194

def url(val, specs = {})
  stable.url(val, specs)
end

.version(val = nil) ⇒ Object

The version string for the stable version of the formula. The version is autodetected from the URL and/or tag so only needs to be declared if it cannot be autodetected correctly.

version "1.2-final"


3204
3205
3206
 
# File 'formula.rb', line 3204

def version(val = nil)
  stable.version(val)
end

.version_scheme(arg = T.unsafe(nil)) ⇒ T.untyped

Parameters:

  • arg (T.untyped) (defaults to: T.unsafe(nil))

Returns:

  • (T.untyped) 


174
 
# File 'sorbet/rbi/parlour.rbi', line 174

def self.version_scheme(arg = T.unsafe(nil)); end

Instance Attribute Details

#alias_name ⇒ String? (readonly)

The name of the alias that was used to identify this Formula. e.g. another-name-for-this-formula

Returns:



86
87
88
 
# File 'formula.rb', line 86

def alias_name
  @alias_name
end

#alias_path ⇒ Pathname? (readonly)

The path to the alias that was used to identify this Formula. e.g. /usr/local/Library/Taps/homebrew/homebrew-core/Aliases/another-name-for-this-formula

Returns:



81
82
83
 
# File 'formula.rb', line 81

def alias_path
  @alias_path
end

#build ⇒ BuildOptions, Tab

The BuildOptions or Tab for this Formula. Lists the arguments passed and any options in the Formula. Note that these may differ at different times during the installation of a Formula. This is annoying but the result of state that we’re trying to eliminate.

Returns:



185
186
187
 
# File 'formula.rb', line 185

def build
  @build
end

#buildpath ⇒ Pathname? (readonly)

The current working directory during builds. Will only be non-nil inside #install.

Returns:



161
162
163
 
# File 'formula.rb', line 161

def buildpath
  @buildpath
end

#follow_installed_alias ⇒ Boolean Also known as: follow_installed_alias?

Whether this formula should be considered outdated if the target of the alias it was installed with has since changed. Defaults to true.

Returns:

  • (Boolean) 


191
192
193
 
# File 'formula.rb', line 191

def follow_installed_alias
  @follow_installed_alias
end

#full_alias_name ⇒ String? (readonly)

The fully-qualified alias referring to this Formula. For core formulae it’s the same as #alias_name. e.g. homebrew/tap-name/another-name-for-this-formula

Returns:



98
99
100
 
# File 'formula.rb', line 98

def full_alias_name
  @full_alias_name
end

#full_name ⇒ String (readonly)

The fully-qualified name of this Formula. For core formulae it’s the same as #name. e.g. homebrew/tap-name/this-formula

Returns:



92
93
94
 
# File 'formula.rb', line 92

def full_name
  @full_name
end

#name ⇒ String (readonly)

The name of this Formula. e.g. this-formula

Returns:



76
77
78
 
# File 'formula.rb', line 76

def name
  @name
end

#path ⇒ Pathname (readonly)

The full path to this Formula. e.g. /usr/local/Library/Taps/homebrew/homebrew-core/Formula/t/this-formula.rb

Returns:



103
104
105
 
# File 'formula.rb', line 103

def path
  @path
end

#revision ⇒ Integer (readonly)

Used for creating new Homebrew versions of software without new upstream versions.

Returns:

  • (Integer)

See Also:



151
152
153
 
# File 'formula.rb', line 151

def revision
  @revision
end

#testpath ⇒ Pathname? (readonly)

The current working directory during tests. Will only be non-nil inside test.

Returns:



166
167
168
 
# File 'formula.rb', line 166

def testpath
  @testpath
end

#version_scheme ⇒ Integer (readonly)

Used to change version schemes for packages.

Returns:

  • (Integer)

See Also:



156
157
158
 
# File 'formula.rb', line 156

def version_scheme
  @version_scheme
end

Class Method Details

.[](name) ⇒ Object 



2028
2029
2030
 
# File 'formula.rb', line 2028

def self.[](name)
  Formulary.factory(name)
end

.conflicts_with(*names) ⇒ Object

One or more formulae that conflict with this one and why.

conflicts_with "imagemagick", because: "both install `convert` binaries"


3450
3451
3452
3453
 
# File 'formula.rb', line 3450

def conflicts_with(*names)
  opts = names.last.is_a?(Hash) ? names.pop : {}
  names.each { |name| conflicts << FormulaConflict.new(name, opts[:because]) }
end

.cxxstdlib_check(check_type) ⇒ Object

Pass :skip to this method to disable post-install stdlib checking.



3484
3485
3486
 
# File 'formula.rb', line 3484

def cxxstdlib_check(check_type)
  define_method(:skip_cxxstdlib_check?) { true } if check_type == :skip
end

.depends_on(dep) ⇒ Object

The dependencies for this formula. Use strings for the names of other formulae. Homebrew provides some :special Requirements for stuff that needs extra handling (often changing some ENV vars or deciding whether to use the system provided version).

:build means this dependency is only needed during build.

depends_on "cmake" => :build

:test means this dependency is only needed during testing.

depends_on "node" => :test

:recommended dependencies are built by default. But a --without-... option is generated to opt-out.

depends_on "readline" => :recommended

:optional dependencies are NOT built by default unless the auto-generated --with-... option is passed.

depends_on "glib" => :optional

If you need to specify that another formula has to be built with/out certain options (note, no -- needed before the option):

depends_on "zeromq" => "with-pgm"
depends_on "qt" => ["with-qtdbus", "developer"] # Multiple options.

Optional and enforce that “boost” is built using --with-c++11.

depends_on "boost" => [:optional, "with-c++11"]

If a dependency is only needed in certain cases:

depends_on "sqlite" if MacOS.version >= :catalina
depends_on xcode: :build # If the formula really needs full Xcode to compile.
depends_on macos: :mojave # Needs at least macOS Mojave (10.14) to run.

It is possible to only depend on something if build.with? or build.without? "another_formula":

depends_on "postgresql" if build.without? "sqlite"


3368
3369
3370
 
# File 'formula.rb', line 3368

def depends_on(dep)
  specs.each { |spec| spec.depends_on(dep) }
end

.deprecate!(date:, because:) ⇒ Object

Deprecates a Formula (on the given date) so a warning is shown on each installation. If the date has not yet passed the formula will not be deprecated.

deprecate! date: "2020-08-27", because: :unmaintained
deprecate! date: "2020-08-27", because: "has been replaced by foo"

See Also:



3653
3654
3655
3656
3657
3658
3659
 
# File 'formula.rb', line 3653

def deprecate!(date:, because:)
  @deprecation_date = Date.parse(date)
  return if @deprecation_date > Date.today

  @deprecation_reason = because
  @deprecated = true
end

.deprecated? ⇒ Boolean

Whether this Formula is deprecated (i.e. warns on installation). Defaults to false.

Returns:

  • (Boolean)

See Also:



3665
3666
3667
 
# File 'formula.rb', line 3665

def deprecated?
  @deprecated == true
end

.disable!(date:, because:) ⇒ Object

Disables a Formula (on the given date) so it cannot be installed. If the date has not yet passed the formula will be deprecated instead of disabled.

disable! date: "2020-08-27", because: :does_not_build
disable! date: "2020-08-27", because: "has been replaced by foo"

See Also:



3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
 
# File 'formula.rb', line 3688

def disable!(date:, because:)
  @disable_date = Date.parse(date)

  if @disable_date > Date.today
    @deprecation_reason = because
    @deprecated = true
    return
  end

  @disable_reason = because
  @disabled = true
end

.disabled? ⇒ Boolean

Whether this Formula is disabled (i.e. cannot be installed). Defaults to false.

Returns:

  • (Boolean)

See Also:



3705
3706
3707
 
# File 'formula.rb', line 3705

def disabled?
  @disabled == true
end

.fails_with(compiler, &block) ⇒ Object

Marks the Formula as failing with a particular compiler so it will fall back to others. For Apple compilers, this should be in the format:

fails_with :clang do
  build 600
  cause "multiple configure and compile errors"
end

The block may be omitted, and if present the build may be omitted; if so, then the compiler will not be allowed for all versions.

major_version should be the major release number only, for instance ‘7’ for the GCC 7 series (7.0, 7.1, etc.). If version or the block is omitted, then the compiler will not be allowed for all compilers in that series.

For example, if a bug is only triggered on GCC 7.1 but is not encountered on 7.2:

fails_with :gcc => '7' do
  version '7.1'
end


3509
3510
3511
 
# File 'formula.rb', line 3509

def fails_with(compiler, &block)
  specs.each { |spec| spec.fails_with(compiler, &block) }
end

.freeze ⇒ Object 



3043
3044
3045
3046
3047
3048
3049
3050
 
# File 'formula.rb', line 3043

def freeze
  specs.each(&:freeze)
  @livecheck.freeze
  @conflicts.freeze
  @skip_clean_paths.freeze
  @link_overwrite_paths.freeze
  super
end

.go_resource(name, &block) ⇒ Object 



3327
3328
3329
3330
 
# File 'formula.rb', line 3327

def go_resource(name, &block)
  # odeprecated "Formula#go_resource", "Go modules"
  specs.each { |spec| spec.go_resource(name, &block) }
end

.inherited(child) ⇒ Object

Initialise instance variables for each subclass. These need to be initialised before the class is frozen, and some DSL may never be called so it can’t be done lazily.



3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
 
# File 'formula.rb', line 3018

def inherited(child)
  super
  child.instance_eval do
    # Ensure this is synced with `freeze`
    @stable = SoftwareSpec.new(flags: build_flags)
    @head = HeadSoftwareSpec.new(flags: build_flags)
    @livecheck = Livecheck.new(self)
    @conflicts = []
    @skip_clean_paths = Set.new
    @link_overwrite_paths = Set.new
    @loaded_from_api = false
  end
end

.installed_with_alias_path(alias_path) ⇒ Object 



1985
1986
1987
1988
1989
 
# File 'formula.rb', line 1985

def self.installed_with_alias_path(alias_path)
  return [] if alias_path.nil?

  installed.select { |f| f.installed_alias_path == alias_path }
end

.keg_only(reason, explanation = "") ⇒ Object

Software that will not be symlinked into the brew --prefix and will only live in its Cellar. Other formulae can depend on it and Homebrew will add the necessary includes, libraries, and other paths while building that other formula.

Keg-only formulae are not in your PATH and are not seen by compilers if you build your own software outside of Homebrew. This way, we don’t shadow software provided by macOS.

keg_only :provided_by_macos
keg_only :versioned_formulae
keg_only "because I want it so"


3479
3480
3481
 
# File 'formula.rb', line 3479

def keg_only(reason, explanation = "")
  @keg_only_reason = KegOnlyReason.new(reason, explanation)
end

.link_overwrite(*paths) ⇒ Object

Permit overwriting certain files while linking.

Sometimes we accidentally install files outside prefix. Once we fix that, users will get a link conflict error. Overwrite those files with:

link_overwrite "bin/foo", "lib/bar"
link_overwrite "share/man/man1/baz-*"


3727
3728
3729
3730
 
# File 'formula.rb', line 3727

def link_overwrite(*paths)
  paths.flatten!
  link_overwrite_paths.merge(paths)
end

.livecheckable? ⇒ Boolean

Whether a livecheck specification is defined or not. It returns true when a livecheck block is present in the Formula and false otherwise, and is used by livecheck.

Returns:

  • (Boolean) 


3118
3119
3120
 
# File 'formula.rb', line 3118

def livecheckable?
  @livecheckable == true
end

.loaded_from_api? ⇒ Boolean

Returns:

  • (Boolean) 


159
 
# File 'sorbet/rbi/parlour.rbi', line 159

def self.loaded_from_api?; end

.needs(*standards) ⇒ Object

Marks the Formula as needing a certain standard, so Homebrew will fall back to other compilers if the default compiler does not implement that standard.

We generally prefer to depends_on a desired compiler and to explicitly use that compiler in a formula’s #install block, rather than implicitly finding a suitable compiler with needs.

See Also:



3522
3523
3524
 
# File 'formula.rb', line 3522

def needs(*standards)
  specs.each { |spec| spec.needs(*standards) }
end

.on_macos(&block) ⇒ Object

This method is included by OnSystem



8
 
# File 'formula.rbi', line 8

def self.on_macos(&block); end

.on_system_blocks_exist? ⇒ Boolean

Returns:

  • (Boolean) 


6
 
# File 'formula.rbi', line 6

def self.on_system_blocks_exist?; end

.patch(strip = :p1, src = nil, &block) ⇒ Object

External patches can be declared using resource-style blocks.

patch do
  url "https://example.com/example_patch.diff"
  sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
end

A strip level of -p1 is assumed. It can be overridden using a symbol argument:

patch :p0 do
  url "https://example.com/example_patch.diff"
  sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
end

Patches can be declared in stable and head blocks. This form is preferred over using conditionals.

stable do
  patch do
    url "https://example.com/example_patch.diff"
    sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
  end
end

Embedded (__END__) patches are declared like so:

patch :DATA
patch :p0, :DATA

Patches can also be embedded by passing a string. This makes it possible to provide multiple embedded patches while making only some of them conditional.

patch :p0, "..."

See Also:



3444
3445
3446
 
# File 'formula.rb', line 3444

def patch(strip = :p1, src = nil, &block)
  specs.each { |spec| spec.patch(strip, src, &block) }
end

.pour_bottle?(only_if: nil, &block) ⇒ Boolean

Defines whether the Formula’s bottle can be used on the given Homebrew installation.

For example, if the bottle requires the Xcode CLT to be installed a Formula would declare:

pour_bottle? do
  reason "The bottle needs the Xcode CLT to be installed."
  satisfy { MacOS::CLT.installed? }
end

If satisfy returns false then a bottle will not be used and instead the Formula will be built from source and reason will be printed.

Alternatively, a preset reason can be passed as a symbol:

pour_bottle? only_if: :clt_installed

Returns:

  • (Boolean) 


3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
 
# File 'formula.rb', line 3607

def pour_bottle?(only_if: nil, &block)
  @pour_bottle_check = PourBottleCheck.new(self)
  @pour_bottle_only_if = only_if

  if only_if.present? && block.present?
    raise ArgumentError, "Do not pass both a preset condition and a block to `pour_bottle?`"
  end

  block ||= case only_if
  when :clt_installed
    lambda do |_|
      on_macos do
        T.bind(self, PourBottleCheck)
        reason(+<<~EOS)
          The bottle needs the Apple Command Line Tools to be installed.
            You can install them, if desired, with:
              xcode-select --install
        EOS
        satisfy { MacOS::CLT.installed? }
      end
    end
  when :default_prefix
    lambda do |_|
      T.bind(self, PourBottleCheck)
      reason(+<<~EOS)
        The bottle (and many others) needs to be installed into #{Homebrew::DEFAULT_PREFIX}.
      EOS
      satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX }
    end
  else
    raise ArgumentError, "Invalid preset `pour_bottle?` condition" if only_if.present?
  end

  @pour_bottle_check.instance_eval(&block)
end

.resource(name, klass = Resource, &block) ⇒ Object

Additional downloads can be defined as resources and accessed in the install method. Resources can also be defined inside a stable or head block. This mechanism replaces ad-hoc “subformula” classes.

resource "additional_files" do
  url "https://example.com/additional-stuff.tar.gz"
  sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
end


3321
3322
3323
3324
3325
 
# File 'formula.rb', line 3321

def resource(name, klass = Resource, &block)
  specs.each do |spec|
    spec.resource(name, klass, &block) unless spec.resource_defined?(name)
  end
end

.service? ⇒ Boolean

Whether a service specification is defined or not. It returns true when a service block is present in the Formula and false otherwise, and is used by service.

Returns:

  • (Boolean) 


3126
3127
3128
 
# File 'formula.rb', line 3126

def service?
  @service_block.present?
end

.skip_clean(*paths) ⇒ Object

Skip cleaning paths in a formula.

Sometimes the formula cleaner breaks things. Preserve cleaned paths with:

skip_clean "bin/foo", "lib/bar"

Keep .la files with:

skip_clean :la


3462
3463
3464
3465
3466
 
# File 'formula.rb', line 3462

def skip_clean(*paths)
  paths.flatten!
  # Specifying :all is deprecated and will become an error
  skip_clean_paths.merge(paths)
end

.test(&block) ⇒ Boolean

A test is required for new formulae and makes us happy. The block will create, run in and delete a temporary directory.

We want tests that don’t require any user input and test the basic functionality of the application. For example, foo build-foo input.foo is a good test and foo --version or foo --help are bad tests. However, a bad test is better than no test at all.

(testpath/"test.file").write <<~EOS
  writing some test file, if you need to
EOS
assert_equal "OK", shell_output("test_command test.file").strip

Need complete control over stdin, stdout?

require "open3"
Open3.popen3("#{bin}/example", "argument") do |stdin, stdout, _|
  stdin.write("some text")
  stdin.close
  assert_equal "result", stdout.read
end

The test will fail if it returns false, or if an exception is raised. Failed assertions and failed system commands will raise exceptions.

Returns:

  • (Boolean)

See Also:



3554
3555
3556
 
# File 'formula.rb', line 3554

def test(&block)
  define_method(:test, &block)
end

.uses_from_macos(dep, bounds = {}) ⇒ void

This method returns an undefined value.

Indicates use of dependencies provided by macOS. On macOS this is a no-op (as we use the provided system libraries) unless :since specifies a minimum macOS version. On Linux this will act as depends_on.

Parameters:



3382
3383
3384
 
# File 'formula.rb', line 3382

def uses_from_macos(dep, bounds = {})
  specs.each { |spec| spec.uses_from_macos(dep, bounds) }
end

Instance Method Details

#active_log_prefix ⇒ String

The prefix, if any, to use in filenames for logging current activity.

Returns:



1052
1053
1054
1055
1056
1057
1058
 
# File 'formula.rb', line 1052

def active_log_prefix
  if active_log_type
    "#{active_log_type}."
  else
    ""
  end
end

#add_global_deps_to_spec(spec) ⇒ void

This method returns an undefined value.

Parameters:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'extend/os/linux/formula.rb', line 30

def add_global_deps_to_spec(spec)
  return unless DevelopmentTools.needs_build_formulae?

  @global_deps ||= begin
    dependency_collector = spec.dependency_collector
    related_formula_names = Set.new([
      name,
      *aliases,
      *versioned_formulae_names,
    ])
    [
      dependency_collector.gcc_dep_if_needed(related_formula_names),
      dependency_collector.glibc_dep_if_needed(related_formula_names),
    ].compact.freeze
  end
  @global_deps.each { |dep| spec.dependency_collector.add(dep) }
end

#alias_changed? ⇒ Boolean

Has the alias used to install the formula changed, or are different formulae already installed with this alias?

Returns:

  • (Boolean) 


1544
1545
1546
 
# File 'formula.rb', line 1544

def alias_changed?
  installed_alias_target_changed? || supersedes_an_installed_formula?
end

#aliases ⇒ Array<String>

All aliases for the formula.

Returns:



564
565
566
 
# File 'formula.rb', line 564

def aliases
  @aliases ||= tap&.alias_reverse_table&.dig(full_name)&.map { _1.split("/").last } || []
end

#any_installed_prefix ⇒ Object 



2100
2101
2102
2103
2104
2105
2106
 
# File 'formula.rb', line 2100

def any_installed_prefix
  if optlinked? && opt_prefix.exist?
    opt_prefix
  elsif (latest_installed_prefix = installed_prefixes.last)
    latest_installed_prefix
  end
end

#any_installed_version ⇒ Object

Returns the PkgVersion for this formula if it is installed. If not, return nil.



2110
2111
2112
 
# File 'formula.rb', line 2110

def any_installed_version
  any_installed_keg&.version
end

#bash_completion ⇒ Pathname

The directory where the formula’s Bash completion files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



1012
1013
1014
 
# File 'formula.rb', line 1012

def bash_completion
  prefix/"etc/bash_completion.d"
end

#bin ⇒ Pathname

The directory where the formula’s binaries should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Need to install into the #bin but the makefile doesn’t mkdir -p prefix/bin?

bin.mkpath

No make install available?

bin.install "binary1"

Returns:



758
759
760
 
# File 'formula.rb', line 758

def bin
  prefix/"bin"
end

#bottle_defined?(*args, **options, &block) ⇒ Boolean

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


36
 
# File 'sorbet/rbi/parlour.rbi', line 36

def bottle_defined?(*args, **options, &block); end

#bottle_hash(compact_for_api: false) ⇒ Object

Returns the bottle information for a formula.



2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
 
# File 'formula.rb', line 2412

def bottle_hash(compact_for_api: false)
  bottle_spec = T.must(stable).bottle_specification

  hash = {}
  hash["rebuild"] = bottle_spec.rebuild if !compact_for_api || !bottle_spec.rebuild.zero?
  hash["root_url"] = bottle_spec.root_url unless compact_for_api
  hash["files"] = {}

  bottle_spec.collector.each_tag do |tag|
    tag_spec = bottle_spec.collector.specification_for(tag, no_older_versions: true)
    os_cellar = tag_spec.cellar
    os_cellar = os_cellar.inspect if os_cellar.is_a?(Symbol)
    checksum = tag_spec.checksum.hexdigest

    file_hash = {}
    file_hash["cellar"] = os_cellar
    unless compact_for_api
      filename = Bottle::Filename.create(self, tag, bottle_spec.rebuild)
      path, = Utils::Bottles.path_resolved_basename(bottle_spec.root_url, name, checksum, filename)
      file_hash["url"] = "#{bottle_spec.root_url}/#{path}"
    end
    file_hash["sha256"] = checksum

    hash["files"][tag.to_sym] = file_hash
  end
  hash
end

#bottle_specification(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


45
 
# File 'sorbet/rbi/parlour.rbi', line 45

def bottle_specification(*args, **options, &block); end

#bottle_tab_attributes ⇒ Hash

Returns:



2920
2921
2922
2923
2924
 
# File 'formula.rb', line 2920

def bottle_tab_attributes
  return {} unless bottled?

  T.must(bottle).tab_attributes
end

#bottle_tag?(*args, **options, &block) ⇒ Boolean

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


39
 
# File 'sorbet/rbi/parlour.rbi', line 39

def bottle_tag?(*args, **options, &block); end

#bottled?(*args, **options, &block) ⇒ Boolean

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


42
 
# File 'sorbet/rbi/parlour.rbi', line 42

def bottled?(*args, **options, &block); end

#cached_download(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


93
 
# File 'sorbet/rbi/parlour.rbi', line 93

def cached_download(*args, **options, &block); end

#caveats ⇒ String?

Warn the user about any Homebrew-specific issues or quirks for this package. These should not contain setup instructions that would apply to installation through a different package manager on a different OS.

def caveats
  <<~EOS
    Are optional. Something the user must be warned about?
  EOS
end
def caveats
  s = <<~EOS
    Print some important notice to the user when `brew info [formula]` is
    called or when brewing a formula.
    This is optional. You can use all the vars like #{version} here.
  EOS
  s += "Some issue only on older systems" if MacOS.version < :el_capitan
  s
end

Returns:



1281
1282
1283
 
# File 'formula.rb', line 1281

def caveats
  nil
end

#clear_cache(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


96
 
# File 'sorbet/rbi/parlour.rbi', line 96

def clear_cache(*args, **options, &block); end

#compiler_failures(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


111
 
# File 'sorbet/rbi/parlour.rbi', line 111

def compiler_failures(*args, **options, &block); end

#conflicts(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


156
 
# File 'sorbet/rbi/parlour.rbi', line 156

def conflicts(*args, **options, &block); end

#current_installed_alias_target ⇒ Object 



1521
1522
1523
 
# File 'formula.rb', line 1521

def current_installed_alias_target
  Formulary.factory(T.must(installed_alias_name)) if installed_alias_path
end

#declared_deps(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


81
 
# File 'sorbet/rbi/parlour.rbi', line 81

def declared_deps(*args, **options, &block); end

#deprecated? ⇒ Boolean

Whether this Formula is deprecated (i.e. warns on installation). Defaults to false.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean)

See Also:



1349
 
# File 'formula.rb', line 1349

delegate deprecated?: :"self.class"

#deprecated_flags(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


105
 
# File 'sorbet/rbi/parlour.rbi', line 105

def deprecated_flags(*args, **options, &block); end

#deprecated_options(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


102
 
# File 'sorbet/rbi/parlour.rbi', line 102

def deprecated_options(*args, **options, &block); end

#deprecation_date ⇒ T.untyped

The date that this Formula was or becomes deprecated. Returns nil if no date is specified.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) —

    Date

See Also:



1356
 
# File 'formula.rb', line 1356

delegate deprecation_date: :"self.class"

#deprecation_reason ⇒ T.untyped

The reason this Formula is deprecated. Returns nil if no reason is specified or the formula is not deprecated.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



1363
 
# File 'formula.rb', line 1363

delegate deprecation_reason: :"self.class"

#deps(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


78
 
# File 'sorbet/rbi/parlour.rbi', line 78

def deps(*args, **options, &block); end

#desc ⇒ T.untyped

The description of the software.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



428
 
# File 'formula.rb', line 428

delegate desc: :"self.class"

#deuniversalize_machos(*targets) ⇒ void

This method returns an undefined value.

Replaces a universal binary with its native slice.

If called with no parameters, does this with all compatible universal binaries in a Formula’s Keg.

Parameters:



27
 
# File 'extend/os/linux/formula.rb', line 27

def deuniversalize_machos(*targets); end

#disable_date ⇒ T.untyped

The date that this Formula was or becomes disabled. Returns nil if no date is specified.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) —

    Date

See Also:



1377
 
# File 'formula.rb', line 1377

delegate disable_date: :"self.class"

#disable_reason ⇒ T.untyped

The reason this Formula is disabled. Returns nil if no reason is specified or the formula is not disabled.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



1384
 
# File 'formula.rb', line 1384

delegate disable_reason: :"self.class"

#disabled? ⇒ Boolean

Whether this Formula is disabled (i.e. cannot be installed). Defaults to false.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean)

See Also:



1370
 
# File 'formula.rb', line 1370

delegate disabled?: :"self.class"

#doc ⇒ Pathname

The directory where the formula’s documentation should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



766
767
768
 
# File 'formula.rb', line 766

def doc
  share/"doc"/name
end

#downloader(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


48
 
# File 'sorbet/rbi/parlour.rbi', line 48

def downloader(*args, **options, &block); end

#elisp ⇒ Pathname

The directory where Emacs Lisp files should be installed, with the formula name appended to avoid linking conflicts.

To install an Emacs mode included with a software package:

elisp.install "contrib/emacs/example-mode.el"

Returns:



940
941
942
 
# File 'formula.rb', line 940

def elisp
  prefix/"share/emacs/site-lisp"/name
end

#env(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


153
 
# File 'sorbet/rbi/parlour.rbi', line 153

def env(*args, **options, &block); end

#etc ⇒ Pathname

The directory where the formula’s configuration files should be installed. Anything using etc.install will not overwrite other files on e.g. upgrades but will write a new file named *.default. This directory is not inside the HOMEBREW_CELLAR so it persists across upgrades.

Returns:



968
969
970
 
# File 'formula.rb', line 968

def etc
  (HOMEBREW_PREFIX/"etc").extend(InstallRenamed)
end

#fetch_bottle_tab ⇒ void

This method returns an undefined value.



2913
2914
2915
2916
2917
 
# File 'formula.rb', line 2913

def fetch_bottle_tab
  return unless bottled?

  T.must(bottle).fetch_tab
end

#fetch_patches ⇒ Object 



2908
2909
2910
 
# File 'formula.rb', line 2908

def fetch_patches
  patchlist.select(&:external?).each(&:fetch)
end

#fish_completion ⇒ Pathname

The directory where the formula’s fish completion files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



1030
1031
1032
 
# File 'formula.rb', line 1030

def fish_completion
  share/"fish/vendor_completions.d"
end

#fish_function ⇒ Pathname

The directory where the formula’s fish function files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



1003
1004
1005
 
# File 'formula.rb', line 1003

def fish_function
  share/"fish/vendor_functions.d"
end

#frameworks ⇒ Pathname

The directory where the formula’s Frameworks should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only. This is not symlinked into HOMEBREW_PREFIX.

Returns:



949
950
951
 
# File 'formula.rb', line 949

def frameworks
  prefix/"Frameworks"
end

#full_installed_alias_name ⇒ Object 



347
348
349
 
# File 'formula.rb', line 347

def full_installed_alias_name
  full_name_with_optional_tap(installed_alias_name)
end

#full_installed_specified_name ⇒ Object

The name (including tap) specified to install this formula.



378
379
380
 
# File 'formula.rb', line 378

def full_installed_specified_name
  full_installed_alias_name || full_name
end

#full_specified_name ⇒ Object

The name (including tap) specified to find this formula.



368
369
370
 
# File 'formula.rb', line 368

def full_specified_name
  full_alias_name || full_name
end

#generate_completions_from_executable(*commands, base_name: name, shells: [:bash, :zsh, :fish], shell_parameter_format: nil) ⇒ void

This method returns an undefined value.

Generate shell completions for a formula for bash, zsh, and fish, using the formula’s executable.

Examples:

Using default values for optional arguments

generate_completions_from_executable(bin/"foo", "completions")

# translates to
(bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
(zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")
(fish_completion/"foo.fish").write Utils.safe_popen_read({ "SHELL" => "fish" }, bin/"foo",
                                                         "completions", "fish")

Selecting shells and using a different base_name

generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar")

# translates to
(bash_completion/"bar").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
(zsh_completion/"_bar").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")

Using predefined shell_parameter_format :flag

generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :flag, shells: [:bash])

# translates to
(bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "--bash")

Using predefined shell_parameter_format :arg

generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :arg, shells: [:bash])

# translates to
(bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
                                                    "completions", "--shell=bash")

Using predefined shell_parameter_format :none

generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :none, shells: [:bash])

# translates to
(bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions")

Using predefined shell_parameter_format :click

generate_completions_from_executable(bin/"foo", shell_parameter_format: :click, shells: [:zsh])

# translates to
(zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh", "_FOO_COMPLETE" => "zsh_source" },
                                                    bin/"foo")

Using custom shell_parameter_format

generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: "--selected-shell=",
                                     shells: [:bash])

# translates to
(bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
                                                    "completions", "--selected-shell=bash")

Parameters:

  • commands (Pathname, String) —

    the path to the executable and any passed subcommand(s) to use for generating the completion scripts.

  • base_name (String) (defaults to: name) —

    the base name of the generated completion script. Defaults to the formula name.

  • shells (Array<Symbol>) (defaults to: [:bash, :zsh, :fish]) —

    the shells to generate completion scripts for. Defaults to [:bash, :zsh, :fish].

  • shell_parameter_format (Symbol, String, nil) (defaults to: nil) —

    specify how shells should each be passed to the executable. Takes either a String representing a prefix, or one of [:flag, :arg, :none, :click]. Defaults to plainly passing the shell.



1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
 
# File 'formula.rb', line 1865

def generate_completions_from_executable(*commands,
                                         base_name: name,
                                         shells: [:bash, :zsh, :fish],
                                         shell_parameter_format: nil)
  completion_script_path_map = {
    bash: bash_completion/base_name,
    zsh:  zsh_completion/"_#{base_name}",
    fish: fish_completion/"#{base_name}.fish",
  }

  shells.each do |shell|
    popen_read_env = { "SHELL" => shell.to_s }
    script_path = completion_script_path_map[shell]
    shell_parameter = if shell_parameter_format.nil?
      shell.to_s
    elsif shell_parameter_format == :flag
      "--#{shell}"
    elsif shell_parameter_format == :arg
      "--shell=#{shell}"
    elsif shell_parameter_format == :none
      nil
    elsif shell_parameter_format == :click
      prog_name = File.basename(commands.first.to_s).upcase.tr("-", "_")
      popen_read_env["_#{prog_name}_COMPLETE"] = "#{shell}_source"
      nil
    else
      "#{shell_parameter_format}#{shell}"
    end

    popen_read_args = %w[]
    popen_read_args << commands
    popen_read_args << shell_parameter if shell_parameter.present?
    popen_read_args.flatten!

    popen_read_options = {}
    popen_read_options[:err] = :err unless ENV["HOMEBREW_STDERR"]

    script_path.dirname.mkpath
    script_path.write Utils.safe_popen_read(popen_read_env, *popen_read_args, **popen_read_options)
  end
end

#head_version_outdated?(version, fetch_head: false) ⇒ Boolean

Returns:

  • (Boolean) 


657
658
659
660
661
662
663
664
665
666
667
668
669
670
 
# File 'formula.rb', line 657

def head_version_outdated?(version, fetch_head: false)
  tab = Tab.for_keg(prefix(version))

  return true if tab.version_scheme < version_scheme
  return true if stable && tab.stable_version && tab.stable_version < T.must(stable).version
  return false unless fetch_head
  return false unless head&.downloader.is_a?(VCSDownloadStrategy)

  downloader = T.must(head).downloader

  with_context quiet: true do
    downloader.commit_outdated?(version.version.commit)
  end
end

#homepage ⇒ T.untyped

The homepage for the software.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



438
 
# File 'formula.rb', line 438

delegate homepage: :"self.class"

#include ⇒ Pathname

The directory where the formula’s headers should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

No make install available?

include.install "example.h"

Returns:



777
778
779
 
# File 'formula.rb', line 777

def include
  prefix/"include"
end

#info ⇒ Pathname

The directory where the formula’s info files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



785
786
787
 
# File 'formula.rb', line 785

def info
  share/"info"
end

#inreplace(paths, before = nil, after = nil, audit_result = true, &block) ⇒ void

This method returns an undefined value.

Sometimes we have to change a bit before we install. Mostly we prefer a patch, but if you need the prefix of this formula in the patch you have to resort to inreplace, because in the patch you don’t have access to any variables defined by the formula, as only HOMEBREW_PREFIX is available in the embedded patch.

inreplace supports regular expressions:

inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"

inreplace supports blocks:

inreplace "Makefile" do |s|
  s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s
end

Parameters:

See Also:



2663
2664
2665
2666
2667
2668
 
# File 'formula.rb', line 2663

def inreplace(paths, before = nil, after = nil, audit_result = true, &block) # rubocop:disable Style/OptionalBooleanParameter
  Utils::Inreplace.inreplace(paths, before, after, audit_result:, &block)
rescue Utils::Inreplace::Error => e
  onoe e.to_s
  raise BuildError.new(self, "inreplace", Array(paths), {})
end

#install ⇒ Object

This method is overridden in Formula subclasses to provide the installation instructions. The sources (from url) are downloaded, hash-checked and then Homebrew changes into a temporary directory where the archive is unpacked or repository cloned.

def install
  system "./configure", "--prefix=#{prefix}"
  system "make", "install"
end


2634
 
# File 'formula.rb', line 2634

def install; end

#installed_alias_name ⇒ String?

Returns:



343
344
345
 
# File 'formula.rb', line 343

def installed_alias_name
  installed_alias_path&.basename&.to_s
end

#installed_alias_path ⇒ Pathname?

The alias path that was used to install this formula, if it exists. Can differ from #alias_path, which is the alias used to find the formula, and is specified to this instance.

Returns:



330
331
332
333
334
335
336
337
338
339
340
 
# File 'formula.rb', line 330

def installed_alias_path
  build_tab = build
  path = build_tab.source["path"] if build_tab.is_a?(Tab)

  return unless path&.match?(%r{#{HOMEBREW_TAP_DIR_REGEX}/Aliases}o)

  path = Pathname(path)
  return unless path.symlink?

  path
end

#installed_alias_target_changed? ⇒ Boolean

Has the target of the alias used to install this formula changed? Returns false if the formula wasn’t installed with an alias.

Returns:

  • (Boolean) 


1528
1529
1530
1531
1532
1533
 
# File 'formula.rb', line 1528

def installed_alias_target_changed?
  target = current_installed_alias_target
  return false unless target

  target.name != name
end

#installed_specified_name ⇒ Object

The name specified to install this formula.



373
374
375
 
# File 'formula.rb', line 373

def installed_specified_name
  installed_alias_name || name
end

#keg_only? ⇒ Boolean

Rarely, you don’t want your library symlinked into the main prefix. See gettext.rb for an example.

Returns:

  • (Boolean)

See Also:



1289
1290
1291
1292
1293
 
# File 'formula.rb', line 1289

def keg_only?
  return false unless keg_only_reason

  keg_only_reason.applicable?
end

#keg_only_reason(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


117
 
# File 'sorbet/rbi/parlour.rbi', line 117

def keg_only_reason(*args, **options, &block); end

#kext_prefix ⇒ Pathname

The directory where the formula’s kernel extensions should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only. This is not symlinked into HOMEBREW_PREFIX.

Returns:



958
959
960
 
# File 'formula.rb', line 958

def kext_prefix
  prefix/"Library/Extensions"
end

#latest_formula ⇒ Object

If the alias has changed value, return the new formula. Otherwise, return self.



1550
1551
1552
 
# File 'formula.rb', line 1550

def latest_formula
  installed_alias_target_changed? ? current_installed_alias_target : self
end

#latest_head_prefix ⇒ Object 



652
653
654
655
 
# File 'formula.rb', line 652

def latest_head_prefix
  head_version = latest_head_version
  prefix(head_version) if head_version
end

#latest_head_version ⇒ Object 



641
642
643
644
645
646
647
648
649
650
 
# File 'formula.rb', line 641

def latest_head_version
  head_versions = installed_prefixes.filter_map do |pn|
    pn_pkgversion = PkgVersion.parse(pn.basename.to_s)
    pn_pkgversion if pn_pkgversion.head?
  end

  head_versions.max_by do |pn_pkgversion|
    [Tab.for_keg(prefix(pn_pkgversion)).source_modified_time, pn_pkgversion.revision]
  end
end

#launchd_service_path ⇒ Pathname

The generated launchd service file path.

Returns:



1116
1117
1118
 
# File 'formula.rb', line 1116

def launchd_service_path
  opt_prefix/"#{plist_name}.plist"
end

#lib ⇒ Pathname

The directory where the formula’s libraries should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

No make install available?

lib.install "example.dylib"

Returns:



796
797
798
 
# File 'formula.rb', line 796

def lib
  prefix/"lib"
end

#libexec ⇒ Pathname

The directory where the formula’s binaries should be installed. This is not symlinked into HOMEBREW_PREFIX. It is commonly used to install files that we do not wish to be symlinked into HOMEBREW_PREFIX from one of the other directories and instead manually create symlinks or wrapper scripts into e.g. #bin.

libexec.install "foo.jar"
bin.write_jar_script libexec/"foo.jar", "foo"

Returns:



809
810
811
 
# File 'formula.rb', line 809

def libexec
  prefix/"libexec"
end

#license ⇒ T.untyped

The SPDX ID of the software license.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



433
 
# File 'formula.rb', line 433

delegate license: :"self.class"

#linked? ⇒ Boolean

Is the formula linked?

Returns:

  • (Boolean) 


700
701
702
 
# File 'formula.rb', line 700

def linked?
  linked_keg.symlink?
end

#linked_version ⇒ PkgVersion?

PkgVersion of the linked keg for the formula.

Returns:



719
720
721
722
723
 
# File 'formula.rb', line 719

def linked_version
  return unless linked?

  Keg.for(linked_keg).version
end

#livecheck ⇒ T.untyped

The livecheck specification for the software.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



443
 
# File 'formula.rb', line 443

delegate livecheck: :"self.class"

#livecheckable? ⇒ Boolean

Is a livecheck specification defined for the software?

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean)

See Also:



448
 
# File 'formula.rb', line 448

delegate livecheckable?: :"self.class"

#loader_path ⇒ String

Returns:



22
23
24
 
# File 'extend/os/linux/formula.rb', line 22

def loader_path
  "$ORIGIN"
end

#man ⇒ Pathname

The root directory where the formula’s manual pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only. Often one of the more specific man functions should be used instead, e.g. #man1.

Returns:



819
820
821
 
# File 'formula.rb', line 819

def man
  share/"man"
end

#man1 ⇒ Pathname

The directory where the formula’s man1 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

No make install available?

man1.install "example.1"

Returns:



830
831
832
 
# File 'formula.rb', line 830

def man1
  man/"man1"
end

#man2 ⇒ Pathname

The directory where the formula’s man2 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



838
839
840
 
# File 'formula.rb', line 838

def man2
  man/"man2"
end

#man3 ⇒ Pathname

The directory where the formula’s man3 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

No make install available?

man3.install "man.3"

Returns:



849
850
851
 
# File 'formula.rb', line 849

def man3
  man/"man3"
end

#man4 ⇒ Pathname

The directory where the formula’s man4 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



857
858
859
 
# File 'formula.rb', line 857

def man4
  man/"man4"
end

#man5 ⇒ Pathname

The directory where the formula’s man5 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



865
866
867
 
# File 'formula.rb', line 865

def man5
  man/"man5"
end

#man6 ⇒ Pathname

The directory where the formula’s man6 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



873
874
875
 
# File 'formula.rb', line 873

def man6
  man/"man6"
end

#man7 ⇒ Pathname

The directory where the formula’s man7 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



881
882
883
 
# File 'formula.rb', line 881

def man7
  man/"man7"
end

#man8 ⇒ Pathname

The directory where the formula’s man8 pages should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



889
890
891
 
# File 'formula.rb', line 889

def man8
  man/"man8"
end

#migration_needed? ⇒ Boolean

Returns:

  • (Boolean) 


1476
1477
1478
 
# File 'formula.rb', line 1476

def migration_needed?
  !oldnames_to_migrate.empty? && !rack.exist?
end

#missing_dependencies(hide: nil) ⇒ Object

Returns a list of formulae depended on by this formula that aren’t installed.



2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
 
# File 'formula.rb', line 2171

def missing_dependencies(hide: nil)
  hide ||= []
  runtime_formula_dependencies.select do |f|
    hide.include?(f.name) || f.installed_prefixes.empty?
  end
# If we're still getting unavailable formulae at this stage the best we can
# do is just return no results.
rescue FormulaUnavailableError
  []
end

#mkdir(name, &block) ⇒ Object

A version of FileUtils.mkdir that also changes to that folder in a block.



2889
2890
2891
2892
2893
2894
 
# File 'formula.rb', line 2889

def mkdir(name, &block)
  result = FileUtils.mkdir_p(name)
  return result unless block

  FileUtils.chdir(name, &block)
end

#mktemp(prefix = name, opts = {}, &block) ⇒ Object

Create a temporary directory then yield. When the block returns, recursively delete the temporary directory. Passing opts[:retain] or calling do |staging| ... staging.retain! in the block will skip the deletion and retain the temporary directory’s contents.



2883
2884
2885
 
# File 'formula.rb', line 2883

def mktemp(prefix = name, opts = {}, &block)
  Mktemp.new(prefix, opts).run(&block)
end

#new_formula_available? ⇒ Boolean

Returns:

  • (Boolean) 


1517
1518
1519
 
# File 'formula.rb', line 1517

def new_formula_available?
  installed_alias_target_changed? && !latest_formula.latest_version_installed?
end

#old_installed_formulae ⇒ Object 



1554
1555
1556
1557
1558
1559
1560
1561
 
# File 'formula.rb', line 1554

def old_installed_formulae
  # If this formula isn't the current target of the alias,
  # it doesn't make sense to say that other formulae are older versions of it
  # because we don't know which came first.
  return [] if alias_path.nil? || installed_alias_target_changed?

  self.class.installed_with_alias_path(alias_path).reject { |f| f.name == name }
end

#oldname ⇒ String?

Deprecated.

Use #oldnames instead.

An old name for the formula.

Returns:



546
547
548
549
 
# File 'formula.rb', line 546

def oldname
  odisabled "Formula#oldname", "Formula#oldnames"
  @oldname ||= oldnames.first
end

#oldnames ⇒ Array<String>

Old names for the formula.

Returns:



553
554
555
556
557
558
559
560
 
# File 'formula.rb', line 553

def oldnames
  @oldnames ||= if (tap = self.tap)
    Tap.tap_migration_oldnames(tap, name) +
      tap.formula_reverse_renames.fetch(name, [])
  else
    []
  end
end

#opt_bin ⇒ Pathname

Returns:



1150
1151
1152
 
# File 'formula.rb', line 1150

def opt_bin
  opt_prefix/"bin"
end

#opt_elisp ⇒ Pathname

Returns:



1185
1186
1187
 
# File 'formula.rb', line 1185

def opt_elisp
  opt_prefix/"share/emacs/site-lisp"/name
end

#opt_frameworks ⇒ Pathname

Returns:



1190
1191
1192
 
# File 'formula.rb', line 1190

def opt_frameworks
  opt_prefix/"Frameworks"
end

#opt_include ⇒ Pathname

Returns:



1155
1156
1157
 
# File 'formula.rb', line 1155

def opt_include
  opt_prefix/"include"
end

#opt_lib ⇒ Pathname

Returns:



1160
1161
1162
 
# File 'formula.rb', line 1160

def opt_lib
  opt_prefix/"lib"
end

#opt_libexec ⇒ Pathname

Returns:



1165
1166
1167
 
# File 'formula.rb', line 1165

def opt_libexec
  opt_prefix/"libexec"
end

#opt_pkgshare ⇒ Pathname

Returns:



1180
1181
1182
 
# File 'formula.rb', line 1180

def opt_pkgshare
  opt_prefix/"share"/name
end

#opt_prefix ⇒ Pathname

A stable path for this formula, when installed. Contains the formula name but no version number. Only the active version will be linked here if multiple versions are installed.

This is the preferred way to refer to a formula in plists or from another formula, as the path is stable even when the software is updated.

args << "--with-readline=#{Formula["readline"].opt_prefix}" if build.with? "readline"

Returns:



1145
1146
1147
 
# File 'formula.rb', line 1145

def opt_prefix
  HOMEBREW_PREFIX/"opt"/name
end

#opt_sbin ⇒ Pathname

Returns:



1170
1171
1172
 
# File 'formula.rb', line 1170

def opt_sbin
  opt_prefix/"sbin"
end

#opt_share ⇒ Pathname

Returns:



1175
1176
1177
 
# File 'formula.rb', line 1175

def opt_share
  opt_prefix/"share"
end

#option_defined? ⇒ Boolean

If a named option is defined for the currently active SoftwareSpec.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


609
 
# File 'formula.rb', line 609

delegate option_defined?: :active_spec

#options(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


99
 
# File 'sorbet/rbi/parlour.rbi', line 99

def options(*args, **options, &block); end

#optlinked? ⇒ Boolean

Is the formula linked to opt?

Returns:

  • (Boolean) 


706
707
708
 
# File 'formula.rb', line 706

def optlinked?
  opt_prefix.symlink?
end

#pin(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


147
 
# File 'sorbet/rbi/parlour.rbi', line 147

def pin(*args, **options, &block); end

#pinnable?(*args, **options, &block) ⇒ Boolean

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


138
 
# File 'sorbet/rbi/parlour.rbi', line 138

def pinnable?(*args, **options, &block); end

#pinned?(*args, **options, &block) ⇒ Boolean

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean) 


141
 
# File 'sorbet/rbi/parlour.rbi', line 141

def pinned?(*args, **options, &block); end

#pinned_version(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


144
 
# File 'sorbet/rbi/parlour.rbi', line 144

def pinned_version(*args, **options, &block); end

#pkg_version ⇒ PkgVersion

The PkgVersion for this formula with version and #revision information.

Returns:



489
490
491
 
# File 'formula.rb', line 489

def pkg_version
  PkgVersion.new(version, revision)
end

#pkgetc ⇒ Pathname

A subdirectory of etc with the formula name suffixed. e.g. $HOMEBREW_PREFIX/etc/openssl@1.1 Anything using pkgetc.install will not overwrite other files on e.g. upgrades but will write a new file named *.default.

Returns:



977
978
979
 
# File 'formula.rb', line 977

def pkgetc
  (HOMEBREW_PREFIX/"etc"/name).extend(InstallRenamed)
end

#pkgshare ⇒ Pathname

The directory where the formula’s shared files should be installed, with the name of the formula appended to avoid linking conflicts. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

No make install available?

pkgshare.install "examples"

Returns:



930
931
932
 
# File 'formula.rb', line 930

def pkgshare
  prefix/"share"/name
end

#plist ⇒ Object

Deprecated.

Please use Homebrew::Service instead.

This method can be overridden to provide a plist.

def plist; <<~EOS
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  <plist version="1.0">
  <dict>
    <key>Label</key>
      <string>#{plist_name}</string>
    <key>ProgramArguments</key>
    <array>
      <string>#{opt_bin}/example</string>
      <string>--do-this</string>
    </array>
    <key>RunAtLoad</key>
    <true />
    <key>KeepAlive</key>
    <true />
    <key>StandardErrorPath</key>
    <string>/dev/null</string>
    <key>StandardOutPath</key>
    <string>/dev/null</string>
  </dict>
  </plist>
  EOS
end

See Also:



1097
1098
1099
1100
 
# File 'formula.rb', line 1097

def plist
  # odeprecated: consider removing entirely in 4.3.0
  nil
end

#plist_name ⇒ String

The generated launchd #plist service name.

Returns:



1104
1105
1106
 
# File 'formula.rb', line 1104

def plist_name
  service.plist_name
end

#post_install ⇒ void

This method returns an undefined value.

Can be overridden to run commands on both source and bottle installation.



1210
 
# File 'formula.rb', line 1210

def post_install; end

#pour_bottle? ⇒ Boolean

Indicates that this formula supports bottles. (Not necessarily that one should be used in the current installation run.) Can be overridden to selectively disable bottles from formulae. Defaults to true so overridden version does not have to check if bottles are supported. Replaced by pour_bottle?’s satisfy method if it is specified.

Returns:

  • (Boolean) 


1201
1202
1203
 
# File 'formula.rb', line 1201

def pour_bottle?
  true
end

#pour_bottle_check_unsatisfied_reason(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


114
 
# File 'sorbet/rbi/parlour.rbi', line 114

def pour_bottle_check_unsatisfied_reason(*args, **options, &block); end

#prefix(version = pkg_version) ⇒ Object

The directory in the cellar that the formula is installed to. This directory points to #opt_prefix if it exists and if #prefix is not called from within the same formula’s #install or #post_install methods. Otherwise, return the full path to the formula’s versioned cellar.



688
689
690
691
692
693
694
695
696
 
# File 'formula.rb', line 688

def prefix(version = pkg_version)
  versioned_prefix = versioned_prefix(version)
  if !@prefix_returns_versioned_prefix && version == pkg_version &&
     versioned_prefix.directory? && Keg.new(versioned_prefix).optlinked?
    opt_prefix
  else
    versioned_prefix
  end
end

#prefix_linked?(version = pkg_version) ⇒ Boolean

If a formula’s linked keg points to the prefix.

Returns:

  • (Boolean) 


711
712
713
714
715
 
# File 'formula.rb', line 711

def prefix_linked?(version = pkg_version)
  return false unless linked?

  linked_keg.resolved_path == versioned_prefix(version)
end

#requirements(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


90
 
# File 'sorbet/rbi/parlour.rbi', line 90

def requirements(*args, **options, &block); end

#resource ⇒ T.untyped

A named Resource for the currently active SoftwareSpec. Additional downloads can be defined as #resources. Resource#stage will create a temporary directory and yield to a block.

resource("additional_files").stage { bin.install "my/extra/tool" }

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


541
 
# File 'formula.rb', line 541

delegate resource: :active_spec

#resources ⇒ Object

The Resources for the currently active SoftwareSpec.



570
 
# File 'formula.rb', line 570

def_delegator :"active_spec.resources", :values, :resources

#rpath(source: bin, target: lib) ⇒ String

Executable/Library RPATH according to platform conventions.

Optionally specify a source or target depending on the location of the file containing the RPATH command and where its target is located.

rpath #=> "@loader_path/../lib"
rpath(target: frameworks) #=> "@loader_path/../Frameworks"
rpath(source: libexec/"bin") #=> "@loader_path/../../lib"

Parameters:

Returns:



1744
1745
1746
1747
1748
1749
1750
 
# File 'formula.rb', line 1744

def rpath(source: bin, target: lib)
  unless target.to_s.start_with?(HOMEBREW_PREFIX)
    raise "rpath `target` should only be used for paths inside HOMEBREW_PREFIX!"
  end

  "#{loader_path}/#{target.relative_path_from(source)}"
end

#runtime_installed_formula_dependents ⇒ Object 



2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
 
# File 'formula.rb', line 2152

def runtime_installed_formula_dependents
  # `any_installed_keg` and `runtime_dependencies` `select`s ensure
  # that we don't end up with something `Formula#runtime_dependencies` can't
  # read from a `Tab`.
  Formula.cache[:runtime_installed_formula_dependents] ||= {}
  Formula.cache[:runtime_installed_formula_dependents][full_name] ||= Formula.installed
                                                                             .select(&:any_installed_keg)
                                                                             .select(&:runtime_dependencies)
                                                                             .select do |f|
    f.runtime_formula_dependencies.any? do |dep|
      full_name == dep.full_name
    rescue
      name == dep.name
    end
  end
end

#sbin ⇒ Pathname

The directory where the formula’s sbin binaries should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only. Generally we try to migrate these to #bin instead.

Returns:



898
899
900
 
# File 'formula.rb', line 898

def sbin
  prefix/"sbin"
end

#service ⇒ Object

The service specification of the software.



1133
1134
1135
 
# File 'formula.rb', line 1133

def service
  @service ||= Homebrew::Service.new(self, &self.class.service)
end

#service? ⇒ Boolean

Is a service specification defined for the software?

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (Boolean)

See Also:



453
 
# File 'formula.rb', line 453

delegate service?: :"self.class"

#service_name ⇒ String

The generated service name.

Returns:



1110
1111
1112
 
# File 'formula.rb', line 1110

def service_name
  service.service_name
end

#share ⇒ Pathname

The directory where the formula’s shared files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Need a custom directory?

(share/"concept").mkpath

Installing something into another custom directory?

(share/"concept2").install "ducks.txt"

Install ./example_code/simple/ones to share/demos:

(share/"demos").install "example_code/simple/ones"

Install ./example_code/simple/ones to share/demos/examples:

(share/"demos").install "example_code/simple/ones" => "examples"

Returns:



918
919
920
 
# File 'formula.rb', line 918

def share
  prefix/"share"
end

#shared_library(name, version = nil) ⇒ String

Shared library names according to platform conventions.

Optionally specify a version to restrict the shared library to a specific version. The special string “*” matches any version.

If name is specified as “*”, match any shared library of any version.

shared_library("foo")      #=> foo.dylib
shared_library("foo", 1)   #=> foo.1.dylib
shared_library("foo", "*") #=> foo.2.dylib, foo.1.dylib, foo.dylib
shared_library("*")        #=> foo.dylib, bar.dylib

Parameters:

  • name (String)
  • version (String, Integer, nil) (defaults to: nil)

Returns:



12
13
14
15
16
17
18
19
 
# File 'extend/os/linux/formula.rb', line 12

def shared_library(name, version = nil)
  suffix = if version == "*" || (name == "*" && version.blank?)
    "{,.*}"
  elsif version.present?
    ".#{version}"
  end
  "#{name}.so#{suffix}"
end

#skip_cxxstdlib_check? ⇒ Boolean

Returns:

  • (Boolean) 


1387
1388
1389
 
# File 'formula.rb', line 1387

def skip_cxxstdlib_check?
  false
end

#specified_name ⇒ Object

The name specified to find this formula.



363
364
365
 
# File 'formula.rb', line 363

def specified_name
  alias_name || name
end

#specified_path ⇒ Object

The path that was specified to find this formula.



352
353
354
355
356
357
358
359
360
 
# File 'formula.rb', line 352

def specified_path
  return alias_path if alias_path&.exist?

  return @unresolved_path if @unresolved_path.exist?

  return local_bottle_path if local_bottle_path.presence&.exist?

  alias_path || @unresolved_path
end

#std_cabal_v2_args ⇒ Array<String>

Standard parameters for cabal-v2 builds.

Returns:



1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
 
# File 'formula.rb', line 1680

def std_cabal_v2_args
  env = T.cast(ENV, T.any(Stdenv, Superenv))

  # cabal-install's dependency-resolution backtracking strategy can
  # easily need more than the default 2,000 maximum number of
  # "backjumps," since Hackage is a fast-moving, rolling-release
  # target. The highest known needed value by a formula was 43,478
  # for git-annex, so 100,000 should be enough to avoid most
  # gratuitous backjumps build failures.
  ["--jobs=#{env.make_jobs}", "--max-backjumps=100000", "--install-method=copy", "--installdir=#{bin}"]
end

#std_cargo_args(root: prefix, path: ".") ⇒ Array<String>

Standard parameters for cargo builds.

Parameters:

Returns:



1637
1638
1639
 
# File 'formula.rb', line 1637

def std_cargo_args(root: prefix, path: ".")
  ["--locked", "--root=#{root}", "--path=#{path}"]
end

#std_cmake_args(install_prefix: prefix, install_libdir: "lib", find_framework: "LAST") ⇒ Array<String> Also known as: generic_std_cmake_args

Standard parameters for CMake builds.

Setting CMAKE_FIND_FRAMEWORK to “LAST” tells CMake to search for our libraries before trying to utilize Frameworks, many of which will be from 3rd party installs.

Parameters:

Returns:



20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'extend/os/mac/formula.rb', line 20

def std_cmake_args(install_prefix: prefix, install_libdir: "lib", find_framework: "LAST")
  args = generic_std_cmake_args(install_prefix:, install_libdir:,
                                find_framework:)

  # Avoid false positives for clock_gettime support on 10.11.
  # CMake cache entries for other weak symbols may be added here as needed.
  args << "-DHAVE_CLOCK_GETTIME:INTERNAL=0" if MacOS.version == "10.11" && MacOS::Xcode.version >= "8.0"

  # Ensure CMake is using the same SDK we are using.
  args << "-DCMAKE_OSX_SYSROOT=#{MacOS.sdk_for_formula(self).path}" if MacOS.sdk_root_needed?

  args
end

#std_configure_args(prefix: self.prefix, libdir: "lib") ⇒ Array<String>

Standard parameters for configure builds.

Parameters:

Returns:



1628
1629
1630
1631
 
# File 'formula.rb', line 1628

def std_configure_args(prefix: self.prefix, libdir: "lib")
  libdir = Pathname(libdir).expand_path(prefix)
  ["--disable-debug", "--disable-dependency-tracking", "--prefix=#{prefix}", "--libdir=#{libdir}"]
end

#std_go_args(output: bin/name, ldflags: nil) ⇒ Array<String>

Standard parameters for Go builds.

Parameters:

Returns:



1672
1673
1674
1675
1676
 
# File 'formula.rb', line 1672

def std_go_args(output: bin/name, ldflags: nil)
  args = ["-trimpath", "-o=#{output}"]
  args += ["-ldflags=#{Array(ldflags).join(" ")}"] if ldflags
  args
end

#std_meson_args ⇒ Array<String>

Standard parameters for meson builds.

Returns:



1694
1695
1696
 
# File 'formula.rb', line 1694

def std_meson_args
  ["--prefix=#{prefix}", "--libdir=#{lib}", "--buildtype=release", "--wrap-mode=nofallback"]
end

#std_pip_args(prefix: self.prefix, build_isolation: false) ⇒ Array<String>

Standard parameters for pip builds.

Parameters:

  • prefix (String, Pathname, false) (defaults to: self.prefix)
  • build_isolation (Boolean) (defaults to: false)

Returns:



1703
1704
1705
1706
1707
1708
 
# File 'formula.rb', line 1703

def std_pip_args(prefix: self.prefix, build_isolation: false)
  args = ["--verbose", "--no-deps", "--no-binary=:all:", "--ignore-installed", "--no-compile"]
  args << "--prefix=#{prefix}" if prefix
  args << "--no-build-isolation" unless build_isolation
  args
end

#supersedes_an_installed_formula? ⇒ Boolean

Is this formula the target of an alias used to install an old formula?

Returns:

  • (Boolean) 


1537
1538
1539
 
# File 'formula.rb', line 1537

def supersedes_an_installed_formula?
  old_installed_formulae.any?
end

#synced_with_other_formulae? ⇒ Boolean

Whether this Formula is version-synced with other formulae.

Returns:

  • (Boolean) 


530
531
532
533
534
 
# File 'formula.rb', line 530

def synced_with_other_formulae?
  return false if @tap.nil?

  @tap.synced_versions_formulae.any? { |synced_formulae| synced_formulae.include?(name) }
end

#system(cmd, *args) ⇒ void

This method returns an undefined value.

To call out to the system, we use the system method and we prefer you give the args separately as in the line below, otherwise a subshell has to be opened first.

system "./bootstrap.sh", "--arg1", "--prefix=#{prefix}"

For CMake and other build systems we have some necessary defaults in e.g. #std_cmake_args:

system "cmake", ".", *std_cmake_args

If the arguments given to configure (or make or cmake) are depending on options defined above, we usually make a list first and then use the args << if <condition> to append each:

args = ["--with-option1", "--with-option2"]
args << "--without-gcc" if ENV.compiler == :clang

# Most software still uses `configure` and `make`.
# Check with `./configure --help` for what our options are.
system "./configure", "--disable-debug", "--disable-dependency-tracking",
                      "--disable-silent-rules", "--prefix=#{prefix}",
                      *args # our custom arg list (needs `*` to unpack)

# If there is a "make install" available, please use it!
system "make", "install"

Parameters:



2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
 
# File 'formula.rb', line 2733

def system(cmd, *args)
  verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots?

  # remove "boring" arguments so that the important ones are more likely to
  # be shown considering that we trim long ohai lines to the terminal width
  pretty_args = args.dup
  unless verbose?
    case cmd
    when "./configure"
      pretty_args -= std_configure_args
    when "cabal"
      pretty_args -= std_cabal_v2_args
    when "cargo"
      pretty_args -= std_cargo_args
    when "cmake"
      pretty_args -= std_cmake_args
    when "go"
      pretty_args -= std_go_args
    when "meson"
      pretty_args -= std_meson_args
    when %r{(^|/)(pip|python)(?:[23](?:\.\d{1,2})?)?$}
      pretty_args -= std_pip_args
    end
  end
  pretty_args.each_index do |i|
    pretty_args[i] = "import setuptools..." if pretty_args[i].to_s.start_with? "import setuptools"
  end
  ohai "#{cmd} #{pretty_args * " "}".strip

  @exec_count ||= 0
  @exec_count += 1
  logfn = format("#{logs}/#{active_log_prefix}%02<exec_count>d.%<cmd_base>s",
                 exec_count: @exec_count,
                 cmd_base:   File.basename(cmd).split.first)
  logs.mkpath

  File.open(logfn, "w") do |log|
    log.puts Time.now, "", cmd, args, ""
    log.flush

    if verbose?
      rd, wr = IO.pipe
      begin
        pid = fork do
          rd.close
          log.close
          exec_cmd(cmd, args, wr, logfn)
        end
        wr.close

        if verbose_using_dots
          last_dot = Time.at(0)
          while (buf = rd.gets)
            log.puts buf
            # make sure dots printed with interval of at least 1 min.
            next if (Time.now - last_dot) <= 60

            print "."
            $stdout.flush
            last_dot = Time.now
          end
          puts
        else
          while (buf = rd.gets)
            log.puts buf
            puts buf
          end
        end
      ensure
        rd.close
      end
    else
      pid = fork do
        exec_cmd(cmd, args, log, logfn)
      end
    end

    Process.wait(T.must(pid))

    $stdout.flush

    unless $CHILD_STATUS.success?
      log_lines = Homebrew::EnvConfig.fail_log_lines

      log.flush
      if !verbose? || verbose_using_dots
        puts "Last #{log_lines} lines from #{logfn}:"
        Kernel.system "/usr/bin/tail", "-n", log_lines.to_s, logfn
      end
      log.puts

      require "system_config"
      require "build_environment"

      env = ENV.to_hash

      SystemConfig.dump_verbose_config(log)
      log.puts
      BuildEnvironment.dump env, log

      raise BuildError.new(self, cmd, args, env)
    end
  end
end

#systemd_service_path ⇒ Pathname

The generated systemd service file path.

Returns:



1122
1123
1124
 
# File 'formula.rb', line 1122

def systemd_service_path
  opt_prefix/"#{service_name}.service"
end

#systemd_timer_path ⇒ Pathname

The generated systemd timer file path.

Returns:



1128
1129
1130
 
# File 'formula.rb', line 1128

def systemd_timer_path
  opt_prefix/"#{service_name}.timer"
end

#time ⇒ Time

Creates a new Time object for use in the formula as the build time.

Returns:

See Also:



1761
1762
1763
1764
1765
1766
1767
 
# File 'formula.rb', line 1761

def time
  if ENV["SOURCE_DATE_EPOCH"].present?
    Time.at(ENV["SOURCE_DATE_EPOCH"].to_i).utc
  else
    Time.now.utc
  end
end

#to_s ⇒ Object 



1611
1612
1613
 
# File 'formula.rb', line 1611

def to_s
  name
end

#unpin(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


150
 
# File 'sorbet/rbi/parlour.rbi', line 150

def unpin(*args, **options, &block); end

#update_head_version ⇒ void

This method returns an undefined value.



469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
 
# File 'formula.rb', line 469

def update_head_version
  return unless head?

  head_spec = T.must(head)
  return unless head_spec.downloader.is_a?(VCSDownloadStrategy)
  return unless head_spec.downloader.cached_location.exist?

  path = if ENV["HOMEBREW_ENV"]
    ENV.fetch("PATH")
  else
    PATH.new(ORIGINAL_PATHS)
  end

  with_env(PATH: path) do
    head_spec.version.update_commit(head_spec.downloader.last_commit)
  end
end

#uses_from_macos_elements(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


84
 
# File 'sorbet/rbi/parlour.rbi', line 84

def uses_from_macos_elements(*args, **options, &block); end

#uses_from_macos_names(*args, **options, &block) ⇒ T.untyped

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped) 


87
 
# File 'sorbet/rbi/parlour.rbi', line 87

def uses_from_macos_names(*args, **options, &block); end

#var ⇒ Pathname

The directory where the formula’s variable files should be installed. This directory is not inside the HOMEBREW_CELLAR so it persists across upgrades.

Returns:



985
986
987
 
# File 'formula.rb', line 985

def var
  HOMEBREW_PREFIX/"var"
end

#version ⇒ T.untyped

The version for the currently active SoftwareSpec. The version is autodetected from the URL and/or tag so only needs to be declared if it cannot be autodetected correctly.

Parameters:

  • args (T.untyped)
  • options (T.untyped)
  • block (T.untyped)

Returns:

  • (T.untyped)

See Also:



460
 
# File 'formula.rb', line 460

delegate version: :active_spec

#versioned_formula? ⇒ Boolean

If this is a @-versioned formula.

Returns:

  • (Boolean) 


495
496
497
 
# File 'formula.rb', line 495

def versioned_formula?
  name.include?("@")
end

#versioned_formulae ⇒ Array<Formula>

Returns any @-versioned Formula objects for any Formula (including versioned formulae).

Returns:



520
521
522
523
524
525
526
 
# File 'formula.rb', line 520

def versioned_formulae
  versioned_formulae_names.filter_map do |name|
    Formula[name]
  rescue FormulaUnavailableError
    nil
  end.sort_by(&:version).reverse
end

#versioned_formulae_names ⇒ Array<String>

Returns any other @-versioned formulae names for any formula (including versioned formulae).

Returns:



501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'formula.rb', line 501

def versioned_formulae_names
  versioned_names = if tap
    name_prefix = name.gsub(/(@[\d.]+)?$/, "")
    T.must(tap).prefix_to_versioned_formulae_names.fetch(name_prefix, [])
  elsif path.exist?
    Pathname.glob(path.to_s.gsub(/(@[\d.]+)?\.rb$/, "@*.rb"))
            .map { |path| path.basename(".rb").to_s }
            .sort
  else
    raise "Either tap or path is required to list versioned formulae"
  end

  versioned_names.reject do |versioned_name|
    versioned_name == name
  end
end

#with_logging(log_type) ⇒ Object

Runs a block with the given log type in effect for its duration.



1061
1062
1063
1064
1065
1066
1067
 
# File 'formula.rb', line 1061

def with_logging(log_type)
  old_log_type = @active_log_type
  @active_log_type = log_type
  yield
ensure
  @active_log_type = old_log_type
end

#xcodebuild(*args) ⇒ void

This method returns an undefined value.

Runs xcodebuild without Homebrew’s compiler environment variables set.

Parameters:



2898
2899
2900
2901
2902
2903
2904
2905
2906
 
# File 'formula.rb', line 2898

def xcodebuild(*args)
  removed = ENV.remove_cc_etc

  begin
    T.unsafe(self).system("xcodebuild", *args)
  ensure
    ENV.update(removed)
  end
end

#zsh_completion ⇒ Pathname

The directory where the formula’s zsh completion files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



1021
1022
1023
 
# File 'formula.rb', line 1021

def zsh_completion
  share/"zsh/site-functions"
end

#zsh_function ⇒ Pathname

The directory where the formula’s zsh function files should be installed. This is symlinked into HOMEBREW_PREFIX after installation or with brew link for formulae that are not keg-only.

Returns:



994
995
996
 
# File 'formula.rb', line 994

def zsh_function
  share/"zsh/site-functions"
end