Permalink
Browse files

More API documentation.

And remove the documented stuff from the `example-formula.rb`.

Closes Homebrew/legacy-homebrew#43241.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
  • Loading branch information...
1 parent 77536e3 commit 2c959a7d5847094d316278188e816a7dadc1a090 @MikeMcQuaid MikeMcQuaid committed Aug 29, 2015
View
@@ -7,7 +7,7 @@
--exclude Library/Homebrew/compat/
Library/Homebrew/**/*.rb
-
+share/doc/homebrew/*.html
Library/Homebrew/*.md
-Library/Homebrew/manpages/*.md
share/doc/homebrew/*.md
*.md
Oops, something went wrong.
@@ -1,4 +1,8 @@
-# Homebrew Public API
-We're (finally) working on a documented public API for Homebrew. It's currently a work in progress; a bunch of public stuff is documented and a bunch of private stuff is undocumented. Sorry about that!
+# Homebrew's Formula API
+This is the (partially) documented public API for Homebrew. It's currently a work in progress. Sorry about that!
-The main class you should look at is {Formula}. Assume everything else is private for now.
+The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private.
+
+You may also find the [Formula Cookbook](Formula-Cookbook.md) and [Ruby Style Guide](https://github.com/styleguide/ruby) helpful in creating formulae.
+
+Good luck!
@@ -1,13 +1,28 @@
class BuildOptions
+ # @private
def initialize(args, options)
@args = args
@options = options
end
+ # True if a {Formula} is being built with a specific option
+ # (which isn't named `with-*` or `without-*`).
+ # @deprecated
def include?(name)
@args.include?("--#{name}")
end
+ # True if a {Formula} is being built with a specific option.
+ # <pre>args << "--i-want-spam" if build.with? "spam"
+ #
+ # args << "--qt-gui" if build.with? "qt" # "--with-qt" ==> build.with? "qt"
+ #
+ # # If a formula presents a user with a choice, but the choice must be fulfilled:
+ # if build.with? "example2"
+ # args << "--with-example2"
+ # else
+ # args << "--with-example1"
+ # end</pre>
def with?(val)
name = val.respond_to?(:option_name) ? val.option_name : val
@@ -20,47 +35,65 @@ def with?(val)
end
end
+ # True if a {Formula} is being built without a specific option.
+ # <pre>args << "--no-spam-plz" if build.without? "spam"
def without?(name)
!with? name
end
+ # True if a {Formula} is being built as a bottle (i.e. binary package).
def bottle?
include? "build-bottle"
end
+ # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}.
+ # <pre>args << "--some-new-stuff" if build.head?</pre>
+ # <pre># If there are multiple conditional arguments use a block instead of lines.
+ # if build.head?
+ # args << "--i-want-pizza"
+ # args << "--and-a-cold-beer" if build.with? "cold-beer"
+ # end</pre>
def head?
include? "HEAD"
end
+ # True if a {Formula} is being built with {Formula.devel} instead of {Formula.stable}.
+ # <pre>args << "--some-beta" if build.devel?</pre>
def devel?
include? "devel"
end
+ # True if a {Formula} is being built with {Formula.stable} instead of {Formula.devel} or {Formula.head}. This is the default.
+ # <pre>args << "--some-beta" if build.devel?</pre>
def stable?
!(head? || devel?)
end
- # True if the user requested a universal build.
+ # True if a {Formula} is being built universally.
+ # e.g. on newer Intel Macs this means a combined x86_64/x86 binary/library.
+ # <pre>args << "--universal-binary" if build.universal?</pre>
def universal?
include?("universal") && option_defined?("universal")
end
- # True if the user requested to enable C++11 mode.
+ # True if a {Formula} is being built in C++11 mode.
def cxx11?
include?("c++11") && option_defined?("c++11")
end
- # Request a 32-bit only build.
+ # True if a {Formula} is being built in 32-bit/x86 mode.
# This is needed for some use-cases though we prefer to build Universal
# when a 32-bit version is needed.
def build_32_bit?
include?("32-bit") && option_defined?("32-bit")
end
+ # @private
def used_options
@options & @args
end
+ # @private
def unused_options
@options - @args
end
@@ -118,7 +118,7 @@ def generate!
def template; <<-EOS.undent
# Documentation: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md
- # #{HOMEBREW_CONTRIB}/example-formula.rb
+ # http://www.rubydoc.info/github/Homebrew/homebrew/master/frames
# PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!
class #{Formulary.class_s(name)} < Formula
@@ -3,6 +3,7 @@
module Homebrew
SOURCE_PATH=HOMEBREW_REPOSITORY/"Library/Homebrew/manpages"
TARGET_PATH=HOMEBREW_REPOSITORY/"share/man/man1"
+ DOC_PATH=HOMEBREW_REPOSITORY/"share/doc/homebrew"
LINKED_PATH=HOMEBREW_PREFIX/"share/man/man1"
def man
@@ -21,12 +22,15 @@ def man
else
Homebrew.install_gem_setup_path! "ronn"
+ puts "Writing HTML fragments to #{DOC_PATH}"
puts "Writing manpages to #{TARGET_PATH}"
target_file = nil
Dir["#{SOURCE_PATH}/*.md"].each do |source_file|
- target_file = TARGET_PATH/File.basename(source_file, ".md")
- safe_system "ronn --roff --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_file}"
+ target_html = DOC_PATH/"#{File.basename(source_file, ".md")}.html"
+ safe_system "ronn --fragment --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_html}"
+ target_man = TARGET_PATH/File.basename(source_file, ".md")
+ safe_system "ronn --roff --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_man}"
end
system "man", target_file if ARGV.flag? "--verbose"
@@ -1,3 +1,4 @@
+# @private
module CompilerConstants
GNU_GCC_VERSIONS = %w[4.3 4.4 4.5 4.6 4.7 4.8 4.9 5]
GNU_GCC_REGEXP = /^gcc-(4\.[3-9]|5)$/
@@ -1,12 +1,20 @@
require "formula"
require "compilers"
+# Homebrew extends Ruby's `ENV` to make our code more readable.
+# Implemented in {SharedEnvExtension} and either {Superenv} or
+# {Stdenv} (depending on the build mode).
+# @see Superenv
+# @see Stdenv
+# @see http://www.rubydoc.info/stdlib/Env Ruby's ENV API
module SharedEnvExtension
include CompilerConstants
+ # @private
CC_FLAG_VARS = %w[CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS]
+ # @private
FC_FLAG_VARS = %w[FCFLAGS FFLAGS]
-
+ # @private
SANITIZED_VARS = %w[
CDPATH GREP_OPTIONS CLICOLOR_FORCE
CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH OBJC_INCLUDE_PATH
@@ -18,11 +26,13 @@ module SharedEnvExtension
LIBRARY_PATH
]
+ # @private
def setup_build_environment(formula = nil)
@formula = formula
reset
end
+ # @private
def reset
SANITIZED_VARS.each { |k| delete(k) }
end
@@ -72,6 +82,10 @@ def append_path(key, path)
append key, path, File::PATH_SEPARATOR if File.directory? path
end
+ # 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.
+ # <pre>ENV.prepend_path "PKG_CONFIG_PATH", "#{Formula["glib"].opt_lib}/pkgconfig"</pre>
def prepend_path(key, path)
prepend key, path, File::PATH_SEPARATOR if File.directory? path
end
@@ -126,6 +140,13 @@ def fcflags
self["FCFLAGS"]
end
+ # Outputs the current compiler.
+ # @return [Symbol]
+ # <pre># Do something only for clang
+ # if ENV.compiler == :clang
+ # # modify CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS in one go:
+ # ENV.append_to_cflags "-I ./missing/includes"
+ # end</pre>
def compiler
@compiler ||= if (cc = ARGV.cc)
warn_about_non_apple_gcc($&) if cc =~ GNU_GCC_REGEXP
@@ -147,6 +168,7 @@ def compiler
end
end
+ # @private
def determine_cc
COMPILER_SYMBOL_MAP.invert.fetch(compiler, compiler)
end
@@ -159,13 +181,14 @@ def determine_cc
end
end
- # Snow Leopard defines an NCURSES value the opposite of most distros
+ # Snow Leopard defines an NCURSES value the opposite of most distros.
# See: https://bugs.python.org/issue6848
- # Currently only used by aalib in core
+ # Currently only used by aalib in core.
def ncurses_define
append "CPPFLAGS", "-DNCURSES_OPAQUE=0"
end
+ # @private
def userpaths!
paths = ORIGINAL_PATHS.map { |p| p.realpath.to_s rescue nil } - %w[/usr/X11/bin /opt/X11/bin]
self["PATH"] = paths.unshift(*self["PATH"].split(File::PATH_SEPARATOR)).uniq.join(File::PATH_SEPARATOR)
@@ -212,12 +235,14 @@ def fortran
end
# ld64 is a newer linker provided for Xcode 2.5
+ # @private
def ld64
ld64 = Formulary.factory("ld64")
self["LD"] = ld64.bin/"ld"
append "LDFLAGS", "-B#{ld64.bin}/"
end
+ # @private
def gcc_version_formula(name)
version = name[GNU_GCC_REGEXP, 1]
gcc_version_name = "gcc#{version.delete(".")}"
@@ -230,6 +255,7 @@ def gcc_version_formula(name)
end
end
+ # @private
def warn_about_non_apple_gcc(name)
begin
gcc_formula = gcc_version_formula(name)
@@ -2,9 +2,11 @@
require "os/mac"
require "extend/ENV/shared"
+# @deprecated
module Stdenv
include SharedEnvExtension
+ # @private
SAFE_CFLAGS_FLAGS = "-w -pipe"
DEFAULT_FLAGS = "-march=core2 -msse4"
@@ -14,6 +16,7 @@ def self.extended(base)
end
end
+ # @private
def setup_build_environment(formula = nil)
super
@@ -69,6 +72,7 @@ def setup_build_environment(formula = nil)
end
end
+ # @private
def determine_pkg_config_libdir
paths = []
paths << "#{HOMEBREW_PREFIX}/lib/pkgconfig"
@@ -106,11 +110,13 @@ def deparallelize
end
end
+ # @private
def determine_cc
s = super
MacOS.locate(s) || Pathname.new(s)
end
+ # @private
def determine_cxx
dir, base = determine_cc.split
dir / base.to_s.sub("gcc", "g++").sub("clang", "clang++")
@@ -295,6 +301,7 @@ def libstdcxx
end
end
+ # @private
def replace_in_cflags(before, after)
CC_FLAG_VARS.each do |key|
self[key] = self[key].sub(before, after) if key?(key)
@@ -308,6 +315,7 @@ def set_cflags(val)
# Sets architecture-specific flags for every environment variable
# given in the list `flags`.
+ # @private
def set_cpu_flags(flags, default = DEFAULT_FLAGS, map = Hardware::CPU.optimization_flags)
cflags =~ /(-Xarch_#{Hardware::CPU.arch_32_bit} )-march=/
xarch = $1.to_s
@@ -319,6 +327,7 @@ def set_cpu_flags(flags, default = DEFAULT_FLAGS, map = Hardware::CPU.optimizati
append flags, map.fetch(effective_arch, default)
end
+ # @private
def effective_arch
if ARGV.build_bottle?
ARGV.bottle_arch || Hardware.oldest_cpu
@@ -332,6 +341,7 @@ def effective_arch
end
end
+ # @private
def set_cpu_cflags(default = DEFAULT_FLAGS, map = Hardware::CPU.optimization_flags)
set_cpu_flags CC_FLAG_VARS, default, map
end
@@ -346,5 +356,6 @@ def make_jobs
end
# This method does nothing in stdenv since there's no arg refurbishment
+ # @private
def refurbish_args; end
end
Oops, something went wrong.

0 comments on commit 2c959a7

Please sign in to comment.