diff options
| -rw-r--r-- | .yardopts | 4 | ||||
| -rw-r--r-- | Library/Homebrew/formula.rb | 105 | ||||
| -rw-r--r-- | Library/Homebrew/global.rb | 8 |
3 files changed, 103 insertions, 14 deletions
@@ -1,6 +1,8 @@ --title "Homebrew" --main Library/Homebrew/README.md ---exclude Library/Homebrew/test/vendor/ +--markup markdown +--no-private +--exclude Library/Homebrew/test/ --exclude Library/Homebrew/vendor/ Library/Homebrew/**/*.rb - diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index c1f3d3ff1..49320a673 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -10,20 +10,76 @@ require 'software_spec' require 'install_renamed' require 'pkg_version' +# 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! +# @abstract class Formula include FileUtils include Utils::Inreplace extend Enumerable - attr_reader :name, :path - attr_reader :stable, :devel, :head, :active_spec - attr_reader :pkg_version, :revision - - # The current working directory during builds and tests. - # Will only be non-nil inside #stage and #test. - attr_reader :buildpath, :testpath - + # The name of this {Formula}. + # e.g. `this-formula` + attr_reader :name + + # The full path to this {Formula}. + # e.g. `/usr/local/Library/Formula/this-formula.rb` + attr_reader :path + + # The stable (and default) {SoftwareSpec} for this {Formula} + # This contains all the attributes like e.g. {#url}, {.sha1} that apply to + # the stable version of this formula. + attr_reader :stable + + # The development {SoftwareSpec} for this {Formula}. + # Installed when using `brew install --devel` + # `nil` if there is no development version. + # @see #stable + attr_reader :devel + + # The HEAD {SoftwareSpec} for this {Formula}. + # Installed when using `brew install --HEAD` + # This is always installed with the version `HEAD` and taken from the latest + # commit in the version control system. + # `nil` if there is no HEAD version. + # @see #stable + attr_reader :head + + # The currently active SoftwareSpec. + # Defaults to stable unless `--devel` or `--HEAD` is passed. + # @private + attr_reader :active_spec + + # The {PkgVersion} for this formula with version and {#revision} information. + attr_reader :pkg_version + + # Used for creating new Homebrew versions of software without new upstream + # versions. + # @see .revision + attr_reader :revision + + # The current working directory during builds. + # Will only be non-`nil` inside {#install}. + attr_reader :buildpath + + # The current working directory during tests. + # Will only be non-`nil` inside {#test}. + attr_reader :testpath + + # When installing a bottle (binary package) from a local path this will be + # set to the full path to the bottle tarball. If not, it will be `nil`. attr_accessor :local_bottle_path + + # 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. attr_accessor :build def initialize(name, path, spec) @@ -233,8 +289,10 @@ class Formula # tell the user about any caveats regarding this package, return a string def caveats; nil end - # Deprecated + # @deprecated DATA = :DATA + + # @deprecated def patches; {} end # rarely, you don't want your library symlinked into the main prefix @@ -267,6 +325,7 @@ class Formula end # yields self with current working directory set to the uncompressed tarball + # @private def brew validate_attributes :name, :version @@ -347,7 +406,7 @@ class Formula ] end - # Deprecated + # @deprecated def python(options={}, &block) opoo 'Formula#python is deprecated and will go away shortly.' block.call if block_given? @@ -648,8 +707,32 @@ class Formula class << self include BuildEnvironmentDSL + # The reason for why this software is not linked (by default) to + # {::HOMEBREW_PREFIX}. attr_reader :keg_only_reason - attr_rw :homepage, :plist_startup, :plist_manual, :revision + + # @!attribute [rw] + # 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 by running `brew home example-formula`. + attr_rw :homepage + + # @!attribute [rw] + # The `:startup` attribute set by {.plist_options}. + attr_rw :plist_startup + + # @!attribute [rw] + # The `:manual` attribute set by {.plist_options}. + attr_rw :plist_manual + + # @!attribute [rw] + # Used for creating new Homebrew versions of software without new upstream + # versions. For example, if we bump the major version of a library this + # {Formula} {.depends_on} then we may need to update the `revision` of this + # {Formula} to install a new version linked against the new library version. + # `0` if unset. + attr_rw :revision def specs @specs ||= [stable, devel, head].freeze diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb index 00f076c86..556276546 100644 --- a/Library/Homebrew/global.rb +++ b/Library/Homebrew/global.rb @@ -48,8 +48,12 @@ if not defined? HOMEBREW_BREW_FILE HOMEBREW_BREW_FILE = ENV['HOMEBREW_BREW_FILE'] || which('brew').to_s end -HOMEBREW_PREFIX = Pathname.new(HOMEBREW_BREW_FILE).dirname.parent # Where we link under -HOMEBREW_REPOSITORY = Pathname.new(HOMEBREW_BREW_FILE).realpath.dirname.parent # Where .git is found +# Where we link under +HOMEBREW_PREFIX = Pathname.new(HOMEBREW_BREW_FILE).dirname.parent + +# Where .git is found +HOMEBREW_REPOSITORY = Pathname.new(HOMEBREW_BREW_FILE).realpath.dirname.parent + HOMEBREW_LIBRARY = HOMEBREW_REPOSITORY/"Library" HOMEBREW_CONTRIB = HOMEBREW_REPOSITORY/"Library/Contributions" |