Class: Formula

Inherits:
Object
  • Object
show all
Extended by:
BuildEnvironment::DSL, Cachable, Enumerable, Forwardable, Predicable
Includes:
Context, FileUtils, Utils::Inreplace, Utils::Shebang, Utils::Shell
Defined in:
Library/Homebrew/formula.rb,
Library/Homebrew/extend/os/mac/formula.rb,
Library/Homebrew/extend/os/linux/formula.rb

Overview

typed: true frozen_string_literal: true

Constant Summary

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 BuildEnvironment::DSL

env

Methods included from Predicable

attr_predicate

Methods included from Cachable

cache, clear_cache

Methods included from Context

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

Methods included from Utils::Shell

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

Methods included from Utils::Shebang

rewrite_shebang

Methods included from Utils::Inreplace

inreplace, inreplace_pairs

Class Attribute Details

.bottle(*args, &block) ⇒ Object

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.
  prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built.
  cellar "/opt/homebrew/Cellar" # Optional HOMEBREW_CELLAR in which the bottles were built.
  rebuild 1 # Marks the old bottle as outdated without bumping the version/revision of the formula.
  sha256 "ef65c759c5097a36323fa9c77756468649e8d1980a3a4e05695c05e39568967c" => :catalina
  sha256 "28f4090610946a4eb207df102d841de23ced0d06ba31cb79e040d883906dcd4f" => :mojave
  sha256 "91dd0caca9bd3f38c439d5a7b6f68440c4274945615fae035ff0a369264b8a2f" => :high_sierra
end

Only formulae where the upstream URL breaks or moves frequently, require compiling or have a reasonable amount of patches/resources should be bottled. Formulae which do not meet the above requirements should not be bottled.

Formulae which should not be bottled and can be installed without any compile required should be tagged with:

bottle :unneeded

Otherwise formulae which do not meet the above requirements and should not be bottled should be tagged with:

bottle :disable, "reasons"

See Also:


2405
2406
2407
 
# File 'Library/Homebrew/formula.rb', line 2405

def bottle(*args, &block)
  stable.bottle(*args, &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"

2568
2569
2570
 
# File 'Library/Homebrew/formula.rb', line 2568

def deprecated_option(hash)
  specs.each { |spec| spec.deprecated_option(hash) }
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) 

2784
2785
2786
 
# File 'Library/Homebrew/formula.rb', line 2784

def deprecation_reason
  @deprecation_reason
end

.desc=(value) ⇒ Object (writeonly)

A one-line description of the software. Used by users to get an overview of the software and Homebrew maintainers. Shows when running brew info.

desc "Example formula"

2225
 
# File 'Library/Homebrew/formula.rb', line 2225

attr_rw :desc

.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:


2814
2815
2816
 
# File 'Library/Homebrew/formula.rb', line 2814

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

2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
 
# File 'Library/Homebrew/formula.rb', line 2460

def head(val = nil, specs = {}, &block)
  @head ||= HeadSoftwareSpec.new(flags: build_flags)
  if block_given?
    @head.instance_eval(&block)
  elsif val
    @head.url(val, specs)
  else
    @head
  end
end

.homepage=(value) ⇒ Object (writeonly)

The homepage for the software. Used by users to get more information about the software and Homebrew maintainers as a point of contact for e.g. submitting patches. Can be opened with running brew home.

homepage "https://www.example.com"

2269
 
# File 'Library/Homebrew/formula.rb', line 2269

attr_rw :homepage

.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:


2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
 
# File 'Library/Homebrew/formula.rb', line 2250

def license(args = nil)
  if args.nil?
    @licenses
  else
    if args.is_a? Array
      odeprecated "`license [...]`", "`license any_of: [...]`"
      args = { any_of: args }
    end
    @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

2735
2736
2737
2738
2739
2740
2741
 
# File 'Library/Homebrew/formula.rb', line 2735

def livecheck(&block)
  @livecheck ||= Livecheck.new(self)
  return @livecheck unless block_given?

  @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

2357
2358
2359
 
# File 'Library/Homebrew/formula.rb', line 2357

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

2559
2560
2561
 
# File 'Library/Homebrew/formula.rb', line 2559

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

.revision=(value) ⇒ Object (writeonly)

Used for creating new Homebrew versions of software without new upstream versions. For example, if we bump the major version of a library that this Formula depends_on then we may need to update the revision of this Formula to install a new version linked against the new library version. 0 if unset.

revision 1

2299
 
# File 'Library/Homebrew/formula.rb', line 2299

attr_rw :revision

.sha256=(value) ⇒ Object (writeonly)

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"

2369
2370
2371
 
# File 'Library/Homebrew/formula.rb', line 2369

Checksum::TYPES.each do |type|
  define_method(type) { |val| stable.send(type, 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 preferrable 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

2436
2437
2438
2439
2440
2441
 
# File 'Library/Homebrew/formula.rb', line 2436

def stable(&block)
  @stable ||= SoftwareSpec.new(flags: build_flags)
  return @stable unless block_given?

  @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 inferrable, 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"

2334
2335
2336
 
# File 'Library/Homebrew/formula.rb', line 2334

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"

2344
2345
2346
 
# File 'Library/Homebrew/formula.rb', line 2344

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

.version_scheme=(value) ⇒ Object (writeonly)

Used for creating new Homebrew version schemes. For example, if we want to change version scheme from one to another, then we may need to update version_scheme of this Formula to be able to use new version scheme, e.g. to move from 20151020 scheme to 1.0.0 we need to increment version_scheme. Without this, the prior scheme will always equate to a higher version. 0 if unset.

version_scheme 1

2311
 
# File 'Library/Homebrew/formula.rb', line 2311

attr_rw :version_scheme

Instance Attribute Details

#alias_name ⇒ Object (readonly)

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


87
88
89
 
# File 'Library/Homebrew/formula.rb', line 87

def alias_name
  @alias_name
end

#alias_path ⇒ Object (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


83
84
85
 
# File 'Library/Homebrew/formula.rb', line 83

def alias_path
  @alias_path
end

#build ⇒ BuildOptions

The BuildOptions 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:


176
177
178
 
# File 'Library/Homebrew/formula.rb', line 176

def build
  @build
end

#buildpath ⇒ Object (readonly)

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


155
156
157
 
# File 'Library/Homebrew/formula.rb', line 155

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) 

182
183
184
 
# File 'Library/Homebrew/formula.rb', line 182

def follow_installed_alias
  @follow_installed_alias
end

#full_alias_name ⇒ Object (readonly)

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


97
98
99
 
# File 'Library/Homebrew/formula.rb', line 97

def full_alias_name
  @full_alias_name
end

#full_name ⇒ Object (readonly)

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


92
93
94
 
# File 'Library/Homebrew/formula.rb', line 92

def full_name
  @full_name
end

#name ⇒ Object (readonly)

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


79
80
81
 
# File 'Library/Homebrew/formula.rb', line 79

def name
  @name
end

#path ⇒ Object (readonly)

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


101
102
103
 
# File 'Library/Homebrew/formula.rb', line 101

def path
  @path
end

#revision ⇒ Object (readonly)

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

See Also:


147
148
149
 
# File 'Library/Homebrew/formula.rb', line 147

def revision
  @revision
end

#testpath ⇒ Object (readonly)

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


159
160
161
 
# File 'Library/Homebrew/formula.rb', line 159

def testpath
  @testpath
end

#version_scheme ⇒ Object (readonly)

Used to change version schemes for packages.

See Also:


151
152
153
 
# File 'Library/Homebrew/formula.rb', line 151

def version_scheme
  @version_scheme
end

Class Method Details

.[](name) ⇒ Object 


1569
1570
1571
 
# File 'Library/Homebrew/formula.rb', line 1569

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"

2629
2630
2631
2632
 
# File 'Library/Homebrew/formula.rb', line 2629

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.


2658
2659
2660
 
# File 'Library/Homebrew/formula.rb', line 2658

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 dependencies for stuff that requires certain extra handling (often changing some ENV vars or deciding if to use the system provided version or not).

# `:build` means this dep is only needed during build.
depends_on "cmake" => :build
# `: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 with `--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.
depends_on x11: :optional # X11/XQuartz components.
depends_on :osxfuse # Permits the use of the upstream signed binary or our cask.
depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and later.
# It is possible to only depend on something if
# `build.with?` or `build.without? "another_formula"`:
depends_on "postgresql" if build.without? "sqlite"
# Require Python if `--with-python` is passed to `brew install example`:
depends_on "python" => :optional

2518
2519
2520
 
# File 'Library/Homebrew/formula.rb', line 2518

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

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

Deprecates a Formula (on a given date, if provided) 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"

2765
2766
2767
2768
2769
2770
2771
2772
 
# File 'Library/Homebrew/formula.rb', line 2765

def deprecate!(date: nil, because: nil)
  odeprecated "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank?

  return if date.present? && Date.parse(date) > Date.today

  @deprecation_reason = because if because.present?
  @deprecated = true
end

.deprecated? ⇒ Boolean

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

Returns:

  • (Boolean) 

2777
2778
2779
 
# File 'Library/Homebrew/formula.rb', line 2777

def deprecated?
  @deprecated == true
end

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

Disables a Formula (on a given date, if provided) 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"

2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
 
# File 'Library/Homebrew/formula.rb', line 2791

def disable!(date: nil, because: nil)
  odeprecated "`disable!` without a reason", "`disable! because: \"reason\"`" if because.blank?

  if date.present? && Date.parse(date) > Date.today
    @deprecation_reason = because if because.present?
    @deprecated = true
    return
  end

  @disable_reason = because if because.present?
  @disabled = true
end

.disabled? ⇒ Boolean

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

Returns:

  • (Boolean) 

2807
2808
2809
 
# File 'Library/Homebrew/formula.rb', line 2807

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

2683
2684
2685
 
# File 'Library/Homebrew/formula.rb', line 2683

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

.go_resource(name, &block) ⇒ Object 


2484
2485
2486
 
# File 'Library/Homebrew/formula.rb', line 2484

def go_resource(name, &block)
  specs.each { |spec| spec.go_resource(name, &block) }
end

.ignore_missing_libraries(*libs) ⇒ Object

Raises:


2827
2828
2829
 
# File 'Library/Homebrew/formula.rb', line 2827

def ignore_missing_libraries(*)
  raise FormulaSpecificationError, "#{__method__} is available on Linux only"
end

.installed_with_alias_path(alias_path) ⇒ Object 


1521
1522
1523
1524
1525
 
# File 'Library/Homebrew/formula.rb', line 1521

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 will only live in its Cellar. Other formulae can depend on it and then brew will add the necessary includes and libs (etc.) during the brewing of that other formula. But generally, keg-only formulae are not in your PATH and 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 "because I want it so"

2653
2654
2655
 
# File 'Library/Homebrew/formula.rb', line 2653

def keg_only(reason, explanation = "")
  @keg_only_reason = KegOnlyReason.new(reason, explanation)
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) 

2274
2275
2276
 
# File 'Library/Homebrew/formula.rb', line 2274

def livecheckable?
  @livecheckable == true
end

.needs(*standards) ⇒ Object 


2687
2688
2689
 
# File 'Library/Homebrew/formula.rb', line 2687

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

.on_linux(&_block) ⇒ Object

Block only executed on Linux. No-op on macOS.

on_linux do
  depends_on "linux_only_dep"
end

2541
2542
2543
 
# File 'Library/Homebrew/formula.rb', line 2541

def on_linux(&_block)
  raise "No block content defined for on_linux block" unless block_given?
end

.on_macos(&_block) ⇒ Object

Block only executed on macOS. No-op on Linux.

on_macos do
  depends_on "mac_only_dep"
end

2533
2534
2535
 
# File 'Library/Homebrew/formula.rb', line 2533

def on_macos(&_block)
  raise "No block content defined for on_macos block" unless block_given?
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:


2603
2604
2605
 
# File 'Library/Homebrew/formula.rb', line 2603

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

.plist_options(options) ⇒ Object

Defines launchd plist handling.

Does your plist need to be loaded at startup?

plist_options startup: true

Or only when necessary or desired by the user?

plist_options manual: "foo"

Or perhaps you'd like to give the user a choice? Ooh fancy.

plist_options startup: true, manual: "foo start"

2617
2618
2619
2620
 
# File 'Library/Homebrew/formula.rb', line 2617

def plist_options(options)
  @plist_startup = options[:startup]
  @plist_manual = options[:manual]
end

.pour_bottle?(&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.

Returns:

  • (Boolean) 

2755
2756
2757
2758
 
# File 'Library/Homebrew/formula.rb', line 2755

def pour_bottle?(&block)
  @pour_bottle_check = PourBottleCheck.new(self)
  @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

2478
2479
2480
2481
2482
 
# File 'Library/Homebrew/formula.rb', line 2478

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

.skip_clean(*paths) ⇒ Object 


2634
2635
2636
2637
2638
 
# File 'Library/Homebrew/formula.rb', line 2634

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:


2719
2720
2721
 
# File 'Library/Homebrew/formula.rb', line 2719

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

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

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


2525
2526
2527
 
# File 'Library/Homebrew/formula.rb', line 2525

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

Instance Method Details

#active_log_prefix ⇒ Object

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


891
892
893
894
895
896
897
 
# File 'Library/Homebrew/formula.rb', line 891

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

#alias_changed? ⇒ Boolean

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

Returns:

  • (Boolean) 

1297
1298
1299
 
# File 'Library/Homebrew/formula.rb', line 1297

def alias_changed?
  installed_alias_target_changed? || supersedes_an_installed_formula?
end

#aliases ⇒ Object

All aliases for the formula.


446
447
448
449
450
451
452
453
454
 
# File 'Library/Homebrew/formula.rb', line 446

def aliases
  @aliases ||= if tap
    tap.alias_reverse_table[full_name].to_a.map do |a|
      a.split("/").last
    end
  else
    []
  end
end

#any_installed_prefix ⇒ Object 


1624
1625
1626
1627
1628
1629
1630
 
# File 'Library/Homebrew/formula.rb', line 1624

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 


1632
1633
1634
 
# File 'Library/Homebrew/formula.rb', line 1632

def any_installed_version
  any_installed_keg&.version
end

#bash_completion ⇒ Object

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.


856
857
858
 
# File 'Library/Homebrew/formula.rb', line 856

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

#bin ⇒ Object

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"

631
632
633
 
# File 'Library/Homebrew/formula.rb', line 631

def bin
  prefix/"bin"
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:


1070
1071
1072
 
# File 'Library/Homebrew/formula.rb', line 1070

def caveats
  nil
end

#current_installed_alias_target ⇒ Object 


1277
1278
1279
 
# File 'Library/Homebrew/formula.rb', line 1277

def current_installed_alias_target
  Formulary.factory(installed_alias_path) if installed_alias_path
end

#deprecated? ⇒ Boolean

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

Returns:

  • (Boolean) 

1143
 
# File 'Library/Homebrew/formula.rb', line 1143

delegate deprecated?: :"self.class"

#deprecation_reason ⇒ String, Symbol

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

Returns:


1149
 
# File 'Library/Homebrew/formula.rb', line 1149

delegate deprecation_reason: :"self.class"

#desc ⇒ Object

The description of the software.

See Also:


364
 
# File 'Library/Homebrew/formula.rb', line 364

delegate desc: :"self.class"

#disable_reason ⇒ String, Symbol

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

Returns:


1161
 
# File 'Library/Homebrew/formula.rb', line 1161

delegate disable_reason: :"self.class"

#disabled? ⇒ Boolean

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

Returns:

  • (Boolean) 

1155
 
# File 'Library/Homebrew/formula.rb', line 1155

delegate disabled?: :"self.class"

#doc ⇒ Object

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.


638
639
640
 
# File 'Library/Homebrew/formula.rb', line 638

def doc
  share/"doc"/name
end

#elisp ⇒ Object

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"

792
793
794
 
# File 'Library/Homebrew/formula.rb', line 792

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

#etc ⇒ Object

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.


817
818
819
 
# File 'Library/Homebrew/formula.rb', line 817

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

#fetch_patches ⇒ Object 


2111
2112
2113
 
# File 'Library/Homebrew/formula.rb', line 2111

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

#fish_completion ⇒ Object

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.


872
873
874
 
# File 'Library/Homebrew/formula.rb', line 872

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

#fish_function ⇒ Object

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.


848
849
850
 
# File 'Library/Homebrew/formula.rb', line 848

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

#frameworks ⇒ Object

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.


800
801
802
 
# File 'Library/Homebrew/formula.rb', line 800

def frameworks
  prefix/"Frameworks"
end

#full_installed_alias_name ⇒ Object 


293
294
295
 
# File 'Library/Homebrew/formula.rb', line 293

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.


318
319
320
 
# File 'Library/Homebrew/formula.rb', line 318

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.


308
309
310
 
# File 'Library/Homebrew/formula.rb', line 308

def full_specified_name
  full_alias_name || full_name
end

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

Returns:

  • (Boolean) 

535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'Library/Homebrew/formula.rb', line 535

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 < stable.version
  return false unless fetch_head
  return false unless head&.downloader.is_a?(VCSDownloadStrategy)

  downloader = head.downloader

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

#homepage ⇒ Object

The homepage for the software.

See Also:


374
 
# File 'Library/Homebrew/formula.rb', line 374

delegate homepage: :"self.class"

#include ⇒ Object

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"

648
649
650
 
# File 'Library/Homebrew/formula.rb', line 648

def include
  prefix/"include"
end

#info ⇒ Object

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.


655
656
657
 
# File 'Library/Homebrew/formula.rb', line 655

def info
  share/"info"
end

#inreplace(paths, before = nil, after = nil) ⇒ Object

Actually implemented in Utils::Inreplace.inreplace. 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 variable defined by the formula. Only HOMEBREW_PREFIX is available in the embedded patch.

inreplace supports regular expressions:

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

See Also:



# File 'Library/Homebrew/formula.rb', line 65

#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

1884
 
# File 'Library/Homebrew/formula.rb', line 1884

def install; end

#installed_alias_name ⇒ Object 


289
290
291
 
# File 'Library/Homebrew/formula.rb', line 289

def installed_alias_name
  File.basename(installed_alias_path) if installed_alias_path
end

#installed_alias_path ⇒ Object

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.


281
282
283
284
285
286
287
 
# File 'Library/Homebrew/formula.rb', line 281

def installed_alias_path
  path = build.source["path"] if build.is_a?(Tab)
  return unless path&.match?(%r{#{HOMEBREW_TAP_DIR_REGEX}/Aliases})
  return unless File.symlink?(path)

  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) 

1283
1284
1285
1286
1287
1288
 
# File 'Library/Homebrew/formula.rb', line 1283

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.


313
314
315
 
# File 'Library/Homebrew/formula.rb', line 313

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:


1077
1078
1079
1080
1081
 
# File 'Library/Homebrew/formula.rb', line 1077

def keg_only?
  return false unless keg_only_reason

  keg_only_reason.applicable?
end

#kext_prefix ⇒ Object

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.


808
809
810
 
# File 'Library/Homebrew/formula.rb', line 808

def kext_prefix
  prefix/"Library/Extensions"
end

#latest_formula ⇒ Object

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


1303
1304
1305
 
# File 'Library/Homebrew/formula.rb', line 1303

def latest_formula
  installed_alias_target_changed? ? current_installed_alias_target : self
end

#latest_head_prefix ⇒ Object 


530
531
532
533
 
# File 'Library/Homebrew/formula.rb', line 530

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

#latest_head_version ⇒ Object 


519
520
521
522
523
524
525
526
527
528
 
# File 'Library/Homebrew/formula.rb', line 519

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

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

#lib ⇒ Object

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"

665
666
667
 
# File 'Library/Homebrew/formula.rb', line 665

def lib
  prefix/"lib"
end

#libexec ⇒ Object

The directory where the formula's binaries should be installed. This is not symlinked into HOMEBREW_PREFIX. It is also 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.


674
675
676
 
# File 'Library/Homebrew/formula.rb', line 674

def libexec
  prefix/"libexec"
end

#license ⇒ Object

The SPDX ID of the software license.

See Also:


369
 
# File 'Library/Homebrew/formula.rb', line 369

delegate license: :"self.class"

#linked? ⇒ Boolean

Is the formula linked?

Returns:

  • (Boolean) 

577
578
579
 
# File 'Library/Homebrew/formula.rb', line 577

def linked?
  linked_keg.symlink?
end

#linked_version ⇒ Object

PkgVersion of the linked keg for the formula.


594
595
596
597
598
 
# File 'Library/Homebrew/formula.rb', line 594

def linked_version
  return unless linked?

  Keg.for(linked_keg).version
end

#livecheck ⇒ Object

The livecheck specification for the software.

See Also:


379
 
# File 'Library/Homebrew/formula.rb', line 379

delegate livecheck: :"self.class"

#livecheckable? ⇒ Object

Is a livecheck specification defined for the software?

See Also:


384
 
# File 'Library/Homebrew/formula.rb', line 384

delegate livecheckable?: :"self.class"

#man ⇒ Object

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.


683
684
685
 
# File 'Library/Homebrew/formula.rb', line 683

def man
  share/"man"
end

#man1 ⇒ Object

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"

693
694
695
 
# File 'Library/Homebrew/formula.rb', line 693

def man1
  man/"man1"
end

#man2 ⇒ Object

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.


700
701
702
 
# File 'Library/Homebrew/formula.rb', line 700

def man2
  man/"man2"
end

#man3 ⇒ Object

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"

710
711
712
 
# File 'Library/Homebrew/formula.rb', line 710

def man3
  man/"man3"
end

#man4 ⇒ Object

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.


717
718
719
 
# File 'Library/Homebrew/formula.rb', line 717

def man4
  man/"man4"
end

#man5 ⇒ Object

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.


724
725
726
 
# File 'Library/Homebrew/formula.rb', line 724

def man5
  man/"man5"
end

#man6 ⇒ Object

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.


731
732
733
 
# File 'Library/Homebrew/formula.rb', line 731

def man6
  man/"man6"
end

#man7 ⇒ Object

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.


738
739
740
 
# File 'Library/Homebrew/formula.rb', line 738

def man7
  man/"man7"
end

#man8 ⇒ Object

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.


745
746
747
 
# File 'Library/Homebrew/formula.rb', line 745

def man8
  man/"man8"
end

#migration_needed? ⇒ Boolean

Returns:

  • (Boolean) 

1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
 
# File 'Library/Homebrew/formula.rb', line 1223

def migration_needed?
  return false unless oldname
  return false if rack.exist?

  old_rack = HOMEBREW_CELLAR/oldname
  return false unless old_rack.directory?
  return false if old_rack.subdirs.empty?

  tap == Tab.for_keg(old_rack.subdirs.min).tap
end

#missing_dependencies(hide: nil) ⇒ Object

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


1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
 
# File 'Library/Homebrew/formula.rb', line 1693

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.


2096
2097
2098
2099
2100
2101
 
# File 'Library/Homebrew/formula.rb', line 2096

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

  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.


2090
2091
2092
 
# File 'Library/Homebrew/formula.rb', line 2090

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

#new_formula_available? ⇒ Boolean

Returns:

  • (Boolean) 

1273
1274
1275
 
# File 'Library/Homebrew/formula.rb', line 1273

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

#old_installed_formulae ⇒ Object 


1307
1308
1309
1310
1311
1312
1313
1314
 
# File 'Library/Homebrew/formula.rb', line 1307

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 ⇒ Object

An old name for the formula.


438
439
440
441
442
443
 
# File 'Library/Homebrew/formula.rb', line 438

def oldname
  @oldname ||= if tap
    formula_renames = tap.formula_renames
    formula_renames.to_a.rassoc(name).first if formula_renames.value?(name)
  end
end

#on_linux(&_block) ⇒ Object

Block only executed on Linux. No-op on macOS.

on_linux do
# Do something Linux-specific
end

1384
1385
1386
 
# File 'Library/Homebrew/formula.rb', line 1384

def on_linux(&_block)
  raise "No block content defined for on_linux block" unless block_given?
end

#on_macos(&_block) ⇒ Object

Block only executed on macOS. No-op on Linux.

on_macos do
# Do something Mac-specific
end

1376
1377
1378
 
# File 'Library/Homebrew/formula.rb', line 1376

def on_macos(&_block)
  raise "No block content defined for on_macos block" unless block_given?
end

#opt_bin ⇒ Object 


965
966
967
 
# File 'Library/Homebrew/formula.rb', line 965

def opt_bin
  opt_prefix/"bin"
end

#opt_elisp ⇒ Object 


993
994
995
 
# File 'Library/Homebrew/formula.rb', line 993

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

#opt_frameworks ⇒ Object 


997
998
999
 
# File 'Library/Homebrew/formula.rb', line 997

def opt_frameworks
  opt_prefix/"Frameworks"
end

#opt_include ⇒ Object 


969
970
971
 
# File 'Library/Homebrew/formula.rb', line 969

def opt_include
  opt_prefix/"include"
end

#opt_lib ⇒ Object 


973
974
975
 
# File 'Library/Homebrew/formula.rb', line 973

def opt_lib
  opt_prefix/"lib"
end

#opt_libexec ⇒ Object 


977
978
979
 
# File 'Library/Homebrew/formula.rb', line 977

def opt_libexec
  opt_prefix/"libexec"
end

#opt_pkgshare ⇒ Object 


989
990
991
 
# File 'Library/Homebrew/formula.rb', line 989

def opt_pkgshare
  opt_prefix/"share"/name
end

#opt_prefix ⇒ Object

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"

961
962
963
 
# File 'Library/Homebrew/formula.rb', line 961

def opt_prefix
  Pathname.new("#{HOMEBREW_PREFIX}/opt/#{name}")
end

#opt_sbin ⇒ Object 


981
982
983
 
# File 'Library/Homebrew/formula.rb', line 981

def opt_sbin
  opt_prefix/"sbin"
end

#opt_share ⇒ Object 


985
986
987
 
# File 'Library/Homebrew/formula.rb', line 985

def opt_share
  opt_prefix/"share"
end

#option_defined? ⇒ Object

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


489
 
# File 'Library/Homebrew/formula.rb', line 489

delegate option_defined?: :active_spec

#optlinked? ⇒ Boolean

Is the formula linked to opt?

Returns:

  • (Boolean) 

582
583
584
 
# File 'Library/Homebrew/formula.rb', line 582

def optlinked?
  opt_prefix.symlink?
end

#pkg_version ⇒ Object

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


410
411
412
 
# File 'Library/Homebrew/formula.rb', line 410

def pkg_version
  PkgVersion.new(version, revision)
end

#pkgetc ⇒ Object

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


825
826
827
 
# File 'Library/Homebrew/formula.rb', line 825

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

#pkgshare ⇒ Object

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"

783
784
785
 
# File 'Library/Homebrew/formula.rb', line 783

def pkgshare
  prefix/"share"/name
end

#plist ⇒ Object

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:


934
935
936
 
# File 'Library/Homebrew/formula.rb', line 934

def plist
  nil
end

#plist_name ⇒ Object

The generated launchd #plist service name.


939
940
941
 
# File 'Library/Homebrew/formula.rb', line 939

def plist_name
  "homebrew.mxcl.#{name}"
end

#plist_path ⇒ Object

The generated launchd #plist file path.


944
945
946
 
# File 'Library/Homebrew/formula.rb', line 944

def plist_path
  prefix/"#{plist_name}.plist"
end

#post_install ⇒ Object

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


1015
 
# File 'Library/Homebrew/formula.rb', line 1015

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) 

1007
1008
1009
 
# File 'Library/Homebrew/formula.rb', line 1007

def pour_bottle?
  true
end

#prefix(v = 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.


566
567
568
569
570
571
572
573
574
 
# File 'Library/Homebrew/formula.rb', line 566

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

#prefix_linked?(v = pkg_version) ⇒ Boolean

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

Returns:

  • (Boolean) 

587
588
589
590
591
 
# File 'Library/Homebrew/formula.rb', line 587

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

  linked_keg.resolved_path == versioned_prefix(v)
end

#resource ⇒ Object

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" }

435
 
# File 'Library/Homebrew/formula.rb', line 435

delegate resource: :active_spec

#resources ⇒ Object

The Resources for the currently active SoftwareSpec.


458
 
# File 'Library/Homebrew/formula.rb', line 458

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

#runtime_installed_formula_dependents ⇒ Object 


1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
 
# File 'Library/Homebrew/formula.rb', line 1674

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 ⇒ Object

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.


753
754
755
 
# File 'Library/Homebrew/formula.rb', line 753

def sbin
  prefix/"sbin"
end

#share ⇒ Object

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"

772
773
774
 
# File 'Library/Homebrew/formula.rb', line 772

def share
  prefix/"share"
end

#shared_library(name, version = nil) ⇒ Object 


1441
1442
1443
 
# File 'Library/Homebrew/formula.rb', line 1441

def shared_library(name, version = nil)
  "#{name}.#{version}#{"." unless version.nil?}dylib"
end

#skip_cxxstdlib_check? ⇒ Boolean

Returns:

  • (Boolean) 

1163
1164
1165
 
# File 'Library/Homebrew/formula.rb', line 1163

def skip_cxxstdlib_check?
  false
end

#specified_name ⇒ Object

The name specified to find this formula.


303
304
305
 
# File 'Library/Homebrew/formula.rb', line 303

def specified_name
  alias_name || name
end

#specified_path ⇒ Object

The path that was specified to find this formula.


298
299
300
 
# File 'Library/Homebrew/formula.rb', line 298

def specified_path
  alias_path || path
end

#std_cabal_v2_args ⇒ Object

Standard parameters for cabal-v2 builds.


1426
1427
1428
1429
1430
1431
1432
1433
1434
 
# File 'Library/Homebrew/formula.rb', line 1426

def std_cabal_v2_args
  # 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 ⇒ Object

Standard parameters for cargo builds.


1389
1390
1391
 
# File 'Library/Homebrew/formula.rb', line 1389

def std_cargo_args
  ["--locked", "--root", prefix, "--path", "."]
end

#std_cmake_args ⇒ Object

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. Note that there isn't a std_autotools variant because autotools is a lot less consistent and the standard parameters are more memorable.


1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
 
# File 'Library/Homebrew/formula.rb', line 1399

def std_cmake_args
  args = %W[
    -DCMAKE_C_FLAGS_RELEASE=-DNDEBUG
    -DCMAKE_CXX_FLAGS_RELEASE=-DNDEBUG
    -DCMAKE_INSTALL_PREFIX=#{prefix}
    -DCMAKE_BUILD_TYPE=Release
    -DCMAKE_FIND_FRAMEWORK=LAST
    -DCMAKE_VERBOSE_MAKEFILE=ON
    -Wno-dev
  ]

  # 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_go_args ⇒ Object

Standard parameters for Go builds.


1421
1422
1423
 
# File 'Library/Homebrew/formula.rb', line 1421

def std_go_args
  ["-trimpath", "-o", bin/name]
end

#std_meson_args ⇒ Object

Standard parameters for meson builds.


1437
1438
1439
 
# File 'Library/Homebrew/formula.rb', line 1437

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

#supersedes_an_installed_formula? ⇒ Boolean

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

Returns:

  • (Boolean) 

1291
1292
1293
 
# File 'Library/Homebrew/formula.rb', line 1291

def supersedes_an_installed_formula?
  old_installed_formulae.any?
end

#system(cmd, *args) ⇒ Object

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 we have some necessary defaults in #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"

1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
 
# File 'Library/Homebrew/formula.rb', line 1950

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 -= %w[--disable-dependency-tracking --disable-debug --disable-silent-rules]
    when "cargo"
      pretty_args -= std_cargo_args
    when "cmake"
      pretty_args -= std_cmake_args
    when "go"
      pretty_args -= std_go_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 unless (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 { exec_cmd(cmd, args, log, logfn) }
    end

    Process.wait(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, 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

#to_s ⇒ Object 


1363
1364
1365
 
# File 'Library/Homebrew/formula.rb', line 1363

def to_s
  name
end

#update_head_version ⇒ Object 


393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'Library/Homebrew/formula.rb', line 393

def update_head_version
  return unless head?
  return unless head.downloader.is_a?(VCSDownloadStrategy)
  return unless head.downloader.cached_location.exist?

  path = if ENV["HOMEBREW_ENV"]
    ENV["PATH"]
  else
    ENV["HOMEBREW_PATH"]
  end

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

#var ⇒ Object

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


832
833
834
 
# File 'Library/Homebrew/formula.rb', line 832

def var
  HOMEBREW_PREFIX/"var"
end

#version ⇒ Object

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.

See Also:


391
 
# File 'Library/Homebrew/formula.rb', line 391

delegate version: :active_spec

#versioned_formula? ⇒ Boolean

If this is a @-versioned formula.

Returns:

  • (Boolean) 

415
416
417
 
# File 'Library/Homebrew/formula.rb', line 415

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

#versioned_formulae ⇒ Object

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


420
421
422
423
424
425
426
427
428
 
# File 'Library/Homebrew/formula.rb', line 420

def versioned_formulae
  Pathname.glob(path.to_s.gsub(/(@[\d.]+)?\.rb$/, "@*.rb")).map do |versioned_path|
    next if versioned_path == path

    Formula[versioned_path.basename(".rb").to_s]
  rescue FormulaUnavailableError
    nil
  end.compact.sort_by(&:version).reverse
end

#with_logging(log_type) ⇒ Object

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


900
901
902
903
904
905
906
 
# File 'Library/Homebrew/formula.rb', line 900

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) ⇒ Object

Runs xcodebuild without Homebrew's compiler environment variables set.


2104
2105
2106
2107
2108
2109
 
# File 'Library/Homebrew/formula.rb', line 2104

def xcodebuild(*args)
  removed = ENV.remove_cc_etc
  system "xcodebuild", *args
ensure
  ENV.update(removed)
end

#zsh_completion ⇒ Object

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.


864
865
866
 
# File 'Library/Homebrew/formula.rb', line 864

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

#zsh_function ⇒ Object

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.


840
841
842
 
# File 'Library/Homebrew/formula.rb', line 840

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