Class: Formula Abstract

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

Overview

This class is abstract.

A formula provides instructions and metadata for Homebrew to install a piece of software. Every Homebrew formula is a Formula. All subclasses of Formula (and all Ruby classes) have to be named UpperCase and not-use-dashes. A formula specified in this-formula.rb should have a class named ThisFormula. Homebrew does enforce that the name of the file and the class correspond. Make sure you check with brew search that the name is free!

class Wget < Formula
  homepage "https://www.gnu.org/software/wget/"
  url "https://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz"
  sha256 "52126be8cf1bddd7536886e74c053ad7d0ed2aa89b4b630f76785bac21695fcd"

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

See Also:

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 Cachable

cache, clear_cache

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

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 # Making the old bottle outdated without bumping the version/revision of the formula.
  sha256 "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865" => :el_capitan
  sha256 "53c234e5e8472b6ac51c1ae1cab3fe06fad053beb8ebfd8977b010655bfdd3c3" => :yosemite
  sha256 "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2" => :mavericks
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:



2306
2307
2308
 
# File 'brew/Library/Homebrew/formula.rb', line 2306

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"


2455
2456
2457
 
# File 'brew/Library/Homebrew/formula.rb', line 2455

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


2167
 
# File 'brew/Library/Homebrew/formula.rb', line 2167

attr_rw :desc

.devel(&block) ⇒ Object

Adds a devel SoftwareSpec. This can be installed by passing the --devel option to allow installing non-stable (e.g. beta) versions of software.

devel do
  url "https://example.com/archive-2.0-beta.tar.gz"
  sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"

  depends_on "cairo"
  depends_on "pixman"
end


2346
2347
2348
2349
2350
2351
 
# File 'brew/Library/Homebrew/formula.rb', line 2346

def devel(&block)
  @devel ||= SoftwareSpec.new
  return @devel unless block_given?

  @devel.instance_eval(&block)
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", :revision => "abc123"

or (if autodetect fails):

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


2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
 
# File 'brew/Library/Homebrew/formula.rb', line 2365

def head(val = nil, specs = {}, &block)
  @head ||= HeadSoftwareSpec.new
  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"


2176
 
# File 'brew/Library/Homebrew/formula.rb', line 2176

attr_rw :homepage

.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


2258
2259
2260
 
# File 'brew/Library/Homebrew/formula.rb', line 2258

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 the autogenerated one from 'depends_on "qt" => :optional'"
option :universal


2446
2447
2448
 
# File 'brew/Library/Homebrew/formula.rb', line 2446

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


2199
 
# File 'brew/Library/Homebrew/formula.rb', line 2199

attr_rw :revision

.sha256=(value) ⇒ Object (writeonly)

To verify the cached download’s integrity and security we verify the SHA-256 hash matches which 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"


2270
2271
2272
 
# File 'brew/Library/Homebrew/formula.rb', line 2270

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


2327
2328
2329
2330
2331
2332
 
# File 'brew/Library/Homebrew/formula.rb', line 2327

def stable(&block)
  @stable ||= SoftwareSpec.new
  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)
  • :s3 (download from S3 using signed request)
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"


2235
2236
2237
 
# File 'brew/Library/Homebrew/formula.rb', line 2235

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"


2245
2246
2247
 
# File 'brew/Library/Homebrew/formula.rb', line 2245

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


2211
 
# File 'brew/Library/Homebrew/formula.rb', line 2211

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



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

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



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

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:



171
172
173
 
# File 'brew/Library/Homebrew/formula.rb', line 171

def build
  @build
end

#buildpath ⇒ Object (readonly)

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



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

def buildpath
  @buildpath
end

#follow_installed_alias ⇒ Boolean Also known as: follow_installed_alias?

A Boolean indicating 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) 


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

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



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

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



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

def full_name
  @full_name
end

#name ⇒ Object (readonly)

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



74
75
76
 
# File 'brew/Library/Homebrew/formula.rb', line 74

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



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

def path
  @path
end

#revision ⇒ Object (readonly)

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

See Also:



143
144
145
 
# File 'brew/Library/Homebrew/formula.rb', line 143

def revision
  @revision
end

#testpath ⇒ Object (readonly)

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



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

def testpath
  @testpath
end

#version_scheme ⇒ Object (readonly)

Used to change version schemes for packages



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

def version_scheme
  @version_scheme
end

Class Method Details

.[](name) ⇒ Object 



1512
1513
1514
 
# File 'brew/Library/Homebrew/formula.rb', line 1512

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

.clear_installed_formulae_cache ⇒ Object

Clear caches of .racks and .installed.



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

def self.clear_installed_formulae_cache
  clear_racks_cache
  @installed = nil
end

.clear_racks_cache ⇒ Object

Clear cache of .racks



1432
1433
1434
 
# File 'brew/Library/Homebrew/formula.rb', line 1432

def self.clear_racks_cache
  @racks = nil
end

.conflicts_with(*names) ⇒ Object

If this formula conflicts with another one.

conflicts_with "imagemagick", :because => "because both install 'convert' binaries"


2515
2516
2517
2518
 
# File 'brew/Library/Homebrew/formula.rb', line 2515

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



2544
2545
2546
 
# File 'brew/Library/Homebrew/formula.rb', line 2544

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
depends_on "homebrew/dupes/tcl-tk" => :optional
# `: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.
# But a `--with-...` options is generated.
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 == :mavericks
depends_on :xcode # If the formula really needs full Xcode.
depends_on :macos => :mojave # Needs at least macOS Mojave (10.14).
depends_on :x11 => :optional # X11/XQuartz components.
depends_on :osxfuse # Permits the use of the upstream signed binary or our source package.
depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.
# It is possible to only depend on something if
# `build.with?` or `build.without? "another_formula"`:
depends_on "postgresql" if build.without? "sqlite"
# Python 3.x if the `--with-python` is given to `brew install example`
depends_on "python3" => :optional


2424
2425
2426
 
# File 'brew/Library/Homebrew/formula.rb', line 2424

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

.deprecate!(date: nil) ⇒ Object

Deprecates a Formula so a warning is shown on each installation.



2623
2624
2625
2626
2627
 
# File 'brew/Library/Homebrew/formula.rb', line 2623

def deprecate!(date: nil)
  return if date.present? && Date.parse(date) > Date.today

  @deprecated = true
end

.deprecated? ⇒ Boolean

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

Returns:

  • (Boolean) 


2632
2633
2634
 
# File 'brew/Library/Homebrew/formula.rb', line 2632

def deprecated?
  @deprecated == true
end

.disable!(date: nil) ⇒ Object

Disables a Formula so it cannot be installed.



2637
2638
2639
2640
2641
 
# File 'brew/Library/Homebrew/formula.rb', line 2637

def disable!(date: nil)
  return if date.present? && Date.parse(date) > Date.today

  @disabled = true
end

.disabled? ⇒ Boolean

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

Returns:

  • (Boolean) 


2646
2647
2648
 
# File 'brew/Library/Homebrew/formula.rb', line 2646

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 be blacklisted 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 be blacklisted 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


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

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

.go_resource(name, &block) ⇒ Object 



2389
2390
2391
 
# File 'brew/Library/Homebrew/formula.rb', line 2389

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

.installed_with_alias_path(alias_path) ⇒ Object 



1464
1465
1466
1467
1468
 
# File 'brew/Library/Homebrew/formula.rb', line 1464

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"


2539
2540
2541
 
# File 'brew/Library/Homebrew/formula.rb', line 2539

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

.needs(*standards) ⇒ Object 



2573
2574
2575
 
# File 'brew/Library/Homebrew/formula.rb', line 2573

def needs(*standards)
  specs.each { |spec| spec.needs(*standards) }
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, devel, 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, "..."


2489
2490
2491
 
# File 'brew/Library/Homebrew/formula.rb', line 2489

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"


2503
2504
2505
2506
 
# File 'brew/Library/Homebrew/formula.rb', line 2503

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) 


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

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, devel 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


2383
2384
2385
2386
2387
 
# File 'brew/Library/Homebrew/formula.rb', line 2383

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 



2520
2521
2522
2523
2524
 
# File 'brew/Library/Homebrew/formula.rb', line 2520

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 are fine if the executable does not error out, so we know linking and building the software was OK.

system bin/"foobar", "--version"
(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) 


2601
2602
2603
 
# File 'brew/Library/Homebrew/formula.rb', line 2601

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

.uses_from_macos(dep) ⇒ Object 



2428
2429
2430
 
# File 'brew/Library/Homebrew/formula.rb', line 2428

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

Instance Method Details

#active_log_prefix ⇒ Object

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



855
856
857
858
859
860
861
 
# File 'brew/Library/Homebrew/formula.rb', line 855

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) 


1253
1254
1255
 
# File 'brew/Library/Homebrew/formula.rb', line 1253

def alias_changed?
  installed_alias_target_changed? || supersedes_an_installed_formula?
end

#aliases ⇒ Object

All aliases for the formula



416
417
418
419
420
421
422
423
424
 
# File 'brew/Library/Homebrew/formula.rb', line 416

def aliases
  @aliases ||= if tap
    tap.alias_reverse_table[full_name].to_a.map do |a|
      a.split("/").last
    end
  else
    []
  end
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.



820
821
822
 
# File 'brew/Library/Homebrew/formula.rb', line 820

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"


603
604
605
 
# File 'brew/Library/Homebrew/formula.rb', line 603

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:



1039
1040
1041
 
# File 'brew/Library/Homebrew/formula.rb', line 1039

def caveats
  nil
end

#current_installed_alias_target ⇒ Object 



1233
1234
1235
 
# File 'brew/Library/Homebrew/formula.rb', line 1233

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) 


1111
1112
1113
 
# File 'brew/Library/Homebrew/formula.rb', line 1111

def deprecated?
  self.class.deprecated?
end

#desc ⇒ Object

The description of the software.

See Also:



349
 
# File 'brew/Library/Homebrew/formula.rb', line 349

delegate desc: :"self.class"

#disabled? ⇒ Boolean

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

Returns:

  • (Boolean) 


1118
1119
1120
 
# File 'brew/Library/Homebrew/formula.rb', line 1118

def disabled?
  self.class.disabled?
end

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



610
611
612
 
# File 'brew/Library/Homebrew/formula.rb', line 610

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.

Install an Emacs mode included with a software package:

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


764
765
766
 
# File 'brew/Library/Homebrew/formula.rb', line 764

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.



789
790
791
 
# File 'brew/Library/Homebrew/formula.rb', line 789

def etc
  (HOMEBREW_PREFIX/"etc").extend(InstallRenamed)
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.



836
837
838
 
# File 'brew/Library/Homebrew/formula.rb', line 836

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.



812
813
814
 
# File 'brew/Library/Homebrew/formula.rb', line 812

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.



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

def frameworks
  prefix/"Frameworks"
end

#full_installed_alias_name ⇒ Object 



283
284
285
 
# File 'brew/Library/Homebrew/formula.rb', line 283

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.



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

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.



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

def full_specified_name
  full_alias_name || full_name
end

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

Returns:

  • (Boolean) 


501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'brew/Library/Homebrew/formula.rb', line 501

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 true if devel && tab.devel_version && tab.devel_version < devel.version
  return false unless fetch_head
  return false unless head&.downloader.is_a?(VCSDownloadStrategy)

  downloader = head.downloader
  downloader.shutup! unless Homebrew.args.verbose?
  downloader.commit_outdated?(version.version.commit)
end

#homepage ⇒ Object

The homepage for the software.

See Also:



354
 
# File 'brew/Library/Homebrew/formula.rb', line 354

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"


620
621
622
 
# File 'brew/Library/Homebrew/formula.rb', line 620

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.



627
628
629
 
# File 'brew/Library/Homebrew/formula.rb', line 627

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 var 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 'brew/Library/Homebrew/formula.rb', line 60

#install ⇒ Object

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

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


1825
 
# File 'brew/Library/Homebrew/formula.rb', line 1825

def install; end

#installed_alias_name ⇒ Object 



279
280
281
 
# File 'brew/Library/Homebrew/formula.rb', line 279

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.



271
272
273
274
275
276
277
 
# File 'brew/Library/Homebrew/formula.rb', line 271

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) 


1239
1240
1241
1242
1243
1244
 
# File 'brew/Library/Homebrew/formula.rb', line 1239

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.



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

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) 


1045
1046
1047
1048
1049
 
# File 'brew/Library/Homebrew/formula.rb', line 1045

def keg_only?
  return false unless keg_only_reason

  keg_only_reason.valid?
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.



780
781
782
 
# File 'brew/Library/Homebrew/formula.rb', line 780

def kext_prefix
  prefix/"Library/Extensions"
end

#latest_formula ⇒ Object

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



1259
1260
1261
 
# File 'brew/Library/Homebrew/formula.rb', line 1259

def latest_formula
  installed_alias_target_changed? ? current_installed_alias_target : self
end

#latest_head_prefix ⇒ Object 



496
497
498
499
 
# File 'brew/Library/Homebrew/formula.rb', line 496

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

#latest_head_version ⇒ Object 



485
486
487
488
489
490
491
492
493
494
 
# File 'brew/Library/Homebrew/formula.rb', line 485

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"


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

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.



646
647
648
 
# File 'brew/Library/Homebrew/formula.rb', line 646

def libexec
  prefix/"libexec"
end

#linked? ⇒ Boolean

Is the formula linked?

Returns:

  • (Boolean) 


552
553
554
 
# File 'brew/Library/Homebrew/formula.rb', line 552

def linked?
  linked_keg.symlink?
end

#linked_version ⇒ Object

PkgVersion of the linked keg for the formula.



569
570
571
572
573
 
# File 'brew/Library/Homebrew/formula.rb', line 569

def linked_version
  return unless linked?

  Keg.for(linked_keg).version
end

#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



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

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"


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

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.



672
673
674
 
# File 'brew/Library/Homebrew/formula.rb', line 672

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"


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

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.



689
690
691
 
# File 'brew/Library/Homebrew/formula.rb', line 689

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.



696
697
698
 
# File 'brew/Library/Homebrew/formula.rb', line 696

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.



703
704
705
 
# File 'brew/Library/Homebrew/formula.rb', line 703

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.



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

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.



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

def man8
  man/"man8"
end

#migration_needed? ⇒ Boolean

Returns:

  • (Boolean) 


1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
 
# File 'brew/Library/Homebrew/formula.rb', line 1179

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



1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
 
# File 'brew/Library/Homebrew/formula.rb', line 1630

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

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



2040
2041
2042
2043
2044
2045
2046
2047
 
# File 'brew/Library/Homebrew/formula.rb', line 2040

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

  FileUtils.chdir name do
    yield
  end
end

#mktemp(prefix = name, opts = {}) ⇒ 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.



2032
2033
2034
2035
2036
 
# File 'brew/Library/Homebrew/formula.rb', line 2032

def mktemp(prefix = name, opts = {})
  Mktemp.new(prefix, opts).run do |staging|
    yield staging
  end
end

#new_formula_available? ⇒ Boolean

Returns:

  • (Boolean) 


1229
1230
1231
 
# File 'brew/Library/Homebrew/formula.rb', line 1229

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

#old_installed_formulae ⇒ Object 



1263
1264
1265
1266
1267
1268
1269
1270
 
# File 'brew/Library/Homebrew/formula.rb', line 1263

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



408
409
410
411
412
413
 
# File 'brew/Library/Homebrew/formula.rb', line 408

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

#opt_bin ⇒ Object 



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

def opt_bin
  opt_prefix/"bin"
end

#opt_elisp ⇒ Object 



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

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

#opt_frameworks ⇒ Object 



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

def opt_frameworks
  opt_prefix/"Frameworks"
end

#opt_include ⇒ Object 



937
938
939
 
# File 'brew/Library/Homebrew/formula.rb', line 937

def opt_include
  opt_prefix/"include"
end

#opt_lib ⇒ Object 



941
942
943
 
# File 'brew/Library/Homebrew/formula.rb', line 941

def opt_lib
  opt_prefix/"lib"
end

#opt_libexec ⇒ Object 



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

def opt_libexec
  opt_prefix/"libexec"
end

#opt_pkgshare ⇒ Object 



957
958
959
 
# File 'brew/Library/Homebrew/formula.rb', line 957

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"


929
930
931
 
# File 'brew/Library/Homebrew/formula.rb', line 929

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

#opt_sbin ⇒ Object 



949
950
951
 
# File 'brew/Library/Homebrew/formula.rb', line 949

def opt_sbin
  opt_prefix/"sbin"
end

#opt_share ⇒ Object 



953
954
955
 
# File 'brew/Library/Homebrew/formula.rb', line 953

def opt_share
  opt_prefix/"share"
end

#option_defined? ⇒ Object

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



459
 
# File 'brew/Library/Homebrew/formula.rb', line 459

delegate option_defined?: :active_spec

#optlinked? ⇒ Boolean

Is the formula linked to opt?

Returns:

  • (Boolean) 


557
558
559
 
# File 'brew/Library/Homebrew/formula.rb', line 557

def optlinked?
  opt_prefix.symlink?
end

#pkg_version ⇒ Object

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



380
381
382
 
# File 'brew/Library/Homebrew/formula.rb', line 380

def pkg_version
  PkgVersion.new(version, revision)
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"


755
756
757
 
# File 'brew/Library/Homebrew/formula.rb', line 755

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:



898
899
900
 
# File 'brew/Library/Homebrew/formula.rb', line 898

def plist
  nil
end

#plist_name ⇒ Object

The generated launchd #plist service name.



903
904
905
 
# File 'brew/Library/Homebrew/formula.rb', line 903

def plist_name
  "homebrew.mxcl." + name
end

#plist_path ⇒ Object

The generated launchd #plist file path.



908
909
910
 
# File 'brew/Library/Homebrew/formula.rb', line 908

def plist_path
  prefix + (plist_name + ".plist")
end

#post_install ⇒ Object

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



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

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) 


975
976
977
 
# File 'brew/Library/Homebrew/formula.rb', line 975

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.



541
542
543
544
545
546
547
548
549
 
# File 'brew/Library/Homebrew/formula.rb', line 541

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) 


562
563
564
565
566
 
# File 'brew/Library/Homebrew/formula.rb', line 562

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


405
 
# File 'brew/Library/Homebrew/formula.rb', line 405

delegate resource: :active_spec

#resources ⇒ Object

The Resources for the currently active SoftwareSpec.



428
 
# File 'brew/Library/Homebrew/formula.rb', line 428

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

#runtime_installed_formula_dependents ⇒ Object 



1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
 
# File 'brew/Library/Homebrew/formula.rb', line 1611

def runtime_installed_formula_dependents  # `opt_or_installed_prefix_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][name] ||= Formula.installed
                                                                        .select(&:opt_or_installed_prefix_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.



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

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"


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

def share
  prefix/"share"
end

#skip_cxxstdlib_check? ⇒ Boolean

Returns:

  • (Boolean) 


1122
1123
1124
 
# File 'brew/Library/Homebrew/formula.rb', line 1122

def skip_cxxstdlib_check?
  false
end

#specified_name ⇒ Object

The name specified to find this formula.



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

def specified_name
  alias_name || name
end

#specified_path ⇒ Object

The path that was specified to find this formula.



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

def specified_path
  alias_path || path
end

#std_cabal_v2_args ⇒ Object

Standard parameters for cabal-v2 builds.



1367
1368
1369
1370
1371
1372
1373
1374
1375
 
# File 'brew/Library/Homebrew/formula.rb', line 1367

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



1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
 
# File 'brew/Library/Homebrew/formula.rb', line 1339

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.
  sdk = MacOS.sdk_path_if_needed
  args << "-DCMAKE_OSX_SYSROOT=#{sdk}" if sdk

  args
end

#std_go_args ⇒ Object

Standard parameters for Go builds.



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

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

#supersedes_an_installed_formula? ⇒ Boolean

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

Returns:

  • (Boolean) 


1247
1248
1249
 
# File 'brew/Library/Homebrew/formula.rb', line 1247

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

args = ["--with-option1", "--with-option2"]

# Most software still uses `configure` and `make`.
# Check with `./configure --help` 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"


1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
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
 
# File 'brew/Library/Homebrew/formula.rb', line 1892

def system(cmd, *args)
  verbose = Homebrew.args.verbose?
  verbose_using_dots = !ENV["HOMEBREW_VERBOSE_USING_DOTS"].nil?

  # 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 "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 = ENV["HOMEBREW_FAIL_LOG_LINES"]
      log_lines ||= "15"

      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
      Homebrew.dump_build_env(env, log)

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

#to_s ⇒ Object 



1324
1325
1326
 
# File 'brew/Library/Homebrew/formula.rb', line 1324

def to_s
  name
end

#update_head_version ⇒ Object 



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
 
# File 'brew/Library/Homebrew/formula.rb', line 363

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.



796
797
798
 
# File 'brew/Library/Homebrew/formula.rb', line 796

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:



361
 
# File 'brew/Library/Homebrew/formula.rb', line 361

delegate version: :active_spec

#versioned_formula? ⇒ Boolean

If this is a @-versioned formula.

Returns:

  • (Boolean) 


385
386
387
 
# File 'brew/Library/Homebrew/formula.rb', line 385

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

#versioned_formulae ⇒ Object

Returns any @-versioned formulae for an non-@-versioned formula.



390
391
392
393
394
395
396
397
398
 
# File 'brew/Library/Homebrew/formula.rb', line 390

def versioned_formulae
  return [] if versioned_formula?

  Pathname.glob(path.to_s.gsub(/\.rb$/, "@*.rb")).map do |path|
    Formula[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



864
865
866
867
868
869
870
 
# File 'brew/Library/Homebrew/formula.rb', line 864

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

Run xcodebuild without Homebrew’s compiler environment variables set.



2050
2051
2052
2053
2054
2055
 
# File 'brew/Library/Homebrew/formula.rb', line 2050

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.



828
829
830
 
# File 'brew/Library/Homebrew/formula.rb', line 828

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.



804
805
806
 
# File 'brew/Library/Homebrew/formula.rb', line 804

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