mirror of
https://github.com/Homebrew/brew.git
synced 2025-07-14 16:09:03 +08:00
Documentation Updates
Mike probably wants to cast an eye over all of this, but in summary: In the Example Formula: * Updates with a revision example. * Updates with a mirror mirror (Whoa meta). * Replaces the bottles with more modern examples. * Adds the Yosemite binary dependency options. * Improves the plist documentation In the Bottles doc: * Modernises the expected bottle readout. * Adds double quotes. In the FAQ: * Updates the bottle language to reflect Yosemite’s arrival and the Bot’s new minimum OS bottle generation. In the Formula-Cookbook: * Adds a mega block on the OpenSSL situation in Homebrew, complete with examples and explanation. * Changes the X11 dependency example to optional to reflect Jack’s recently-expressed pattern in other formulae. * Explains why and how formulae are sometimes revisioned, and the mechanism behind that. * Updates the Ldapvi `otool` readout to reflect the new usage of OpenSSL. Setting a good example and all that. * Updates the Python language to match Tim’s new Python handling. * Updates the naming block to explain how Homebrew handles name conflicts, complete with examples. * Updates (a tiny bit) the sandbox creation in /tmp to reflect the current style. * Updates the chmod to move away from +x towards 0555 instead. * Labels the `enable-ham` option depreciated rather than old. Slightly firmer. * Updates the bottle block instructions to reflect Homebrew’s audit mechanism not crying about it locally. Closes Homebrew/homebrew#34275. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
This commit is contained in:
Dominyk Tiller
Mike McQuaid
parent
24f1a6e9fc
commit
e8d7d1df9c
@ -11,11 +11,14 @@ require "formula"
|
||||
# Homebrew does enforce that the name of the file and the class correspond.
|
||||
# Check with `brew search` that the name is free.
|
||||
class ExampleFormula < Formula
|
||||
homepage "http://www.example.com" # used by `brew home example-formula`.
|
||||
homepage "https://www.example.com" # used by `brew home example-formula`.
|
||||
revision 1 # This is used when there's no new version but it needs recompiling for another reason.
|
||||
# 0 is default & unwritten.
|
||||
|
||||
# The url of the archive. Prefer https (security and proxy issues):
|
||||
url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
|
||||
mirror "https://in.case.the.host.is.down.example.com" # `mirror` is optional.
|
||||
mirror "https://in.case.the.mirror.is.down.example.com" # Mirrors are limitless, but don't go too wild.
|
||||
|
||||
# Optionally specify the download strategy `:using => ...`
|
||||
# `:git`, `:hg`, `:svn`, `:bzr`, `:cvs`,
|
||||
@ -93,10 +96,9 @@ class ExampleFormula < Formula
|
||||
prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built.
|
||||
cellar "/opt/homebrew/Cellar" # Optional HOMEBREW_CELLAR in which the bottles were built.
|
||||
revision 1 # Making the old bottle outdated without bumping the version of the formula.
|
||||
sha1 "d3d13fe6f42416765207503a946db01378131d7b" => :mountain_lion
|
||||
sha1 "cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee" => :lion
|
||||
sha1 "a19b544c8c645d7daad1d39a070a0eb86dfe9b9c" => :snow_leopard
|
||||
sha1 "583dc9d98604c56983e17d66cfca2076fc56312b" => :snow_leopard_32
|
||||
sha1 "d3d13fe6f42416765207503a946db01378131d7b" => :yosemite
|
||||
sha1 "cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee" => :mavericks
|
||||
sha1 "a19b544c8c645d7daad1d39a070a0eb86dfe9b9c" => :mountain_lion
|
||||
end
|
||||
|
||||
def pour_bottle?
|
||||
@ -154,6 +156,8 @@ class ExampleFormula < Formula
|
||||
depends_on :arch => :ppc # Only builds on PowerPC?
|
||||
depends_on :ld64 # Sometimes ld fails on `MacOS.version < :leopard`. Then use this.
|
||||
depends_on :x11 # 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 :mysql => :recommended
|
||||
# It is possible to only depend on something if
|
||||
# `build.with?` or `build.without? "another_formula"`:
|
||||
@ -404,10 +408,30 @@ class ExampleFormula < Formula
|
||||
|
||||
## 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"
|
||||
|
||||
# Define this method to provide a plist.
|
||||
# Todo: Expand this example with a little demo plist? I dunno.
|
||||
# There is more to startup plists. Help, I suck a plists!
|
||||
def plist; nil; end
|
||||
# Looking for another example? Check out Apple's handy manpage =>
|
||||
# https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html
|
||||
def plist; <<-EOS.undent
|
||||
<?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>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
</plist>
|
||||
EOS
|
||||
end
|
||||
end
|
||||
|
||||
__END__
|
||||
|
||||
@ -16,6 +16,10 @@ duplicate tools
|
||||
|
||||
There are exceptions:
|
||||
|
||||
* OpenSSL - Apple has formally deprecated OpenSSL on OS X in favour of their own Security Framework
|
||||
& consequently the OS X OpenSSL is rarely updated and frequently falls behind important security updates.
|
||||
Homebrew endeavours to use our shipped OpenSSL as much
|
||||
as possible.
|
||||
* Programs that a user will regularly interact with directly, like editors and
|
||||
language runtimes
|
||||
* Libraries that provide functionality or contain security updates not found in
|
||||
|
||||
@ -23,24 +23,22 @@ Bottles have a DSL to be used in formulae which is contained in the `bottle do .
|
||||
A simple (and typical) example:
|
||||
```ruby
|
||||
bottle do
|
||||
sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion
|
||||
sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion
|
||||
sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard
|
||||
sha1 "23ef6a81af2f37166d7d7423b88f7716bf9b0629" => :yosemite
|
||||
sha1 "fdc919d750012fbfeeec8b3f95d07000adc3c946" => :mavericks
|
||||
sha1 "0d08b3ca611f47a25a922b2d942f157f1d6268c1" => :mountain_lion
|
||||
end
|
||||
```
|
||||
|
||||
A full example:
|
||||
```ruby
|
||||
bottle do
|
||||
root_url 'http://mikemcquaid.com'
|
||||
prefix '/opt/homebrew'
|
||||
cellar '/opt/homebrew/Cellar'
|
||||
root_url "http://mikemcquaid.com"
|
||||
prefix "/opt/homebrew"
|
||||
cellar "/opt/homebrew/Cellar"
|
||||
revision 4
|
||||
sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion
|
||||
sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion
|
||||
sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard
|
||||
sha1 '583dc9d98604c56983e17d66cfca2076fc56312b' => :snow_leopard_32
|
||||
sha1 '2ef5f57afae319a3e7618d5723059eae568276fa' => :leopard
|
||||
sha1 "23ef6a81af2f37166d7d7423b88f7716bf9b0629" => :yosemite
|
||||
sha1 "fdc919d750012fbfeeec8b3f95d07000adc3c946" => :mavericks
|
||||
sha1 "0d08b3ca611f47a25a922b2d942f157f1d6268c1" => :mountain_lion
|
||||
end
|
||||
```
|
||||
|
||||
|
||||
@ -96,8 +96,8 @@ will use a bottled version of $FORMULA, but
|
||||
`brew install $FORMULA —enable-bar` will trigger a source build.
|
||||
* The `--build-from-source` option is invoked.
|
||||
* The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set.
|
||||
* The machine is not running OS X 10.7+ as all bottled builds are
|
||||
generated on Lion or later.
|
||||
* The machine is not running OS X 10.8+ as all bottled builds are
|
||||
generated on Mountain Lion or later.
|
||||
* Homebrew is installed to a prefix other than the standard
|
||||
`/usr/local` (although some bottles support this)
|
||||
|
||||
|
||||
@ -149,7 +149,11 @@ There are plenty of others. Check `/usr/lib` to see.
|
||||
|
||||
We try to not duplicate libraries and complicated tools in core Homebrew. We dupe some common tools though. But generally, we avoid dupes because it’s one of Homebrew’s foundations. (And it causes build and usage problems!)
|
||||
|
||||
However, we maintain a special [tap that provides dupes](https://github.com/Homebrew/homebrew-dupes).
|
||||
The one special exception is OpenSSL. Anything that uses OpenSSL *should* be built using Homebrew’s shipped OpenSSL and our test bot's post-install audit will warn of this when it is detected. (*Of course, there are exceptions to the exception. Not everything can be forced onto our OpenSSL)*.
|
||||
|
||||
Because Homebrew’s OpenSSL is `keg_only` to avoid conflicting with the system sometimes formulae need to have environmental variables set or special configuration flags passed to locate our preferred OpenSSL; you can see this mechanism in the [clamav](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/clamav.rb#L28) formula. Usually this is unnecessary because when OpenSSL is specified as a dependency Homebrew temporarily prepends the $PATH with that prefix.
|
||||
|
||||
Homebrew maintains a special [tap that provides other useful dupes](https://github.com/Homebrew/homebrew-dupes).
|
||||
|
||||
*Important:* Since the introduction of `superenv`, `brew --prefix`/bin is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH`. You can test around this with `--env=std`.
|
||||
|
||||
@ -162,7 +166,7 @@ class Foo < Formula
|
||||
depends_on "gtk+" => :optional
|
||||
depends_on "readline" => :recommended
|
||||
depends_on "boost" => "with-icu"
|
||||
depends_on :x11
|
||||
depends_on :x11 => :optional
|
||||
end
|
||||
```
|
||||
|
||||
@ -196,6 +200,15 @@ A Hash specifies a formula dependency with some additional information. Given a
|
||||
depends_on "foo" => [:optional, "with-bar"]
|
||||
```
|
||||
|
||||
## Formulae Revisions
|
||||
|
||||
In Homebrew we sometimes accept formulae updates that don’t include a version bump. These include homepage changes, resource updates, new patches or fixing a security issue with a formula.
|
||||
|
||||
Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a `revision` and inserted underneath the homepage/url/sha block.
|
||||
|
||||
Where a dependent of a formula fails against a new version of that dependency it must receive a `revision`. An example of such failure can be seen [here](https://github.com/Homebrew/homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/homebrew/pull/31207).
|
||||
|
||||
`Revisions` are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users aren’t left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96).
|
||||
|
||||
## Double-check for dependencies
|
||||
|
||||
@ -205,17 +218,16 @@ You can double-check which libraries a binary links to with the `otool` command
|
||||
|
||||
$ otool -L /usr/local/bin/ldapvi
|
||||
/usr/local/bin/ldapvi:
|
||||
/usr/lib/libssl.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8)
|
||||
/usr/lib/libcrypto.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8)
|
||||
/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.3)
|
||||
/usr/local/Cellar/glib/2.22.4/lib/libglib-2.0.0.dylib (compatibility version 2201.0.0, current version 2201.4.0)
|
||||
/usr/local/Cellar/gettext/0.17/lib/libintl.8.dylib (compatibility version 9.0.0, current version 9.2.0)
|
||||
/usr/local/Cellar/readline/6.0/lib/libreadline.6.0.dylib (compatibility version 6.0.0, current version 6.0.0)
|
||||
/usr/local/Cellar/popt/1.15/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
|
||||
/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.2.0)
|
||||
/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 38.0.0)
|
||||
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.0.0)
|
||||
/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
/usr/local/lib/libglib-2.0.0.dylib (compatibility version 4201.0.0, current version 4201.0.0)
|
||||
/usr/local/opt/gettext/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0)
|
||||
/usr/local/opt/readline/lib/libreadline.6.dylib (compatibility version 6.0.0, current version 6.3.0)
|
||||
/usr/local/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
|
||||
/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
|
||||
/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)
|
||||
|
||||
|
||||
## Specifying gems, Python modules etc. as dependencies
|
||||
@ -232,12 +244,12 @@ class Foo < Formula
|
||||
end
|
||||
|
||||
def install
|
||||
resource("pycrypto").stage { system "python", "setup.py", "install", "--prefix=#{libexec}" }
|
||||
resource("pycrypto").stage { Language::Python.setup_install "python", libexec/"vendor" }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
See [ansible](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/ansible.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `ansible`.
|
||||
See [jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `jrnl`.
|
||||
|
||||
[This script](https://raw.githubusercontent.com/tdsmith/labmisc/master/mkpydeps) can help you generate resource stanzas for the dependencies of your Python application.
|
||||
|
||||
@ -292,7 +304,11 @@ If you’re not sure about the name check the homepage, and check the Wikipedia
|
||||
|
||||
[ALSO CHECK WHAT DEBIAN CALLS IT!](http://www.debian.org/distrib/packages)
|
||||
|
||||
If you’re *still* not sure, just commit. I’ll apply some arbitrary rule and make a decision ;)
|
||||
Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectation.
|
||||
|
||||
When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
|
||||
|
||||
If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision ;)
|
||||
|
||||
When importing classes, Homebrew will require the formula and then create an instance of the class. It does this by assuming the formula name can be directly converted to the class name using a `regexp`. The rules are simple:
|
||||
|
||||
@ -360,7 +376,7 @@ If a commit touches multiple files, or isn’t one logical bug fix, or a file is
|
||||
|
||||
* The result of `Formula.download_strategy` is instantiated.
|
||||
* `DownloadStrategy.fetch` is called (downloads tarball, checks out git repository, etc.)
|
||||
* A temporary sandbox is created in `/tmp/homebrew`
|
||||
* A temporary sandbox is created in `/tmp/$formulaname`
|
||||
* `DownloadStrategy.stage` is called (extracts tarball to above sandbox, exports git repository to sandbox, etc.)
|
||||
* Patches are applied
|
||||
* Current directory is changed to the stage root (so when you `system make`, it works)
|
||||
@ -393,7 +409,7 @@ end
|
||||
|
||||
## bin.install "foo"
|
||||
|
||||
You’ll see stuff like that in other formulae. This installs the file foo into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod +x foo`).
|
||||
You’ll see stuff like that in other formulae. This installs the file foo into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`).
|
||||
|
||||
## inreplace
|
||||
|
||||
@ -823,7 +839,7 @@ if build.without? "ham"
|
||||
end
|
||||
|
||||
if build.include? "enable-ham"
|
||||
# the old style, only useful for options other than `with`/`without` style
|
||||
# the deprecated style, only useful for options other than `with`/`without` style
|
||||
end
|
||||
```
|
||||
|
||||
@ -860,7 +876,7 @@ Homebrew provides two Formula methods for launchd plist files. `plist_name` will
|
||||
|
||||
## Updating formulae
|
||||
|
||||
Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Even although it will warn on your local machine please leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change.
|
||||
Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Please leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change.
|
||||
|
||||
Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency please `brew reinstall` all the dependencies after it is installed and verify they work correctly.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user