Class: Formula Abstract

Inherits:
Object
  • Object
show all
Extended by:
BuildEnvironment::DSL, Cachable, Enumerable, Forwardable, OnOS, Predicable, T::Sig
Includes:
Context, FileUtils, OnOS, Utils::Inreplace, Utils::Shebang, Utils::Shell
Defined in:
extend/os/linux/formula.rb,
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 OnOS

on_linux, on_macos

Methods included from BuildEnvironment::DSL

env

Methods included from Cachable

cache, clear_cache

Methods included from Predicable

attr_predicate

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

Homebrew maintainers aim to bottle all formulae that require compilation.

Formulae that can be installed without compilation should be tagged with:

bottle :unneeded

Formulae which should not be bottled should be tagged with:

bottle :disable, "reasons"

See Also:



2552
2553
2554
 
# File 'formula.rb', line 2552

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"


2700
2701
2702
 
# File 'formula.rb', line 2700

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

.deprecation_date ⇒ Object (readonly)

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

Returns:

  • Date

See Also:



2957
2958
2959
 
# File 'formula.rb', line 2957

def deprecation_date
  @deprecation_date
end

.deprecation_reason ⇒ nil, ... (readonly)

The reason for deprecation of a Formula.

Returns:

  • (nil) —

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

  • (String, Symbol)

See Also:



2963
2964
2965
 
# File 'formula.rb', line 2963

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"


2374
 
# File 'formula.rb', line 2374

attr_rw :desc

.disable_date ⇒ Object (readonly)

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

Returns:

  • Date

See Also:



3000
3001
3002
 
# File 'formula.rb', line 3000

def disable_date
  @disable_date
end

.disable_reason ⇒ String, Symbol (readonly)

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

Returns:

See Also:



3006
3007
3008
 
# File 'formula.rb', line 3006

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


2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
 
# File 'formula.rb', line 2602

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


2414
 
# File 'formula.rb', line 2414

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:



2399
2400
2401
2402
2403
2404
2405
 
# File 'formula.rb', line 2399

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

.livecheck(&block) ⇒ Object

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

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


2886
2887
2888
2889
2890
2891
2892
 
# File 'formula.rb', line 2886

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

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

.mirror(val) ⇒ Object

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

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


2509
2510
2511
 
# File 'formula.rb', line 2509

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


2691
2692
2693
 
# File 'formula.rb', line 2691

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


2451
 
# File 'formula.rb', line 2451

attr_rw :revision

.service(&block) ⇒ Object

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

service do
  run [opt_bin/"foo"]
end


2903
2904
2905
2906
2907
 
# File 'formula.rb', line 2903

def service(&block)
  return @service_block unless block

  @service_block = block
end

.sha256(val) ⇒ Object

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

sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"


2521
2522
2523
 
# File 'formula.rb', line 2521

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

.stable(&block) ⇒ Object

Allows adding depends_on and Patches just to the stable SoftwareSpec. This is required instead of using a conditional. It is 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


2583
2584
2585
2586
2587
2588
 
# File 'formula.rb', line 2583

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

  @stable.instance_eval(&block)
end

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

The URL used to download the source for the stable version of the formula. We prefer https for security and proxy reasons. If not 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"


2486
2487
2488
 
# File 'formula.rb', line 2486

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"


2496
2497
2498
 
# File 'formula.rb', line 2496

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


2463
 
# File 'formula.rb', line 2463

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



84
85
86
 
# File 'formula.rb', line 84

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



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

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:



169
170
171
 
# File 'formula.rb', line 169

def build
  @build
end

#buildpath ⇒ Object (readonly)

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



148
149
150
 
# File 'formula.rb', line 148

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) 


175
176
177
 
# File 'formula.rb', line 175

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



94
95
96
 
# File 'formula.rb', line 94

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



89
90
91
 
# File 'formula.rb', line 89

def full_name
  @full_name
end

#name ⇒ Object (readonly)

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



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

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



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

def path
  @path
end

#revision ⇒ Object (readonly)

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

See Also:



140
141
142
 
# File 'formula.rb', line 140

def revision
  @revision
end

#testpath ⇒ Object (readonly)

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



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

def testpath
  @testpath
end

#version_scheme ⇒ Object (readonly)

Used to change version schemes for packages.

See Also:



144
145
146
 
# File 'formula.rb', line 144

def version_scheme
  @version_scheme
end

Class Method Details

.[](name) ⇒ Object 



1676
1677
1678
 
# File 'formula.rb', line 1676

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"


2761
2762
2763
2764
 
# File 'formula.rb', line 2761

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.



2800
2801
2802
 
# File 'formula.rb', line 2800

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

.depends_on(dep) ⇒ Object

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

:build means this dependency is only needed during build.

depends_on "cmake" => :build

:test means this dependency is only needed during testing.

depends_on "node" => :test

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

depends_on "readline" => :recommended

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

depends_on "glib" => :optional

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

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

Optional and enforce that “boost” is built 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.

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

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


2666
2667
2668
 
# File 'formula.rb', line 2666

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"

See Also:



2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
 
# File 'formula.rb', line 2933

def deprecate!(date: nil, because: nil)
  odisabled "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank?
  odisabled "`deprecate!` without a date", "`deprecate! date: \"#{Date.today}\"`" if date.blank?

  @deprecation_date = Date.parse(date) if date.present?

  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)

See Also:



2949
2950
2951
 
# File 'formula.rb', line 2949

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"

See Also:



2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
 
# File 'formula.rb', line 2972

def disable!(date: nil, because: nil)
  odisabled "`disable!` without a reason", "`disable! because: \"reason\"`" if because.blank?
  odisabled "`disable!` without a date", "`disable! date: \"#{Date.today}\"`" if date.blank?

  @disable_date = Date.parse(date) if date.present?

  if @disable_date && @disable_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)

See Also:



2992
2993
2994
 
# File 'formula.rb', line 2992

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


2825
2826
2827
 
# File 'formula.rb', line 2825

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

.go_resource(name, &block) ⇒ Object 



2626
2627
2628
 
# File 'formula.rb', line 2626

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

.ignore_missing_libraries ⇒ Object

Permit links to certain libraries that don’t exist. Available on Linux only.

Raises:



3025
3026
3027
3028
3029
3030
3031
3032
 
# File 'formula.rb', line 3025

def ignore_missing_libraries(*libs)
  libraries = libs.flatten
  if libraries.any? { |x| !x.is_a?(String) && !x.is_a?(Regexp) }
    raise FormulaSpecificationError, "#{__method__} can handle Strings and Regular Expressions only"
  end

  allowed_missing_libraries.merge(libraries)
end

.installed_with_alias_path(alias_path) ⇒ Object 



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

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

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

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

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

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

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


2795
2796
2797
 
# File 'formula.rb', line 2795

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

.link_overwrite(*paths) ⇒ Object

Permit overwriting certain files while linking.

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

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


3014
3015
3016
3017
 
# File 'formula.rb', line 3014

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

.livecheckable? ⇒ Boolean

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

Returns:

  • (Boolean) 


2419
2420
2421
 
# File 'formula.rb', line 2419

def livecheckable?
  @livecheckable == true
end

.needs(*standards) ⇒ Object

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

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

See Also:

  • #fails_with


2838
2839
2840
 
# File 'formula.rb', line 2838

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



2735
2736
2737
 
# File 'formula.rb', line 2735

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"


2749
2750
2751
2752
 
# File 'formula.rb', line 2749

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) 


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

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


2620
2621
2622
2623
2624
 
# File 'formula.rb', line 2620

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

.service? ⇒ Boolean

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

Returns:

  • (Boolean) 


2426
2427
2428
 
# File 'formula.rb', line 2426

def service?
  @service_block.present?
end

.skip_clean(*paths) ⇒ Object

Skip cleaning paths in a formula.

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

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

Keep .la files with:

skip_clean :la


2773
2774
2775
2776
2777
 
# File 'formula.rb', line 2773

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:



2870
2871
2872
 
# File 'formula.rb', line 2870

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.



2673
2674
2675
 
# File 'formula.rb', line 2673

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

Instance Method Details

#active_log_prefix ⇒ String

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

Returns:



912
913
914
915
916
917
918
 
# File 'formula.rb', line 912

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) 


1368
1369
1370
 
# File 'formula.rb', line 1368

def alias_changed?
  installed_alias_target_changed? || supersedes_an_installed_formula?
end

#aliases ⇒ Object

All aliases for the formula.



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

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 



1733
1734
1735
1736
1737
1738
1739
 
# File 'formula.rb', line 1733

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

#any_installed_version ⇒ Object

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



1743
1744
1745
 
# File 'formula.rb', line 1743

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.



876
877
878
 
# File 'formula.rb', line 876

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"


648
649
650
 
# File 'formula.rb', line 648

def bin
  prefix/"bin"
end

#bottle_hash ⇒ Object

Returns the bottle information for a formula



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
 
# File 'formula.rb', line 1914

def bottle_hash
  bottle_spec = stable.bottle_specification
  hash = {
    "rebuild"  => bottle_spec.rebuild,
    "root_url" => bottle_spec.root_url,
    "files"    => {},
  }
  bottle_spec.collector.each_key do |os|
    collector_os = bottle_spec.collector[os]
    os_cellar = collector_os[:cellar]
    os_cellar = os_cellar.is_a?(Symbol) ? os_cellar.inspect : os_cellar

    checksum = collector_os[:checksum].hexdigest
    filename = Bottle::Filename.create(self, os, bottle_spec.rebuild)
    path, = Utils::Bottles.path_resolved_basename(bottle_spec.root_url, name, checksum, filename)
    url = "#{bottle_spec.root_url}/#{path}"

    hash["files"][os] = {
      "cellar" => os_cellar,
      "url"    => url,
      "sha256" => checksum,
    }
  end
  hash
end

#bottle_tab_attributes ⇒ Hash

Returns:

  • (Hash) 


2260
2261
2262
2263
2264
 
# File 'formula.rb', line 2260

def bottle_tab_attributes
  return {} unless bottled?

  T.must(bottle).tab_attributes
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:



1130
1131
1132
 
# File 'formula.rb', line 1130

def caveats
  nil
end

#current_installed_alias_target ⇒ Object 



1348
1349
1350
 
# File 'formula.rb', line 1348

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)

See Also:



1197
 
# File 'formula.rb', line 1197

delegate deprecated?: :"self.class"

#deprecation_date ⇒ Object

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

Returns:

  • Date

See Also:



1204
 
# File 'formula.rb', line 1204

delegate deprecation_date: :"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:

See Also:



1211
 
# File 'formula.rb', line 1211

delegate deprecation_reason: :"self.class"

#desc ⇒ Object

The description of the software.

See Also:



373
 
# File 'formula.rb', line 373

delegate desc: :"self.class"

#disable_date ⇒ Object

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

Returns:

  • Date

See Also:



1225
 
# File 'formula.rb', line 1225

delegate disable_date: :"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:

See Also:



1232
 
# File 'formula.rb', line 1232

delegate disable_reason: :"self.class"

#disabled? ⇒ Boolean

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

Returns:

  • (Boolean)

See Also:



1218
 
# File 'formula.rb', line 1218

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.



655
656
657
 
# File 'formula.rb', line 655

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"


812
813
814
 
# File 'formula.rb', line 812

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.



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

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

#fetch_bottle_tab ⇒ void

This method returns an undefined value.



2253
2254
2255
2256
2257
 
# File 'formula.rb', line 2253

def fetch_bottle_tab
  return unless bottled?

  T.must(bottle).fetch_tab
end

#fetch_patches ⇒ Object 



2248
2249
2250
 
# File 'formula.rb', line 2248

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.



892
893
894
 
# File 'formula.rb', line 892

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.



868
869
870
 
# File 'formula.rb', line 868

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.



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

def frameworks
  prefix/"Frameworks"
end

#full_installed_alias_name ⇒ Object 



305
306
307
 
# File 'formula.rb', line 305

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.



330
331
332
 
# File 'formula.rb', line 330

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.



320
321
322
 
# File 'formula.rb', line 320

def full_specified_name
  full_alias_name || full_name
end

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

Returns:

  • (Boolean) 


550
551
552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'formula.rb', line 550

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:



383
 
# File 'formula.rb', line 383

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"


665
666
667
 
# File 'formula.rb', line 665

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.



672
673
674
 
# File 'formula.rb', line 672

def info
  share/"info"
end

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

See Also:




# File 'formula.rb', line 71

#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


2010
 
# File 'formula.rb', line 2010

def install; end

#installed_alias_name ⇒ String?

Returns:



301
302
303
 
# File 'formula.rb', line 301

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.



292
293
294
295
296
297
298
 
# File 'formula.rb', line 292

def installed_alias_path
  path = build.source["path"] if build.is_a?(Tab)
  return unless path&.match?(%r{#{HOMEBREW_TAP_DIR_REGEX}/Aliases}o)
  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) 


1354
1355
1356
1357
1358
1359
 
# File 'formula.rb', line 1354

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.



325
326
327
 
# File 'formula.rb', line 325

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:



1137
1138
1139
1140
1141
 
# File 'formula.rb', line 1137

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.



828
829
830
 
# File 'formula.rb', line 828

def kext_prefix
  prefix/"Library/Extensions"
end

#latest_formula ⇒ Object

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



1374
1375
1376
 
# File 'formula.rb', line 1374

def latest_formula
  installed_alias_target_changed? ? current_installed_alias_target : self
end

#latest_head_prefix ⇒ Object 



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

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

#latest_head_version ⇒ Object 



534
535
536
537
538
539
540
541
542
543
 
# File 'formula.rb', line 534

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"


682
683
684
 
# File 'formula.rb', line 682

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 commonly used to install files that we do not wish to be symlinked into HOMEBREW_PREFIX from one of the other directories and instead manually create symlinks or wrapper scripts into e.g. #bin.

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



694
695
696
 
# File 'formula.rb', line 694

def libexec
  prefix/"libexec"
end

#license ⇒ Object

The SPDX ID of the software license.

See Also:



378
 
# File 'formula.rb', line 378

delegate license: :"self.class"

#linked? ⇒ Boolean

Is the formula linked?

Returns:

  • (Boolean) 


592
593
594
 
# File 'formula.rb', line 592

def linked?
  linked_keg.symlink?
end

#linked_version ⇒ PkgVersion?

PkgVersion of the linked keg for the formula.

Returns:



610
611
612
613
614
 
# File 'formula.rb', line 610

def linked_version
  return unless linked?

  Keg.for(linked_keg).version
end

#livecheck ⇒ Object

The livecheck specification for the software.

See Also:



388
 
# File 'formula.rb', line 388

delegate livecheck: :"self.class"

#livecheckable? ⇒ Object

Is a livecheck specification defined for the software?

See Also:



393
 
# File 'formula.rb', line 393

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.



703
704
705
 
# File 'formula.rb', line 703

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"


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

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.



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

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"


730
731
732
 
# File 'formula.rb', line 730

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.



737
738
739
 
# File 'formula.rb', line 737

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.



744
745
746
 
# File 'formula.rb', line 744

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.



751
752
753
 
# File 'formula.rb', line 751

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.



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

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.



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

def man8
  man/"man8"
end

#migration_needed? ⇒ Boolean

Returns:

  • (Boolean) 


1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
 
# File 'formula.rb', line 1296

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.



1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
 
# File 'formula.rb', line 1804

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.



2229
2230
2231
2232
2233
2234
 
# File 'formula.rb', line 2229

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

  FileUtils.chdir(name, &block)
end

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

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



2223
2224
2225
 
# File 'formula.rb', line 2223

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

#new_formula_available? ⇒ Boolean

Returns:

  • (Boolean) 


1344
1345
1346
 
# File 'formula.rb', line 1344

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

#old_installed_formulae ⇒ Object 



1378
1379
1380
1381
1382
1383
1384
1385
 
# File 'formula.rb', line 1378

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.



453
454
455
456
457
458
 
# File 'formula.rb', line 453

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

Returns:



1009
1010
1011
 
# File 'formula.rb', line 1009

def opt_bin
  opt_prefix/"bin"
end

#opt_elisp ⇒ Pathname

Returns:



1044
1045
1046
 
# File 'formula.rb', line 1044

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

#opt_frameworks ⇒ Pathname

Returns:



1049
1050
1051
 
# File 'formula.rb', line 1049

def opt_frameworks
  opt_prefix/"Frameworks"
end

#opt_include ⇒ Pathname

Returns:



1014
1015
1016
 
# File 'formula.rb', line 1014

def opt_include
  opt_prefix/"include"
end

#opt_lib ⇒ Pathname

Returns:



1019
1020
1021
 
# File 'formula.rb', line 1019

def opt_lib
  opt_prefix/"lib"
end

#opt_libexec ⇒ Pathname

Returns:



1024
1025
1026
 
# File 'formula.rb', line 1024

def opt_libexec
  opt_prefix/"libexec"
end

#opt_pkgshare ⇒ Pathname

Returns:



1039
1040
1041
 
# File 'formula.rb', line 1039

def opt_pkgshare
  opt_prefix/"share"/name
end

#opt_prefix ⇒ Pathname

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

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

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

Returns:



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

def opt_prefix
  HOMEBREW_PREFIX/"opt"/name
end

#opt_sbin ⇒ Pathname

Returns:



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

def opt_sbin
  opt_prefix/"sbin"
end

#opt_share ⇒ Pathname

Returns:



1034
1035
1036
 
# File 'formula.rb', line 1034

def opt_share
  opt_prefix/"share"
end

#option_defined? ⇒ Object

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



504
 
# File 'formula.rb', line 504

delegate option_defined?: :active_spec

#optlinked? ⇒ Boolean

Is the formula linked to opt?

Returns:

  • (Boolean) 


597
598
599
 
# File 'formula.rb', line 597

def optlinked?
  opt_prefix.symlink?
end

#pkg_version ⇒ PkgVersion

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

Returns:



425
426
427
 
# File 'formula.rb', line 425

def pkg_version
  PkgVersion.new(version, revision)
end

#pkgetc ⇒ Object

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



845
846
847
 
# File 'formula.rb', line 845

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"


803
804
805
 
# File 'formula.rb', line 803

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:



955
956
957
 
# File 'formula.rb', line 955

def plist
  nil
end

#plist_name ⇒ String

The generated launchd #plist service name.

Returns:



961
962
963
 
# File 'formula.rb', line 961

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

#plist_path ⇒ Pathname

The generated launchd #plist file path.

Returns:



973
974
975
 
# File 'formula.rb', line 973

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

#post_install ⇒ void

This method returns an undefined value.

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



1069
 
# File 'formula.rb', line 1069

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) 


1060
1061
1062
 
# File 'formula.rb', line 1060

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.



581
582
583
584
585
586
587
588
589
 
# File 'formula.rb', line 581

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) 


602
603
604
605
606
 
# File 'formula.rb', line 602

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


450
 
# File 'formula.rb', line 450

delegate resource: :active_spec

#resources ⇒ Object

The Resources for the currently active SoftwareSpec.



473
 
# File 'formula.rb', line 473

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

#rpath ⇒ String

Executable/Library RPATH according to platform conventions.

Returns:



1540
1541
1542
 
# File 'formula.rb', line 1540

def rpath
  "'$ORIGIN/../lib'"
end

#runtime_installed_formula_dependents ⇒ Object 



1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
 
# File 'formula.rb', line 1785

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.



773
774
775
 
# File 'formula.rb', line 773

def sbin
  prefix/"sbin"
end

#service ⇒ Object

The service specification of the software.



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

def service
  return unless service?

  Homebrew::Service.new(self, &self.class.service)
end

#service? ⇒ Object

Is a service specification defined for the software?

See Also:



398
 
# File 'formula.rb', line 398

delegate service?: :"self.class"

#service_name ⇒ String

The generated service name.

Returns:



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

def service_name
  "homebrew.#{name}"
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"


792
793
794
 
# File 'formula.rb', line 792

def share
  prefix/"share"
end

#shared_library(name, version = nil) ⇒ String

Shared library names according to platform conventions.

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

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


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

Parameters:

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

Returns:



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

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

#skip_cxxstdlib_check? ⇒ Boolean

Returns:

  • (Boolean) 


1235
1236
1237
 
# File 'formula.rb', line 1235

def skip_cxxstdlib_check?
  false
end

#specified_name ⇒ Object

The name specified to find this formula.



315
316
317
 
# File 'formula.rb', line 315

def specified_name
  alias_name || name
end

#specified_path ⇒ Object

The path that was specified to find this formula.



310
311
312
 
# File 'formula.rb', line 310

def specified_path
  alias_path || path
end

#std_cabal_v2_args ⇒ Array<String>

Standard parameters for cabal-v2 builds.

Returns:



1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
 
# File 'formula.rb', line 1495

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

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

#std_cargo_args ⇒ Array<String, Pathname>

Standard parameters for cargo builds.

Returns:



1452
1453
1454
 
# File 'formula.rb', line 1452

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

#std_cmake_args ⇒ Array<String>

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.

Returns:



1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
 
# File 'formula.rb', line 1462

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

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

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

  args
end

#std_configure_args ⇒ Array<String>

Standard parameters for configure builds.

Returns:



1446
1447
1448
 
# File 'formula.rb', line 1446

def std_configure_args
  ["--disable-debug", "--disable-dependency-tracking", "--prefix=#{prefix}", "--libdir=#{lib}"]
end

#std_go_args(ldflags: nil) ⇒ Array<String>

Standard parameters for Go builds.

Parameters:

  • ldflags (String, nil) (defaults to: nil)

Returns:



1487
1488
1489
1490
1491
 
# File 'formula.rb', line 1487

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

#std_meson_args ⇒ Array<String>

Standard parameters for meson builds.

Returns:



1509
1510
1511
 
# File 'formula.rb', line 1509

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) 


1362
1363
1364
 
# File 'formula.rb', line 1362

def supersedes_an_installed_formula?
  old_installed_formulae.any?
end

#system(cmd, *args) ⇒ void

This method returns an undefined value.

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

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

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

system "cmake", ".", *std_cmake_args

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

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

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

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

Parameters:



2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
 
# File 'formula.rb', line 2081

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 do
        exec_cmd(cmd, args, log, logfn)
      end
    end

    Process.wait(T.must(pid))

    $stdout.flush

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

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

      require "system_config"
      require "build_environment"

      env = ENV.to_hash

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

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

#systemd_service_path ⇒ Pathname

The generated systemd service file path.

Returns:



979
980
981
 
# File 'formula.rb', line 979

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

#to_s ⇒ Object 



1434
1435
1436
 
# File 'formula.rb', line 1434

def to_s
  name
end

#update_head_version ⇒ Object 



407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'formula.rb', line 407

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.



852
853
854
 
# File 'formula.rb', line 852

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:



405
 
# File 'formula.rb', line 405

delegate version: :active_spec

#versioned_formula? ⇒ Boolean

If this is a @-versioned formula.

Returns:

  • (Boolean) 


430
431
432
 
# File 'formula.rb', line 430

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

#versioned_formulae ⇒ Object

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



435
436
437
438
439
440
441
442
443
 
# File 'formula.rb', line 435

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.



921
922
923
924
925
926
927
 
# File 'formula.rb', line 921

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

#xcodebuild(*args) ⇒ void

This method returns an undefined value.

Runs xcodebuild without Homebrew’s compiler environment variables set.

Parameters:



2238
2239
2240
2241
2242
2243
2244
2245
2246
 
# File 'formula.rb', line 2238

def xcodebuild(*args)
  removed = ENV.remove_cc_etc

  begin
    T.unsafe(self).system("xcodebuild", *args)
  ensure
    ENV.update(removed)
  end
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.



884
885
886
 
# File 'formula.rb', line 884

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.



860
861
862
 
# File 'formula.rb', line 860

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