From c1376f9f18f6e5da3d2290d5cdd808d32767068b Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Thu, 6 Sep 2018 15:07:00 +0100 Subject: [PATCH] docs: various updates. I read through the docs locally and made various fixes. --- docs/Acceptable-Formulae.md | 2 +- docs/Analytics.md | 4 +- docs/Bottles.md | 5 +- ...lding-Against-Non-Homebrew-Dependencies.md | 2 +- docs/C++-Standard-Libraries.md | 10 ++-- docs/External-Commands.md | 46 +++++++++++-------- docs/FAQ.md | 8 +--- docs/Formula-Cookbook.md | 4 ++ docs/How-To-Open-a-Homebrew-Pull-Request.md | 2 +- docs/Interesting-Taps-and-Forks.md | 2 - docs/Maintainers-Avoiding-Burnout.md | 12 ++--- docs/Prose-Style-Guidelines.md | 10 ++-- docs/Querying-Brew.md | 2 - docs/Shell-Completion.md | 2 +- docs/Taps.md | 2 +- docs/Tips-N'-Tricks.md | 2 +- docs/Versions.md | 2 +- 17 files changed, 59 insertions(+), 58 deletions(-) diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index 778993ae46..9b7320ba8b 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -16,7 +16,7 @@ Software that can upgrade itself does not integrate well with Homebrew's own upgrade functionality. The self-update functionality should be disabled (if possible without complicating the formula). ### We don’t like install-scripts that download unversioned things -We don't like install scripts that are pulling from the `master` branch of Git repositories or unversioned, unchecksummed tarballs. These should use `resource` blocks with specific revisions or checksummed tarballs instead. Note that we now allow tools like `cargo`, `gem` and `pip` to download things during installation. +We don't like install scripts that are pulling from the `master` branch of Git repositories or unversioned, unchecksummed tarballs. These should use `resource` blocks with specific revisions or checksummed tarballs instead. Note that we now allow tools like `cargo`, `gem` and `pip` to download specifically versioned libraries during installation. ### We don’t like binary formulae Our policy is that formulae in the core tap diff --git a/docs/Analytics.md b/docs/Analytics.md index b989d30b85..0c54261f44 100644 --- a/docs/Analytics.md +++ b/docs/Analytics.md @@ -42,9 +42,7 @@ As far as we can tell it would be impossible for Google to match the randomly ge Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS. ## Who? -Homebrew's detailed analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access. - -Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). +Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available. ## How? 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. diff --git a/docs/Bottles.md b/docs/Bottles.md index 426b9e91c4..22c4b884e2 100644 --- a/docs/Bottles.md +++ b/docs/Bottles.md @@ -10,7 +10,7 @@ Bottles will not be used if the user requests it (see above), if the formula req ## 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! +By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit OSs). 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! ## 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). @@ -76,6 +76,3 @@ pour_bottle? do satisfy { MacOS::CLT.installed? } end ``` - -## Planned improvements -Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions. diff --git a/docs/Building-Against-Non-Homebrew-Dependencies.md b/docs/Building-Against-Non-Homebrew-Dependencies.md index 4e85757a1b..b04fb55df7 100644 --- a/docs/Building-Against-Non-Homebrew-Dependencies.md +++ b/docs/Building-Against-Non-Homebrew-Dependencies.md @@ -2,7 +2,7 @@ ## History -Originally Homebrew was a build-from-source package manager and all user environment variables and non-Homebrew-installed software were available to builds. Since then Homebrew added `Requirement`s to specify dependencies on non-Homebrew software (such as those provided by `brew cask` like X11/XQuartz), the `superenv` build system to strip out unspecified dependencies, environment filtering to stop the user environment leaking into Homebrew builds and `default_formula` to specify that a `Requirement` can be satisifed by a particular formula. +Originally Homebrew was a build-from-source package manager and all user environment variables and non-Homebrew-installed software were available to builds. Since then Homebrew added `Requirement`s to specify dependencies on non-Homebrew software (such as those provided by `brew cask` like X11/XQuartz), the `superenv` build system to strip out unspecified dependencies, environment filtering to stop the user environment leaking into Homebrew builds and `default_formula` to specify that a `Requirement` can be satisfied by a particular formula. As Homebrew became primarily a binary package manager, most users were fulfilling `Requirement`s with the `default_formula`, not with arbitrary alternatives. To improve quality and reduce variation, Homebrew now exclusively supports using the default formula, as an ordinary dependency, and no longer supports using arbitrary alternatives. diff --git a/docs/C++-Standard-Libraries.md b/docs/C++-Standard-Libraries.md index 7f41c9007a..4afb95baf4 100644 --- a/docs/C++-Standard-Libraries.md +++ b/docs/C++-Standard-Libraries.md @@ -2,19 +2,19 @@ There are two C++ standard libraries supported by Apple compilers. -The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC +The default for 10.9 and later is **libc++**, which is also the default for `clang` on older +platforms when building C++11 code. + +The default for 10.8 and earlier was **libstdc++**, supported by Apple GCC compilers, GNU GCC compilers, and `clang`. This was marked deprecated with a warning during compile as of Xcode 8. -The default for 10.9 is **libc++**, which is also the default for `clang` on older -platforms when building C++11 code. - There are subtle incompatibilities between several of the C++ standard libraries, so Homebrew will refuse to install software if a dependency was built with an incompatible C++ library. It's recommended that you install the dependency tree using a compatible compiler. -**If you've upgraded to 10.9 from an earlier version** - because the default C++ +**If you've upgraded to or later 10.9 from an earlier version** - because the default C++ standard library is now libc++, you may not be able to build software using dependencies that you built on 10.8 or lower. If you're reading this page because you were directed here by a build error, you can most likely fix the issue if diff --git a/docs/External-Commands.md b/docs/External-Commands.md index 65282fcb16..b84bdc0eae 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -9,12 +9,12 @@ brew mycommand --option1 --option3 formula without modifying Homebrew's internals. ## Command types -External commands come in two flavors: Ruby commands and shell scripts. +External commands come in two flavours: Ruby commands and shell scripts. In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`. ### 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. +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. Be wary of using Homebrew internals; they may change at any time without warning. The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return `0`. @@ -37,12 +37,9 @@ All internal and external Homebrew commands can provide styled `--help` output b For example, see the [header of `brew services`](https://github.com/Homebrew/homebrew-services/blob/a5115e47b05e8d2a632ba7775599e698b240e5a2/cmd/brew-services.rb#L1-L31) which is output with `brew services --help`. -## 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. +## Homebrew organisation external commands -Note they are largely untested, and as always, be careful about running untested code on your machine. - -### brew-livecheck +### homebrew-livecheck Check if there is a new upstream version of a formula. See the [`README`](https://github.com/Homebrew/homebrew-livecheck/blob/master/README.md) for more info and usage. @@ -52,19 +49,32 @@ Install using: brew tap homebrew/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`. - -### brew-growl -Get Growl notifications for Homebrew: - -### brew-services -Simple support for starting formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): +### homebrew-command-not-found +Ubuntu's `command-not-found equivalent` for Homebrew. +See the [`README`](https://github.com/Homebrew/homebrew-command-not-found/blob/master/README.md) for more info and usage. Install using: ```sh -brew tap homebrew/services +brew tap homebrew/command-not-found ``` + +### homebrew-aliases +Allows you to alias your Homebrew commands. +See the [`README`](https://github.com/Homebrew/homebrew-aliases/blob/master/README.md) for more info and usage. + +Install using: + +```sh +brew tap homebrew/aliases +``` + +## Unofficial external commands +These commands have been contributed by Homebrew users but are not included in the main Homebrew organisation, 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. + +### brew-gem +Install any `gem` package into a self-contained Homebrew Cellar location: + +Note this can also be installed with `brew install brew-gem`. diff --git a/docs/FAQ.md b/docs/FAQ.md index fdbbb7eb0c..2faeb8ad37 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -108,10 +108,6 @@ cd $(brew --repository) hub pull someone_else ``` -Or: - - brew install https://raw.github.com/user/repo/branch/formula.rb - Or: brew pull https://github.com/Homebrew/homebrew-core/pull/1234 @@ -142,7 +138,7 @@ anyway. Homebrew refuses to work using sudo. You should only ever sudo a tool you trust. Of course, you can trust Homebrew -;) But do you trust the multi-megabyte Makefile that Homebrew runs? Developers +😉 But do you trust the multi-megabyte Makefile that Homebrew runs? Developers often understand C++ far better than they understand make syntax. It’s too high a risk to sudo such stuff. It could modify (or upload) any files on your system.And indeed, we’ve seen some build scripts try to modify `/usr` even when @@ -205,7 +201,7 @@ our analytics identified it was not widely used. ## Homebrew is a poor name, it's too 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, it was too +project may actually prove popular. By the time he realised it was, it was too late. However, today, the first Google hit for “homebrew” is not beer related ;-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 2575d214fb..d2dc6de682 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -160,6 +160,8 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati depends_on "foo" => :optional # Generated description is "Build with foo support" ``` +We frown on [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s in Homebrew/homebrew-core as they are not tested by CI. + ### Specifying conflicts with other formulae Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method). @@ -663,6 +665,8 @@ end Note that [`option`](http://www.rubydoc.info/github/Homebrew/brew/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/brew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb#L27-L31) for an example. +We frown on [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s in Homebrew/homebrew-core as they are not tested by CI. + ### File level operations You can use the file utilities provided by Ruby's [`FileUtils`](https://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them. diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md index 16b1234940..934652af76 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request.md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -32,7 +32,7 @@ To make a new branch and submit it for review, create a GitHub pull request with 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). +4. Make your changes. For formulae, use `brew edit` or your favourite 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. * `brew tests` diff --git a/docs/Interesting-Taps-and-Forks.md b/docs/Interesting-Taps-and-Forks.md index 57f0730b72..1442a84efe 100644 --- a/docs/Interesting-Taps-and-Forks.md +++ b/docs/Interesting-Taps-and-Forks.md @@ -25,8 +25,6 @@ Your taps are Git repositories located at `$(brew --repository)/Library/Taps`. * [brewsci/bio](https://github.com/brewsci/homebrew-bio): Bioinformatics formulae. -* [brewsci/science](https://github.com/brewsci/homebrew-science): Software tailored to scientific endeavours. - * [davidchall/hep](https://github.com/davidchall/homebrew-hep): High energy physics formulae. * [lifepillar/appleii](https://github.com/lifepillar/homebrew-appleii): Formulae for vintage Apple emulation. diff --git a/docs/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md index a10a79cdfc..9a55338e5d 100644 --- a/docs/Maintainers-Avoiding-Burnout.md +++ b/docs/Maintainers-Avoiding-Burnout.md @@ -15,12 +15,12 @@ you should also decide not to be a maintainer and find other things to work on. ## 2. No Guilt About Leaving All maintainers can stop working on Homebrew at any time without any guilt or -explanation (like a job). We may still ask for your help with questions after -you leave but you are under no obligation to answer them. Like a job, if you -create a big mess and then leave you still have no obligations but we may think -less of you (or, realistically, probably just revert the problematic work). -Like a job, you should probably take a break from Homebrew at least a few times -a year. +explanation (like leaving a job). We may still ask for your help with questions +after you leave but you are under no obligation to answer them. Like a job, if +you create a big mess and then leave you still have no obligations but we may +think less of you (or, realistically, probably just revert the problematic +work). Like a job, you should probably take a break from Homebrew at least a few +times a year. This also means contributors should be consumers. If an owner finds they are not using a project in the real world, they should reconsider their involvement diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md index 4fe19bdb82..3c4b268da5 100644 --- a/docs/Prose-Style-Guidelines.md +++ b/docs/Prose-Style-Guidelines.md @@ -42,10 +42,10 @@ We prefer: * Sentence case in section headings, not Title Case * Periods at the ends of list items where most items in that list are complete sentences * More generally, parallel list item structure -* Capitalize all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page +* Capitalise all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page * Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments * Prefer Markdown over other markup formats unless their specific features are needed - * GitHub Flavored Markdown. GitHub's implementation is the standard, period. + * GitHub Flavoured Markdown. GitHub's implementation is the standard, period. ### Typographical conventions @@ -56,12 +56,12 @@ We prefer: * No "$" with environment variables mentioned outside code snippets * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5" * One space after periods, not two -* Capitalized proper nouns -* We do not defer to extensive nonstandard capitalization, typesetting, or other styling of brand names, aside from the normal capitalization of proper nouns and simple internal capitalization +* Capitalised proper nouns +* We do not defer to extensive nonstandard capitalisation, typesetting, or other styling of brand names, aside from the normal capitalisation of proper nouns and simple internal capitalisation * No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned * Tap names like `homebrew/core` are styled in `fixed width font`. Repository names may be styled in either fixed width font like "`Homebrew/homebrew-core`", as links like "[Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core)", or regular text like "Homebrew/homebrew-core", based on which looks best for a given use. * But be consistent within a single document - * Capitalize repository names to match the user and repository names on GitHub. Keep tap names in lower case. + * Capitalise repository names to match the user and repository names on GitHub. Keep tap names in lower case. * Commas * No Oxford commas * Prefer a "loose" comma style: "when in doubt, leave it out" unless needed for clarity diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index dd884d7d9b..2b621c13a4 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -27,8 +27,6 @@ The current schema version is `v1`. Note that fields may be added to the schema The schema itself is not currently documented outside of the code that generates it: [Formula#to_hash](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/formula.rb) -(**TODO**: add a manpage for the schema) - ## Examples _The top-level element of the JSON output is always an array, so the `map` operator is used to act on the data._ diff --git a/docs/Shell-Completion.md b/docs/Shell-Completion.md index dc81d8aa9c..7da17d5951 100644 --- a/docs/Shell-Completion.md +++ b/docs/Shell-Completion.md @@ -18,7 +18,7 @@ fi ``` ## Configuring Completions in `zsh` -To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `$FPATH` before initializing `zsh`'s completion facility. Add the following to your `~/.zshrc` file: +To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `$FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc` file: ```sh if type brew &>/dev/null; then diff --git a/docs/Taps.md b/docs/Taps.md index 59825a0c9d..7dd3301c26 100644 --- a/docs/Taps.md +++ b/docs/Taps.md @@ -59,7 +59,7 @@ If your tap contains a formula that is also present in [`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine, but it means that you must install it explicitly by default. -If you would like to prioritize a tap over `homebrew/core`, you can use +If you would like to prioritise a tap over `homebrew/core`, you can use `brew tap-pin username/repo` to pin the tap, and use `brew tap-unpin username/repo` to revert the pin. diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index a88940f0ef..867e88e7c5 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -3,7 +3,7 @@ ## Installing previous versions of formulae The supported method of installing specific versions of -some formulae is to see if there is a versioned formula (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)! +some formulae is to see if there is a versioned formula (e.g. `gcc@6`) available. If the version you’re looking for isn’t available, consider using `brew extract`. ### Installing directly from pull requests You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls) diff --git a/docs/Versions.md b/docs/Versions.md index d0fc04ee03..90b269070f 100644 --- a/docs/Versions.md +++ b/docs/Versions.md @@ -13,7 +13,7 @@ Versioned formulae we include in [homebrew/core](https://github.com/homebrew/hom * 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 only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for it, e.g. using suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once. * A `keg_only :versioned_formula` should not `post_install` anything in the `HOMEBREW_PREFIX` that conflicts with or duplicates the non-versioned counterpart (or other versioned formulae). For example, a `node@6` formula should not install its `npm` into `HOMEBREW_PREFIX` like the `node` formula does. -* Versioned formulae submitted should be expected to be used by a large number of people. If this ceases to be the case: they will be removed. We will aim not to remove those in the [top 1000 `install_on_request` formulae](https://brew.sh/analytics/install-on-request/). +* Versioned formulae submitted should be expected to be used by a large number of people. If this ceases to be the case: they will be removed. We will aim not to remove those in the [top 3,000 `install_on_request` formulae](https://brew.sh/analytics/install-on-request/). * Versioned formulae should not have `resource`s that require security updates. For example, a `node@6` formula should not have an `npm` resource but instead rely on the `npm` provided by the upstream tarball. * Versioned formulae should be as similar as possible and sensible to the unversioned formulae. Creating or updating a versioned formula should be a chance to ask questions of the unversioned formula e.g. can some unused or useless options be removed or made default? * No more than five versions of a formula (including the non-versioned one) will be supported at any given time, regardless of usage. When removing formulae that violate this we will aim to do so based on usage and support status rather than age.