mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Adjust comments to tidy API docs output.

Browse Source
This commit is contained in:
EricFromCanada 2018-10-18 21:42:43 -04:00
parent de9cb69206
commit 20167e5f1b
52 changed files with 267 additions and 260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.yardopts
View File

@ -7,7 +7,4 @@
--exclude Library/Homebrew/compat/
Library/Homebrew/**/*.rb
-
share/doc/homebrew/*.html
Library/Homebrew/*.md
share/doc/homebrew/*.md
*.md

4
Library/Homebrew/cache_store.rb
View File

@ -2,7 +2,7 @@ require "json"
#
# `CacheStoreDatabase` acts as an interface to a persistent storage mechanism
# residing in the `HOMEBREW_CACHE`
# residing in the `HOMEBREW_CACHE`.
#
class CacheStoreDatabase
# Yields the cache store database.
@ -107,7 +107,7 @@ end
#
# `CacheStore` provides methods to mutate and fetch data from a persistent
# storage mechanism
# storage mechanism.
#
class CacheStore
# @param [CacheStoreDatabase] database

2
Library/Homebrew/cask/cmd/doctor.rb
View File

@ -42,7 +42,7 @@ module Cask
end
# This could be done by calling into Homebrew, but the situation
# where "doctor" is needed is precisely the situation where such
# where `brew doctor` is needed is precisely the situation where such
# things are less dependable.
def check_install_location
ohai "Homebrew Cask Install Location"

6
Library/Homebrew/cask/installer.rb
View File

@ -221,9 +221,9 @@ module Cask
end
end
# TODO: move dependencies to a separate class
# dependencies should also apply for "brew cask stage"
# override dependencies with --force or perhaps --force-deps
# TODO: move dependencies to a separate class,
# dependencies should also apply for `brew cask stage`,
# override dependencies with `--force` or perhaps `--force-deps`
def satisfy_dependencies
return unless @cask.depends_on

7
Library/Homebrew/cleaner.rb
View File

@ -1,8 +1,9 @@
# Cleans a newly installed keg.
# By default:
# * removes .la files
# * removes perllocal.pod files
# * removes .packlist files
#
# * removes `.la` files
# * removes `perllocal.pod` files
# * removes `.packlist` files
# * removes empty directories
# * sets permissions on executables
# * removes unresolved symlinks

4
Library/Homebrew/cmd/upgrade.rb
View File

@ -91,8 +91,8 @@ module Homebrew
def upgrade_formulae(formulae_to_install)
return if formulae_to_install.empty?
# Sort keg_only before non-keg_only formulae to avoid any needless conflicts
# with outdated, non-keg_only versions of formulae being upgraded.
# Sort keg-only before non-keg-only formulae to avoid any needless conflicts
# with outdated, non-keg-only versions of formulae being upgraded.
formulae_to_install.sort! do |a, b|
if !a.keg_only? && b.keg_only?
1

6
Library/Homebrew/config.rb
View File

@ -2,13 +2,13 @@ unless ENV["HOMEBREW_BREW_FILE"]
raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!"
end
# Path to `bin/brew` main executable in HOMEBREW_PREFIX
# Path to `bin/brew` main executable in `HOMEBREW_PREFIX`
HOMEBREW_BREW_FILE = Pathname.new(ENV["HOMEBREW_BREW_FILE"])
# Where we link under
HOMEBREW_PREFIX = Pathname.new(ENV["HOMEBREW_PREFIX"])
# Where .git is found
# Where `.git` is found
HOMEBREW_REPOSITORY = Pathname.new(ENV["HOMEBREW_REPOSITORY"])
# Where we store most of Homebrew, taps, and various metadata
@ -38,7 +38,7 @@ HOMEBREW_CACHE_FORMULA = HOMEBREW_CACHE/"Formula"
# Where build, postinstall, and test logs of formulae are written to
HOMEBREW_LOGS = Pathname.new(ENV["HOMEBREW_LOGS"] || "~/Library/Logs/Homebrew/").expand_path
# Must use /tmp instead of $TMPDIR because long paths break Unix domain sockets
# Must use `/tmp` instead of `TMPDIR` because long paths break Unix domain sockets
HOMEBREW_TEMP = begin
# /tmp fallback is here for people auto-updating from a version where
# HOMEBREW_TEMP isn't set.

6
Library/Homebrew/cxxstdlib.rb
View File

@ -40,10 +40,10 @@ class CxxStdlib
@compiler = compiler.to_sym
end
# If either package doesn't use C++, all is well
# libstdc++ and libc++ aren't ever intercompatible
# If either package doesn't use C++, all is well.
# libstdc++ and libc++ aren't ever intercompatible.
# libstdc++ is compatible across Apple compilers, but
# not between Apple and GNU compilers, or between GNU compiler versions
# not between Apple and GNU compilers, or between GNU compiler versions.
def compatible_with?(other)
return true if type.nil? || other.type.nil?

2
Library/Homebrew/dependable.rb
View File

@ -1,7 +1,7 @@
require "options"
module Dependable
# :run and :linked are no longer used but keep them here to avoid them being
# `:run` and `:linked` are no longer used but keep them here to avoid them being
# misused in future.
RESERVED_TAGS = [:build, :optional, :recommended, :run, :test, :linked].freeze

2
Library/Homebrew/dependency.rb
View File

@ -71,7 +71,7 @@ class Dependency
class << self
# Expand the dependencies of dependent recursively, optionally yielding
# [dependent, dep] pairs to allow callers to apply arbitrary filters to
# `[dependent, dep]` pairs to allow callers to apply arbitrary filters to
# the list.
# The default filter, which is applied when a block is not given, omits
# optionals and recommendeds based on what the dependent has asked for.

18
Library/Homebrew/description_cache_store.rb
View File

@ -4,24 +4,24 @@ require "searchable"
#
# `DescriptionCacheStore` provides methods to fetch and mutate linkage-specific data used
# by the `brew linkage` command
# by the `brew linkage` command.
#
class DescriptionCacheStore < CacheStore
include Searchable
# Inserts a formula description into the cache if it does not exist or
# updates the formula description if it does exist
# updates the formula description if it does exist.
#
# @param [String] formula_name: the name of the formula to set
# @param [String] description: the description from the formula to set
# @param formula_name [String] the name of the formula to set
# @param description [String] the description from the formula to set
# @return [nil]
def update!(formula_name, description)
database.set(formula_name, description)
end
# Delete the formula description from the `DescriptionCacheStore`
# Delete the formula description from the `DescriptionCacheStore`.
#
# @param [String] formula_name: the name of the formula to delete
# @param formula_name [String] the name of the formula to delete
# @return [nil]
def delete!(formula_name)
database.delete(formula_name)
@ -37,7 +37,7 @@ class DescriptionCacheStore < CacheStore
# Use an update report to update the `DescriptionCacheStore`.
#
# @param [Report] report: an update report generated by cmd/update.rb
# @param report [Report] an update report generated by cmd/update.rb
# @return [nil]
def update_from_report!(report)
return populate_if_empty! if database.empty?
@ -55,7 +55,7 @@ class DescriptionCacheStore < CacheStore
# Use an array of formulae names to update the `DescriptionCacheStore`.
#
# @param [Array] formula_names: the formulae to update.
# @param formula_names [Array] the formulae to update
# @return [nil]
def update_from_formula_names!(formula_names)
return populate_if_empty! if database.empty?
@ -71,7 +71,7 @@ class DescriptionCacheStore < CacheStore
# Use an array of formulae names to delete them from the `DescriptionCacheStore`.
#
# @param [Array] formula_names: the formulae to delete.
# @param formula_names [Array] the formulae to delete
# @return [nil]
def delete_from_formula_names!(formula_names)
return if database.empty?

16
Library/Homebrew/dev-cmd/pull.rb
View File

@ -453,9 +453,9 @@ module Homebrew
{ files: files, formulae: formulae, others: others }
end
# Get current formula versions without loading formula definition in this process
# Returns info as a hash (type => version), for pull.rb's internal use
# Uses special key :nonexistent => true for nonexistent formulae
# Get current formula versions without loading formula definition in this process.
# Returns info as a hash (type => version), for pull.rb's internal use.
# Uses special key `:nonexistent => true` for nonexistent formulae.
def current_versions_from_info_external(formula_name)
info = FormulaInfoFromJson.lookup(formula_name)
versions = {}
@ -540,7 +540,7 @@ module Homebrew
false
end
# Formula info drawn from an external "brew info --json" call
# Formula info drawn from an external `brew info --json` call
class FormulaInfoFromJson
# The whole info structure parsed from the JSON
attr_accessor :info
@ -549,8 +549,8 @@ module Homebrew
@info = info
end
# Looks up formula on disk and reads its info
# Returns nil if formula is absent or if there was an error reading it
# Looks up formula on disk and reads its info.
# Returns nil if formula is absent or if there was an error reading it.
def self.lookup(name)
json = Utils.popen_read(HOMEBREW_BREW_FILE, "info", "--json=v1", name)
@ -600,11 +600,11 @@ module Homebrew
end
end
# Bottle info as used internally by pull, with alternate platform support
# Bottle info as used internally by pull, with alternate platform support.
class BottleInfo
# URL of bottle as string
attr_accessor :url
# Expected SHA256 as string
# Expected SHA-256 as string
attr_accessor :sha256
def initialize(url, sha256)

4
Library/Homebrew/diagnostic.rb
View File

@ -59,8 +59,8 @@ module Homebrew
class Checks
############# HELPERS
# Finds files in HOMEBREW_PREFIX *and* /usr/local.
# Specify paths relative to a prefix eg. "include/foo.h".
# Finds files in `HOMEBREW_PREFIX` *and* /usr/local.
# Specify paths relative to a prefix e.g. "include/foo.h".
# Sets @found for your convenience.
def find_relative_paths(*relative_paths)
@found = [HOMEBREW_PREFIX, "/usr/local"].uniq.reduce([]) do |found, prefix|

17
Library/Homebrew/download_strategy.rb
View File

@ -72,8 +72,8 @@ class AbstractDownloadStrategy
end
private :chdir
# @!attribute [r]
# return most recent modified time for all files in the current working directory after stage.
# @!attribute [r] source_modified_time
# Returns the most recent modified time for all files in the current working directory after stage.
def source_modified_time
Pathname.pwd.to_enum(:find).select(&:file?).map(&:mtime).max
end
@ -405,7 +405,7 @@ class CurlDownloadStrategy < AbstractFileDownloadStrategy
end
end
# Detect and download from Apache Mirror
# Detect and download from Apache Mirror.
class CurlApacheMirrorDownloadStrategy < CurlDownloadStrategy
def mirrors
return @combined_mirrors if defined?(@combined_mirrors)
@ -440,7 +440,7 @@ class CurlApacheMirrorDownloadStrategy < CurlDownloadStrategy
end
# Download via an HTTP POST.
# Query parameters on the URL are converted into POST parameters
# Query parameters on the URL are converted into POST parameters.
class CurlPostDownloadStrategy < CurlDownloadStrategy
private
@ -477,7 +477,7 @@ end
# S3DownloadStrategy downloads tarballs from AWS S3.
# To use it, add `:using => :s3` to the URL section of your
# formula. This download strategy uses AWS access tokens (in the
# environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
# environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`)
# to sign the request. This strategy is good in a corporate setting,
# because it lets you use a private S3 bucket as a repo for internal
# distribution. (It will work for public buckets as well.)
@ -510,7 +510,7 @@ end
# Private Repository. To use it, add
# `:using => :github_private_repo` to the URL section of
# your formula. This download strategy uses GitHub access tokens (in the
# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request. This
# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request. This
# strategy is suitable for corporate use just like S3DownloadStrategy, because
# it lets you use a private GitHub repository for internal distribution. It
# works with public one, but in that case simply use CurlDownloadStrategy.
@ -568,7 +568,7 @@ end
# GitHubPrivateRepositoryReleaseDownloadStrategy downloads tarballs from GitHub
# Release assets. To use it, add `:using => :github_private_release` to the URL section
# of your formula. This download strategy uses GitHub access tokens (in the
# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request.
# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request.
class GitHubPrivateRepositoryReleaseDownloadStrategy < GitHubPrivateRepositoryDownloadStrategy
def parse_url_pattern
url_pattern = %r{https://github.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\S+)}
@ -615,8 +615,7 @@ end
# authentication. If a public/private keypair is configured, it will not
# prompt for a password.
#
# Usage:
#
# @example
# class Abc < Formula
# url "scp://example.com/src/abc.1.0.tar.gz"
# ...

28
Library/Homebrew/exceptions.rb
View File

@ -436,9 +436,9 @@ class BuildError < RuntimeError
end
end
# raised by FormulaInstaller.check_dependencies_bottled and
# FormulaInstaller.install if the formula or its dependencies are not bottled
# and are being installed on a system without necessary build tools
# Raised by {FormulaInstaller#check_dependencies_bottled} and
# {FormulaInstaller#install} if the formula or its dependencies are not bottled
# and are being installed on a system without necessary build tools.
class BuildToolsError < RuntimeError
def initialize(formulae)
super <<~EOS
@ -450,9 +450,9 @@ class BuildToolsError < RuntimeError
end
end
# raised by Homebrew.install, Homebrew.reinstall, and Homebrew.upgrade
# Raised by Homebrew.install, Homebrew.reinstall, and Homebrew.upgrade
# if the user passes any flags/environment that would case a bottle-only
# installation on a system without build tools to fail
# installation on a system without build tools to fail.
class BuildFlagsError < RuntimeError
def initialize(flags, bottled: true)
if flags.length > 1
@ -478,8 +478,8 @@ class BuildFlagsError < RuntimeError
end
end
# raised by CompilerSelector if the formula fails with all of
# the compilers available on the user's system
# Raised by {CompilerSelector} if the formula fails with all of
# the compilers available on the user's system.
class CompilerSelectionError < RuntimeError
def initialize(formula)
super <<~EOS
@ -489,7 +489,7 @@ class CompilerSelectionError < RuntimeError
end
end
# Raised in Resource.fetch
# Raised in {Resource#fetch}.
class DownloadError < RuntimeError
def initialize(resource, cause)
super <<~EOS
@ -500,7 +500,7 @@ class DownloadError < RuntimeError
end
end
# raised in CurlDownloadStrategy.fetch
# Raised in {CurlDownloadStrategy#fetch}.
class CurlDownloadStrategyError < RuntimeError
def initialize(url)
case url
@ -512,14 +512,14 @@ class CurlDownloadStrategyError < RuntimeError
end
end
# raised in ScpDownloadStrategy.fetch
# Raised in {ScpDownloadStrategy#fetch}.
class ScpDownloadStrategyError < RuntimeError
def initialize(cause)
super "Download failed: #{cause}"
end
end
# raised by safe_system in utils.rb
# Raised by {#safe_system} in `utils.rb`.
class ErrorDuringExecution < RuntimeError
attr_reader :cmd
attr_reader :status
@ -556,10 +556,10 @@ class ErrorDuringExecution < RuntimeError
end
end
# raised by Pathname#verify_checksum when "expected" is nil or empty
# Raised by {Pathname#verify_checksum} when "expected" is nil or empty.
class ChecksumMissingError < ArgumentError; end
# raised by Pathname#verify_checksum when verification fails
# Raised by {Pathname#verify_checksum} when verification fails.
class ChecksumMismatchError < RuntimeError
attr_reader :expected, :hash_type
@ -589,7 +589,7 @@ class DuplicateResourceError < ArgumentError
end
end
# raised when a single patch file is not found and apply hasn't been specified
# Raised when a single patch file is not found and apply hasn't been specified.
class MissingApplyError < RuntimeError; end
class BottleFormulaUnavailableError < RuntimeError

2
Library/Homebrew/extend/ARGV.rb
View File

@ -243,7 +243,7 @@ module HomebrewArgvExtension
include? "--fetch-HEAD"
end
# eg. `foo -ns -i --bar` has three switches, n, s and i
# e.g. `foo -ns -i --bar` has three switches: `n`, `s` and `i`
def switch?(char)
return false if char.length > 1

8
Library/Homebrew/extend/ENV/shared.rb
View File

@ -88,11 +88,11 @@ module SharedEnvExtension
# Prepends a directory to `PATH`.
# Is the formula struggling to find the pkgconfig file? Point it to it.
# This is done automatically for `keg_only` formulae.
# This is done automatically for keg-only formulae.
# <pre>ENV.prepend_path "PKG_CONFIG_PATH", "#{Formula["glib"].opt_lib}/pkgconfig"</pre>
# Prepending a system path such as /usr/bin is a no-op so that requirements
# don't accidentally override superenv shims or formulae's `bin` directories
# (e.g. <pre>ENV.prepend_path "PATH", which("emacs").dirname</pre>)
# don't accidentally override superenv shims or formulae's `bin` directories, e.g.
# <pre>ENV.prepend_path "PATH", which("emacs").dirname</pre>
def prepend_path(key, path)
return if %w[/usr/bin /bin /usr/sbin /sbin].include? path.to_s
@ -194,7 +194,7 @@ module SharedEnvExtension
end
# Snow Leopard defines an NCURSES value the opposite of most distros.
# See: https://bugs.python.org/issue6848
# @see https://bugs.python.org/issue6848
# Currently only used by aalib in core.
def ncurses_define
append "CPPFLAGS", "-DNCURSES_OPAQUE=0"

2
Library/Homebrew/extend/os/mac/hardware/cpu.rb
View File

@ -94,7 +94,7 @@ module Hardware
# Determines whether the current CPU and macOS combination
# can run an executable of the specified architecture.
# `arch` is a symbol in the same format returned by
# Hardware::CPU.family
# {Hardware::CPU.family}.
def can_run?(arch)
if Hardware::CPU.intel?
intel_can_run? arch

8
Library/Homebrew/extend/pathname.rb
View File

@ -145,7 +145,7 @@ class Pathname
# @private
alias old_write write
# we assume this pathname object is a file obviously
# We assume this pathname object is a file, obviously
def write(content, *open_args)
raise "Will not overwrite #{self}" if exist?
@ -196,7 +196,7 @@ class Pathname
# @private
alias extname_old extname
# extended to support common double extensions
# Extended to support common double extensions
def extname(path = to_s)
basename = File.basename(path)
@ -212,7 +212,7 @@ class Pathname
File.extname(basename)
end
# for filetypes we support, basename without extension
# For filetypes we support, basename without extension
def stem
File.basename((path = to_s), extname(path))
end
@ -351,7 +351,7 @@ class Pathname
end
end
# Writes an exec script that invokes a java jar
# Writes an exec script that invokes a Java jar
def write_jar_script(target_jar, script_name, java_opts = "", java_version: nil)
mkpath
java_home = if java_version

2
Library/Homebrew/extend/string.rb
View File

@ -18,7 +18,7 @@ class NilClass
def chuzzle; end
end
# used by the inreplace function (in utils.rb)
# Used by the inreplace function (in `utils.rb`).
module StringInreplaceExtension
attr_accessor :errors

110
Library/Homebrew/formula.rb
View File

@ -29,8 +29,8 @@ require "mktemp"
# Make sure you check with `brew search` that the name is free!
# @abstract
# @see SharedEnvExtension
# @see FileUtils
# @see Pathname
# @see https://www.rubydoc.info/stdlib/fileutils FileUtils
# @see https://docs.brew.sh/Formula-Cookbook Formula Cookbook
# @see https://github.com/styleguide/ruby Ruby Style Guide
#
@ -57,8 +57,9 @@ class Formula
# 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.
# `HOMEBREW_PREFIX` is available in the embedded patch.
#
# `inreplace` supports regular expressions:
# <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
# @see Utils::Inreplace.inreplace
@ -132,7 +133,7 @@ class Formula
# Used for creating new Homebrew versions of software without new upstream
# versions.
# @see .revision
# @see .revision=
attr_reader :revision
# Used to change version schemes for packages
@ -143,7 +144,7 @@ class Formula
attr_reader :buildpath
# The current working directory during tests.
# Will only be non-`nil` inside {#test}.
# Will only be non-`nil` inside {.test}.
attr_reader :testpath
# When installing a bottle (binary package) from a local path this will be
@ -157,13 +158,13 @@ class Formula
attr_reader :active_log_type
# The {BuildOptions} for this {Formula}. Lists the arguments passed and any
# {#options} in the {Formula}. Note that these may differ at different times
# {.option}s 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.
# @return [BuildOptions]
attr_accessor :build
# A {Boolean} indicating whether this formula should be considered outdated
# 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.
# @return [Boolean]
@ -265,7 +266,7 @@ class Formula
public
# 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,
# Can differ from {#alias_path}, which is the alias used to find the formula,
# and is specified to this instance.
def installed_alias_path
path = build.source["path"] if build.is_a?(Tab)
@ -344,12 +345,12 @@ class Formula
# The description of the software.
# @method desc
# @see .desc
# @see .desc=
delegate desc: :"self.class"
# The homepage for the software.
# @method homepage
# @see .homepage
# @see .homepage=
delegate homepage: :"self.class"
# The version for the currently active {SoftwareSpec}.
@ -413,7 +414,7 @@ class Formula
end
end
# All of aliases for the formula
# All aliases for the formula
def aliases
@aliases ||= if tap
tap.alias_reverse_table[full_name].to_a.map do |a|
@ -555,12 +556,12 @@ class Formula
linked_keg.symlink?
end
# Is the formula linked to opt?
# Is the formula linked to `opt`?
def optlinked?
opt_prefix.symlink?
end
# Is formula's linked keg points to the prefix.
# If a formula's linked keg points to the prefix.
def prefix_linked?(v = pkg_version)
return false unless linked?
@ -597,7 +598,7 @@ class Formula
# 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?
# Need to install into the {.bin} but the makefile doesn't `mkdir -p prefix/bin`?
# <pre>bin.mkpath</pre>
#
# No `make install` available?
@ -643,7 +644,7 @@ class Formula
# 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
# symlinked into `HOMEBREW_PREFIX` from one of the other directories and
# instead manually create symlinks or wrapper scripts into e.g. {#bin}.
def libexec
prefix/"libexec"
@ -652,7 +653,7 @@ class Formula
# 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
# Often one of the more specific `man` functions should be used instead,
# e.g. {#man1}
def man
share/"man"
@ -786,14 +787,14 @@ class Formula
# 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 is persisted
# This directory is not inside the `HOMEBREW_CELLAR` so it persists
# across upgrades.
def etc
(HOMEBREW_PREFIX/"etc").extend(InstallRenamed)
end
# The directory where the formula's variable files should be installed.
# This directory is not inside the `HOMEBREW_CELLAR` so it is persisted
# This directory is not inside the `HOMEBREW_CELLAR` so it persists
# across upgrades.
def var
HOMEBREW_PREFIX/"var"
@ -872,8 +873,7 @@ class Formula
end
# This method can be overridden to provide a plist.
# For more examples read Apple's handy manpage:
# https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html
# @see https://www.unix.com/man-page/all/5/plist/ Apple's plist(5) man page
# <pre>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">
@ -894,6 +894,7 @@ class Formula
# <string>/dev/null</string>
# <key>StandardOutPath</key>
# <string>/dev/null</string>
# </dict>
# </plist>
# EOS
# end</pre>
@ -925,7 +926,7 @@ class Formula
# but no version number. Only the active version will be linked here if
# multiple versions are installed.
#
# This is the prefered way to refer a formula in plists or from another
# 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.
# <pre>args << "--with-readline=#{Formula["readline"].opt_prefix}" if build.with? "readline"</pre>
def opt_prefix
@ -1029,7 +1030,7 @@ class Formula
#
# <pre>def caveats
# s = <<~EOS
# Print some important notice to the user when `brew info <formula>` is
# 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
@ -1040,8 +1041,8 @@ class Formula
nil
end
# rarely, you don't want your library symlinked into the main prefix
# see gettext.rb for an example
# Rarely, you don't want your library symlinked into the main prefix.
# See `gettext.rb` for an example.
def keg_only?
return false unless keg_only_reason
@ -1319,7 +1320,7 @@ class Formula
end
# Standard parameters for CMake builds.
# Setting CMAKE_FIND_FRAMEWORK to "LAST" tells CMake to search for our
# 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
@ -1951,7 +1952,7 @@ class Formula
end
# Create a temporary directory then yield. When the block returns,
# recursively delete the temporary directory. Passing opts[:retain]
# 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.
def mktemp(prefix = name, opts = {})
@ -2159,10 +2160,10 @@ class Formula
attr_rw :revision
# @!attribute [w] version_scheme
# Used for creating new Homebrew versions schemes. For example, if we want
# 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
# 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.
@ -2177,14 +2178,15 @@ class Formula
end
# @!attribute [w] url
# The URL used to download the source for the {#stable} version of the formula.
# 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`, `:cvs`,
# `:curl` (normal file download. Will also extract.)
# `:nounzip` (without extracting)
# `:post` (download via an HTTP POST)
# `:s3` (download from S3 using signed request)
#
# - `: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)
#
# <pre>url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"</pre>
# <pre>url "https://some.dont.provide.archives.example.com",
@ -2196,7 +2198,7 @@ class Formula
end
# @!attribute [w] version
# The version string for the {#stable} version of the formula.
# 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.
#
@ -2206,7 +2208,7 @@ class Formula
end
# @!attribute [w] mirror
# Additional URLs for the {#stable} version of the formula.
# 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
@ -2220,8 +2222,8 @@ class Formula
# @!attribute [w] sha256
# @scope class
# 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
# 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.
#
@ -2237,7 +2239,7 @@ class Formula
# 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.
# https://docs.brew.sh/Bottles
# @see https://docs.brew.sh/Bottles
# You can ignore this block entirely if submitting to Homebrew/homebrew-core.
# It'll be handled for you by the Brew Test Bot.
#
@ -2251,11 +2253,11 @@ class Formula
# sha256 "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2" => :mavericks
# end</pre>
#
# Only formulae where the upstream URL breaks or moves frequently, require compile
# 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 & can be installed without any compile
# Formulae which should not be bottled and can be installed without any compile
# required should be tagged with:
# <pre>bottle :unneeded</pre>
#
@ -2272,7 +2274,7 @@ class Formula
end
# @!attribute [w] stable
# Allows adding {.depends_on} and {#patch}es just to the {.stable} {SoftwareSpec}.
# Allows adding {.depends_on} and {Patch}es 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.
#
@ -2314,7 +2316,7 @@ class Formula
# 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 {#patch}es just to the {.head} {SoftwareSpec}.
# If a block is provided you can also add {.depends_on} and {Patch}es 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.
# <pre>head "https://we.prefer.https.over.git.example.com/.git"</pre>
@ -2333,8 +2335,8 @@ class Formula
end
# 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.
# install method. Resources can also be defined inside a {.stable}, {.devel} or
# {.head} block. This mechanism replaces ad-hoc "subformula" classes.
# <pre>resource "additional_files" do
# url "https://example.com/additional-stuff.tar.gz"
# sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
@ -2378,11 +2380,10 @@ class Formula
# depends_on :ld64 # Sometimes ld fails on `MacOS.version < :leopard`. Then use this.
# 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.
# depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.</pre>
# <pre># It is possible to only depend on something if
# # `build.with?` or `build.without? "another_formula"`:
# depends_on "postgresql" if build.without? "sqlite"
#
# depends_on "postgresql" if build.without? "sqlite"</pre>
# <pre># Python 3.x if the `--with-python` is given to `brew install example`
# depends_on "python3" => :optional</pre>
# <pre># Python 2.7:
@ -2397,10 +2398,11 @@ class Formula
# 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
# 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).
# <pre>option "with-spam", "The description goes here without a dot at the end"</pre>
@ -2491,10 +2493,10 @@ class Formula
@skip_clean_paths ||= Set.new
end
# Software that will not be sym-linked into the `brew --prefix` will only
# 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
# 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.
# <pre>keg_only :provided_by_macos</pre>
@ -2503,7 +2505,7 @@ class Formula
@keg_only_reason = KegOnlyReason.new(reason, explanation)
end
# Pass :skip to this method to disable post-install stdlib checking
# Pass `:skip` to this method to disable post-install stdlib checking
def cxxstdlib_check(check_type)
define_method(:skip_cxxstdlib_check?) { true } if check_type == :skip
end
@ -2538,13 +2540,13 @@ class Formula
specs.each { |spec| spec.needs(*standards) }
end
# Test (is required for new formula and makes us happy).
# A test is required for new formulae and makes us happy.
# @return [Boolean]
#
# 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.
# and building the software was OK.
# <pre>system bin/"foobar", "--version"</pre>
#
# <pre>(testpath/"test.file").write <<~EOS

4
Library/Homebrew/formula_support.rb
View File

@ -1,4 +1,4 @@
# Used to track formulae that cannot be installed at the same time
# Used to track formulae that cannot be installed at the same time.
FormulaConflict = Struct.new(:name, :reason)
# Used to annotate formulae that duplicate macOS provided software
@ -39,7 +39,7 @@ class KegOnlyReason
end
end
# Used to annotate formulae that don't require compiling or cannot build bottle.
# Used to annotate formulae that don't require compiling or cannot build a bottle.
class BottleDisableReason
SUPPORTED_TYPES = [:unneeded, :disable].freeze

11
Library/Homebrew/formulary.rb
View File

@ -1,7 +1,7 @@
require "digest/md5"
require "extend/cachable"
# The Formulary is responsible for creating instances of Formula.
# The Formulary is responsible for creating instances of {Formula}.
# It is not meant to be used directly from formulae.
module Formulary
@ -175,7 +175,7 @@ module Formulary
end
end
# Loads formulae from disk using a path
# Loads formulae from disk using a path.
class FromPathLoader < FormulaLoader
def initialize(path)
path = Pathname.new(path).expand_path
@ -183,7 +183,7 @@ module Formulary
end
end
# Loads formulae from URLs
# Loads formulae from URLs.
class FromUrlLoader < FormulaLoader
attr_reader :url
@ -280,7 +280,7 @@ module Formulary
end
end
# Load formulae directly from their contents
# Load formulae directly from their contents.
class FormulaContentsLoader < FormulaLoader
# The formula's contents
attr_reader :contents
@ -298,7 +298,8 @@ module Formulary
end
# Return a Formula instance for the given reference.
# `ref` is string containing:
# `ref` is a string containing:
#
# * a formula name
# * a formula pathname
# * a formula URL

2
Library/Homebrew/global.rb
View File

@ -51,7 +51,7 @@ HOMEBREW_USER_AGENT_FAKE_SAFARI =
"(KHTML, like Gecko) Version/10.0.3 Safari/602.4.8".freeze
# Bintray fallback is here for people auto-updating from a version where
# HOMEBREW_BOTTLE_DEFAULT_DOMAIN isn't set.
# `HOMEBREW_BOTTLE_DEFAULT_DOMAIN` isn't set.
HOMEBREW_BOTTLE_DEFAULT_DOMAIN = if ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
elsif OS.mac?

3
Library/Homebrew/keg.rb
View File

@ -111,9 +111,8 @@ class Keg
].freeze
# Given an array of kegs, this method will try to find some other kegs
# that depend on them.
# that depend on them. If it does, it returns:
#
# If it does, it returns:
# - some kegs in the passed array that have installed dependents
# - some installed dependents of those kegs.
#

4
Library/Homebrew/language/python.rb
View File

@ -94,7 +94,7 @@ module Language
end
# Instantiates, creates, and yields a {Virtualenv} object for use from
# Formula#install, which provides helper methods for instantiating and
# {Formula#install}, which provides helper methods for instantiating and
# installing packages into a Python virtualenv.
# @param venv_root [Pathname, String] the path to the root of the virtualenv
# (often `libexec/"venv"`)
@ -140,7 +140,7 @@ module Language
# Helper method for the common case of installing a Python application.
# Creates a virtualenv in `libexec`, installs all `resource`s defined
# on the formula, and then installs the formula. An options hash may be
# passed (e.g., :using => "python") to override the default, guessed
# passed (e.g., `:using => "python"`) to override the default, guessed
# formula preference for python or python2, or to resolve an ambiguous
# case where it's not clear whether python or python2 should be the
# default guess.

12
Library/Homebrew/linkage_cache_store.rb
View File

@ -3,11 +3,11 @@ require "cache_store"
#
# `LinkageCacheStore` provides methods to fetch and mutate linkage-specific data used
# by the `brew linkage` command
# by the `brew linkage` command.
#
class LinkageCacheStore < CacheStore
# @param [String] keg_path
# @param [CacheStoreDatabase] database
# @param keg_path [String]
# @param database [CacheStoreDatabase]
# @return [nil]
def initialize(keg_path, database)
@keg_path = keg_path
@ -24,7 +24,7 @@ class LinkageCacheStore < CacheStore
# Inserts dylib-related information into the cache if it does not exist or
# updates data into the linkage cache if it does exist
#
# @param [Hash] hash_values: hash containing KVPs of { :type => Hash }
# @param hash_values [Hash] hash containing KVPs of { :type => Hash }
# @return [nil]
def update!(hash_values)
hash_values.each_key do |type|
@ -38,7 +38,7 @@ class LinkageCacheStore < CacheStore
database.set @keg_path, hash_values
end
# @param [Symbol] the type to fetch from the `LinkageCacheStore`
# @param type [Symbol] the type to fetch from the `LinkageCacheStore`
# @raise [TypeError] error if the type is not in `HASH_LINKAGE_TYPES`
# @return [Hash]
def fetch(type)
@ -64,7 +64,7 @@ class LinkageCacheStore < CacheStore
HASH_LINKAGE_TYPES = [:keg_files_dylibs].freeze
# @param [Symbol] type
# @param type [Symbol]
# @return [Hash]
def fetch_hash_values(type)
keg_cache = database.get(@keg_path)

2
Library/Homebrew/messages.rb
View File

@ -1,5 +1,5 @@
# A Messages object collects messages that may need to be displayed together
# at the end of a multi-step `brew` command run
# at the end of a multi-step `brew` command run.
class Messages
attr_reader :caveats, :formula_count, :install_times

4
Library/Homebrew/migrator.rb
View File

@ -137,7 +137,7 @@ class Migrator
@old_pin_link_record = old_pin_record.readlink if @pinned
end
# Fix INSTALL_RECEIPTS for tap-migrated formula.
# Fix INSTALL_RECEIPTs for tap-migrated formula.
def fix_tabs
old_tabs.each do |tab|
tab.tap = formula.tap
@ -160,7 +160,7 @@ class Migrator
if formula_tap_user == old_tap_user
true
# Homebrew didn't use to update tabs while performing tap-migrations,
# so there can be INSTALL_RECEIPT's containing wrong information about tap,
# so there can be INSTALL_RECEIPTs containing wrong information about tap,
# so we check if there is an entry about oldname migrated to tap and if
# newname's tap is the same as tap to which oldname migrated, then we
# can perform migrations and the taps for oldname and newname are the same.

2
Library/Homebrew/os/linux/elf.rb
View File

@ -1,5 +1,5 @@
# @see https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
module ELFShim
# See: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
MAGIC_NUMBER_OFFSET = 0
MAGIC_NUMBER_ASCII = "\x7fELF".freeze

32
Library/Homebrew/os/mac.rb
View File

@ -72,20 +72,23 @@ module OS
@active_developer_dir ||= Utils.popen_read("/usr/bin/xcode-select", "-print-path").strip
end
# If a specific SDK is requested
# a) The requested SDK is returned, if it's installed.
# b) If the requested SDK is not installed, the newest SDK (if any SDKs
# If a specific SDK is requested:
#
# 1. The requested SDK is returned, if it's installed.
# 2. If the requested SDK is not installed, the newest SDK (if any SDKs
# are available) is returned.
# c) If no SDKs are available, nil is returned.
# If no specific SDK is requested
# a) For Xcode >= 7, the latest SDK is returned even if the latest SDK is
# 3. If no SDKs are available, nil is returned.
#
# If no specific SDK is requested:
#
# 1. For Xcode >= 7, the latest SDK is returned even if the latest SDK is
# named after a newer OS version than the running OS. The
# MACOSX_DEPLOYMENT_TARGET must be set to the OS for which you're
# `MACOSX_DEPLOYMENT_TARGET` must be set to the OS for which you're
# actually building (usually the running OS version).
# https://github.com/Homebrew/legacy-homebrew/pull/50355
# https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
# - https://github.com/Homebrew/legacy-homebrew/pull/50355
# - https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
# Section "About SDKs and Simulator"
# b) For Xcode < 7, proceed as if the SDK for the running OS version had
# 2. For Xcode < 7, proceed as if the SDK for the running OS version had
# specifically been requested according to the rules above.
def sdk(v = nil)
@ -98,7 +101,7 @@ module OS
@locator.sdk_if_applicable(v)
end
# Returns the path to an SDK or nil, following the rules set by #sdk.
# Returns the path to an SDK or nil, following the rules set by {.sdk}.
def sdk_path(v = nil)
s = sdk(v)
s&.path
@ -122,9 +125,10 @@ module OS
end
# See these issues for some history:
# https://github.com/Homebrew/legacy-homebrew/issues/13
# https://github.com/Homebrew/legacy-homebrew/issues/41
# https://github.com/Homebrew/legacy-homebrew/issues/48
#
# - https://github.com/Homebrew/legacy-homebrew/issues/13
# - https://github.com/Homebrew/legacy-homebrew/issues/41
# - https://github.com/Homebrew/legacy-homebrew/issues/48
def macports_or_fink
paths = []

14
Library/Homebrew/os/mac/xquartz.rb
View File

@ -60,8 +60,8 @@ module OS
"2.7.11"
end
# https://xquartz.macosforge.org/trac/wiki
# https://xquartz.macosforge.org/trac/wiki/Releases
# - https://xquartz.macosforge.org/trac/wiki
# - https://xquartz.macosforge.org/trac/wiki/Releases
def latest_version
case MacOS.version
when "10.5"
@ -114,8 +114,8 @@ module OS
end
# This should really be private, but for compatibility reasons it must
# remain public. New code should use MacOS::X11.bin, MacOS::X11.lib and
# MacOS::X11.include instead, as that accounts for Xcode-only systems.
# remain public. New code should use `MacOS::X11.bin`, `MacOS::X11.lib` and
# `MacOS::X11.include` instead, as that accounts for Xcode-only systems.
def prefix
@prefix ||= if Pathname.new("/opt/X11/lib/libpng.dylib").exist?
Pathname.new("/opt/X11")
@ -139,10 +139,10 @@ module OS
end
# If XQuartz and/or the CLT are installed, headers will be found under
# /opt/X11/include or /usr/X11/include. For Xcode-only systems, they are
# found in the SDK, so we use sdk_path for both the headers and libraries.
# `/opt/X11/include` or `/usr/X11/include`. For Xcode-only systems, they are
# found in the SDK, so we use {.sdk_path} for both the headers and libraries.
# Confusingly, executables (e.g. config scripts) are only found under
# /opt/X11/bin or /usr/X11/bin in all cases.
# `/opt/X11/bin` or `/usr/X11/bin` in all cases.
def effective_prefix
if provided_by_apple? && Xcode.without_clt?
Pathname.new("#{OS::Mac.sdk_path}/usr/X11")

2
Library/Homebrew/patch.rb
View File

@ -162,7 +162,7 @@ class ExternalPatch
end
end
# Legacy patches have no checksum and are not cached
# Legacy patches have no checksum and are not cached.
class LegacyPatch < ExternalPatch
def initialize(strip, url)
super(strip)

8
Library/Homebrew/requirement.rb
View File

@ -49,7 +49,7 @@ class Requirement
s
end
# Overriding #satisfied? is unsupported.
# Overriding {#satisfied?} is unsupported.
# Pass a block or boolean to the satisfy DSL method instead.
def satisfied?
satisfy = self.class.satisfy
@ -61,7 +61,7 @@ class Requirement
true
end
# Overriding #fatal? is unsupported.
# Overriding {#fatal?} is unsupported.
# Pass a boolean to the fatal DSL method instead.
def fatal?
self.class.fatal || false
@ -77,7 +77,7 @@ class Requirement
parent
end
# Overriding #modify_build_environment is unsupported.
# Overriding {#modify_build_environment} is unsupported.
# Pass a block to the env DSL method instead.
def modify_build_environment
satisfied?
@ -196,7 +196,7 @@ class Requirement
class << self
# Expand the requirements of dependent recursively, optionally yielding
# [dependent, req] pairs to allow callers to apply arbitrary filters to
# `[dependent, req]` pairs to allow callers to apply arbitrary filters to
# the list.
# The default filter, which is applied when a block is not given, omits
# optionals and recommendeds based on what the dependent has asked for.

18
Library/Homebrew/resource.rb
View File

@ -61,10 +61,10 @@ class Resource
downloader.clear_cache
end
# Verifies download and unpacks it
# Verifies download and unpacks it.
# The block may call `|resource,staging| staging.retain!` to retain the staging
# directory. Subclasses that override stage should implement the tmp
# dir using Resource#mktemp so that works with all subtypes.
# dir using {Mktemp} so that works with all subtypes.
def stage(target = nil, &block)
unless target || block
raise ArgumentError, "target directory or block is required"
@ -91,8 +91,8 @@ class Resource
end
# If a target is given, unpack there; else unpack to a temp folder.
# If block is given, yield to that block with |stage|, where stage
# is a ResourceStagingContext.
# If block is given, yield to that block with `|stage|`, where stage
# is a {ResourceStageContext}.
# A target or a block must be given, but not both.
def unpack(target = nil)
mktemp(download_name) do |staging|
@ -210,15 +210,15 @@ class Resource
end
end
# The context in which a Resource.stage() occurs. Supports access to both
# the Resource and associated Mktemp in a single block argument. The interface
# is back-compatible with Resource itself as used in that context.
# The context in which a {Resource.stage} occurs. Supports access to both
# the {Resource} and associated {Mktemp} in a single block argument. The interface
# is back-compatible with {Resource} itself as used in that context.
class ResourceStageContext
extend Forwardable
# The Resource that is being staged
# The {Resource} that is being staged
attr_reader :resource
# The Mktemp in which @resource is staged
# The {Mktemp} in which {#resource} is staged
attr_reader :staging
def_delegators :@resource, :version, :url, :mirrors, :specs, :using, :source_modified_time

2
Library/Homebrew/rubocops/class_cop.rb
View File

@ -68,7 +68,7 @@ module RuboCop
end
module FormulaAuditStrict
# - `test do ..end` should be meaningfully defined in the formula
# - `test do ..end` should be meaningfully defined in the formula.
class Test < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
test = find_block(body_node, :test)

10
Library/Homebrew/rubocops/components_order_cop.rb
View File

@ -3,9 +3,9 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop checks for correct order of components in a Formula
# This cop checks for correct order of components in Formulae.
#
# - component_precedence_list has component hierarchy in a nested list
# - `component_precedence_list` has component hierarchy in a nested list
# where each sub array contains components' details which are at same precedence level
class ComponentsOrder < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
@ -96,9 +96,9 @@ module RuboCop
end
end
# Reorder two nodes in the source, using the corrector instance in autocorrect method
# Components of same type are grouped together when rewriting the source
# Linebreaks are introduced if components are of two different methods/blocks/multilines
# Reorder two nodes in the source, using the corrector instance in autocorrect method.
# Components of same type are grouped together when rewriting the source.
# Linebreaks are introduced if components are of two different methods/blocks/multilines.
def reorder_components(corrector, node1, node2)
# order_idx : node1's index in component_precedence_list
# curr_p_idx: node1's index in preceding_comp_arr

4
Library/Homebrew/rubocops/components_redundancy_cop.rb
View File

@ -3,11 +3,11 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop checks if redundant components are present and other component errors
# This cop checks if redundant components are present and other component errors.
#
# - `url|checksum|mirror` should be inside `stable` block
# - `head` and `head do` should not be simultaneously present
# - `bottle :unneeded/:disable` and `bottle do` should not be simultaneously present
# - `bottle :unneeded`/`:disable` and `bottle do` should not be simultaneously present
# - `stable do` should not be present without a `head` or `devel` spec
class ComponentsRedundancy < FormulaCop

2
Library/Homebrew/rubocops/conflicts_cop.rb
View File

@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
# This cop audits versioned Formulae for `conflicts_with`
# This cop audits versioned Formulae for `conflicts_with`.
class Conflicts < FormulaCop
MSG = "Versioned formulae should not use `conflicts_with`. " \
"Use `keg_only :versioned_formula` instead.".freeze

2
Library/Homebrew/rubocops/dependency_order_cop.rb
View File

@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop checks for correct order of `depends_on` in a Formula
# This cop checks for correct order of `depends_on` in Formulae.
#
# precedence order:
# build-time > run-time > normal > recommended > optional

61
Library/Homebrew/rubocops/extend/formula_cop.rb
View File

@ -30,7 +30,7 @@ module RuboCop
end
# Checks for regex match of pattern in the node and
# Sets the appropriate instance variables to report the match
# sets the appropriate instance variables to report the match
def regex_match_group(node, pattern)
string_repr = string_content(node)
match_object = string_repr.match(pattern)
@ -51,9 +51,9 @@ module RuboCop
match_object
end
# Yields to block when there is a match
# Parameters: urls : Array of url/mirror method call nodes
# regex: regex pattern to match urls
# Yields to block when there is a match.
# @param urls [Array] url/mirror method call nodes
# @param regex [Regexp] pattern to match urls
def audit_urls(urls, regex)
urls.each do |url_node|
url_string_node = parameters(url_node).first
@ -104,8 +104,8 @@ module RuboCop
node.each_child_node(:send).select { |method_node| method_name == method_node.method_name }
end
# Returns an array of method call nodes matching method_name in every descendant of node
# Returns every method call if no method_name is passed
# Returns an array of method call nodes matching method_name in every descendant of node.
# Returns every method call if no method_name is passed.
def find_every_method_call_by_name(node, method_name = nil)
return if node.nil?
@ -115,10 +115,11 @@ module RuboCop
end
end
# Returns array of function call nodes matching func_name in every descendant of node
# Ex. function call: foo(*args, **kwargs)
# Does not match method calls: foo.bar(*args, **kwargs)
# Returns every function calls if no func_name is passed
# Returns array of function call nodes matching func_name in every descendant of node.
#
# - matches function call: `foo(*args, **kwargs)`
# - does not match method calls: `foo.bar(*args, **kwargs)`
# - returns every function calls if no func_name is passed
def find_every_func_call_by_name(node, func_name = nil)
return if node.nil?
@ -139,12 +140,13 @@ module RuboCop
end
end
# Matches a method with a receiver,
# EX: to match `Formula.factory(name)`
# Matches a method with a receiver.
#
# - e.g. to match `Formula.factory(name)`
# call `find_instance_method_call(node, "Formula", :factory)`
# EX: to match `build.head?`
# - e.g. to match `build.head?`
# call `find_instance_method_call(node, :build, :head?)`
# yields to a block with matching method node
# - yields to a block with matching method node
def find_instance_method_call(node, instance, method_name)
methods = find_every_method_call_by_name(node, method_name)
methods.each do |method|
@ -160,10 +162,11 @@ module RuboCop
end
end
# Matches receiver part of method,
# EX: to match `ARGV.<whatever>()`
# Matches receiver part of method.
#
# - e.g. to match `ARGV.<whatever>()`
# call `find_instance_call(node, "ARGV")`
# yields to a block with parent node of receiver
# - yields to a block with parent node of receiver
def find_instance_call(node, name)
node.each_descendant(:send) do |method_node|
next if method_node.receiver.nil?
@ -178,8 +181,8 @@ module RuboCop
end
end
# Returns nil if does not depend on dependency_name
# args: node - dependency_name - dependency's name
# Returns nil if does not depend on dependency_name.
# @param dependency_name dependency's name
def depends_on?(dependency_name, *types)
types = [:any] if types.empty?
dependency_nodes = find_every_method_call_by_name(@body, :depends_on)
@ -192,7 +195,7 @@ module RuboCop
@offensive_node = dependency_nodes[idx]
end
# Returns true if given dependency name and dependency type exist in given dependency method call node
# Returns true if given dependency name and dependency type exist in given dependency method call node.
# TODO: Add case where key of hash is an array
def depends_on_name_type?(node, name = nil, type = :required)
if name
@ -223,8 +226,8 @@ module RuboCop
type_match && name_match
end
# Find CONSTANTs in the source
# if block given, yield matching nodes
# Find CONSTANTs in the source.
# If block given, yield matching nodes.
def find_const(node, const_name)
return if node.nil?
@ -284,7 +287,7 @@ module RuboCop
node.each_child_node(:block).select { |block_node| block_name == block_node.method_name }
end
# Returns an array of block nodes of any depth below node in AST
# Returns an array of block nodes of any depth below node in AST.
# If a block is given then yields matching block node to the block!
def find_all_blocks(node, block_name)
return if node.nil?
@ -298,8 +301,8 @@ module RuboCop
end
end
# Returns a method definition node with method_name
# Returns first method def if method_name is nil
# Returns a method definition node with method_name.
# Returns first method def if method_name is nil.
def find_method_def(node, method_name = nil)
return if node.nil?
@ -332,8 +335,8 @@ module RuboCop
false
end
# Check if method_name is called among the direct children nodes in the given node
# Check if the node itself is the method
# Check if method_name is called among the direct children nodes in the given node.
# Check if the node itself is the method.
def method_called?(node, method_name)
if node.send_type? && node.method_name == method_name
offending_node(node)
@ -400,8 +403,8 @@ module RuboCop
end
# Returns true if the given parameters are present in method call
# and sets the method call as the offending node
# params can be string, symbol, array, hash, matching regex
# and sets the method call as the offending node.
# Params can be string, symbol, array, hash, matching regex.
def parameters_passed?(method_node, *params)
method_params = parameters(method_node)
@offensive_node = method_node

4
Library/Homebrew/rubocops/formula_desc_cop.rb
View File

@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
# This cop audits `desc` in Formulae
# This cop audits `desc` in Formulae.
#
# - Checks for existence of `desc`
# - Checks if size of `desc` > 80
@ -37,7 +37,7 @@ module RuboCop
end
module FormulaAuditStrict
# This cop audits `desc` in Formulae
# This cop audits `desc` in Formulae.
#
# - Checks for leading/trailing whitespace in `desc`
# - Checks if `desc` begins with an article

2
Library/Homebrew/rubocops/homepage_cop.rb
View File

@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop audits `homepage` url in Formulae
# This cop audits the `homepage` URL in Formulae.
class Homepage < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
homepage_node = find_node_method_by_name(body_node, :homepage)

2
Library/Homebrew/rubocops/lines_cop.rb
View File

@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop checks for various miscellaneous Homebrew coding styles
# This cop checks for various miscellaneous Homebrew coding styles.
class Lines < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, _body_node)
[:automake, :ant, :autoconf, :emacs, :expat, :libtool, :mysql, :perl,

2
Library/Homebrew/rubocops/options_cop.rb
View File

@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop audits `options` in Formulae
# This cop audits `options` in Formulae.
class Options < FormulaCop
DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so 32-bit options are deprecated.".freeze

2
Library/Homebrew/rubocops/patches_cop.rb
View File

@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
# This cop audits patches in Formulae
# This cop audits patches in Formulae.
class Patches < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body)
external_patches = find_all_blocks(body, :patch)

2
Library/Homebrew/rubocops/urls_cop.rb
View File

@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
# This cop audits urls and mirrors in Formulae
# This cop audits URLs and mirrors in Formulae.
class Urls < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
urls = find_every_func_call_by_name(body_node, :url)

2
Library/Homebrew/software_spec.rb
View File

@ -359,7 +359,7 @@ class BottleSpecification
cellar == :any || cellar == :any_skip_relocation || cellar == HOMEBREW_CELLAR.to_s
end
# Does the Bottle this BottleSpecification belongs to need to be relocated?
# Does the {Bottle} this BottleSpecification belongs to need to be relocated?
def skip_relocation?
cellar == :any_skip_relocation
end

36
Library/Homebrew/tap.rb
View File

@ -2,7 +2,7 @@ require "extend/cachable"
require "readall"
require "description_cache_store"
# a {Tap} is used to extend the formulae provided by Homebrew core.
# A {Tap} is used to extend the formulae provided by Homebrew core.
# Usually, it's synced with a remote git repository. And it's likely
# a GitHub repository with the name of `user/homebrew-repo`. In such
# case, `user/repo` will be used as the {#name} of this {Tap}, where
@ -55,7 +55,7 @@ class Tap
extend Enumerable
# The user name of this {Tap}. Usually, it's the GitHub username of
# this #{Tap}'s remote repository.
# this {Tap}'s remote repository.
attr_reader :user
# The repository name of this {Tap} without leading `homebrew-`.
@ -87,7 +87,7 @@ class Tap
@alias_reverse_table = nil
end
# clear internal cache
# Clear internal cache
def clear_cache
@remote = nil
@repo_var = nil
@ -153,7 +153,7 @@ class Tap
path.git_short_head
end
# time since git last commit for this {Tap}.
# Time since git last commit for this {Tap}.
def git_last_commit
raise TapUnavailableError, name unless installed?
@ -224,7 +224,7 @@ class Tap
false
end
# install this {Tap}.
# Install this {Tap}.
#
# @param [Hash] options
# @option options [String] :clone_target If passed, it will be used as the clone remote.
@ -324,7 +324,7 @@ class Tap
Utils::Link.link_completions(path, command)
end
# uninstall this {Tap}.
# Uninstall this {Tap}.
def uninstall
require "descriptions"
raise TapUnavailableError, name unless installed?
@ -354,7 +354,7 @@ class Tap
remote.casecmp(default_remote).nonzero?
end
# path to the directory of all {Formula} files for this {Tap}.
# Path to the directory of all {Formula} files for this {Tap}.
def formula_dir
@formula_dir ||= potential_formula_dirs.find(&:directory?) || path/"Formula"
end
@ -363,7 +363,7 @@ class Tap
@potential_formula_dirs ||= [path/"Formula", path/"HomebrewFormula", path].freeze
end
# path to the directory of all {Cask} files for this {Tap}.
# Path to the directory of all {Cask} files for this {Tap}.
def cask_dir
@cask_dir ||= path/"Casks"
end
@ -386,7 +386,7 @@ class Tap
contents
end
# an array of all {Formula} files of this {Tap}.
# An array of all {Formula} files of this {Tap}.
def formula_files
@formula_files ||= if formula_dir.directory?
formula_dir.children.select(&method(:ruby_file?))
@ -395,7 +395,7 @@ class Tap
end
end
# an array of all {Cask} files of this {Tap}.
# An array of all {Cask} files of this {Tap}.
def cask_files
@cask_files ||= if cask_dir.directory?
cask_dir.children.select(&method(:ruby_file?))
@ -428,7 +428,7 @@ class Tap
ruby_file?(file) && file.parent == cask_dir
end
# an array of all {Formula} names of this {Tap}.
# An array of all {Formula} names of this {Tap}.
def formula_names
@formula_names ||= formula_files.map { |f| formula_file_to_name(f) }
end
@ -487,7 +487,7 @@ class Tap
(file.executable? || file.extname == ".rb")
end
# an array of all commands files of this {Tap}.
# An array of all commands files of this {Tap}.
def command_files
@command_files ||= if command_dir.directory?
command_dir.children.select(&method(:command_file?))
@ -509,7 +509,7 @@ class Tap
@pinned = pinned_symlink_path.directory?
end
# pin this {Tap}.
# Pin this {Tap}.
def pin
raise TapUnavailableError, name unless installed?
raise TapPinStatusError.new(name, true) if pinned?
@ -518,7 +518,7 @@ class Tap
@pinned = true
end
# unpin this {Tap}.
# Unpin this {Tap}.
def unpin
raise TapUnavailableError, name unless installed?
raise TapPinStatusError.new(name, false) unless pinned?
@ -591,12 +591,12 @@ class Tap
end
end
# an array of all installed {Tap} names.
# An array of all installed {Tap} names.
def self.names
map(&:name).sort
end
# an array of all tap cmd directory {Pathname}s
# An array of all tap cmd directory {Pathname}s
def self.cmd_directories
Pathname.glob TAP_DIRECTORY/"*/*/cmd"
end
@ -633,7 +633,7 @@ class Tap
end
end
# A specialized {Tap} class for the core formulae
# A specialized {Tap} class for the core formulae.
class CoreTap < Tap
def default_remote
"https://github.com/Homebrew/homebrew-core".freeze
@ -722,7 +722,7 @@ class CoreTap < Tap
end
end
# Permanent configuration per {Tap} using `git-config(1)`
# Permanent configuration per {Tap} using `git-config(1)`.
class TapConfig
attr_reader :tap

6
Library/Homebrew/utils.rb
View File

@ -303,7 +303,7 @@ def safe_system(cmd, *args, **options)
raise(ErrorDuringExecution.new([cmd, *args], status: $CHILD_STATUS))
end
# prints no output
# Prints no output
def quiet_system(cmd, *args)
Homebrew._system(cmd, *args) do
# Redirect output streams to `/dev/null` instead of closing as some programs
@ -504,9 +504,9 @@ end
# Calls the given block with the passed environment variables
# added to ENV, then restores ENV afterwards.
# Example:
# with_env(PATH: "/bin") do
# <pre>with_env(PATH: "/bin") do
# system "echo $PATH"
# end
# end</pre>
#
# Note that this method is *not* thread-safe - other threads
# which happen to be scheduled during the block will also

5
Library/Homebrew/utils/inreplace.rb
View File

@ -13,8 +13,9 @@ module Utils
# 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.
# `HOMEBREW_PREFIX` is available in the embedded patch.
#
# `inreplace` supports regular expressions:
# <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
def inreplace(paths, before = nil, after = nil, audit_result = true)
errors = {}

2
Library/Homebrew/utils/shell.rb
View File

@ -35,7 +35,7 @@ module Utils
end
end
# return the shell profile file based on users' preferred shell
# return the shell profile file based on user's preferred shell
def profile
SHELL_PROFILE_MAP.fetch(preferred, "~/.bash_profile")
end