admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Merge pull request #962 from DomT4/docs

Browse Source 
Documentation Updates.
This commit is contained in:
Dominyk Tiller 2016-09-15 02:04:34 +01:00 committed by GitHub
commit 0992951634
8 changed files with 90 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
share/doc/homebrew/Bottles.md
View File

@ -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`. 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 ## 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! 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: A simple (and typical) example:
```ruby ```ruby
bottle do bottle do
sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :yosemite sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra
sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :mavericks sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :mountain_lion sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite
end end
``` ```
@ -33,9 +33,9 @@ bottle do
prefix "/opt/homebrew" prefix "/opt/homebrew"
cellar "/opt/homebrew/Cellar" cellar "/opt/homebrew/Cellar"
rebuild 4 rebuild 4
sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :yosemite sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra
sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :mavericks sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :mountain_lion sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite
end end
``` ```
@ -45,11 +45,11 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi
### `cellar` ### `cellar`
Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built. 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` ### `prefix`
Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. 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` ### `rebuild`
Optionally contains the rebuild version of the bottle. 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. 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`. 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 ## 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.

18
share/doc/homebrew/C++-Standard-Libraries.md
View File

@ -1,13 +1,23 @@
# C++ Standard Libraries # C++ Standard Libraries
There are two C++ standard libraries supported by Apple compilers. 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```. Example install using GCC 4.8: ```brew install DESIRED_FORMULA --cc=gcc-4.8```.
Get GCC 4.8 via: ```brew install gcc48``` Get GCC 4.8 via: ```brew install gcc48```

6
share/doc/homebrew/Common-Issues-for-Core-Contributors.md
View File

@ -10,7 +10,5 @@ This is a page for maintainers to diagnose certain build errors.
The exact atom may be different. The exact atom may be different.
This can be caused by passing the obsolete `-s` flag to the linker. 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).
See:
https://github.com/Homebrew/homebrew/commit/7c9a9334631dc84d59131ca57419e8c828b1574b

26
share/doc/homebrew/Custom-GCC-and-cross-compilers.md
View File

@ -1,15 +1,21 @@
# Custom GCC and cross compilers # 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 provides a `gcc` formula for use with Xcode 4.2+ or when needing
* [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48` C++11 support on earlier versions.
* [MSP430 development](https://github.com/Homebrew/homebrew/issues/issue/2336) * [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an
* [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. up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48`
* [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
* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V toolchain including binutils and gcc. toolchain including binutils and gcc.

18
share/doc/homebrew/External-Commands.md
View File

@ -64,17 +64,6 @@ These commands have been contributed by Homebrew users but are not included in t
> $ brew tap youtux/livecheck > $ 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 ### brew-gem
>Install any gem package into a self-contained Homebrew cellar location: <https://github.com/sportngin/brew-gem> >Install any gem package into a self-contained Homebrew cellar location: <https://github.com/sportngin/brew-gem>
> >
@ -83,15 +72,12 @@ These commands have been contributed by Homebrew users but are not included in t
### brew-growl ### brew-growl
>Get Growl notifications for Homebrew https://github.com/secondplanet/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 ### 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: > Install using:
> ``` > ```
$ brew tap gapple/services $ brew tap homebrew/services
> ``` > ```
## SEE ALSO ## SEE ALSO

32
share/doc/homebrew/Formula-Cookbook.md
View File

@ -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)) * 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) * 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. * 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). 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. 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 Homebrew’s OpenSSL is
[`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method) [`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 have environment variables set or special configuration flags passed
to locate our OpenSSL. You can see this mechanism in the to locate our OpenSSL. You can see this mechanism in the
[clamav](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/clamav.rb#L38) [clamav](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/clamav.rb#L38)
formula. Usually this is unnecessary because when OpenSSL is specified 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)
as a dependency Homebrew temporarily prepends the `$PATH` with that to favour finding `keg_only` formulae first.
prefix.
Homebrew maintains a special [tap that provides other useful system duplicates](https://github.com/Homebrew/homebrew-dupes). 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 ```ruby
class Foo < Formula class Foo < Formula
depends_on "pkg-config" => :run
depends_on "jpeg" depends_on "jpeg"
depends_on "gtk+" => :optional
depends_on "readline" => :recommended
depends_on "boost" => "with-icu" depends_on "boost" => "with-icu"
depends_on "readline" => :recommended
depends_on "gtk+" => :optional
depends_on :x11 => :optional depends_on :x11 => :optional
end 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 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 - `:build` means that dependency is a build-time only dependency so it can
be skipped when installing from a bottle or when listing missing be skipped when installing from a bottle or when listing missing
dependencies using `brew missing`. dependencies using `brew missing`.
- `:optional` generates an implicit `with-foo` option for the formula. - `: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. 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 - `:recommended` generates an implicit `without-foo` option, meaning that
the dependency is enabled by default and the user must pass the dependency is enabled by default and the user must pass
`--without-foo` to disable this dependency. The default `--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. 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 ## Version Scheme Changes
@ -227,8 +231,8 @@ If you're installing an application then please use [`resource`](http://www.ruby
```ruby ```ruby
class Foo < Formula class Foo < Formula
resource "pycrypto" do resource "pycrypto" do
url "https://pypi.python.org/packages/source/p/pycrypto/pycrypto-2.6.tar.gz" url "https://files.pythonhosted.org/packages/60/db/645aa9af249f059cc3a368b118de33889219e0362141e75d4eaf6f80f163/pycrypto-2.6.1.tar.gz"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" sha256 "f2ce1e989b272cfcb677616763e0a2e7ec659effa67a88aa92b3a65528f60a3c"
end end
def install 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. 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 ## 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. 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 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. correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) if not.

36
share/doc/homebrew/Maintainer-Guidelines.md
View File

@ -9,17 +9,17 @@ Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)?
## Quick Checklist ## Quick Checklist
This is all that really matters: This is all that really matters:
- Ensure the name is correct. This cannot be changed later, so it must - Ensure the name seems reasonable.
be right the first time! - Add aliases.
- Add aliases - Ensure it is not an unreasonable dupe of anything that comes with OS X.
- Ensure it is not a dupe of anything that comes with OS X
- Ensure it is not a library that can be installed with - Ensure it is not a library that can be installed with
[gem](https://en.wikipedia.org/wiki/RubyGems), [gem](https://en.wikipedia.org/wiki/RubyGems),
[cpan](https://en.wikipedia.org/wiki/Cpan) or [cpan](https://en.wikipedia.org/wiki/Cpan) or
[pip](https://pip.pypa.io/en/stable/). [pip](https://pip.pypa.io/en/stable/).
- Ensure that any dependencies are accurate and minimal. We don't need to - Ensure that any dependencies are accurate and minimal. We don't need to
support every possible optional feature for the software. 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. - Thank people for contributing.
Checking dependencies is important, because they will probably stick around 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. `:optional` and `:recommended` modifiers as appropriate.
Depend on as little stuff as possible. Disable X11 functionality by default. 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 For example, we build Wireshark, but not the heavy GTK/Qt GUI by default.
that, they should just grab the DMG that Wireshark themselves provide.
Homebrew is about Unix software. Stuff that builds to an `.app` should Homebrew is about Unix software. Stuff that builds to an `.app` should
probably be in Homebrew Cask instead. probably be in Homebrew Cask instead.
### Naming ### 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. 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. 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 Add other names as aliases as symlinks in `Aliases` in the tap root. Ensure the
referenced on the homepage is one of these, as it may be different and have name referenced on the homepage is one of these, as it may be different and have
underscores and hyphens and so on. underscores and hyphens and so on.
We don’t allow versions in formula names (e.g. `bash4.rb`); these should be in We mostly don’t allow versions in formula names (e.g. `bash4.rb`); these should
the `homebrew/versions` tap. This is sometimes frustrating, but we’re trying to be in the `homebrew/versions` tap. (`python3.rb` is a rare exception, because it’s
solve this properly. (`python3.rb` is a rare exception, because it’s basically basically a “new” language and installs no conflicting executables.)
a “new” language and installs no conflicting executables.)
For now, if someone submits a formula like this, we’ll leave them in For now, if someone submits a formula like this, we’ll leave them in
their own tree. their own tree.
### Merging, rebasing, cherry-picking ### Merging, rebasing, cherry-picking
Merging is mainly useful when new work is being done. Please use `brew pull` Merging should be done in the brew repo to preserve history & GPG commit signing,
(or `rebase`/`cherry-pick` contributions) rather than fill Homebrew's Git and squash/merge via GitHub should be used for formulae where those formulae
history up with noisy merge commits. 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 Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t
`rebase` : **you’re a maintainer now!** `rebase` : **you’re a maintainer now!**

3
share/doc/homebrew/brew-tap.md
View File

@ -29,7 +29,8 @@ edavis/emacs
fine. fine.
* Add `--full` to either the one- or two-argument invocations above, and git * 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 * `brew tap --repair` migrates tapped formulae from symlink-based to
directory-based structure. (This should only need to be run once.) directory-based structure. (This should only need to be run once.)