forked from Homebrew/brew
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
51 changed files
with
3,023 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| # Acceptable Formulae | ||
| Some formulae should not go in | ||
| [Homebrew/homebrew](https://github.com/Homebrew/homebrew). But there are | ||
| additional [Interesting Taps & Branches](Interesting-Taps-&-Branches.md) and anyone can start his/her | ||
| own! | ||
|
|
||
| ### We try hard to avoid dupes in Homebrew/homebrew | ||
| Stuff that comes with OS X or is a library that is provided by | ||
| [RubyGems, CPAN or PyPi](http://github.com/Homebrew/homebrew/wiki/Gems,-Eggs-and-Perl-Modules) | ||
| should not be duplicated. There are good reasons for this: | ||
|
|
||
| * Duplicate libraries regularly break builds | ||
| * Subtle bugs emerge with duplicate libraries, and to a lesser extent, | ||
| duplicate tools | ||
| * We want our formulae to work with what comes with OS X | ||
|
|
||
| There are exceptions: | ||
|
|
||
| * Programs that a user will regularly interact with directly, like editors and | ||
| language runtimes | ||
| * Libraries that provide functionality or contain security updates not found in | ||
| the system version | ||
| * Things that are **designed to be installed in parallel to earlier versions of | ||
| themselves** | ||
|
|
||
| #### Examples | ||
|
|
||
| Formula | Reason | ||
| --- | --- | ||
| ruby, python | People want newer versions | ||
| bash | OS X's bash is stuck at 3.2 because newer versions are licensed under GPLv3 | ||
| zsh | This was a mistake, but it’s too late to remove it | ||
| emacs, vim | [Too popular to move to dupes](https://github.com/Homebrew/homebrew/pull/21594#issuecomment-21968819) | ||
| subversion | Originally added for 10.5, but people want the latest version | ||
| libcurl | Some formulae require a newer version than OS X provides | ||
| openssl | OS X's openssl is deprecated | ||
| libxml2 | Historically, OS X's libxml2 has been buggy | ||
|
|
||
| We also maintain [a tap](https://github.com/Homebrew/homebrew-dueps) that | ||
| contains many duplicates not otherwise found in Homebrew. | ||
|
|
||
| ### We don’t like tools that upgrade themselves | ||
| Software that can upgrade itself does not integrate well with Homebrew's own | ||
| upgrade functionality. | ||
|
|
||
| ### We don’t like install-scripts that download things | ||
| Because that circumvents our hash-checks, makes finding/fixing bugs | ||
| harder, often breaks patches and disables the caching. Almost always you | ||
| can add a resource to the formula file to handle the | ||
| separate download and then the installer script will not attempt to load | ||
| that stuff on demand. Or there is a command line switch where you can | ||
| point it to the downloaded archive in order to avoid loading. | ||
|
|
||
| ### We don’t like binary formulae | ||
| Our policy is that formulae in the core repository | ||
| ([Homebrew/homebrew](https://github.com/Homebrew/homebrew)) must be built | ||
| from source. Binary-only formulae should go to | ||
| [Homebrew/homebrew-binary](https://github.com/Homebrew/homebrew-binary). | ||
|
|
||
| ### Stable versions | ||
| Formulae in the core repository should have a stable version tagged by | ||
| the upstream project. Tarballs are preferred to git checkouts, and | ||
| tarballs should include the version in the filename whenever possible. | ||
|
|
||
| Software that does not provide a stable, tagged version, or had guidance to | ||
| always install the most recent version, should be put in | ||
| [Homebrew/homebrew-headonly](https://github.com/Homebrew/homebrew-headonly). | ||
|
|
||
| ### Bindings | ||
| First check that there is not already a binding available via | ||
| [`gem`](http://rubygems.org/) or [`pip`](http://www.pip-installer.org/) | ||
| etc.. | ||
|
|
||
| If not, then put bindings in the formula they bind to. This is more | ||
| useful to people. Just install the stuff! Having to faff around with | ||
| foo-ruby foo-perl etc. sucks. | ||
|
|
||
| ### Niche (or self-submitted) Stuff<a name="Niche_Stuff"></a> | ||
| The software in question must be | ||
| * maintained | ||
| * known | ||
| * stable | ||
| * used | ||
| * have a homepage | ||
|
|
||
| We will reject formulae that seem too obscure, partly because they won’t | ||
| get maintained and partly because we have to draw the line somewhere. | ||
|
|
||
| We frown on authors submitting their own work unless it is very popular. | ||
|
|
||
| Don’t forget Homebrew is all git underneath! Maintain your own fork or | ||
| tap if you have to! | ||
|
|
||
| ### Stuff that builds a .app | ||
| Don’t make your formula build an `.app` (native OS X Application), we | ||
| don’t want those things in Homebrew. Make it build a command line tool | ||
| or a library. However, we have a few exceptions to that, e.g. when the | ||
| App is just additional to CLI or if the GUI-application is non-native | ||
| for OS X and/or hard to get in binary elsewhere (example: font forge). | ||
| Check out the [homebrew-cask](https://github.com/phinze/homebrew-cask) | ||
| project if you’d like to brew native OS X Applications. | ||
|
|
||
| ### Building under “superenv” is best | ||
| The “superenv” is code Homebrew uses to try to minimize finding | ||
| undeclared dependencies accidentally. Some formulae will only work under | ||
| the original “standard env” which is selected in a formula by adding | ||
| `env :std`. The preference for new formulae is that they be made to | ||
| work under superenv (which is the default) whenever possible. | ||
|
|
||
| ### Sometimes there are exceptions | ||
| Even if all criteria are met we may not accept the formula. | ||
| Documentation tends to lag behind current decision-making. Although some | ||
| rejections may seem arbitrary or strange they are based from years of | ||
| experience making Homebrew work acceptably for our users. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # Bottles | ||
| Bottles are Homebrew's binary packages. They are produced by installing a formula with `brew install --build-bottle $FORMULA` and then bottling it with `brew bottle $FORMULA`. This outputs the bottle DSL which should be inserted into the formula file. | ||
|
|
||
| ## Bottle Usage | ||
| If a bottle is available and usable it will be downloaded and poured automatically when you `brew install <formula>`. If you wish to disable this you can do it by specifying `--build-from-source` or set `export HOMEBREW_BUILD_FROM_SOURCE=1` environment variable. | ||
|
|
||
| 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`. | ||
|
|
||
| ### Local Bottle Usage | ||
| Bottles can also be cached locally and installed by path e.g. `brew install /Library/Caches/Homebrew/qt-4.8.4.mountain_lion.bottle.1.tar.gz`. | ||
|
|
||
| ## Bottle Creation | ||
| Bottles are currently created using the [Brew Test Bot](Brew-Test-Bot.md). We will be slowly adding them to all formulae. | ||
|
|
||
| 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=penyrn`. 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! | ||
|
|
||
| ## Bottle Format | ||
| Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. MacOS version, revision). | ||
|
|
||
| ## Bottle DSL (Domain Specific Language) | ||
| Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block. | ||
|
|
||
| A simple (and typical) example: | ||
| ```ruby | ||
| bottle do | ||
| sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion | ||
| sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion | ||
| sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard | ||
| end | ||
| ``` | ||
|
|
||
| A full example: | ||
| ```ruby | ||
| bottle do | ||
| root_url 'http://mikemcquaid.com' | ||
| prefix '/opt/homebrew' | ||
| cellar '/opt/homebrew/Cellar' | ||
| revision 4 | ||
| sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion | ||
| sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion | ||
| sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard | ||
| sha1 '583dc9d98604c56983e17d66cfca2076fc56312b' => :snow_leopard_32 | ||
| sha1 '2ef5f57afae319a3e7618d5723059eae568276fa' => :leopard | ||
| end | ||
| ``` | ||
|
|
||
| ### `root_url` | ||
| Optionally contains the URL root used to calculate bottle URLs. | ||
| By default this is omitted and the Homebrew default bottle URL root is used. This may be useful for taps which wish to provide bottles for their formulae or to cater for a non-default `HOMEBREW_CELLAR`. | ||
|
|
||
| ### `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` | ||
|
|
||
| ### `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. | ||
|
|
||
| ### `revision` | ||
| Optionally contains the revision of the bottle. | ||
| Sometimes bottles may need be updated without bumping the version of the formula e.g. a new patch was applied. In that case the revision will have a value of 1 or more. | ||
|
|
||
| ### `sha1` | ||
| Contains the SHA-1 of bottle for a particular version of OS X. | ||
|
|
||
| ## Formula DSL | ||
| Additionally there is a method available in the formula DSL. | ||
|
|
||
| ### `pour_bottle?` | ||
| 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`. | ||
|
|
||
| ## Planned Improvements | ||
| Most bottle features have been (and planned improvements will be) implemented by @mikemcquaid. Contact him directly with questions. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # Brew Test Bot For Core Contributors | ||
| If a build has run and passed on `brew test-bot` then it can be used to quickly bottle formulae. | ||
|
|
||
| There are three types of Jenkins jobs: | ||
|
|
||
| ## Homebrew | ||
| This job automatically builds anything committed to the master branch. On | ||
| failure it sends an email to `brew-test-bot@googlegroups.com`. It tests rather than builds bottles. | ||
|
|
||
| ## Homebrew Pull Requests | ||
|
|
||
| This job automatically builds any pull requests submitted to Homebrew/homebrew. On | ||
| success or failure it updates the pull request status (see more details on the | ||
| [main Brew Test Bot wiki page](Brew-Test-Bot)). On a successful build it automatically uploads bottles. | ||
|
|
||
| ## Homebrew Testing | ||
|
|
||
| This job is manually triggered to run | ||
| [`brew-test-bot.rb`](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/cmd/brew-test-bot.rb) | ||
| on with user-specified parameters. On a successful build it automatically uploads bottles. | ||
|
|
||
| You can manually start this job with parameters to run [`brew-test-bot`](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have `brew-test-bot` test them, report the results and produce bottles. | ||
|
|
||
| ## Bottling | ||
| To pull and bottle a pull request with `brew pull`: | ||
|
|
||
| 1. Ensure the job has already completed successfully. | ||
| 2. Run `brew pull --bottle 12345` where `12345` is the pull request number (or URL). If it complains about a missing URL with `BrewTestBot` in it then the bottles have not finished uploading yet; wait and try again later. | ||
| 3. Run `brew fetch --force-bottle $FORMULAE` to check the SHA-1 in the bottled formulae match the uploaded files. | ||
| 4. Run `git push` to push the commits. | ||
|
|
||
| To bottle a test build or pull request without `brew pull`: | ||
|
|
||
| 1. Ensure the job has already completed successfully. | ||
| 2. For testing builds note the job number (e.g. `123`). For pull request builds note the pull request number (e.g. `45678`). | ||
| 3. Run `git fetch --tags https://github.com/BrewTestBot/homebrew.git` | ||
| 4. For testing builds run `git merge testing-123` (where `123` is the testing job number). For pull requests builds run `git merge pr-45678` (where `45678` is the pull request number). | ||
| 5. Run `git rebase origin/master` to get rid of any nasty merge commits. | ||
| 6. Run `brew fetch --force-bottle $FORMULAE` to check the SHA-1 in the bottled formulae match the uploaded files. | ||
| 7. Run `git push` to push the commits. |
Oops, something went wrong.