From cd167d74ff89f84aa7eaaf46178e64dff881261b Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:18:32 +0100 Subject: [PATCH 01/19] bottles: documentation update --- share/doc/homebrew/Bottles.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/share/doc/homebrew/Bottles.md b/share/doc/homebrew/Bottles.md index 28a0d79ee3..a72ba51edc 100644 --- a/share/doc/homebrew/Bottles.md +++ b/share/doc/homebrew/Bottles.md @@ -7,7 +7,7 @@ If a bottle is available and usable it will be downloaded and poured automatical Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified on installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or the bottle's `cellar` is not `:any` or equal to the current `HOMEBREW_CELLAR`. ## Bottle Creation -Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew). +Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew). By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for. (That's Core 2 for 64-bit OSs, Core for 32-bit.) This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad! @@ -20,9 +20,9 @@ Bottles have a DSL to be used in formulae which is contained in the `bottle do . A simple (and typical) example: ```ruby bottle do - sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :yosemite - sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :mavericks - sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :mountain_lion + sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra + sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite end ``` @@ -33,9 +33,9 @@ bottle do prefix "/opt/homebrew" cellar "/opt/homebrew/Cellar" rebuild 4 - sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :yosemite - sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :mavericks - sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :mountain_lion + sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra + sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite end ``` @@ -45,11 +45,11 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi ### `cellar` Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built. -Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar` +Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar` ### `prefix` Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. -See description of `cellar`. When `cellar` is `:any` prefix should be omitted. +See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` prefix should be omitted. ### `rebuild` Optionally contains the rebuild version of the bottle. @@ -65,5 +65,13 @@ Additionally there is a method available in the formula DSL. Optionally returns a boolean to decide whether a bottle should be used for this formula. For example a bottle may break if another formula has been compiled with non-default options so this method could check for that case and return `false`. +A full example: +```ruby +pour_bottle? do + reason "The bottle needs the Xcode CLT to be installed." + satisfy { MacOS::CLT.installed? } +end +``` + ## Planned Improvements -Most bottle features have been (and planned improvements will be) implemented by @mikemcquaid. Contact him directly with questions. +Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions. From 9d17e6faaa00a2dca8f3c1b3e28993b305672294 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:21:53 +0100 Subject: [PATCH 02/19] brew-tap: note developers get full clones by default --- share/doc/homebrew/brew-tap.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/share/doc/homebrew/brew-tap.md b/share/doc/homebrew/brew-tap.md index af0e5fe7f2..624a83f33b 100644 --- a/share/doc/homebrew/brew-tap.md +++ b/share/doc/homebrew/brew-tap.md @@ -29,7 +29,8 @@ edavis/emacs fine. * Add `--full` to either the one- or two-argument invocations above, and git - will make a complete clone rather than a shallow one. + will make a complete clone rather than a shallow one. Full is the default for + Homebrew developers. * `brew tap --repair` migrates tapped formulae from symlink-based to directory-based structure. (This should only need to be run once.) From 06145dd6d0c1b05478855efcdb384ab51a395da1 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:27:48 +0100 Subject: [PATCH 03/19] C++-Standard-Libraries: note Xcode 8's libstdc++ deprecation --- share/doc/homebrew/C++-Standard-Libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/doc/homebrew/C++-Standard-Libraries.md b/share/doc/homebrew/C++-Standard-Libraries.md index f841044b99..4912832f8b 100644 --- a/share/doc/homebrew/C++-Standard-Libraries.md +++ b/share/doc/homebrew/C++-Standard-Libraries.md @@ -1,7 +1,7 @@ # C++ Standard Libraries There are two C++ standard libraries supported by Apple compilers. -The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC compilers, GNU GCC compilers, and clang. +The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC compilers, GNU GCC compilers, and clang. This was marked deprecated with a warning during compile as of Xcode 8. The default for 10.9 is **libc++**, which is also the default for clang on older platforms when building C++11 code. From 372a2b247073f54ce0cc88eb1628a8f69c770499 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:29:07 +0100 Subject: [PATCH 04/19] C++-Standard-Libraries: wrap to ~80 characters --- share/doc/homebrew/C++-Standard-Libraries.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/share/doc/homebrew/C++-Standard-Libraries.md b/share/doc/homebrew/C++-Standard-Libraries.md index 4912832f8b..0bb987def7 100644 --- a/share/doc/homebrew/C++-Standard-Libraries.md +++ b/share/doc/homebrew/C++-Standard-Libraries.md @@ -1,13 +1,23 @@ # C++ Standard Libraries There are two C++ standard libraries supported by Apple compilers. -The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC compilers, GNU GCC compilers, and clang. This was marked deprecated with a warning during compile as of Xcode 8. +The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC +compilers, GNU GCC compilers, and clang. This was marked deprecated with a +warning during compile as of Xcode 8. -The default for 10.9 is **libc++**, which is also the default for clang on older platforms when building C++11 code. +The default for 10.9 is **libc++**, which is also the default for clang on older +platforms when building C++11 code. -There are subtle incompatibilities between several of the C++ standard libraries, so Homebrew will refuse to install software if a dependency was built with an incompatible C++ library. It's recommended that you install the dependency tree using a compatible compiler. +There are subtle incompatibilities between several of the C++ standard libraries, +so Homebrew will refuse to install software if a dependency was built with an +incompatible C++ library. It's recommended that you install the dependency tree +using a compatible compiler. -**If you've upgraded to 10.9 from an earlier version** - because the default C++ standard library is now libc++, you may not be able to build software using dependencies that you built on 10.8 or lower. If you're reading this page because you were directed here by a build error, you can most likely fix the issue if you reinstall all the dependencies of the package you're trying to build. +**If you've upgraded to 10.9 from an earlier version** - because the default C++ +standard library is now libc++, you may not be able to build software using +dependencies that you built on 10.8 or lower. If you're reading this page because +you were directed here by a build error, you can most likely fix the issue if +you reinstall all the dependencies of the package you're trying to build. Example install using GCC 4.8: ```brew install DESIRED_FORMULA --cc=gcc-4.8```. Get GCC 4.8 via: ```brew install gcc48``` From e25bcfe9335848f2e21f6d7f11040fcda39badf6 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:33:30 +0100 Subject: [PATCH 05/19] Common-Issues-for-Core-Contributors: update link --- share/doc/homebrew/Common-Issues-for-Core-Contributors.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/share/doc/homebrew/Common-Issues-for-Core-Contributors.md b/share/doc/homebrew/Common-Issues-for-Core-Contributors.md index 3ec63a5136..b0bea8c39c 100644 --- a/share/doc/homebrew/Common-Issues-for-Core-Contributors.md +++ b/share/doc/homebrew/Common-Issues-for-Core-Contributors.md @@ -10,7 +10,5 @@ This is a page for maintainers to diagnose certain build errors. The exact atom may be different. -This can be caused by passing the obsolete `-s` flag to the linker. - -See: -https://github.com/Homebrew/homebrew/commit/7c9a9334631dc84d59131ca57419e8c828b1574b +This can be caused by passing the obsolete `-s` flag to the linker and can be +fixed like [this](https://github.com/Homebrew/legacy-homebrew/commit/7c9a9334631dc84d59131ca57419e8c828b1574b). From e4f607e4c8a4368a506edfcbbecfe6d24abc7f34 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:37:24 +0100 Subject: [PATCH 06/19] Custom-GCC-and-cross-compilers: remove dead taps --- share/doc/homebrew/Custom-GCC-and-cross-compilers.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md index bbc3665cf9..030f6c842f 100644 --- a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md +++ b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md @@ -9,7 +9,4 @@ Rather than merging in brews for either of these cases at this time, we're listi * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing C++11 support on earlier versions. * [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48` -* [MSP430 development](https://github.com/Homebrew/homebrew/issues/issue/2336) -* [OS161 development](https://github.com/maxpow4h/homebrew-os161) Your university probably uses a different version, replacing the URLs with your university's URLs will probably work. -* [ARM-EABI](https://github.com/paxswill/homebrew-paxswill) provides an arm-none-eabi toolchain formula. * [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V toolchain including binutils and gcc. From c5df95302164c85718d1e2f4511cbb1e3c03b0b6 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:38:51 +0100 Subject: [PATCH 07/19] Custom-GCC-and-cross-compilers: wrap to ~80 characters --- .../Custom-GCC-and-cross-compilers.md | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md index 030f6c842f..1d662c1587 100644 --- a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md +++ b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md @@ -1,12 +1,21 @@ # Custom GCC and cross compilers -Homebrew depends on having an up-to-date version of Xcode because it comes with specific versions of build tools e.g. `clang`. +Homebrew depends on having an up-to-date version of Xcode because it comes with +specific versions of build tools e.g. `clang`. -Installing a custom version of GCC or `autotools` into the `$PATH` has the potential to break lots of compiles so we prefer the Apple or Homebrew provided compilers. +Installing a custom version of GCC or `autotools` into the `$PATH` has the +potential to break lots of compiles so we prefer the Apple or Homebrew provided +compilers. -Cross-compilers based on GCC will typically be "keg-only" and therefore not linked into the path by default. +Cross-compilers based on GCC will typically be "keg-only" and therefore not +linked into the path by default. -Rather than merging in brews for either of these cases at this time, we're listing them on this page. If you come up with a formula for a new version of GCC or cross-compiler suite, please link it in here. +Rather than merging in brews for either of these cases at this time, we're +listing them on this page. If you come up with a formula for a new version of +GCC or cross-compiler suite, please link it in here. -* Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing C++11 support on earlier versions. -* [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48` -* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V toolchain including binutils and gcc. +* Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing +C++11 support on earlier versions. +* [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an +up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48` +* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V +toolchain including binutils and gcc. From edd2c3d968acca4e22aa76161e71fbca9bb14175 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:43:39 +0100 Subject: [PATCH 08/19] External-Commands: update homebrew-services URL --- share/doc/homebrew/External-Commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/share/doc/homebrew/External-Commands.md b/share/doc/homebrew/External-Commands.md index b5a21435e4..a13922e77b 100644 --- a/share/doc/homebrew/External-Commands.md +++ b/share/doc/homebrew/External-Commands.md @@ -87,11 +87,11 @@ These commands have been contributed by Homebrew users but are not included in t >Scrapes a formula's homepage to get more information: [https://gist.github.com/475200](https://gist.github.com/475200) ### brew-services ->Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://github.com/gapple/homebrew-services](https://github.com/gapple/homebrew-services) +>Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://github.com/Homebrew/homebrew-services](https://github.com/Homebrew/homebrew-services) > Install using: > ``` - $ brew tap gapple/services + $ brew tap homebrew/services > ``` ## SEE ALSO From 23b120e1550be3250676f220e5a85865d782f24c Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:44:09 +0100 Subject: [PATCH 09/19] External-Commands: remove replaced brew-more tool --- share/doc/homebrew/External-Commands.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/share/doc/homebrew/External-Commands.md b/share/doc/homebrew/External-Commands.md index a13922e77b..721c4a86a8 100644 --- a/share/doc/homebrew/External-Commands.md +++ b/share/doc/homebrew/External-Commands.md @@ -83,9 +83,6 @@ These commands have been contributed by Homebrew users but are not included in t ### brew-growl >Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl -### brew-more ->Scrapes a formula's homepage to get more information: [https://gist.github.com/475200](https://gist.github.com/475200) - ### brew-services >Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://github.com/Homebrew/homebrew-services](https://github.com/Homebrew/homebrew-services) From 840e86d454941896b6250bb355056d5b6c987aa8 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:53:13 +0100 Subject: [PATCH 10/19] Formula-Cookbook: recommend audit --new-formula for new formula --- share/doc/homebrew/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 4498c1e23b..01b0d882bf 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -32,7 +32,7 @@ Before submitting a new formula make sure your package: * isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/pulls)) * is still supported by upstream (i.e. doesn't require extensive patching) * has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Forks](Interesting-Taps-&-Forks.md) for where pre-release versions belong. -* passes all `brew audit --strict --online $FORMULA` tests. +* passes all `brew audit --new-formula $FORMULA` tests. Before submitting a new formula make sure you read over our [contribution guidelines](https://github.com/Homebrew/brew/blob/master/.github/CONTRIBUTING.md). From f744cdbc81a4e5bc8f7d7bb1e5a0e3593846d002 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:54:55 +0100 Subject: [PATCH 11/19] Formula-Cookbook: note LibreSSL audit check --- share/doc/homebrew/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 01b0d882bf..75a53f60f9 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -102,7 +102,7 @@ There are plenty of others; check `/usr/lib` for them. We generally try to not duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools. -One very 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 if it detects you haven't done this. +Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be built using Homebrew’s shipped equivalent and our test bot's post-install `audit` will warn if it detects you haven't done this. Homebrew’s OpenSSL is [`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method) From 3eb966c309798e733f6cc6546423d53b74c3d0b2 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 17:59:20 +0100 Subject: [PATCH 12/19] Formula-Cookbook: detail build env less generically --- share/doc/homebrew/Formula-Cookbook.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 75a53f60f9..ea5c3c221a 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -110,9 +110,8 @@ to avoid conflicting with the system so sometimes formulae need to have environment variables set or special configuration flags passed to locate our OpenSSL. You can see this mechanism in the [clamav](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/clamav.rb#L38) -formula. Usually this is unnecessary because when OpenSSL is specified -as a dependency Homebrew temporarily prepends the `$PATH` with that -prefix. +formula. Usually this is unnecessary because Homebrew sets up our [build environment](https://github.com/Homebrew/brew/blob/fb3bec8d70d375a97554d4c3fed82ad2332b2191/Library/Homebrew/extend/ENV/super.rb) +to favour finding `keg_only` formulae first. Homebrew maintains a special [tap that provides other useful system duplicates](https://github.com/Homebrew/homebrew-dupes). From 0cc4d530dc4725a9f3bcd51565bc06118598bfa3 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 18:12:47 +0100 Subject: [PATCH 13/19] Formula-Cookbook: document :run --- share/doc/homebrew/Formula-Cookbook.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index ea5c3c221a..828ea82752 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -121,10 +121,11 @@ Homebrew maintains a special [tap that provides other useful system duplicates]( ```ruby class Foo < Formula + depends_on "pkg-config" => :run depends_on "jpeg" - depends_on "gtk+" => :optional - depends_on "readline" => :recommended depends_on "boost" => "with-icu" + depends_on "readline" => :recommended + depends_on "gtk+" => :optional depends_on :x11 => :optional end ``` @@ -135,12 +136,16 @@ A Symbol (e.g. `:x11`) specifies a [`Requirement`](http://www.rubydoc.info/githu A Hash (e.g. `=>`) specifies a formula dependency with some additional information. Given a single string key, the value can take several forms: -* a Symbol (currently one of `:build`, `:optional`, `:recommended`). +* a Symbol (currently one of `:build`, `:optional`, `:run` or `:recommended`). - `:build` means that dependency is a build-time only dependency so it can be skipped when installing from a bottle or when listing missing dependencies using `brew missing`. - `:optional` generates an implicit `with-foo` option for the formula. This means that, given `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to use the dependency. + - `:run` can mean the dependency is only required at run, or it can be used + to declare build dependencies such as `pkg-config` are needed during + runtime as well, which will silence the audit warning. `:run` currently + implies `:build` as well. - `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled by default and the user must pass `--without-foo` to disable this dependency. The default From ec2302ad901105417479c9b43426824d41cd250f Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 19:03:29 +0100 Subject: [PATCH 14/19] Formula-Cookbook: update urls --- share/doc/homebrew/Formula-Cookbook.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 828ea82752..0efc24f0ac 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -193,9 +193,9 @@ In Homebrew we sometimes accept formulae updates that don’t include a version 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`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method) 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`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method). 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). +Where a dependent of a formula fails against a new version of that dependency it must receive a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method). An example of such failure can be seen [here](https://github.com/Homebrew/legacy-homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/legacy-homebrew/pull/31207). -[`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method)s 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). +[`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method)s 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/legacy-homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96). ## Version Scheme Changes @@ -231,8 +231,8 @@ If you're installing an application then please use [`resource`](http://www.ruby ```ruby class Foo < Formula resource "pycrypto" do - url "https://pypi.python.org/packages/source/p/pycrypto/pycrypto-2.6.tar.gz" - sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" + url "https://files.pythonhosted.org/packages/60/db/645aa9af249f059cc3a368b118de33889219e0362141e75d4eaf6f80f163/pycrypto-2.6.1.tar.gz" + sha256 "f2ce1e989b272cfcb677616763e0a2e7ec659effa67a88aa92b3a65528f60a3c" end def install From f870faf92e2931de86d0d1fbd237eb6388939f36 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 19:14:59 +0100 Subject: [PATCH 15/19] Formula-Cookbook: update Alias creation advice --- share/doc/homebrew/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 0efc24f0ac..9df375d63c 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -300,7 +300,7 @@ When importing classes, Homebrew will require the formula and then create an ins Thus, if you change the name of the class, you must also rename the file. Filenames should be all lowercase, and class names should be the strict CamelCase equivalent, e.g. formulae `gnu-go` and `sdl_mixer` become classes `GnuGo` and `SdlMixer`, even if part of their name is an acronym. -Add aliases by creating symlinks in `Library/Aliases`. +Add aliases by creating symlinks in an `Aliases` directory in the tap root. ## Audit the formula From 49e9be1970ae7f58d9ed64ac2dad5187a3ea6d5d Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 19:18:37 +0100 Subject: [PATCH 16/19] Formula-Cookbook: note audit --new-formula for new formula --- share/doc/homebrew/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 9df375d63c..aaffea5a0d 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -306,7 +306,7 @@ Add aliases by creating symlinks in an `Aliases` directory in the tap root. You can run `brew audit --strict --online` to test formulae for adherence to Homebrew house style. The `audit` command includes warnings for trailing whitespace, preferred URLs for certain source hosts, and a lot of other style issues. Fixing these warnings before committing will make the process a lot quicker for everyone. -New formulae being submitted to Homebrew should run `brew audit --strict --online foo`. This command is performed by the Brew Test Bot on new submissions as part of the automated build and test process, and highlights more potential issues than the standard audit. +New formulae being submitted to Homebrew should run `brew audit --new-formula foo`. This command is performed by the Brew Test Bot on new submissions as part of the automated build and test process, and highlights more potential issues than the standard audit. Use `brew info` and check if the version guessed by Homebrew from the URL is correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) if not. From de283d81c5a27860f80803ffe9103c4eed177243 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 19:53:35 +0100 Subject: [PATCH 17/19] Maintainer-Guidelines: tweak guidelines --- share/doc/homebrew/Maintainer-Guidelines.md | 36 ++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/share/doc/homebrew/Maintainer-Guidelines.md b/share/doc/homebrew/Maintainer-Guidelines.md index 59f5eb9865..6ecf690db5 100644 --- a/share/doc/homebrew/Maintainer-Guidelines.md +++ b/share/doc/homebrew/Maintainer-Guidelines.md @@ -9,17 +9,17 @@ Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)? ## Quick Checklist This is all that really matters: -- Ensure the name is correct. This cannot be changed later, so it must - be right the first time! -- Add aliases -- Ensure it is not a dupe of anything that comes with OS X +- Ensure the name seems reasonable. +- Add aliases. +- Ensure it is not an unreasonable dupe of anything that comes with OS X. - Ensure it is not a library that can be installed with [gem](https://en.wikipedia.org/wiki/RubyGems), [cpan](https://en.wikipedia.org/wiki/Cpan) or [pip](https://pip.pypa.io/en/stable/). - Ensure that any dependencies are accurate and minimal. We don't need to support every possible optional feature for the software. -- Use `brew pull` when possible to add messages to auto-close pull requests (which may take ~5m, be patient) and pull bottles built by BrewTestBot. +- Use the GitHub squash & merge workflow where bottles aren't required. +- Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by BrewTestBot. - Thank people for contributing. Checking dependencies is important, because they will probably stick around @@ -27,35 +27,35 @@ forever. Nobody really checks if they are necessary or not. Use the `:optional` and `:recommended` modifiers as appropriate. Depend on as little stuff as possible. Disable X11 functionality by default. -For example, we build Wireshark, but not the monolithic GUI. If users want -that, they should just grab the DMG that Wireshark themselves provide. +For example, we build Wireshark, but not the heavy GTK/Qt GUI by default. Homebrew is about Unix software. Stuff that builds to an `.app` should probably be in Homebrew Cask instead. ### Naming -The name is the strictest item, because we can’t change it afterwards. +The name is the strictest item, because avoiding a later name change is +desirable. Choose a name that’s the most common name for the project. -For example, we chose `objective-caml`, but we should have chosen `ocaml`. +For example, we initially chose `objective-caml` but we should have chosen `ocaml`. Choose what people say to each other when talking about the project. -Add other names as aliases as symlinks in `Library/Aliases`. Ensure the name -referenced on the homepage is one of these, as it may be different and have +Add other names as aliases as symlinks in `Aliases` in the tap root. Ensure the +name referenced on the homepage is one of these, as it may be different and have underscores and hyphens and so on. -We don’t allow versions in formula names (e.g. `bash4.rb`); these should be in -the `homebrew/versions` tap. This is sometimes frustrating, but we’re trying to -solve this properly. (`python3.rb` is a rare exception, because it’s basically -a “new” language and installs no conflicting executables.) +We mostly don’t allow versions in formula names (e.g. `bash4.rb`); these should +be in the `homebrew/versions` tap. (`python3.rb` is a rare exception, because it’s +basically a “new” language and installs no conflicting executables.) For now, if someone submits a formula like this, we’ll leave them in their own tree. ### Merging, rebasing, cherry-picking -Merging is mainly useful when new work is being done. Please use `brew pull` -(or `rebase`/`cherry-pick` contributions) rather than fill Homebrew's Git -history up with noisy merge commits. +Merging should be done in the brew repo to preserve history & GPG commit signing, +and squash/merge via GitHub should be used for formulae where those formulae +don't need bottles or the change does not require new bottles to be pulled. +Otherwise, you should use `brew pull` (or `rebase`/`cherry-pick` contributions). Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t `rebase` : **you’re a maintainer now!** From da3e98070bdba967c14543afce8785d6ba20b5d0 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 20:55:13 +0100 Subject: [PATCH 18/19] Formula-Cookbook: tweak :run explanation --- share/doc/homebrew/Formula-Cookbook.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index aaffea5a0d..56d566809e 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -143,9 +143,9 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati - `:optional` generates an implicit `with-foo` option for the formula. This means that, given `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to use the dependency. - `:run` can mean the dependency is only required at run, or it can be used - to declare build dependencies such as `pkg-config` are needed during - runtime as well, which will silence the audit warning. `:run` currently - implies `:build` as well. + to declare build dependencies such as `pkg-config` are needed at + runtime as well, which will silence the audit warning. `:run` dependencies + are currently available at build-time. - `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled by default and the user must pass `--without-foo` to disable this dependency. The default From ba20823a66685e99226ca489d93687a9db881485 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 14 Sep 2016 21:15:07 +0100 Subject: [PATCH 19/19] External-Commands: brew-cask is now part of Homebrew --- share/doc/homebrew/External-Commands.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/share/doc/homebrew/External-Commands.md b/share/doc/homebrew/External-Commands.md index 721c4a86a8..090b664cb1 100644 --- a/share/doc/homebrew/External-Commands.md +++ b/share/doc/homebrew/External-Commands.md @@ -64,17 +64,6 @@ These commands have been contributed by Homebrew users but are not included in t > $ brew tap youtux/livecheck > ``` -### brew-cask - ->Install .app and other "Drag to install" packages from Homebrew. -> -> https://github.com/caskroom/homebrew-cask -> -> Install using: -> ``` - $ brew tap caskroom/cask -> ``` - ### brew-gem >Install any gem package into a self-contained Homebrew cellar location: >