From cc09bb14c16c8e4f6b360f30074522c2ee25167b Mon Sep 17 00:00:00 2001 From: Tom Schoonjans Date: Mon, 19 Dec 2016 21:51:57 +0100 Subject: brew create: add meson support meson is quickly gaining popularity as build system, in combination with ninja. Several Gnome projects for example are currently transitioning from autotools to meson, mostly because it allows for Visual Studio builds, which is impossible to accomplish with autotools. In order to facilitate generating meson based Formulas, I added support for meson to brew-create. --- docs/brew.1.html | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/brew.1.html b/docs/brew.1.html index 7b7251faf..8a24e499b 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -504,7 +504,7 @@ message.

url-and-sha256 style specification into a tag-and-revision style specification, nor vice versa. It must use whichever style specification the preexisting formula already uses.

-
create URL [--autotools|--cmake] [--no-fetch] [--set-name name] [--set-version version] [--tap user/repo]

Generate a formula for the downloadable file at URL and open it in the editor. +

create URL [--autotools|--cmake|--meson] [--no-fetch] [--set-name name] [--set-version version] [--tap user/repo]

Generate a formula for the downloadable file at URL and open it in the editor. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you'll have to make your own template. The wget formula serves as a simple example. For the complete API have a look at

@@ -512,7 +512,8 @@ formula serves as a simple example. For the complete API have a look at

http://www.rubydoc.info/github/Homebrew/brew/master/Formula

If --autotools is passed, create a basic template for an Autotools-style build. -If --cmake is passed, create a basic template for a CMake-style build.

+If --cmake is passed, create a basic template for a CMake-style build. +If --meson is passed, create a basic template for a Meson-style build.

If --no-fetch is passed, Homebrew will not download URL to the cache and will thus not add the SHA256 to the formula for you.

-- cgit v1.2.3 From 4c379dffb740478f7dba3df078435dc8f64b8a14 Mon Sep 17 00:00:00 2001 From: Andrew McKinlay Date: Tue, 27 Dec 2016 16:35:40 -0500 Subject: Correct location of taps (doc) --- docs/Interesting-Taps-&-Forks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md index d23277b15..d42a97f54 100644 --- a/docs/Interesting-Taps-&-Forks.md +++ b/docs/Interesting-Taps-&-Forks.md @@ -60,4 +60,4 @@ You can be added as a maintainer for one of the Homebrew organization taps and a ## Technical Details -Your taps are git repositories located at `$(brew --prefix)/Library/Taps`. +Your taps are git repositories located at `$(brew --repository)/Library/Taps`. -- cgit v1.2.3 From 79f9896d2ffd03819236318c9f0742d40f1826ac Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Mon, 2 Jan 2017 16:05:14 +0000 Subject: bottles: --force-bottle feigns or_later. When reproducing issues with software that hasn’t been bottled yet on your version of macOS it can sometimes be helpful to use `or_later` bottle functionality i.e. just use the bottle for the latest version of macOS available. This maps well to the existing `--force-bottle` argument so it will now act as if the latest bottle has a `or_later` ending. --- docs/brew.1.html | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/brew.1.html b/docs/brew.1.html index 8a24e499b..d69c141bb 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -127,8 +127,9 @@ checksum of a previously cached version no longer matches.

If --build-from-source is passed, download the source rather than a bottle.

-

If --force-bottle is passed, download a bottle if it exists for the current -version of macOS, even if it would not be used during installation.

+

If --force-bottle is passed, download a bottle if it exists for the +current or newest version of macOS, even if it would not be used during +installation.

gist-logs [--new-issue|-n] formula

Upload logs for a failed build of formula to a new Gist.

formula is usually the name of the formula to install, but it can be specified @@ -185,6 +186,10 @@ from bottles if they are available.

passed, then both formula and the dependencies installed as part of this process are built from source even if bottles are available.

+

If --force-bottle is passed, install from a bottle if it exists for the +current or newest version of macOS, even if it would not normally be used +for installation.

+

If --devel is passed, and formula defines it, install the development version.

If --HEAD is passed, and formula defines it, install the HEAD version, -- cgit v1.2.3 From 91c09c5b11beb0f9ff9915b6e949f17c3973c9a5 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Mon, 2 Jan 2017 18:29:00 +0000 Subject: General documentation updates. Mostly related to the newer ways we’re handling versions and the incoming deprecation of devel-only, head-only and versions. --- docs/Acceptable-Formulae.md | 6 +----- docs/Custom-GCC-and-cross-compilers.md | 3 +-- docs/FAQ.md | 19 ++----------------- docs/Formula-Cookbook.md | 6 +++--- ...pen-a-Homebrew-Pull-Request-(and-get-it-merged).md | 3 +++ docs/Interesting-Taps-&-Forks.md | 6 ------ docs/Tips-N'-Tricks.md | 4 +--- 7 files changed, 11 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index b827403d8..ac65d0802 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -67,12 +67,8 @@ Formulae in the core repository must 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 only provides a development/beta, tagged version should be put in -[homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only). We don’t accept software without a tagged version because they regularly break -due to upstream changes; we can’t provide [bottles](Bottles.md) for them; and -we don’t have an automatic update mechanism for `head-only` formulae which -makes them very quickly outdated. +due to upstream changes and we can’t provide [bottles](Bottles.md) for them. ### Bindings First check that there is not already a binding available via diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md index 1d662c158..43b8dfc01 100644 --- a/docs/Custom-GCC-and-cross-compilers.md +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -15,7 +15,6 @@ 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` +* Homebrew provides older GCC formulae e.g. `gcc@4.8` and `gcc@6` * [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V toolchain including binutils and gcc. diff --git a/docs/FAQ.md b/docs/FAQ.md index b9cbcd225..82efbf454 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -212,23 +212,8 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created ``` ### Where was a formula deleted? -Use `brew log $FORMULA` to find out! - -Sometimes formulae are moved to specialized repositories. These are the -likely candidates: - -* [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) -* [homebrew/games](https://github.com/Homebrew/homebrew-games) -* [homebrew/versions](https://github.com/Homebrew/homebrew-versions) - -You can use `brew tap` to access these formulae: - -```bash -brew tap homebrew/games -brew install … -``` - -Note that brew search still finds formula in taps. +Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or +our analytics identified it was not widely used. ### Homebrew is a poor name, it is generic, why was it chosen? @mxcl was too concerned with the beer theme and didn’t consider that the diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 6657b9766..72afa387e 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -9,11 +9,11 @@ A formula is a package definition written in Ruby. It can be created with `brew | **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` | | **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` | | **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` | -| **Tap** | An optional Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-versions` | +| **Tap** | An Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` | | **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` | | **Cask** | An [extension of homebrew](https://github.com/caskroom/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` | | **Brew Bundle**| An [extension of homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` | - + ## An Introduction Homebrew uses Git for downloading updates and contributing to the project. @@ -33,7 +33,7 @@ Before submitting a new formula make sure your package: * isn't in another official [Homebrew tap](https://github.com/Homebrew) * 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. +* has a stable, tagged version (i.e. not just a GitHub repository with no versions). * 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/CONTRIBUTING.md). diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md index a3497abca..ef6091e2c 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md @@ -4,6 +4,9 @@ The following commands are used by Homebrew contributors to set up a fork of Hom Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on [the `homebrew/core` tap](https://github.com/Homebrew/homebrew-core) or another [official tap](https://github.com/Homebrew), based on the formula type. +## Submit a new version of an existing formula +1. Use `brew bump-formula-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more. + ## Set up your own fork of the Homebrew repository ### Core `brew` code related pull request diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md index d42a97f54..dcb860a23 100644 --- a/docs/Interesting-Taps-&-Forks.md +++ b/docs/Interesting-Taps-&-Forks.md @@ -12,16 +12,12 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst * [homebrew/completions](https://github.com/Homebrew/homebrew-completions): Shell completion formulae. -* [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only): A tap for brews that only have pre-release/development versions. - * [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes): Need GDB or a newer Tk? System duplicates go here. * [homebrew/emacs](https://github.com/Homebrew/homebrew-emacs): A tap for Emacs packages. * [homebrew/games](https://github.com/Homebrew/homebrew-games): Game or gaming-emulation related formulae. -* [homebrew/head-only](https://github.com/Homebrew/homebrew-head-only): A tap for brews that only have unstable, unreleased versions. This tap is **deprecated** and doesn’t accept new formulae. - * [homebrew/nginx](https://github.com/Homebrew/homebrew-nginx): Feature rich Nginx tap for modules. * [homebrew/php](https://github.com/Homebrew/homebrew-php): Repository for php-related formulae. @@ -32,8 +28,6 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst * [homebrew/services](https://github.com/Homebrew/homebrew-services): A tool to start Homebrew formulae's plists with `launchctl`. -* [homebrew/versions](https://github.com/Homebrew/homebrew-versions): Need e.g. older or newer versions of Postgresql? Older versions of GCC? - * [homebrew/x11](https://github.com/Homebrew/homebrew-x11): Formulae with hard X11 dependencies. `brew search` looks in these main taps as well as in [homebrew/core](https://github.com/Homebrew/homebrew-core). So don't worry about missing stuff. We will add other taps to the search as they become well maintained and popular. diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index fc532c019..e2257e534 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -3,9 +3,7 @@ ## Installing previous versions of formulae The preferred and supported method of installing specific versions of -formulae is to use the -[homebrew/versions](https://github.com/Homebrew/homebrew-versions) -tap. If the version you’re looking for isn’t available, consider [opening a +formulae is to use formula like e.g. `gcc@6`. If the version you’re looking for isn’t available, consider [opening a pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)! ### Installing directly from pull-requests -- cgit v1.2.3 From 824768e26ff34a63c0ff809b500c2f3910b982ed Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Tue, 3 Jan 2017 15:59:15 +0000 Subject: Set theme jekyll-theme-cayman --- docs/_config.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/_config.yml (limited to 'docs') diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 000000000..c4192631f --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman \ No newline at end of file -- cgit v1.2.3 From bc0aa4e64ce4eaf53476aa448b71b711feb9939e Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Tue, 3 Jan 2017 18:01:03 +0000 Subject: Add versions documentation. --- docs/Formula-Cookbook.md | 2 +- docs/Tips-N'-Tricks.md | 4 ++-- docs/Versions.md | 15 +++++++++++++++ 3 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 docs/Versions.md (limited to 'docs') diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 72afa387e..69a47b211 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -9,7 +9,7 @@ A formula is a package definition written in Ruby. It can be created with `brew | **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` | | **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` | | **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` | -| **Tap** | An Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` | +| **Tap** | A Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` | | **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` | | **Cask** | An [extension of homebrew](https://github.com/caskroom/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` | | **Brew Bundle**| An [extension of homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` | diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index e2257e534..3adf26b87 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -2,8 +2,8 @@ ## Installing previous versions of formulae -The preferred and supported method of installing specific versions of -formulae is to use formula like e.g. `gcc@6`. If the version you’re looking for isn’t available, consider [opening a +The supported method of installing specific versions of +some formulae is to see if there is a versions formula like e.g. `gcc@6` available. If the version you’re looking for isn’t available, consider [opening a pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)! ### Installing directly from pull-requests diff --git a/docs/Versions.md b/docs/Versions.md new file mode 100644 index 000000000..87bc9f566 --- /dev/null +++ b/docs/Versions.md @@ -0,0 +1,15 @@ +# Versions +Now that [Homebrew/versions](https://github.com/homebrew/homebrew-versions) has been deprecated [Homebrew/core](https://github.com/homebrew/homebrew-core) supports multiple versions of formulae with a new naming format. + +In [Homebrew/versions](https://github.com/homebrew/homebrew-versions) the formula for GCC 6 was named `gcc6.rb` and began `class Gcc6 < Formula`. In [Homebrew/core](https://github.com/homebrew/homebrew-core) this same formula is named `gcc@6.rb` and begins `class GccAT6 < Formula`. + +## Acceptable Versioned Formulae +Homebrew's versions are not intended to be used for any old versions you personally require for your project; formulae submitted should be expected to be used by a large number of people and still supported by their upstream projects. + +Versioned formulae we include must meet the following standards: + +* Versioned formulae should differ in major/minor (not patch) versions from the current stable release. This is because patch versions indicate bug or security updates and we want to ensure you apply security updates. +* Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`. +* Versioned formulae should strive to be linked at the same time as their non-versioned counterpart (without patching). If this is not possible, favour either `conflicts_with` or `keg_only` depending on whether users expect to have multiple versions installed at once or not. + +You should create your own [tap](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wishes to control the versioning of or those that do not meet the above standards. -- cgit v1.2.3 From 127e9def5084063cf33e8acb26a970556ef51148 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 4 Jan 2017 10:53:21 +0000 Subject: Cleanup documentation site GitHub now nicely generates a documentation site for us at http://brew.sh/brew based on our docs folder. Optimise the output of this and the GitHub docs directory for readability and the various user groupings. --- docs/.ruby-version | 1 + docs/Acceptable-Formulae.md | 23 ++-- docs/Analytics.md | 4 +- docs/Bottles.md | 25 +++-- docs/Brew-Test-Bot-For-Core-Contributors.md | 2 +- docs/CNAME | 1 + docs/Checksum_Deprecation.md | 3 +- docs/Custom-GCC-and-cross-compilers.md | 2 +- docs/External-Commands.md | 80 +++++--------- docs/FAQ.md | 45 ++++---- docs/Gemfile | 6 ++ docs/Homebrew-and-Python.md | 14 +-- ...-a-Homebrew-Pull-Request-(and-get-it-merged).md | 73 ------------- docs/How-To-Open-a-Homebrew-Pull-Request.md | 73 +++++++++++++ docs/Installation.md | 5 +- docs/New-Maintainer-Checklist.md | 24 ++--- docs/Python-for-Formula-Authors.md | 2 + docs/Querying-Brew.md | 2 +- docs/README.md | 71 ++++++------ docs/Tips-N'-Tricks.md | 23 +--- docs/Xcode.md | 120 ++++++++++----------- docs/_config.yml | 3 +- docs/brew-tap.md | 5 +- docs/brew.1.html | 4 +- 24 files changed, 293 insertions(+), 318 deletions(-) create mode 100644 docs/.ruby-version create mode 100644 docs/CNAME create mode 100644 docs/Gemfile delete mode 100644 docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md create mode 100644 docs/How-To-Open-a-Homebrew-Pull-Request.md (limited to 'docs') diff --git a/docs/.ruby-version b/docs/.ruby-version new file mode 100644 index 000000000..bec3a35ee --- /dev/null +++ b/docs/.ruby-version @@ -0,0 +1 @@ +system diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index ac65d0802..12084fad7 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -29,16 +29,16 @@ There are exceptions: #### Examples - Formula | Reason - --- | --- - ruby, python, perl | People want newer versions - bash | macOS'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 macOS provides - openssl | macOS's openssl is deprecated & outdated. - libxml2 | Historically, macOS's libxml2 has been buggy +| Formula | Reason | +|--------------------|-------------------------------------------------------------------------------------------------------| +| ruby, python, perl | People want newer versions | +| bash | macOS'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 macOS provides | +| openssl | macOS's openssl is deprecated & outdated. | +| libxml2 | Historically, macOS's libxml2 has been buggy | We also maintain [a tap](https://github.com/Homebrew/homebrew-dupes) that contains many duplicates not otherwise found in Homebrew. @@ -80,7 +80,8 @@ useful to people. Just install the stuff! Having to faff around with foo-ruby foo-perl etc. sucks. ### Niche (or self-submitted) Stuff -The software in question must be +The software in question must be: + * maintained (e.g. upstream is still making new releases) * known * stable (e.g. not declared "unstable" or "beta" by upstream) diff --git a/docs/Analytics.md b/docs/Analytics.md index 83386b3ee..80515d079 100644 --- a/docs/Analytics.md +++ b/docs/Analytics.md @@ -1,4 +1,4 @@ -# Homebrew's Anonymous Aggregate User Behaviour Analytics +# Anonymous Aggregate User Behaviour Analytics Homebrew has begun gathering anonymous aggregate user behaviour analytics and reporting these to Google Analytics. You will be notified the first time you run `brew update` or install Homebrew. ## Why? @@ -41,7 +41,7 @@ Homebrew's analytics are sent throughout Homebrew's execution to Google Analytic Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @mikemcquaid if you are a maintainer and need access. ## How? -The code is viewable in https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb and https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh. They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection. +The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection. ## Opting out Homebrew analytics helps us maintainers and leaving it on is appreciated. However, if you want to opt out of Homebrew's analytics, you can set this variable in your environment: diff --git a/docs/Bottles.md b/docs/Bottles.md index 196b36e1f..7d2982c14 100644 --- a/docs/Bottles.md +++ b/docs/Bottles.md @@ -1,23 +1,24 @@ -# 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. +# Bottles (binary packages) +Bottles 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 +## Usage If a bottle is available and usable it will be downloaded and poured automatically when you `brew install `. If you wish to disable this you can do it by specifying `--build-from-source`. 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 +## 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 --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! -## Bottle Format +## 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 sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra @@ -27,6 +28,7 @@ end ``` A full example: + ```ruby bottle do root_url "https://example.com" @@ -39,33 +41,34 @@ bottle do end ``` -### `root_url` +### Root URL (`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` +### 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` 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 (`prefix`) Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` prefix should be omitted. -### `rebuild` +### Rebuild version (`rebuild`) Optionally contains the rebuild version 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 rebuild will have a value of 1 or more. -### `sha256` +### Checksum (`sha256`) Contains the SHA-256 of bottle for a particular version of macOS. ## Formula DSL Additionally there is a method available in the formula DSL. -### `pour_bottle?` +### Pour Bottle (`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`. A full example: + ```ruby pour_bottle? do reason "The bottle needs the Xcode CLT to be installed." diff --git a/docs/Brew-Test-Bot-For-Core-Contributors.md b/docs/Brew-Test-Bot-For-Core-Contributors.md index 8e264ea7e..4b697066c 100644 --- a/docs/Brew-Test-Bot-For-Core-Contributors.md +++ b/docs/Brew-Test-Bot-For-Core-Contributors.md @@ -4,7 +4,7 @@ If a build has run and passed on `brew test-bot` then it can be used to quickly There are two types of Jenkins jobs you will interact with: ## [Homebrew Pull Requests](https://bot.brew.sh/job/Homebrew%20Core%20Pull%20Requests/) -This job automatically builds any pull requests submitted to Homebrew/homebrew-core. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot wiki page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles. +This job automatically builds any pull requests submitted to Homebrew/homebrew-core. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot documentation page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles. ## [Homebrew Testing](https://bot.brew.sh/job/Homebrew%20Testing/) This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/dev-cmd/test-bot.rb) with user-specified parameters. On a successful build it automatically uploads bottles. diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 000000000..01a3ad9d8 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +docs.brew.sh diff --git a/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md index 62985848b..c86f3a1a3 100644 --- a/docs/Checksum_Deprecation.md +++ b/docs/Checksum_Deprecation.md @@ -1,5 +1,4 @@ -# Checksum Deprecation - +# MD5 and SHA-1 Deprecation During early 2015 Homebrew started the process of deprecating _SHA1_ for package integrity verification. Since then every formulae under the Homebrew organisation has been moved onto _SHA256_ verification; this includes both source packages diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md index 43b8dfc01..99b52c060 100644 --- a/docs/Custom-GCC-and-cross-compilers.md +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -1,4 +1,4 @@ -# 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`. diff --git a/docs/External-Commands.md b/docs/External-Commands.md index 8fe6932b0..b88ba3fa5 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -7,78 +7,56 @@ $ brew mycommand --option1 --option3 formula without modifying Homebrew's internals. -## COMMAND TYPES +## Command Types External commands come in two flavors: Ruby commands and shell scripts. In both cases, the command file should be executable (`chmod +x`) and live somewhere in `$PATH`. -### RUBY COMMANDS +### Ruby Commands An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to. The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return 0. -### SHELL SCRIPTS +### Shell Scripts A shell script for an command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environmental variables, and passed any additional command-line arguments. - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableDescription
HOMEBREW_CACHEWhere Homebrew caches downloaded tarballs to, by default ~/Library/Caches/Homebrew.
HOMEBREW_CELLARThe location of the Homebrew Cellar, where software is staged. This will be $HOMEBREW_PREFIX/Cellar if that directory exists, or $HOMEBREW_REPOSITORY/Cellar otherwise.
HOMEBREW_LIBRARY_PATHThe directory containing Homebrew’s own application code.
HOMEBREW_PREFIXWhere Homebrew installs software. This is always the grandparent directory of the `brew` executable, /usr/local by default.
HOMEBREW_REPOSITORYIf installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives).
+| Variable | Description | +|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| HOMEBREW_CACHE | Where Homebrew caches downloaded tarballs to, by default ~/Library/Caches/Homebrew. | +| HOMEBREW_CELLAR | The location of the Homebrew Cellar, where software is staged. This will be $HOMEBREW_PREFIX/Cellar if that directory exists, or $HOMEBREW_REPOSITORY/Cellar otherwise. | +| HOMEBREW_LIBRARY_PATH | The directory containing Homebrew’s own application code. | +| HOMEBREW_PREFIX | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, /usr/local by default. | +| HOMEBREW_REPOSITORY | If installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives). | + Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else. -## USER-SUBMITTED COMMANDS +## User-submitted Commands These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above. ->*NOTE:* They are largely untested, and as always, be careful about running untested code on your machine. +Note they are largely untested, and as always, be careful about running untested code on your machine. ### brew-livecheck -> Check if there is a new upstream version of a formula. -> -> See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage. -> -> Install using: -> ``` -> $ brew tap youtux/livecheck -> ``` +Check if there is a new upstream version of a formula. +See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage. + +Install using: +```sh +brew tap youtux/livecheck +``` ### brew-gem ->Install any gem package into a self-contained Homebrew cellar location: -> ->*Note:* This can also be installed with `brew install brew-gem`. +Install any gem package into a self-contained Homebrew cellar location: [https://github.com/sportngin/brew-gem](https://github.com/sportngin/brew-gem). + +Note this can also be installed with `brew install brew-gem`. ### 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-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 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) -## SEE ALSO -Homebrew Docs: +Install using: +```sh +brew tap homebrew/services +``` diff --git a/docs/FAQ.md b/docs/FAQ.md index 82efbf454..7a32cf926 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,5 +1,6 @@ # FAQ -### How do I update my local packages? + +## How do I update my local packages? First update the formulae and Homebrew itself: brew update @@ -18,7 +19,7 @@ Or upgrade a specific formula with: -### How do I stop certain formulae from being updated? +## How do I stop certain formulae from being updated? To stop something from being updated/upgraded: brew pin $FORMULA @@ -27,7 +28,7 @@ To allow that formulae to update again: brew unpin $FORMULA -### How do I uninstall old versions of a formula? +## How do I uninstall old versions of a formula? By default, Homebrew does not uninstall old versions of a formula, so over time you will accumulate old versions. To remove them, simply use: @@ -43,7 +44,7 @@ to see what would be cleaned up: -### How do I uninstall Homebrew? +## How do I uninstall Homebrew? To uninstall Homebrew, paste the command below in a terminal prompt. ```bash @@ -54,7 +55,7 @@ and run `./uninstall --help` to view more uninstall options. -### How do I uninstall a formula? +## How do I uninstall a formula? If you do not uninstall all of the versions that Homebrew has installed, Homebrew will continue to attempt to install the newest version it knows about when you do (`brew upgrade --all`). This can be surprising. @@ -64,13 +65,13 @@ To remove a formula entirely, you may do Be careful as this is a destructive operation. -### Where does stuff get downloaded? +## Where does stuff get downloaded? brew --cache Which is usually: `~/Library/Caches/Homebrew` -### My Mac `.app`s don’t find `/usr/local/bin` utilities! +## My Mac `.app`s don’t find `/usr/local/bin` utilities! GUI apps on macOS don’t have `/usr/local/bin` in their `PATH` by default. If you’re on Mountain Lion, you can fix this by running `launchctl setenv PATH "/usr/local/bin:$PATH"`. [More details @@ -79,10 +80,10 @@ including how to set this across reboots. If you’re pre-Mountain Lion, [here’s an official alternative](https://developer.apple.com/legacy/library/qa/qa1067/_index.html). -### How do I contribute to Homebrew? +## How do I contribute to Homebrew? Read [CONTRIBUTING.md](/CONTRIBUTING.md). -### Why do you compile everything? +## Why do you compile everything? Homebrew provides pre-compiled versions for many formulae. These pre-compiled versions are referred to as **bottles** and are available at: @@ -107,7 +108,7 @@ your profile. We aim to bottle everything. -### How do I get a formula from someone else’s branch? +## How do I get a formula from someone else’s branch? brew install hub brew update @@ -122,7 +123,7 @@ Or: `brew pull https://github.com/Homebrew/homebrew-core/pull/1234` -### Why does Homebrew prefer I install to `/usr/local`? +## Why does Homebrew prefer I install to `/usr/local`? 1. **It’s easier**
`/usr/local/bin` is already in your @@ -142,7 +143,7 @@ brews then save yourself a bunch of hassle and install to It is not always straightforward to tell `gem` to look in non-standard directories for headers and libraries. If you choose `/usr/local`, many things will "just work". -### Why does Homebrew say sudo is bad? +## Why does Homebrew say sudo is bad? **tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo anyway. @@ -168,17 +169,17 @@ not. So is it that important to `chown root wget`? If you need to run Homebrew in a multi-user environment, consider creating a separate user account especially for use of Homebrew. -### Why isn’t a particular command documented? +## Why isn’t a particular command documented? If it’s not in `man brew`, it’s probably an external command. These are documented [here](External-Commands.md). -### Why haven’t you pulled my pull request? +## Why haven’t you pulled my pull request? If it’s been a while, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. Maybe we were thinking on something. It will encourage consideration. In the meantime if you could rebase the pull request so that it can be cherry-picked more easily we will love you for a long time. -### Can I edit formulae myself? +## Can I edit formulae myself? Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to *Homebrew/homebrew-core*, just edit the formula as you personally need it and `brew install`. As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications! -### Can I make new formulae? +## Can I make new formulae? Yes! It’s easy! Just `brew create URL` Homebrew will then open the formula in `$EDITOR` so you can edit it, but it probably already installs; try it: `brew install $FORMULA`. If you come up with any issues, @@ -188,7 +189,7 @@ which drops you into a debugging shell. If you want your new formula to be part of *homebrew/core* or want to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md). -### Can I install my own stuff to `/usr/local`? +## Can I install my own stuff to `/usr/local`? Yes, brew is designed to not get in your way so you can use it how you like. @@ -211,25 +212,25 @@ $ brew link foo Linking /usr/local/Cellar/foo/0.1… 17 symlinks created ``` -### Where was a formula deleted? +## Why was a formula deleted? Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or our analytics identified it was not widely used. -### Homebrew is a poor name, it is generic, why was it chosen? +## Homebrew is a poor name, it is generic, why was it chosen? @mxcl was too concerned with the beer theme and didn’t consider that the project may actually prove popular. By the time he realized it was too late. However, today, the first google hit for “homebrew” is not beer related ;-) -### What does *keg-only* mean? +## What does *keg-only* mean? It means the formula is installed only into the Cellar; it is not linked into `/usr/local`. This means most tools will not find it. We don’t do this for stupid reasons. You can still link in the formula if you need to with `brew link`. -### How can I specify different configure arguments for a formula? +## How can I specify different configure arguments for a formula? `brew edit $FORMULA` and edit the formula. Currently there is no other way to do this. -### Is there a glossary of terms around? +## Is there a glossary of terms around? All your terminology needs can be [found here](Formula-Cookbook.md#homebrew-terminology). diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 000000000..fac2f802d --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,6 @@ +source "https://rubygems.org" + +gem "github-pages", group: :jekyll_plugins + +# Nokogiri >=1.7 requires Ruby >=2.1 +gem "nokogiri", "<1.7" diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index 2500b8592..0757b5d24 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -1,6 +1,4 @@ -# Homebrew and Python -## Overview - +# Python This page describes how Python is handled in Homebrew for users. See [Python for Formula Authors](Python-for-Formula-Authors.md) for advice on writing formulae to install packages written in Python. Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS system Python. @@ -11,14 +9,12 @@ Homebrew provides formulae to brew a more up-to-date Python 2.7.x (and 3.x). ## Python 2.x or Python 3.x - Homebrew provides a formula for Python 2.7.x and one for Python 3.x. They don't conflict, so they can both be installed. The executable `python` will always point to the 2.x and `python3` to the 3.x version. ([Wondering which one to choose?](https://wiki.python.org/moin/Python2orPython3)) ## Setuptools, Pip, etc. - The Python formulae install [`pip`](http://www.pip-installer.org) and [Setuptools](https://pypi.python.org/pypi/setuptools). Setuptools can be updated via Pip, without having to re-brew Python: @@ -30,7 +26,6 @@ Similarly, Pip can be used to upgrade itself via: pip install --upgrade pip ### Note on `pip install --user` - The normal `pip install --user` is disabled for brewed Python. This is because of a bug in distutils, because Homebrew writes a `distutils.cfg` which sets the package `prefix`. A possible workaround (which puts executable scripts in `~/Library/Python/./bin`) is: @@ -38,7 +33,6 @@ A possible workaround (which puts executable scripts in `~/Library/Python/. ## `site-packages` and the `PYTHONPATH` - The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here: $(brew --prefix)/lib/pythonX.Y/site-packages @@ -53,11 +47,9 @@ Python 2.7 also searches for modules in: Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`. ### Why here? - The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the `brew --prefix`, so we don't spam your system. ## Homebrew-provided Python bindings - Some formulae provide python bindings. Sometimes a `--with-python` or `--with-python3` option has to be passed to `brew install` in order to build the python bindings. (Check with `brew options `.) Homebrew builds bindings against the first `python` (and `python-config`) in your `PATH`. (Check with `which python`). @@ -65,12 +57,10 @@ Homebrew builds bindings against the first `python` (and `python-config`) in you **Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import ` from a brewed Python if you ran `brew install ` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`). ## Policy for non-brewed Python bindings - These should be installed via `pip install `. To discover, you can use `pip search` or . (**Note:** System Python does not provide `pip`. Follow the instructions at https://pip.readthedocs.org/en/stable/installing/#install-pip to install it for your system Python if you would like it.) ## Brewed Python modules - For brewed Python, modules installed with `pip` or `python setup.py install` will be installed to `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable python scripts will be in `$(brew --prefix)/bin`. The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to: @@ -79,7 +69,6 @@ The system Python may not know which compiler flags to set in order to build bin ## Virtualenv - **WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. Activate the virtualenv *after* you've brewed, or brew in a fresh Terminal window. @@ -88,5 +77,4 @@ Homebrew will still install Python modules into Homebrew's `site-packages` and * Virtualenv has a switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv. ## Why is Homebrew's Python being installed as a dependency? - Formulae that depend on the special :python target are bottled against the Homebrew Python and require it to be installed. You can avoid installing Homebrew's Python by building these formulae with `--build-from-source`. diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md deleted file mode 100644 index ef6091e2c..000000000 --- a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md +++ /dev/null @@ -1,73 +0,0 @@ -# How To Open a Homebrew Pull Request (and get it merged) - -The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch. - -Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on [the `homebrew/core` tap](https://github.com/Homebrew/homebrew-core) or another [official tap](https://github.com/Homebrew), based on the formula type. - -## Submit a new version of an existing formula -1. Use `brew bump-formula-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more. - -## Set up your own fork of the Homebrew repository - -### Core `brew` code related pull request - -1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork). - * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. -2. Change to the directory containing your Homebrew installation with `cd $(brew --repository)`. -3. Add your pushable forked repository with `git remote add https://github.com//brew.git`. - * `` is your GitHub username, not your local machine username. - -### Formulae related pull request - -1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork). - * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. -2. Change to the directory containing Homebrew formulae with `cd $(brew --repository homebrew/core)`. -3. Add your pushable forked repository with `git remote add https://github.com//homebrew-core.git` - * `` is your GitHub username, not your local machine username. - -For formulae in central taps other than `homebrew/core`, such as `homebrew/science` or `homebrew/games`, substitute that tap's name for `homebrew/core` in each step, and alter the GitHub repository URLs as necessary. - -## Create your pull request from a new branch - -To make a new branch and submit it for review, create a GitHub pull request with the following steps: - -1. Check out the `master` branch with `git checkout master`. -2. Retrieve new changes to the `master` branch with `brew update`. -3. Create a new branch from the latest `master` branch with `git checkout -b origin/master`. -4. Make your changes. For formulae, use `brew edit` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md). - * If there's a `bottle do` block in the formula: don't remove or change it; we'll update it when we pull your PR. -5. Test your changes by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed. - 1. `brew tests` - 2. `brew install --build-from-source ` - 3. `brew test ` - 4. `brew audit --strict ` -6. Make a separate commit for each changed formula with `git add` and `git commit`. -7. Upload your new commits to the branch on your fork with `git push --set-upstream `. -8. Go to the relevant repository (e.g. https://github.com/Homebrew/brew, https://github.com/Homebrew/homebrew-core, etc.) and create a pull request to request review and merging of the commits in your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR. - * Please note that our preferred commit message format for simple version updates is "` `", e.g. "`source-highlight 3.1.8`". `devel` version updates should have the commit message suffixed with `(devel)`, e.g. "`nginx 1.9.1 (devel)`". If updating both stable and `devel`, the format should be a concatenation of these two forms, e.g. "`x264 r2699, r2705 (devel)`". -9. Await feedback or a merge from Homebrew's maintainers. We typically respond to all PRs within a couple days, but it may take up to a week, depending on the maintainers' workload. -10. Thank you! - -## Following up - -To respond well to feedback: - -1. Ask for clarification of anything you don't understand and for help with anything you don't know how to do. -2. Post a comment on your pull request if you've provided all the requested changes/information and it hasn't been merged after a week. Post a comment on your pull request if you're stuck and need help. - * A `needs response` label on a PR means that the Homebrew maintainers need you to respond to previous comments. -3. Keep discussion in the pull request unless requested otherwise (i.e. do not email maintainers privately). -4. Do not continue discussion in closed pull requests. -5. Do not argue with Homebrew maintainers. You may disagree but unless they change their mind, please implement what they request. Ultimately they control what is included in Homebrew, as they have to support any changes that are made. - -To make changes based on feedback: - -1. Check out your branch again with `git checkout `. -2. Make any requested changes and commit them with `git add` and `git commit`. -3. Squash new commits into one commit per formula with `git rebase --interactive origin/master`. -4. Push to your remote fork's branch and the pull request with `git push --force`. - -If you are working on a PR for a single formula, `git commit --amend` is a convenient way of keeping your commits squashed as you go. - -Once all feedback has been addressed and if it's a change we want to include (we include most changes), then we'll add your commit to Homebrew. Note that the PR status may show up as "Closed" instead of "Merged" because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit. - -Well done, you are now a Homebrew contributor! diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md new file mode 100644 index 000000000..ef6091e2c --- /dev/null +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -0,0 +1,73 @@ +# How To Open a Homebrew Pull Request (and get it merged) + +The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch. + +Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on [the `homebrew/core` tap](https://github.com/Homebrew/homebrew-core) or another [official tap](https://github.com/Homebrew), based on the formula type. + +## Submit a new version of an existing formula +1. Use `brew bump-formula-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more. + +## Set up your own fork of the Homebrew repository + +### Core `brew` code related pull request + +1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork). + * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. +2. Change to the directory containing your Homebrew installation with `cd $(brew --repository)`. +3. Add your pushable forked repository with `git remote add https://github.com//brew.git`. + * `` is your GitHub username, not your local machine username. + +### Formulae related pull request + +1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork). + * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. +2. Change to the directory containing Homebrew formulae with `cd $(brew --repository homebrew/core)`. +3. Add your pushable forked repository with `git remote add https://github.com//homebrew-core.git` + * `` is your GitHub username, not your local machine username. + +For formulae in central taps other than `homebrew/core`, such as `homebrew/science` or `homebrew/games`, substitute that tap's name for `homebrew/core` in each step, and alter the GitHub repository URLs as necessary. + +## Create your pull request from a new branch + +To make a new branch and submit it for review, create a GitHub pull request with the following steps: + +1. Check out the `master` branch with `git checkout master`. +2. Retrieve new changes to the `master` branch with `brew update`. +3. Create a new branch from the latest `master` branch with `git checkout -b origin/master`. +4. Make your changes. For formulae, use `brew edit` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md). + * If there's a `bottle do` block in the formula: don't remove or change it; we'll update it when we pull your PR. +5. Test your changes by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed. + 1. `brew tests` + 2. `brew install --build-from-source ` + 3. `brew test ` + 4. `brew audit --strict ` +6. Make a separate commit for each changed formula with `git add` and `git commit`. +7. Upload your new commits to the branch on your fork with `git push --set-upstream `. +8. Go to the relevant repository (e.g. https://github.com/Homebrew/brew, https://github.com/Homebrew/homebrew-core, etc.) and create a pull request to request review and merging of the commits in your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR. + * Please note that our preferred commit message format for simple version updates is "` `", e.g. "`source-highlight 3.1.8`". `devel` version updates should have the commit message suffixed with `(devel)`, e.g. "`nginx 1.9.1 (devel)`". If updating both stable and `devel`, the format should be a concatenation of these two forms, e.g. "`x264 r2699, r2705 (devel)`". +9. Await feedback or a merge from Homebrew's maintainers. We typically respond to all PRs within a couple days, but it may take up to a week, depending on the maintainers' workload. +10. Thank you! + +## Following up + +To respond well to feedback: + +1. Ask for clarification of anything you don't understand and for help with anything you don't know how to do. +2. Post a comment on your pull request if you've provided all the requested changes/information and it hasn't been merged after a week. Post a comment on your pull request if you're stuck and need help. + * A `needs response` label on a PR means that the Homebrew maintainers need you to respond to previous comments. +3. Keep discussion in the pull request unless requested otherwise (i.e. do not email maintainers privately). +4. Do not continue discussion in closed pull requests. +5. Do not argue with Homebrew maintainers. You may disagree but unless they change their mind, please implement what they request. Ultimately they control what is included in Homebrew, as they have to support any changes that are made. + +To make changes based on feedback: + +1. Check out your branch again with `git checkout `. +2. Make any requested changes and commit them with `git add` and `git commit`. +3. Squash new commits into one commit per formula with `git rebase --interactive origin/master`. +4. Push to your remote fork's branch and the pull request with `git push --force`. + +If you are working on a PR for a single formula, `git commit --amend` is a convenient way of keeping your commits squashed as you go. + +Once all feedback has been addressed and if it's a change we want to include (we include most changes), then we'll add your commit to Homebrew. Note that the PR status may show up as "Closed" instead of "Merged" because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit. + +Well done, you are now a Homebrew contributor! diff --git a/docs/Installation.md b/docs/Installation.md index 15ea71b08..ff5649a72 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -3,7 +3,7 @@ The suggested and easiest way to install Homebrew is on the [homepage](http://brew.sh). The standard script installs Homebrew to `/usr/local` so that -[you don’t need sudo](FAQ.md#why-does-homebrew-say-sudo-is-bad-) when you +[you don’t need sudo](FAQ.md) when you `brew install`. It is a careful script, it can be run even if you have stuff installed to `/usr/local` already. It tells you exactly what it will do before it does it too. And you have to confirm everything it will do before it starts. @@ -12,11 +12,12 @@ it does it too. And you have to confirm everything it will do before it starts. * An Intel CPU [1](#1) * OS X 10.10 or higher [2](#2) * Command Line Tools (CLT) for Xcode: `xcode-select --install`, - https://developer.apple.com/downloads or + [developer.apple.com/downloads](https://developer.apple.com/downloads) or [Xcode](https://itunes.apple.com/us/app/xcode/id497799835) [3](#3) * A Bourne-compatible shell for installation (e.g. bash or zsh) [4](#4) ## Alternative Installs + ### Untar anywhere Just extract (or `git clone`) Homebrew wherever you want. Just avoid: diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md index 8745f9b91..b1117ce9b 100644 --- a/docs/New-Maintainer-Checklist.md +++ b/docs/New-Maintainer-Checklist.md @@ -18,10 +18,10 @@ A few requests: non-trivial (e.g. not a test or audit improvement or version bump) changes to formulae code and don't merge them unless you get at least one approval and passing tests. -- use `brew pull` for formulae changes that require new bottles or change - multiple formulae and let it auto-close issues wherever possible (it may - take ~5m). When this isn't necessary use GitHub's "Merge pull request" - button in "create a merge commit" mode for Homebrew/brew or "squash and +- use `brew pull` for formulae changes that require new bottles or change + multiple formulae and let it auto-close issues wherever possible (it may + take ~5m). When this isn't necessary use GitHub's "Merge pull request" + button in "create a merge commit" mode for Homebrew/brew or "squash and merge" for a single formulae change. If in doubt, check with e.g. GitX that you've not accidentally added merge commits - still create your branches on your fork rather than in the main repository @@ -38,14 +38,14 @@ Thanks for all your work so far! If they accept, follow a few steps to get them set up: -- [x] Invite them to the [**@Homebrew/maintainers** team](https://github.com/orgs/Homebrew/teams/maintainers) to give them write access to all repositories (but don't make them owners yet). They will need to enable [GitHub's Two Factor Authentication](https://help.github.com/articles/about-two-factor-authentication/). -- [x] Ask them to sign in to [Bintray](https://bintray.com) using their GitHub account and they should auto-sync to [Bintray's Homebrew organisation](https://bintray.com/homebrew/organization/edit/members) as a member so they can publish new bottles -- [x] Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://bot.brew.sh/configureSecurity/) so they can adjust settings and restart jobs -- [x] Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://bot.brew.sh/configure) to enable `@BrewTestBot test this please` for them -- [x] Invite them to the [`homebrew-dev` private maintainers mailing list](https://groups.google.com/forum/#!managemembers/homebrew-dev/invite) -- [x] Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) -- [x] Invite them to the [`homebrew` private maintainers 1Password](https://homebrew.1password.com/signin) -- [x] Add them to [Homebrew's README](https://github.com/Homebrew/brew/edit/master/README.md) +- Invite them to the [**@Homebrew/maintainers** team](https://github.com/orgs/Homebrew/teams/maintainers) to give them write access to all repositories (but don't make them owners yet). They will need to enable [GitHub's Two Factor Authentication](https://help.github.com/articles/about-two-factor-authentication/). +- Ask them to sign in to [Bintray](https://bintray.com) using their GitHub account and they should auto-sync to [Bintray's Homebrew organisation](https://bintray.com/homebrew/organization/edit/members) as a member so they can publish new bottles +- Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://bot.brew.sh/configureSecurity/) so they can adjust settings and restart jobs +- Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://bot.brew.sh/configure) to enable `@BrewTestBot test this please` for them +- Invite them to the [`homebrew-dev` private maintainers mailing list](https://groups.google.com/forum/#!managemembers/homebrew-dev/invite) +- Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) +- Invite them to the [`homebrew` private maintainers 1Password](https://homebrew.1password.com/signin) +- Add them to [Homebrew's README](https://github.com/Homebrew/brew/edit/master/README.md) After a few weeks/months with no problems consider making them [owners on the Homebrew GitHub organisation](https://github.com/orgs/Homebrew/people). diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index 716a3b359..93830a6c7 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -45,6 +45,7 @@ If you submit a formula with this syntax to core, you may be asked to rewrite it ## Python declarations Applications that are compatible with Python 2 **should** use the Apple-provided system Python in /usr/bin on systems that provide Python 2.7. To do this, declare: + ```ruby depends_on :python if MacOS.version <= :snow_leopard ``` @@ -159,6 +160,7 @@ Bindings should follow the same advice for Python module dependencies as librari ## Installing bindings If the bindings are installed by invoking a `setup.py`, do something like: + ```ruby cd "source/python" do system "python", *Language::Python.setup_install_args(prefix) diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index 84a2ba4eb..70fe6bb06 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -1,4 +1,4 @@ -# Querying Brew +# Querying `brew` _In this document we will be using [jq](https://stedolan.github.io/jq/) to parse JSON, available from Homebrew using `brew install jq`._ ## Overview diff --git a/docs/README.md b/docs/README.md index ac9dbcd79..0e3e0f0fd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,34 +1,43 @@ -# README -Homebrew installs the stuff you need that Apple didn’t. +# Documentation -- [Install Homebrew](Installation.md) +## Users +- [Troubleshooting](Troubleshooting.md) +- [Installation](Installation.md) - [Frequently Asked Questions](FAQ.md) -- [Tips and Tricks](Tips-N'-Tricks.md) -- [Gems, Eggs and Perl Modules](Gems,-Eggs-and-Perl-Modules.md) -- [Homebrew and Python](Homebrew-and-Python.md) - -Please note: Homebrew generally works well, but when it doesn’t we’d hope you -report the bug. - -## Troubleshooting -First, please run `brew update` (twice) and `brew doctor`. - -Second, please read the [Troubleshooting Checklist](Troubleshooting.md). - -**If you don’t follow these steps it will take us far longer to help you with -your problem.** +- [Common Issues](Common-Issues.md) -However! Fixing build issues is easier than you think: try -`brew edit $FORMULA` and see how you fare. - -## Contributing -Read [CONTRIBUTING.md](/CONTRIBUTING.md). - -### Community Forums -- [@MacHomebrew](https://twitter.com/MacHomebrew) -- [homebrew-discuss@googlegroups.com](mailto:homebrew-discuss@googlegroups.com) ([archive](https://groups.google.com/forum/#!forum/homebrew-discuss)) - subscribe by sending a mail to [homebrew-discuss+subscribe@googlegroups.com](mailto:homebrew-discuss+subscribe@googlegroups.com) -- [freenode.net\#machomebrew](irc://irc.freenode.net/#machomebrew) - -## Supporters -[A list of the awesome people who gave £5 or more to our -Kickstarter](./Kickstarter-Supporters.md). +- [Tips and Tricks](Tips-N'-Tricks.md) +- [Bottles (binary packages)](Bottles.md) +- [Taps (third-party repositories)](brew-tap.md) +- [Interesting Taps and Forks](Interesting-Taps-&-Forks.md) +- [Anonymous Aggregate User Behaviour Analytics](Analytics.md) + +- [Querying `brew`](Querying-Brew.md) +- [C++ Standard Libraries](C++-Standard-Libraries.md) +- [MD5 and SHA-1 Deprecation](Checksum_Deprecation.md) +- [Custom GCC and Cross Compilers](Custom-GCC-and-cross-compilers.md) +- [External Commands](External-Commands.md) +- [Ruby Gems, Python Eggs and Perl Modules](Gems,-Eggs-and-Perl-Modules.md) +- [Python](Homebrew-and-Python.md) +- [How To Build Software Outside Homebrew With Homebrew `keg_only` dependencies](How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md) +- [Xcode](Xcode.md) +- [Kickstarter Supporters](Kickstarter-Supporters.md) + +## Contributors +- [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md) +- [Formula Cookbook](Formula-Cookbook.md) +- [Acceptable Formulae](Acceptable-Formulae.md) +- [Node for Formula Authors](Node-for-Formula-Authors.md) +- [Python for Formula Authors](Python-for-Formula-Authors.md) +- [Migrating A Formula To A Tap](Migrating-A-Formula-To-A-Tap.md) +- [Rename A Formula](Rename-A-Formula.md) +- [How To Create (And Maintain) A Tap](How-to-Create-and-Maintain-a-Tap.md) +- [Brew Test Bot](Brew-Test-Bot.md) +- [Prose Style Guidelines](Prose-Style-Guidelines.md) + +## Maintainers +- [New Maintainer Checklist](New-Maintainer-Checklist.md) +- [Maintainers Avoiding Burnout](Maintainers-Avoiding-Burnout.md) +- [Maintainer Guidelines](Maintainer-Guidelines.md) +- [Brew Test Bot For Maintainers](Brew-Test-Bot-For-Core-Contributors.md) +- [Common Issues for Maintainers](Common-Issues-for-Core-Contributors.md) diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index 3adf26b87..3e14158d4 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -1,4 +1,4 @@ -# Tips N' Tricks +# Tips and Tricks ## Installing previous versions of formulae @@ -7,16 +7,14 @@ some formulae is to see if there is a versions formula like e.g. `gcc@6` availab pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)! ### Installing directly from pull-requests - -You can browse pull requests https://github.com/Homebrew/homebrew-core/pulls -and install through the direct link. For example Python 3.3.0 pull request https://github.com/Homebrew/homebrew/pull/15199 +You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls) +and install through the direct link. For example Python 3.3.0 pull request [Homebrew/homebrew#15199](https://github.com/Homebrew/homebrew/pull/15199) ```sh brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb ``` ## Quickly remove something from /usr/local - ```sh brew unlink $FORMULA ``` @@ -26,7 +24,6 @@ This can be useful if a package can't build against the version of something you And of course, you can simply `brew link $FORMULA` again afterwards! ## Activate a previously installed version of a formula - ```sh brew info $FORMULA brew switch $FORMULA $VERSION @@ -35,21 +32,18 @@ brew switch $FORMULA $VERSION Use `brew info $FORMULA` to check what versions are installed but not currently activated, then `brew switch $FORMULA $VERSION` to activate the desired version. This can be useful if you would like to switch between versions of a formula. ## Install into Homebrew without formulae - ```sh ./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo ``` ## Pre-downloading a file for a formula - Sometimes it's faster to download a file via means other than those strategies that are available as part of Homebrew. For example, Erlang provides a torrent that'll let you download at 4–5× the normal HTTP method. Download the file and drop it in `~/Library/Caches/Homebrew`, but -watch the file name. Homebrew downloads files as {{ formula -name }}-{{ version }}. In the case of Erlang, this requires +watch the file name. Homebrew downloads files as ${FORMULA_NAME}-${VERSION}. In the case of Erlang, this requires renaming the file from otp_src_R13B03 to erlang-R13B03. @@ -60,7 +54,6 @@ run `mv the_tarball $(brew --cache -s $FORMULA)`. You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA256 value. This can be useful for updating formulae to new versions. ## Using Homebrew behind a proxy - Behind the scenes, Homebrew uses several commands for downloading files (e.g. curl, git, svn). Many of these tools can download via a proxy. It's a common (though not universal) convention for these command-line tools to observe getting the proxy parameters from environment variables (e.g. `http_proxy`). Unfortunately, most tools are inconsistent in their use of these environment parameters (e.g. curl supports `http_proxy`, `HTTPS_PROXY`, `FTP_PROXY`, `GOPHER_PROXY`, `ALL_PROXY`, `NO_PROXY`). Luckily, for the majority of cases setting `http_proxy` is enough. @@ -72,13 +65,11 @@ http_proxy=http://: brew install $FORMULA ``` ### Proxy Authentication - ```sh http_proxy=http://:@: brew install $FORMULA ``` ## Installing stuff without the Xcode-CLT - ```sh $ brew sh # or: eval $(brew --env) $ gem install ronn # or c-programs @@ -87,13 +78,11 @@ $ gem install ronn # or c-programs This imports the brew environment into your existing shell, gem will pick up the environment variables and be able to build. As a bonus brew's automatically determined optimization flags are set. ## Install only a formula's dependencies (not the formula) - ```sh brew install --only-dependencies $FORMULA ``` ## Interactive Homebrew Shell - ```sh $ brew irb 1.8.7 :001 > Formula.factory("ace").methods - Object.methods @@ -102,7 +91,6 @@ $ brew irb ``` ## Hiding the beer mug emoji when finishing a build - ```sh export HOMEBREW_NO_EMOJI=1 ``` @@ -125,12 +113,10 @@ In Sublime Text 2/3, you can use Package Control to install which adds highlighting for inline patches. ### Vim - [brew.vim](https://github.com/xu-cheng/brew.vim) adds highlighting to inline patches in Vim. ### Emacs - [homebrew-mode](https://github.com/dunn/homebrew-mode) provides syntax highlighting for inline patches as well as a number of helper functions for editing formula files. @@ -139,7 +125,6 @@ for editing formula files. for emacs shell-mode and eshell-mode. ### Atom - [language-homebrew-formula](https://atom.io/packages/language-homebrew-formula) adds highlighting and diff support (with the [language-diff](https://atom.io/packages/language-diff) plugin). diff --git a/docs/Xcode.md b/docs/Xcode.md index 7697a9c55..025cee9d7 100644 --- a/docs/Xcode.md +++ b/docs/Xcode.md @@ -1,71 +1,71 @@ # Xcode + ## Supported Xcode Versions Homebrew supports and recommends the latest Xcode and/or Command Line Tools available for your platform: - macOS | Xcode | Command Line Tools - ----- | ----- | ---------------------------- - 10.6 | 3.2.6 | N/A - 10.7 | 4.6.3 | April 2013 - 10.8 | 5.1.1 | April 2014 - 10.9 | 6.2 | 6.2 - 10.10 | 7.2.1 | 7.2 - 10.11 | 8.0 | 7.3 - 10.12 | 8.0 | 8.0 - +| macOS | Xcode | Command Line Tools | +|-------|-------|--------------------| +| 10.6 | 3.2.6 | N/A | +| 10.7 | 4.6.3 | April 2013 | +| 10.8 | 5.1.1 | April 2014 | +| 10.9 | 6.2 | 6.2 | +| 10.10 | 7.2.1 | 7.2 | +| 10.11 | 8.0 | 7.3 | +| 10.12 | 8.0 | 8.0 | ## Compiler Version Database - Xcode | GCC 4.0 | GCC 4.2 | LLVM-GCC 4.2 | LLVM | Clang | LLVM (SVN) - --------- | ----------- | ----------- | ---------------- | ----------- | --------------- | ---------- - 2.5.0 | 5370 | — | — | — | — | — - 3.1.4 | 5493 | 5577 | 5555 | 2064.3 | — | — - 3.2.0 | 5493 | 5646 | 5646 | 2118 | — | — - 3.2.1 | 5493 | 5646 | 5646 | 2206 | — | — - 3.2.2 | 5493 | 5659 | 5646 | 2207.5 | 1.0.2 | — - 3.2.3 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — - 3.2.4 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — - 3.2.5 | 5494 | 5664 | 5658 | 2333.4 | 1.6 (70) | — - 3.2.6 | 5494 | 5666 | 5658 | 2335.6 | 1.7 (77) | 2.9 - 4.0.0 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 - 4.0.2 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 - 4.1.0 | — | 5666 | 5658 | 2335.15.00 | 2.1 (163.7.1) | 3.0 - 4.2.0 | — | — | 5658 | 2336.1.00 | 3.0 (211.10.1) | 3.0 - 4.3.0 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.45) | 3.1 - 4.3.1 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.54) | 3.1 - 4.3.2 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.58) | 3.1 - 4.3.3 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.61) | 3.1 - 4.4.0 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.57) | 3.1 - 4.4.1 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.60) | 3.1 - 4.5.0 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.65) | 3.1 - 4.5.1 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 - 4.5.2 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 - 4.6.0 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.24) | 3.2 - 4.6.1 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.27) | 3.2 - 4.6.2 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 - 4.6.3 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 - 5.0.0 | — | — | — | — | 5.0 (500.2.76) | 3.3 - 5.0.1 | — | — | — | — | 5.0 (500.2.78) | 3.3 - 5.0.1 | — | — | — | — | 5.0 (500.2.79) | 3.3 - 5.1 | — | — | — | — | 5.1 (503.0.38) | 3.4 - 5.1.1 | — | — | — | — | 5.1 (503.0.40) | 3.4 - 6.0 | — | — | — | — | 6.0 (600.0.51) | 3.5 - 6.0.1 | — | — | — | — | 6.0 (600.0.51) | 3.5 - 6.1 | — | — | — | — | 6.0 (600.0.54) | 3.5 - 6.2 | — | — | — | — | 6.0 (600.0.57) | 3.5 - 6.3 | — | — | — | — | 6.1 (602.0.49) | 3.6 - 6.3.1 | — | — | — | — | 6.1 (602.0.49) | 3.6 - 6.3.2 | — | — | — | — | 6.1 (602.0.53) | 3.6 - 6.4 | — | — | — | — | 6.1 (602.0.53) | 3.6 - 7.0 | — | — | — | — | 7.0 (700.0.72) | - - 7.0.1 | — | — | — | — | 7.0 (700.0.72) | - - 7.1 | — | — | — | — | 7.0 (700.1.76) | - - 7.1.1 | — | — | — | — | 7.0 (700.1.76) | - - 7.2 | — | — | — | — | 7.0 (700.1.81) | - - 7.2.1 | — | — | — | — | 7.0 (700.1.81) | - - 7.3 | — | — | — | — | 7.3 (703.0.29) | - - 7.3.1 | — | — | — | — | 7.3 (703.0.31) | - - 8.0 | — | — | — | — | 8.0 (800.0.38) | - + | Xcode | GCC 4.0 | GCC 4.2 | LLVM-GCC 4.2 | LLVM | Clang | LLVM (SVN) | + |-------|---------|---------|--------------|------------|-----------------|------------| + | 2.5.0 | 5370 | — | — | — | — | — | + | 3.1.4 | 5493 | 5577 | 5555 | 2064.3 | — | — | + | 3.2.0 | 5493 | 5646 | 5646 | 2118 | — | — | + | 3.2.1 | 5493 | 5646 | 5646 | 2206 | — | — | + | 3.2.2 | 5493 | 5659 | 5646 | 2207.5 | 1.0.2 | — | + | 3.2.3 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | + | 3.2.4 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | + | 3.2.5 | 5494 | 5664 | 5658 | 2333.4 | 1.6 (70) | — | + | 3.2.6 | 5494 | 5666 | 5658 | 2335.6 | 1.7 (77) | 2.9 | + | 4.0.0 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | + | 4.0.2 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | + | 4.1.0 | — | 5666 | 5658 | 2335.15.00 | 2.1 (163.7.1) | 3.0 | + | 4.2.0 | — | — | 5658 | 2336.1.00 | 3.0 (211.10.1) | 3.0 | + | 4.3.0 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.45) | 3.1 | + | 4.3.1 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.54) | 3.1 | + | 4.3.2 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.58) | 3.1 | + | 4.3.3 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.61) | 3.1 | + | 4.4.0 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.57) | 3.1 | + | 4.4.1 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.60) | 3.1 | + | 4.5.0 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.65) | 3.1 | + | 4.5.1 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | + | 4.5.2 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | + | 4.6.0 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.24) | 3.2 | + | 4.6.1 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.27) | 3.2 | + | 4.6.2 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | + | 4.6.3 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | + | 5.0.0 | — | — | — | — | 5.0 (500.2.76) | 3.3 | + | 5.0.1 | — | — | — | — | 5.0 (500.2.78) | 3.3 | + | 5.0.1 | — | — | — | — | 5.0 (500.2.79) | 3.3 | + | 5.1 | — | — | — | — | 5.1 (503.0.38) | 3.4 | + | 5.1.1 | — | — | — | — | 5.1 (503.0.40) | 3.4 | + | 6.0 | — | — | — | — | 6.0 (600.0.51) | 3.5 | + | 6.0.1 | — | — | — | — | 6.0 (600.0.51) | 3.5 | + | 6.1 | — | — | — | — | 6.0 (600.0.54) | 3.5 | + | 6.2 | — | — | — | — | 6.0 (600.0.57) | 3.5 | + | 6.3 | — | — | — | — | 6.1 (602.0.49) | 3.6 | + | 6.3.1 | — | — | — | — | 6.1 (602.0.49) | 3.6 | + | 6.3.2 | — | — | — | — | 6.1 (602.0.53) | 3.6 | + | 6.4 | — | — | — | — | 6.1 (602.0.53) | 3.6 | + | 7.0 | — | — | — | — | 7.0 (700.0.72) | - | + | 7.0.1 | — | — | — | — | 7.0 (700.0.72) | - | + | 7.1 | — | — | — | — | 7.0 (700.1.76) | - | + | 7.1.1 | — | — | — | — | 7.0 (700.1.76) | - | + | 7.2 | — | — | — | — | 7.0 (700.1.81) | - | + | 7.2.1 | — | — | — | — | 7.0 (700.1.81) | - | + | 7.3 | — | — | — | — | 7.3 (703.0.29) | - | + | 7.3.1 | — | — | — | — | 7.3 (703.0.31) | - | + | 8.0 | — | — | — | — | 8.0 (800.0.38) | - | ## References to Xcode and compiler versions in code When a new Xcode release is made, the following things need to be diff --git a/docs/_config.yml b/docs/_config.yml index c4192631f..687739b4a 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1,2 @@ -theme: jekyll-theme-cayman \ No newline at end of file +theme: jekyll-theme-cayman +exclude: [bin, vendor, CNAME, Gemfile, Gemfile.lock] diff --git a/docs/brew-tap.md b/docs/brew-tap.md index 624a83f33..f73f1813e 100644 --- a/docs/brew-tap.md +++ b/docs/brew-tap.md @@ -1,10 +1,9 @@ -# brew tap - +# Taps (third-party repositories) `brew tap` adds more repos to the list of formulae that `brew` tracks, updates, and installs from. By default, `tap` assumes that the repos come from GitHub, but the command isn't limited to any one location. -## The command +## The command (`brew tap`) * `brew tap` without arguments lists the currently tapped repositories. For example: diff --git a/docs/brew.1.html b/docs/brew.1.html index d69c141bb..e3a44ec87 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -780,9 +780,9 @@ your shell profile, or you can use it before a brew command:

Homebrew's lead maintainer is Mike McQuaid.

-

Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Tomasz Pajor, Josh Hagins, Baptiste Fontaine, Markus Reiter, ilovezfs, Martin Afanasjew, Tom Schoonjans, Uladzislau Shablinski, Tim Smith and Alex Dunn.

+

Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Tomasz Pajor, Josh Hagins, Baptiste Fontaine, Markus Reiter, ilovezfs, Tom Schoonjans, Uladzislau Shablinski, Tim Smith and Alex Dunn.

-

Former maintainers with significant contributions include Dominyk Tiller, Brett Koonce, Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.

+

Former maintainers with significant contributions include Martin Afanasjew, Dominyk Tiller, Brett Koonce, Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.

BUGS

-- cgit v1.2.3 From a3bffe70bcf33e6051140b1a93c9f48714605af6 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 4 Jan 2017 11:13:41 +0000 Subject: Use docs.brew.sh links. --- docs/Formula-Cookbook.md | 2 +- docs/Tips-N'-Tricks.md | 3 +-- docs/brew.1.html | 10 +++++----- 3 files changed, 7 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 69a47b211..6304d7b0e 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -352,7 +352,7 @@ If you have already forked Homebrew on GitHub, then you can manually push (just git push https://github.com/myname/homebrew-core/ ``` -Now, please [open a pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes. +Now, please [open a pull request](http://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request.html) for your changes. * One formula per commit; one commit per formula * Keep merge commits out of the pull request diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index 3e14158d4..8f67c9ca8 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -3,8 +3,7 @@ ## Installing previous versions of formulae The supported method of installing specific versions of -some formulae is to see if there is a versions formula like e.g. `gcc@6` available. If the version you’re looking for isn’t available, consider [opening a -pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)! +some formulae is to see if there is a versions formula like e.g. `gcc@6` available. If the version you’re looking for isn’t available, consider [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md)! ### Installing directly from pull-requests You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls) diff --git a/docs/brew.1.html b/docs/brew.1.html index e3a44ec87..8c81b1ddb 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -36,7 +36,7 @@ If no search term is given, all locally available formulae are listed.

analytics [state]

Display anonymous user behaviour analytics state. -Read more at https://git.io/brew-analytics.

+Read more at http://docs.brew.sh/Analytics.html.

analytics (on|off)

Turn on/off Homebrew's analytics.

analytics regenerate-uuid

Regenerate UUID used in Homebrew's analytics.

cat formula

Display the source to formula.

@@ -152,7 +152,7 @@ for version is v1.

information on all installed formulae.

See the docs for examples of using the JSON: -https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md

+http://docs.brew.sh/Querying-Brew.html

install [--debug] [--env=std|super] [--ignore-dependencies] [--only-dependencies] [--cc=compiler] [--build-from-source] [--devel|--HEAD] [--keep-tmp] formula

Install formula.

formula is usually the name of the formula to install, but it can be specified @@ -352,7 +352,7 @@ for version is v1.

Pass --installed to get information on installed taps.

See the docs for examples of using the JSON: -https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md

+http://docs.brew.sh/Querying-Brew.html

tap-pin tap

Pin tap, prioritizing its formulae over core when formula names are supplied by the user. See also tap-unpin.

tap-unpin tap

Unpin tap so its formulae are no longer prioritized. See also tap-pin.

@@ -641,7 +641,7 @@ scripts that reside somewhere in the PATH, named brew- to create your own commands without modifying Homebrew's internals.

Instructions for creating your own commands can be found in the docs: -https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md

+http://docs.brew.sh/External-Commands.html

SPECIFYING FORMULAE

@@ -720,7 +720,7 @@ Homebrew uses the GitHub API for features such as brew search.

the number of parallel jobs to run when building with make(1).

Default: the number of available CPU cores.

-
HOMEBREW_NO_ANALYTICS

If set, Homebrew will not send analytics. See: https://github.com/Homebrew/brew/blob/master/docs/Analytics.md#analytics

+
HOMEBREW_NO_ANALYTICS

If set, Homebrew will not send analytics. See: http://docs.brew.sh/Analytics.html

HOMEBREW_NO_AUTO_UPDATE

If set, Homebrew will not auto-update before running brew install, brew upgrade or brew tap.

HOMEBREW_NO_EMOJI

If set, Homebrew will not print the HOMEBREW_INSTALL_BADGE on a -- cgit v1.2.3 From 9a6cd9b83fc8596727df0157e89faee302907cda Mon Sep 17 00:00:00 2001 From: Jonathan Chang Date: Wed, 4 Jan 2017 16:16:00 -0600 Subject: docs: fix titles on docs.brew.sh --- docs/Acceptable-Formulae.md | 1 + docs/Analytics.md | 1 + docs/Bottles.md | 1 + docs/Brew-Test-Bot-For-Core-Contributors.md | 1 + docs/Brew-Test-Bot.md | 1 + docs/C++-Standard-Libraries.md | 1 + docs/Checksum_Deprecation.md | 1 + docs/Common-Issues.md | 1 + docs/Custom-GCC-and-cross-compilers.md | 1 + docs/External-Commands.md | 1 + docs/Formula-Cookbook.md | 1 + docs/Gems,-Eggs-and-Perl-Modules.md | 1 + docs/Homebrew-and-Python.md | 1 + docs/How-to-Create-and-Maintain-a-Tap.md | 1 + docs/Installation.md | 1 + docs/Interesting-Taps-&-Forks.md | 1 + docs/Kickstarter-Supporters.md | 1 + docs/Maintainer-Guidelines.md | 1 + docs/Maintainers-Avoiding-Burnout.md | 1 + docs/Migrating-A-Formula-To-A-Tap.md | 1 + docs/New-Maintainer-Checklist.md | 1 + docs/Querying-Brew.md | 1 + docs/Versions.md | 1 + docs/brew-tap.md | 1 + 24 files changed, 24 insertions(+) (limited to 'docs') diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index 12084fad7..9f4fb45db 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -1,4 +1,5 @@ # Acceptable Formulae + Some formulae should not go in [homebrew/core](https://github.com/Homebrew/homebrew-core). But there are additional [Interesting Taps & Forks](Interesting-Taps-&-Forks.md) and anyone can start their diff --git a/docs/Analytics.md b/docs/Analytics.md index 80515d079..b4e73f75d 100644 --- a/docs/Analytics.md +++ b/docs/Analytics.md @@ -1,4 +1,5 @@ # Anonymous Aggregate User Behaviour Analytics + Homebrew has begun gathering anonymous aggregate user behaviour analytics and reporting these to Google Analytics. You will be notified the first time you run `brew update` or install Homebrew. ## Why? diff --git a/docs/Bottles.md b/docs/Bottles.md index 7d2982c14..2752ebe03 100644 --- a/docs/Bottles.md +++ b/docs/Bottles.md @@ -1,4 +1,5 @@ # Bottles (binary packages) + Bottles 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. ## Usage diff --git a/docs/Brew-Test-Bot-For-Core-Contributors.md b/docs/Brew-Test-Bot-For-Core-Contributors.md index 4b697066c..f4c9a0ec6 100644 --- a/docs/Brew-Test-Bot-For-Core-Contributors.md +++ b/docs/Brew-Test-Bot-For-Core-Contributors.md @@ -1,4 +1,5 @@ # 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 two types of Jenkins jobs you will interact with: diff --git a/docs/Brew-Test-Bot.md b/docs/Brew-Test-Bot.md index 0a5f76bda..db39327fa 100644 --- a/docs/Brew-Test-Bot.md +++ b/docs/Brew-Test-Bot.md @@ -1,4 +1,5 @@ # Brew Test Bot + `brew test-bot` is the name for the automated review and testing system funded by [our Kickstarter in 2013](https://www.kickstarter.com/projects/homebrew/brew-test-bot). diff --git a/docs/C++-Standard-Libraries.md b/docs/C++-Standard-Libraries.md index 0bb987def..c1725f202 100644 --- a/docs/C++-Standard-Libraries.md +++ b/docs/C++-Standard-Libraries.md @@ -1,4 +1,5 @@ # 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 diff --git a/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md index c86f3a1a3..3ef0d41ec 100644 --- a/docs/Checksum_Deprecation.md +++ b/docs/Checksum_Deprecation.md @@ -1,4 +1,5 @@ # MD5 and SHA-1 Deprecation + During early 2015 Homebrew started the process of deprecating _SHA1_ for package integrity verification. Since then every formulae under the Homebrew organisation has been moved onto _SHA256_ verification; this includes both source packages diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index 14f2836c4..8da622ab4 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -1,4 +1,5 @@ # Common Issues + This is a list of commonly encountered problems, known issues, and their solutions. ### `brew` complains about absence of "Command Line Tools" diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md index 99b52c060..08a8b2b19 100644 --- a/docs/Custom-GCC-and-cross-compilers.md +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -1,4 +1,5 @@ # 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`. diff --git a/docs/External-Commands.md b/docs/External-Commands.md index b88ba3fa5..59622bd3a 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -1,4 +1,5 @@ # External Commands + Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like: ```shell diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 69a47b211..9d02a0f9a 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1,4 +1,5 @@ # Formula Cookbook + A formula is a package definition written in Ruby. It can be created with `brew create $URL`, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. ## Homebrew Terminology diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md index dfbdc224f..770d770f6 100644 --- a/docs/Gems,-Eggs-and-Perl-Modules.md +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -1,4 +1,5 @@ # Gems, Eggs and Perl Modules + On a fresh macOS installation there are three empty directories for add-ons available to all users: diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index 0757b5d24..e2f59c322 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -1,4 +1,5 @@ # Python + This page describes how Python is handled in Homebrew for users. See [Python for Formula Authors](Python-for-Formula-Authors.md) for advice on writing formulae to install packages written in Python. Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS system Python. diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index ff7de8029..5c8f3a8c4 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -1,4 +1,5 @@ # How to Create and Maintain a Tap + Taps are external sources of Homebrew formulae and/or external commands. They can be created by anyone to provide their own formulae and/or external commands to any Homebrew user. diff --git a/docs/Installation.md b/docs/Installation.md index ff5649a72..dbe8b9917 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,4 +1,5 @@ # Installation + The suggested and easiest way to install Homebrew is on the [homepage](http://brew.sh). diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md index dcb860a23..a5c609441 100644 --- a/docs/Interesting-Taps-&-Forks.md +++ b/docs/Interesting-Taps-&-Forks.md @@ -1,4 +1,5 @@ # Interesting Taps & Forks + A Tap is homebrew-speak for a git repository containing extra formulae. Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` command. Type `man brew` in your Terminal. The main repository https://github.com/Homebrew/homebrew-core, often called `homebrew/core`, is always built-in. diff --git a/docs/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md index ae9556390..3f39b435c 100644 --- a/docs/Kickstarter-Supporters.md +++ b/docs/Kickstarter-Supporters.md @@ -1,4 +1,5 @@ # Kickstarter Supporters + This file contains a list of the awesome people who gave £5 or more to [our Kickstarter](https://www.kickstarter.com/projects/homebrew/brew-test-bot). diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index d83118642..fdb7e88f9 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -1,4 +1,5 @@ # Maintainer Guidelines + **This guide is for maintainers.** These special people have **write access** to Homebrew’s repository and help merge the contributions of others. You may find what is written here interesting, but it’s diff --git a/docs/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md index f3ba3e346..99353d946 100644 --- a/docs/Maintainers-Avoiding-Burnout.md +++ b/docs/Maintainers-Avoiding-Burnout.md @@ -1,4 +1,5 @@ # Maintainers: Avoiding Burnout + **This guide is for maintainers.** These special people have **write access** to Homebrew’s repository and help merge the contributions of others. You may find what is written here interesting, but it’s diff --git a/docs/Migrating-A-Formula-To-A-Tap.md b/docs/Migrating-A-Formula-To-A-Tap.md index 7bc984f84..ba5577056 100644 --- a/docs/Migrating-A-Formula-To-A-Tap.md +++ b/docs/Migrating-A-Formula-To-A-Tap.md @@ -1,4 +1,5 @@ # Migrating A Formula To A Tap + There are times when we may wish to migrate a formula from one tap into another tap. To do this: 1. Create a pull request to the new tap adding the formula file as-is from the original tap. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formula (e.g. `brew audit --strict` must pass for that formula). diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md index b1117ce9b..29c2d4ece 100644 --- a/docs/New-Maintainer-Checklist.md +++ b/docs/New-Maintainer-Checklist.md @@ -1,4 +1,5 @@ # New Maintainer Checklist + **This is a guide used by existing maintainers to invite new maintainers. You might find it interesting but there's nothing here users should have to know.** So, there's someone who has been making consistently high-quality contributions to Homebrew for a long time and shown themselves able to make slightly more advanced contributions than just e.g. formula updates? Let's invite them to be a maintainer! diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index 70fe6bb06..6d37cb588 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -1,4 +1,5 @@ # Querying `brew` + _In this document we will be using [jq](https://stedolan.github.io/jq/) to parse JSON, available from Homebrew using `brew install jq`._ ## Overview diff --git a/docs/Versions.md b/docs/Versions.md index 87bc9f566..9e679db7d 100644 --- a/docs/Versions.md +++ b/docs/Versions.md @@ -1,4 +1,5 @@ # Versions + Now that [Homebrew/versions](https://github.com/homebrew/homebrew-versions) has been deprecated [Homebrew/core](https://github.com/homebrew/homebrew-core) supports multiple versions of formulae with a new naming format. In [Homebrew/versions](https://github.com/homebrew/homebrew-versions) the formula for GCC 6 was named `gcc6.rb` and began `class Gcc6 < Formula`. In [Homebrew/core](https://github.com/homebrew/homebrew-core) this same formula is named `gcc@6.rb` and begins `class GccAT6 < Formula`. diff --git a/docs/brew-tap.md b/docs/brew-tap.md index f73f1813e..15f8c7936 100644 --- a/docs/brew-tap.md +++ b/docs/brew-tap.md @@ -1,4 +1,5 @@ # Taps (third-party repositories) + `brew tap` adds more repos to the list of formulae that `brew` tracks, updates, and installs from. By default, `tap` assumes that the repos come from GitHub, but the command isn't limited to any one location. -- cgit v1.2.3 From 2aac904eac522a4d746a852ecc244509f5cfdafa Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sat, 7 Jan 2017 13:02:09 +0000 Subject: docs/README: link to Versions.md. --- docs/README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 0e3e0f0fd..ec7564733 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,6 +27,7 @@ - [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md) - [Formula Cookbook](Formula-Cookbook.md) - [Acceptable Formulae](Acceptable-Formulae.md) +- [Formulae Versions](Versions.md) - [Node for Formula Authors](Node-for-Formula-Authors.md) - [Python for Formula Authors](Python-for-Formula-Authors.md) - [Migrating A Formula To A Tap](Migrating-A-Formula-To-A-Tap.md) -- cgit v1.2.3 From f5b63f4a8dd3e22ffc405a1a6119a961f8332578 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Mon, 9 Jan 2017 12:31:00 +0000 Subject: Deprecate brew (un)linkapps. Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight using either aliases or symlinks and Homebrew formulae do not build "proper" `.app` bundles that can be relocated. Instead, please consider using `brew cask` and migrate formulae using `.app`s to casks. --- docs/brew.1.html | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/brew.1.html b/docs/brew.1.html index 8c81b1ddb..ba65157cb 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -223,7 +223,12 @@ actually link or delete any files.

If --force is passed, Homebrew will allow keg-only formulae to be linked.

linkapps [--local] [formulae]

Find installed formulae that provide .app-style macOS apps and symlink them -into /Applications, allowing for easier access.

+into /Applications, allowing for easier access (deprecated).

+ +

Unfortunately brew linkapps cannot behave nicely with e.g. Spotlight using +either aliases or symlinks and Homebrew formulae do not build "proper" .app +bundles that can be relocated. Instead, please consider using brew cask and +migrate formulae using .apps to casks.

If no formulae are provided, all of them will have their apps symlinked.

@@ -369,7 +374,12 @@ for temporarily disabling a formula:

If --dry-run or -n is passed, Homebrew will list all files which would be unlinked, but will not actually unlink or delete any files.

-
unlinkapps [--local] [--dry-run] [formulae]

Remove symlinks created by brew linkapps from /Applications.

+
unlinkapps [--local] [--dry-run] [formulae]

Remove symlinks created by brew linkapps from /Applications (deprecated).

+ +

Unfortunately brew linkapps cannot behave nicely with e.g. Spotlight using +either aliases or symlinks and Homebrew formulae do not build "proper" .app +bundles that can be relocated. Instead, please consider using brew cask and +migrate formulae using .apps to casks.

If no formulae are provided, all linked apps will be removed.

-- cgit v1.2.3 From 3ccbfa72a2be56037375ee413b66c96d14384373 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 11 Jan 2017 14:19:56 -0800 Subject: brew.1: use uninstall instead of remove. Fixes #1817. --- docs/brew.1.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/brew.1.html b/docs/brew.1.html index ba65157cb..8ec35ac61 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -22,7 +22,7 @@ didn't include with macOS.

install formula

Install formula.

-
remove formula

Uninstall formula.

+
uninstall formula

Uninstall formula.

update

Fetch the newest version of Homebrew from GitHub using git(1).

list

List all installed formulae.

search text|/text/

Perform a substring search of formula names for text. If text is -- cgit v1.2.3 From 7c7a878b1f1be672fd8b259e7089cb84afab6428 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 13 Jan 2017 16:20:30 -0500 Subject: clarify what should be in brew create url resolves https://github.com/Homebrew/brew/issues/1821--- docs/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index df86be92f..bb3ad33dc 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1,6 +1,6 @@ # Formula Cookbook -A formula is a package definition written in Ruby. It can be created with `brew create $URL`, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. +A formula is a package definition written in Ruby. It can be created with `brew create $URL` where `$URL` is a zip or tarball, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. ## Homebrew Terminology -- cgit v1.2.3 From 7c159449910d5c6fe2f4fea7416fed8a8ba2d4db Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sun, 15 Jan 2017 02:25:51 -0800 Subject: Fix documentation for HEAD upgrades. These can now be done with just `brew upgrade`, like other upgrades. Fixes #1818. --- docs/brew.1.html | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/brew.1.html b/docs/brew.1.html index ba65157cb..9cc52a131 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -196,10 +196,7 @@ for installation.

aka master, trunk, unstable.

If --keep-tmp is passed, the temporary files created during installation -are not deleted.

- -

To install a newer version of HEAD use -brew rm <foo> && brew install --HEAD <foo>.

+are not deleted.

install --interactive [--git] formula

Download and patch formula, then open a shell. This allows the user to run ./configure --help and otherwise determine how to turn the software package into a Homebrew formula.

-- cgit v1.2.3 From dac66c4ada178c09b3b9b77feb2eaa7442b7443e Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Tue, 17 Jan 2017 10:43:43 +0000 Subject: Add `keg_only :versioned_formula`. This is used to indicate a formula is a version of another formula. This will be used to provide a consistent interface for older formulae versions and replaces the use of `conflicts_with`. --- docs/Versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Versions.md b/docs/Versions.md index 9e679db7d..bd3ef8a5f 100644 --- a/docs/Versions.md +++ b/docs/Versions.md @@ -11,6 +11,6 @@ Versioned formulae we include must meet the following standards: * Versioned formulae should differ in major/minor (not patch) versions from the current stable release. This is because patch versions indicate bug or security updates and we want to ensure you apply security updates. * Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`. -* Versioned formulae should strive to be linked at the same time as their non-versioned counterpart (without patching). If this is not possible, favour either `conflicts_with` or `keg_only` depending on whether users expect to have multiple versions installed at once or not. +* Versioned formulae should only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for e.g. suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once. You should create your own [tap](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wishes to control the versioning of or those that do not meet the above standards. -- cgit v1.2.3