X Tutup
Skip to content
This repository was archived by the owner on Jan 16, 2025. It is now read-only.

Commit 71cba60

Browse files
xu-chengxu-cheng
committed
doc: update for core/formula separation
Closes #50632. Signed-off-by: Xu Cheng <xucheng@me.com>
1 parent dc94fbc commit 71cba60

13 files changed

+79
-60
lines changed

‎Library/Homebrew/manpages/brew.1.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -560,7 +560,7 @@ can take several different forms:
560560

561561
* An arbitrary URL:
562562
Homebrew can install formulae via URL, e.g.
563-
`https://raw.github.com/Homebrew/homebrew/master/Library/Formula/git.rb`.
563+
`https://raw.github.com/Homebrew/homebrew-core/master/Formula/git.rb`.
564564
The formula file will be cached for later use.
565565

566566
## ENVIRONMENT
@@ -726,4 +726,8 @@ Former maintainers with significant contributions include Jack Nagel, Adam Vande
726726

727727
## BUGS
728728

729-
See our issues on GitHub: <https://github.com/Homebrew/homebrew/issues>
729+
See our issues on GitHub:
730+
731+
* Homebrew <https://github.com/Homebrew/homebrew/issues>
732+
733+
* Homebrew/homebrew-core <https://github.com/Homebrew/homebrew-core/issues>

‎share/doc/homebrew/Acceptable-Formulae.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Acceptable Formulae
22
Some formulae should not go in
3-
[Homebrew/homebrew](https://github.com/Homebrew/homebrew). But there are
3+
[homebrew/core](https://github.com/Homebrew/homebrew-core). But there are
44
additional [Interesting Taps & Branches](Interesting-Taps-&-Branches.md) and anyone can start their
55
own!
66

@@ -57,7 +57,7 @@ point it to the downloaded archive in order to avoid loading.
5757

5858
### We don’t like binary formulae
5959
Our policy is that formulae in the core repository
60-
([Homebrew/homebrew](https://github.com/Homebrew/homebrew)) must be built
60+
([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be built
6161
from source (or produce cross-platform binaries like e.g. Java). Binary-only
6262
formulae should go to [homebrew/binary](https://github.com/Homebrew/homebrew-binary) or [homebrew-cask](https://github.com/caskroom/homebrew-cask).
6363

‎share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ If a build has run and passed on `brew test-bot` then it can be used to quickly
33

44
There are two types of Jenkins jobs you will interact with:
55

6-
## [Homebrew Pull Requests](http://bot.brew.sh/job/Homebrew%20Pull%20Requests/)
7-
This job automatically builds any pull requests submitted to Homebrew/homebrew. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot wiki page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles.
6+
## [Homebrew Pull Requests](http://bot.brew.sh/job/Homebrew%20Core%20Pull%20Requests/)
7+
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.
88

99
## [Homebrew Testing](http://bot.brew.sh/job/Homebrew%20Testing/)
1010
This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/homebrew/blob/master/Library/Homebrew/cmd/test-bot.rb) with user-specified parameters. On a successful build it automatically uploads bottles.

‎share/doc/homebrew/FAQ.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ Or:
120120

121121
Or:
122122

123-
`brew pull https://github.com/Homebrew/homebrew/pull/1234`
123+
`brew pull https://github.com/Homebrew/homebrew-core/pull/1234`
124124

125125
### Why does Homebrew prefer I install to `/usr/local`?
126126
<a name="usrlocal"></a>
@@ -176,7 +176,7 @@ If it’s not in `man brew`, it’s probably an external command. These are docu
176176
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.
177177

178178
### Can I edit formulae myself?
179-
Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to*Homebrew/homebrew*, 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!
179+
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!
180180

181181
### Can I make new formulae?
182182
Yes! It’s easy! Just `brew create URL` Homebrew will then open the
@@ -185,7 +185,7 @@ installs; try it: `brew install $FORMULA`. If you come up with any issues,
185185
run the command with the `-d` switch like so: `brew install -d $FORMULA`,
186186
which drops you into a debugging shell.
187187

188-
If you want your new formula to be part of *Homebrew/homebrew* or want
188+
If you want your new formula to be part of *homebrew/core* or want
189189
to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md).
190190

191191
### Can I install my own stuff to `/usr/local`?

‎share/doc/homebrew/Formula-Cookbook.md‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,22 @@ A formula is a package definition written in Ruby. It can be created with `brew
33

44
## Homebrew Terminology
55

6-
| Term | Description | Example |
7-
|----------------|------------------------------------------------------------|------------------------------------------------------|
8-
| **Formula** | The package definition | `/usr/local/Library/Formula/foo.rb` |
9-
| **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` |
10-
| **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` |
11-
| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` |
12-
| **Tap** | An optional Git repository of **Formulae** and/or commands | `/usr/local/Library/Taps/homebrew/homebrew-versions` |
13-
| **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` |
6+
| Term | Description | Example |
7+
|----------------|------------------------------------------------------------|-----------------------------------------------------------------|
8+
| **Formula** | The package definition | `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` |
9+
| **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` |
10+
| **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` |
11+
| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` |
12+
| **Tap** | An optional Git repository of **Formulae** and/or commands | `/usr/local/Library/Taps/homebrew/homebrew-versions` |
13+
| **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` |
1414

1515
## An Introduction
1616

1717
Homebrew uses Git for downloading updates and contributing to the project.
1818

1919
Homebrew installs to the `Cellar` it then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged.
2020

21-
Packages are installed according to their formulae, which live in `/usr/local/Library/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` or [Git](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb).
21+
Packages are installed according to their formulae, which live in `/usr/local/Library/Taps/homebrew/homebrew-core/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` or [Git](https://github.com/Homebrew/homebrew-core/blob/master/Formula/git.rb).
2222

2323
# Basic Instructions
2424

@@ -29,7 +29,7 @@ Before submitting a new formula make sure your package:
2929
* meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements
3030
* isn't already in Homebrew (check `brew search $FORMULA`)
3131
* isn't in another official [Homebrew tap](https://github.com/Homebrew)
32-
* isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew/issues))
32+
* isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues))
3333
* is still supported by upstream (i.e. doesn't require extensive patching)
3434
* has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Branches](Interesting-Taps-&-Branches.md) for where pre-release versions belong.
3535
* passes all `brew audit --strict --online $FORMULA` tests.
@@ -44,7 +44,7 @@ Run `brew create` with a URL to the source tarball:
4444
brew create https://example.com/foo-0.1.tar.gz
4545
```
4646

47-
This creates `/usr/local/Library/Formula/foo.rb` and opens it in your `$EDITOR`. It'll look something like:
47+
This creates `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `$EDITOR`. It'll look something like:
4848

4949
```ruby
5050
class Foo < Formula
@@ -109,7 +109,7 @@ Homebrew’s OpenSSL is
109109
to avoid conflicting with the system so sometimes formulae need to
110110
have environment variables set or special configuration flags passed
111111
to locate our OpenSSL. You can see this mechanism in the
112-
[clamav](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/clamav.rb#L28)
112+
[clamav](https://github.com/Homebrew/homebrew-core/blob/master/Formula/clamav.rb#L28)
113113
formula. Usually this is unnecessary because when OpenSSL is specified
114114
as a dependency Homebrew temporarily prepends the `$PATH` with that
115115
prefix.
@@ -168,11 +168,11 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati
168168

169169
Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#keg_only-class_method).
170170

171-
`mbedtls` is a good [example](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/mbedtls.rb) formula for minor conflict.
171+
`mbedtls` is a good [example](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mbedtls.rb) formula for minor conflict.
172172

173173
`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just remove it.
174174

175-
[pdftohtml](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/pdftohtml.rb) provides an example of a serious
175+
[pdftohtml](https://github.com/Homebrew/homebrew-core/blob/master/Formula/pdftohtml.rb) provides an example of a serious
176176
conflict, where both formula ship an identically-named binary that is essential to functionality, so a [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#conflicts_with-class_method) is preferable.
177177

178178
As a general rule, [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#conflicts_with-class_method) should be a last-resort option. It’s a fairly blunt instrument.
@@ -231,7 +231,7 @@ class Foo < Formula
231231
end
232232
```
233233

234-
[jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have use `pip` or Python and can just run `jrnl`.
234+
[jrnl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have use `pip` or Python and can just run `jrnl`.
235235
236236
[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate resource stanzas for the dependencies of your Python application and [gdm](https://github.com/sparrc/gdm#homebrew) can help you generate go\_resource stanzas for the dependencies of your go application.
237237
@@ -261,7 +261,7 @@ the `test do` block.
261261
262262
We want tests that don't require any user input and test the basic functionality of the application. For example `foo build-foo input.foo` is a good test and (despite their widespread use) `foo --version` and `foo --help` are bad tests. However, a bad test is better than no test at all.
263263

264-
See [cmake](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/cmake.rb) for an example of a formula with a good test. The formula writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. Another good example is [tinyxml2](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully.
264+
See [cmake](https://github.com/Homebrew/homebrew-core/blob/master/Formula/cmake.rb) for an example of a formula with a good test. The formula writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. Another good example is [tinyxml2](https://github.com/Homebrew/homebrew-core/blob/master/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully.
265265
266266
## Manuals
267267
@@ -279,7 +279,7 @@ If you’re not sure about the name check the homepage, and check the Wikipedia
279279
280280
Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectation.
281281
282-
When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
282+
When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew/blob-core/master/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
283283
284284
If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision :wink:.
285285
@@ -307,11 +307,11 @@ Everything is built on Git, so contribution is easy:
307307
308308
```shell
309309
brew update # required in more ways than you think (initializes the brew git repository if you don't already have it)
310-
cd /usr/local
310+
cd $(brew --repo homebrew/core)
311311
# Create a new git branch for your formula so your pull request is easy to
312312
# modify if any changes come up during review.
313313
git checkout -b <some-descriptive-name>
314-
git add Library/Formula/foo.rb
314+
git add Formula/foo.rb
315315
git commit
316316
```
317317

@@ -481,7 +481,7 @@ Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formu
481481

482482
# Advanced Formula Tricks
483483

484-
If anything isn’t clear, you can usually figure it out by `grep`ping the `Library/Formula` directory. Please submit a pull request to amend this document if you think it will help!
484+
If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repo homebrew/core` directory. Please submit a pull request to amend this document if you think it will help!
485485

486486
## Unstable versions (`devel`, `head`)
487487

@@ -744,7 +744,7 @@ end
744744

745745
[`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method) names should be prefixed with the words `with` or `without`. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library `--with-shared` rather than `--shared` or `--enable-shared`.
746746

747-
Note that [`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method)s that aren’t `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/wget.rb#L27-L31) for an example.
747+
Note that [`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method)s that aren’t `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb#L27-L31) for an example.
748748

749749

750750
## File level operations
@@ -804,7 +804,7 @@ system "make" # separate make and make install steps
804804
system "make", "install"
805805
```
806806

807-
If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew/issues) so that we can fix it for everyone.
807+
If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew-core/issues) so that we can fix it for everyone.
808808

809809
## Still won’t work?
810810

0 commit comments

Comments
 (0)
X Tutup