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. diff --git a/share/doc/homebrew/C++-Standard-Libraries.md b/share/doc/homebrew/C++-Standard-Libraries.md index f841044b99..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. +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``` 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). diff --git a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md index bbc3665cf9..1d662c1587 100644 --- a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md +++ b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md @@ -1,15 +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` -* [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. +* 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. diff --git a/share/doc/homebrew/External-Commands.md b/share/doc/homebrew/External-Commands.md index b5a21435e4..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: > @@ -83,15 +72,12 @@ 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/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 diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 4498c1e23b..56d566809e 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). @@ -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) @@ -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). @@ -122,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 ``` @@ -136,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 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 @@ -189,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 @@ -227,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 @@ -296,13 +300,13 @@ 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 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. 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!** 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.)