From aee23ccb0355228f24d387fcbe7cf5d30f57d8b6 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Sun, 5 Mar 2017 21:45:15 -0500 Subject: [PATCH] Add more flags and descriptions to man pages. --- Library/Homebrew/cmd/install.rb | 5 +- Library/Homebrew/cmd/sh.rb | 10 ++-- Library/Homebrew/dev-cmd/bottle.rb | 26 ++++++++++- Library/Homebrew/dev-cmd/tests.rb | 20 +++++++- Library/Homebrew/dev-cmd/update-test.rb | 2 +- Library/Homebrew/manpages/brew.1.md.erb | 2 +- docs/brew.1.html | 61 ++++++++++++++++++++---- manpages/brew.1 | 62 +++++++++++++++++++++---- 8 files changed, 157 insertions(+), 31 deletions(-) diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb index 5a3aeb7b32..c825e27960 100644 --- a/Library/Homebrew/cmd/install.rb +++ b/Library/Homebrew/cmd/install.rb @@ -1,4 +1,4 @@ -#: * `install` [`--debug`] [`--env=`|] [`--ignore-dependencies`] [`--only-dependencies`] [`--cc=`] [`--build-from-source`] [`--devel`|`--HEAD`] [`--keep-tmp`] : +#: * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] : #: Install . #: #: is usually the name of the formula to install, but it can be specified @@ -44,6 +44,9 @@ #: If `--keep-tmp` is passed, the temporary files created during installation #: are not deleted. #: +#: If `--build-bottle` is passed, prepare the formula for eventual bottling +#: during installation. +#: #: * `install` `--interactive` [`--git`] : #: Download and patch , then open a shell. This allows the user to #: run `./configure --help` and otherwise determine how to turn the software diff --git a/Library/Homebrew/cmd/sh.rb b/Library/Homebrew/cmd/sh.rb index 09e7f435e5..2497533555 100644 --- a/Library/Homebrew/cmd/sh.rb +++ b/Library/Homebrew/cmd/sh.rb @@ -1,9 +1,11 @@ #: * `sh` [`--env=std`]: -#: Instantiate a Homebrew build environment. Uses our years-battle-hardened +#: Start a Homebrew build environment shell. Uses our years-battle-hardened #: Homebrew build logic to help your `./configure && make && make install` #: or even your `gem install` succeed. Especially handy if you run Homebrew #: in an Xcode-only configuration since it adds tools like `make` to your `PATH` -#: which otherwise build-systems would not find. +#: which otherwise build systems would not find. +#: +#: If `--env=std` is passed, use the standard `PATH` instead of superenv's. require "extend/ENV" require "formula" @@ -20,13 +22,13 @@ module Homebrew end ENV.setup_build_environment if superenv? - # superenv stopped adding brew's bin but generally user's will want it + # superenv stopped adding brew's bin but generally users will want it ENV["PATH"] = ENV["PATH"].split(File::PATH_SEPARATOR).insert(1, "#{HOMEBREW_PREFIX}/bin").join(File::PATH_SEPARATOR) end ENV["PS1"] = 'brew \[\033[1;32m\]\w\[\033[0m\]$ ' ENV["VERBOSE"] = "1" puts <<-EOS.undent_________________________________________________________72 - Your shell has been configured to use Homebrew's build environment: + Your shell has been configured to use Homebrew's build environment; this should help you build stuff. Notably though, the system versions of gem and pip will ignore our configuration and insist on using the environment they were built under (mostly). Sadly, scons will also diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb index 91bdcba93d..619986f767 100644 --- a/Library/Homebrew/dev-cmd/bottle.rb +++ b/Library/Homebrew/dev-cmd/bottle.rb @@ -1,7 +1,29 @@ -#: * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=`] [`--force-core-tap`]: -#: * `bottle` `--merge` [`--no-commit`] [`--keep-old`] [`--write`]: +#: * `bottle` [`--verbose`] [`--no-rebuild`|`--keep-old`] [`--skip-relocation`] [`--root-url=`] [`--force-core-tap`] : #: Generate a bottle (binary package) from a formula installed with #: `--build-bottle`. +#: +#: If the formula specifies a rebuild version, it will be incremented in the +#: generated DSL. Passing `--keep-old` will attempt to keep it at its +#: original value, while `--no-rebuild` will remove it. +#: +#: If `--verbose` is passed, print the bottling commands and any warnings +#: encountered. +#: +#: If `--skip-relocation` is passed, do not check if the bottle can be marked +#: as relocatable. +#: +#: If `--root-url` is passed, use the specified as the root of the +#: bottle's URL instead of Homebrew's default. +#: +#: If `--force-core-tap` is passed, build a bottle even if is not +#: in homebrew/core or any installed taps. +#: +#: * `bottle` `--merge` [`--keep-old`] [`--write` [`--no-commit`]] : +#: Generate a bottle from a formula and print the new DSL merged into the +#: existing formula. +#: +#: If `--write` is passed, write the changes to the formula file. A new +#: commit will then be generated unless `--no-commit` is passed. require "formula" require "utils/bottles" diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb index b66d8db16d..4f7f9e7714 100644 --- a/Library/Homebrew/dev-cmd/tests.rb +++ b/Library/Homebrew/dev-cmd/tests.rb @@ -1,5 +1,21 @@ -#: * `tests` [`-v`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=``:`] [`--seed` ] [`--online`] [`--official-cmd-taps`]: -#: Run Homebrew's unit and integration tests. +#: * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`[`:`]] [`--seed` ] [`--online`] [`--official-cmd-taps`]: +#: Run Homebrew's unit and integration tests. If provided, +#: `--only=` runs only _spec.rb, and `--seed` +#: randomizes tests with the provided value instead of a random seed. +#: +#: If `--verbose` is passed, print the command that runs the tests. +#: +#: If `--coverage` is passed, also generate code coverage reports. +#: +#: If `--generic` is passed, only run OS-agnostic tests. +#: +#: If `--no-compat` is passed, do not load the compatibility layer when +#: running tests. +#: +#: If `--online` is passed, include tests that use the GitHub API. +#: +#: If `--official-cmd-taps` is passed, include tests that use any of the +#: taps for official external commands. require "fileutils" require "tap" diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb index 9704426ddd..2ff1686698 100644 --- a/Library/Homebrew/dev-cmd/update-test.rb +++ b/Library/Homebrew/dev-cmd/update-test.rb @@ -1,4 +1,4 @@ -#: * `update-test` [`--commit=`] [`--before=`] [`--keep-tmp`]: +#: * `update-test` [`--commit=`] [`--before=`] [`--to-tag`] [`--keep-tmp`]: #: Runs a test of `brew update` with a new repository clone. #: #: If no arguments are passed, use `origin/master` as the start commit. diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index 05fc1cb237..5b0228e3f2 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -65,7 +65,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `services`: - Integrates Homebrew formulae with macOS's `launchctl` manager: + Integrates Homebrew formulae with macOS's `launchctl`(1) manager: ## CUSTOM EXTERNAL COMMANDS diff --git a/docs/brew.1.html b/docs/brew.1.html index 7175421273..7a06426ae8 100644 --- a/docs/brew.1.html +++ b/docs/brew.1.html @@ -152,7 +152,7 @@ information on all installed formulae.

See the docs for examples of using the JSON output: 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.

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

Install formula.

formula is usually the name of the formula to install, but it can be specified in several different ways. See SPECIFYING FORMULAE.

@@ -195,7 +195,10 @@ for installation.

aka master, trunk, unstable.

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

+are not deleted.

+ +

If --build-bottle is passed, prepare the formula for eventual bottling +during installation.

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.

@@ -301,11 +304,13 @@ The search for text is extended online to some popular taps.

If --desc is passed, browse available packages matching text including a description for each.

search (--debian|--fedora|--fink|--macports|--opensuse|--ubuntu) text

Search for text in the given package manager's list.

-
sh [--env=std]

Instantiate a Homebrew build environment. Uses our years-battle-hardened +

sh [--env=std]

Start a Homebrew build environment shell. Uses our years-battle-hardened Homebrew build logic to help your ./configure && make && make install or even your gem install succeed. Especially handy if you run Homebrew in an Xcode-only configuration since it adds tools like make to your PATH -which otherwise build-systems would not find.

+which otherwise build systems would not find.

+ +

If --env=std is passed, use the standard PATH instead of superenv's.

style [--fix] [--display-cop-names] [files|taps|formulae]

Check formulae or files for conformance to Homebrew style guidelines.

formulae and files may not be combined. If both are omitted, style will run @@ -478,9 +483,29 @@ name of the file or formula being audited, to make the output easy to grep.

audit exits with a non-zero status if any errors are found. This is useful, for instance, for implementing pre-commit hooks.

-
bottle [--verbose] [--no-rebuild] [--keep-old] [--skip-relocation] [--root-url=URL] [--force-core-tap]:

-
bottle --merge [--no-commit] [--keep-old] [--write]

Generate a bottle (binary package) from a formula installed with ---build-bottle.

+
bottle [--verbose] [--no-rebuild|--keep-old] [--skip-relocation] [--root-url=URL] [--force-core-tap] formulae

Generate a bottle (binary package) from a formula installed with +--build-bottle.

+ +

If the formula specifies a rebuild version, it will be incremented in the +generated DSL. Passing --keep-old will attempt to keep it at its +original value, while --no-rebuild will remove it.

+ +

If --verbose is passed, print the bottling commands and any warnings +encountered.

+ +

If --skip-relocation is passed, do not check if the bottle can be marked +as relocatable.

+ +

If --root-url is passed, use the specified URL as the root of the +bottle's URL instead of Homebrew's default.

+ +

If --force-core-tap is passed, build a bottle even if formula is not +in homebrew/core or any installed taps.

+
bottle --merge [--keep-old] [--write [--no-commit]] formulae

Generate a bottle from a formula and print the new DSL merged into the +existing formula.

+ +

If --write is passed, write the changes to the formula file. A new +commit will then be generated unless --no-commit is passed.

bump-formula-pr [--devel] [--dry-run [--write]] [--audit|--strict] [--mirror=URL] [--version=version] [--message=message] (--url=URL --sha256=sha-256|--tag=tag --revision=revision) formula

Creates a pull request to update the formula with a new URL or a new tag.

If a URL is specified, the sha-256 checksum of the new download must @@ -612,8 +637,24 @@ launched with access to IRB or a shell inside the temporary test directory.

not deleted.

Example: brew install jruby && brew test jruby

-
tests [-v] [--coverage] [--generic] [--no-compat] [--only=test_script:line_number] [--seed seed] [--online] [--official-cmd-taps]

Run Homebrew's unit and integration tests.

-
update-test [--commit=commit] [--before=date] [--keep-tmp]

Runs a test of brew update with a new repository clone.

+
tests [--verbose] [--coverage] [--generic] [--no-compat] [--only=test_script[:line_number]] [--seed seed] [--online] [--official-cmd-taps]

Run Homebrew's unit and integration tests. If provided, +--only=test_script runs only test_script_spec.rb, and --seed +randomizes tests with the provided value instead of a random seed.

+ +

If --verbose is passed, print the command that runs the tests.

+ +

If --coverage is passed, also generate code coverage reports.

+ +

If --generic is passed, only run OS-agnostic tests.

+ +

If --no-compat is passed, do not load the compatibility layer when +running tests.

+ +

If --online is passed, include tests that use the GitHub API.

+ +

If --official-cmd-taps is passed, include tests that use any of the +taps for official external commands.

+
update-test [--commit=commit] [--before=date] [--to-tag] [--keep-tmp]

Runs a test of brew update with a new repository clone.

If no arguments are passed, use origin/master as the start commit.

@@ -637,7 +678,7 @@ the new repository clone.

https://github.com/Homebrew/homebrew-bundle

cask

Install macOS applications distributed as binaries: https://github.com/caskroom/homebrew-cask

-
services

Integrates Homebrew formulae with macOS's launchctl manager: +

services

Integrates Homebrew formulae with macOS's launchctl(1) manager: https://github.com/Homebrew/homebrew-services

diff --git a/manpages/brew.1 b/manpages/brew.1 index 405e673012..7cad105713 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -216,7 +216,7 @@ Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to See the docs for examples of using the JSON output: \fIhttp://docs\.brew\.sh/Querying\-Brew\.html\fR . .TP -\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR\fIstd\fR|\fIsuper\fR] [\fB\-\-ignore\-dependencies\fR] [\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] \fIformula\fR +\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR(\fBstd\fR|\fBsuper\fR)] [\fB\-\-ignore\-dependencies\fR|\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR|\fB\-\-force\-bottle\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] [\fB\-\-build\-bottle\fR] \fIformula\fR Install \fIformula\fR\. . .IP @@ -258,6 +258,9 @@ If \fB\-\-HEAD\fR is passed, and \fIformula\fR defines it, install the HEAD vers .IP If \fB\-\-keep\-tmp\fR is passed, the temporary files created during installation are not deleted\. . +.IP +If \fB\-\-build\-bottle\fR is passed, prepare the formula for eventual bottling during installation\. +. .TP \fBinstall\fR \fB\-\-interactive\fR [\fB\-\-git\fR] \fIformula\fR Download and patch \fIformula\fR, then open a shell\. This allows the user to run \fB\./configure \-\-help\fR and otherwise determine how to turn the software package into a Homebrew formula\. @@ -406,7 +409,10 @@ Search for \fItext\fR in the given package manager\'s list\. . .TP \fBsh\fR [\fB\-\-env=std\fR] -Instantiate a Homebrew build environment\. Uses our years\-battle\-hardened Homebrew build logic to help your \fB\./configure && make && make install\fR or even your \fBgem install\fR succeed\. Especially handy if you run Homebrew in an Xcode\-only configuration since it adds tools like \fBmake\fR to your \fBPATH\fR which otherwise build\-systems would not find\. +Start a Homebrew build environment shell\. Uses our years\-battle\-hardened Homebrew build logic to help your \fB\./configure && make && make install\fR or even your \fBgem install\fR succeed\. Especially handy if you run Homebrew in an Xcode\-only configuration since it adds tools like \fBmake\fR to your \fBPATH\fR which otherwise build systems would not find\. +. +.IP +If \fB\-\-env=std\fR is passed, use the standard \fBPATH\fR instead of superenv\'s\. . .TP \fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fIfiles\fR|\fItaps\fR|\fIformulae\fR] @@ -653,12 +659,30 @@ If \fB\-\-display\-filename\fR is passed, every line of output is prefixed with \fBaudit\fR exits with a non\-zero status if any errors are found\. This is useful, for instance, for implementing pre\-commit hooks\. . .TP -\fBbottle\fR [\fB\-\-verbose\fR] [\fB\-\-no\-rebuild\fR] [\fB\-\-keep\-old\fR] [\fB\-\-skip\-relocation\fR] [\fB\-\-root\-url=\fR\fIURL\fR] [\fB\-\-force\-core\-tap\fR]: - +\fBbottle\fR [\fB\-\-verbose\fR] [\fB\-\-no\-rebuild\fR|\fB\-\-keep\-old\fR] [\fB\-\-skip\-relocation\fR] [\fB\-\-root\-url=\fR\fIURL\fR] [\fB\-\-force\-core\-tap\fR] \fIformulae\fR +Generate a bottle (binary package) from a formula installed with \fB\-\-build\-bottle\fR\. +. +.IP +If the formula specifies a rebuild version, it will be incremented in the generated DSL\. Passing \fB\-\-keep\-old\fR will attempt to keep it at its original value, while \fB\-\-no\-rebuild\fR will remove it\. +. +.IP +If \fB\-\-verbose\fR is passed, print the bottling commands and any warnings encountered\. +. +.IP +If \fB\-\-skip\-relocation\fR is passed, do not check if the bottle can be marked as relocatable\. +. +.IP +If \fB\-\-root\-url\fR is passed, use the specified \fIURL\fR as the root of the bottle\'s URL instead of Homebrew\'s default\. +. +.IP +If \fB\-\-force\-core\-tap\fR is passed, build a bottle even if \fIformula\fR is not in homebrew/core or any installed taps\. . .TP -\fBbottle\fR \fB\-\-merge\fR [\fB\-\-no\-commit\fR] [\fB\-\-keep\-old\fR] [\fB\-\-write\fR] -Generate a bottle (binary package) from a formula installed with \fB\-\-build\-bottle\fR\. +\fBbottle\fR \fB\-\-merge\fR [\fB\-\-keep\-old\fR] [\fB\-\-write\fR [\fB\-\-no\-commit\fR]] \fIformulae\fR +Generate a bottle from a formula and print the new DSL merged into the existing formula\. +. +.IP +If \fB\-\-write\fR is passed, write the changes to the formula file\. A new commit will then be generated unless \fB\-\-no\-commit\fR is passed\. . .TP \fBbump\-formula\-pr\fR [\fB\-\-devel\fR] [\fB\-\-dry\-run\fR [\fB\-\-write\fR]] [\fB\-\-audit\fR|\fB\-\-strict\fR] [\fB\-\-mirror=\fR\fIURL\fR] [\fB\-\-version=\fR\fIversion\fR] [\fB\-\-message=\fR\fImessage\fR] (\fB\-\-url=\fR\fIURL\fR \fB\-\-sha256=\fR\fIsha\-256\fR|\fB\-\-tag=\fR\fItag\fR \fB\-\-revision=\fR\fIrevision\fR) \fIformula\fR @@ -816,11 +840,29 @@ If \fB\-\-keep\-tmp\fR is passed, the temporary files created for the test are n Example: \fBbrew install jruby && brew test jruby\fR . .TP -\fBtests\fR [\fB\-v\fR] [\fB\-\-coverage\fR] [\fB\-\-generic\fR] [\fB\-\-no\-compat\fR] [\fB\-\-only=\fR\fItest_script\fR\fB:\fR\fIline_number\fR] [\fB\-\-seed\fR \fIseed\fR] [\fB\-\-online\fR] [\fB\-\-official\-cmd\-taps\fR] -Run Homebrew\'s unit and integration tests\. +\fBtests\fR [\fB\-\-verbose\fR] [\fB\-\-coverage\fR] [\fB\-\-generic\fR] [\fB\-\-no\-compat\fR] [\fB\-\-only=\fR\fItest_script\fR[\fB:\fR\fIline_number\fR]] [\fB\-\-seed\fR \fIseed\fR] [\fB\-\-online\fR] [\fB\-\-official\-cmd\-taps\fR] +Run Homebrew\'s unit and integration tests\. If provided, \fB\-\-only=\fR\fItest_script\fR runs only \fItest_script\fR_spec\.rb, and \fB\-\-seed\fR randomizes tests with the provided value instead of a random seed\. +. +.IP +If \fB\-\-verbose\fR is passed, print the command that runs the tests\. +. +.IP +If \fB\-\-coverage\fR is passed, also generate code coverage reports\. +. +.IP +If \fB\-\-generic\fR is passed, only run OS\-agnostic tests\. +. +.IP +If \fB\-\-no\-compat\fR is passed, do not load the compatibility layer when running tests\. +. +.IP +If \fB\-\-online\fR is passed, include tests that use the GitHub API\. +. +.IP +If \fB\-\-official\-cmd\-taps\fR is passed, include tests that use any of the taps for official external commands\. . .TP -\fBupdate\-test\fR [\fB\-\-commit=\fR\fIcommit\fR] [\fB\-\-before=\fR\fIdate\fR] [\fB\-\-keep\-tmp\fR] +\fBupdate\-test\fR [\fB\-\-commit=\fR\fIcommit\fR] [\fB\-\-before=\fR\fIdate\fR] [\fB\-\-to\-tag\fR] [\fB\-\-keep\-tmp\fR] Runs a test of \fBbrew update\fR with a new repository clone\. . .IP @@ -850,7 +892,7 @@ Install macOS applications distributed as binaries: \fIhttps://github\.com/caskr . .TP \fBservices\fR -Integrates Homebrew formulae with macOS\'s \fBlaunchctl\fR manager: \fIhttps://github\.com/Homebrew/homebrew\-services\fR +Integrates Homebrew formulae with macOS\'s \fBlaunchctl\fR(1) manager: \fIhttps://github\.com/Homebrew/homebrew\-services\fR . .SH "CUSTOM EXTERNAL COMMANDS" Homebrew, like \fBgit\fR(1), supports external commands\. These are executable scripts that reside somewhere in the \fBPATH\fR, named \fBbrew\-\fR\fIcmdname\fR or \fBbrew\-\fR\fIcmdname\fR\fB\.rb\fR, which can be invoked like \fBbrew\fR \fIcmdname\fR\. This allows you to create your own commands without modifying Homebrew\'s internals\.