Skip to content
Snippets Groups Projects
Commit 5cae4532 authored by Markus Reiter's avatar Markus Reiter
Browse files

Remove Homebrew Cask documentation.

parent 0c3bb42a
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 0 additions and 1375 deletions
Library/Homebrew/cask/CONDUCT.md deleted 100644 → 0
+ 0
− 74
View file @ 0c3bb42a
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team. All complaints will be reviewed and
investigated and will result in a response that is deemed necessary and
appropriate to the circumstances. The project team is obligated to maintain
confidentiality with regard to the reporter of an incident. Further details of
specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
Library/Homebrew/cask/CONTRIBUTING.md deleted 100644 → 0
+ 0
− 71
View file @ 0c3bb42a
# How To Contribute
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
* [Updating a Cask](#updating-a-cask)
* [Getting Set Up To Contribute](#getting-set-up-to-contribute)
* [Adding a Cask](#adding-a-cask)
* [Style guide](#style-guide)
* [Reporting Bugs](README.md#reporting-bugs)
## Updating a Cask
Notice an application that's out-of-date in Homebrew-Cask? In most cases, it's very simple to update it. We have a [script](https://github.com/vitorgalvao/tiny-scripts/blob/master/cask-repair) that will ask for the new version number, and take care of updating the Cask file and submitting a pull request to us:
```bash
# install and setup script - only needed once
brew install vitorgalvao/tiny-scripts/cask-repair
cask-repair --help
# fork homebrew-cask to your account - only needed once
cd "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/Casks"
hub fork
# use to update <outdated_cask>
outdated_cask='<the-cask-i-want-to-update>'
github_user='<my-github-username>'
cd "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/Casks"
cask-repair --pull origin --push $github_user $outdated_cask
```
If there is a more complicated change, or there is a case where `cask-repair` fails, you can also follow the steps in [Adding a Cask](doc/development/adding_a_cask.md) to do the same thing manually. Remember to update the `version` and `shasum` values, as well as the appcast [`checkpoint`](doc/cask_language_reference/stanzas/appcast.md), if there is one.
## Getting Set Up To Contribute
For manual updates, you'll need to fork the repository and add your copy as a remote (can also be done with `hub fork`).
1. Fork the repository in GitHub with the `Fork` button.
2. Add your GitHub fork as a remote for your homebrew-cask Tap:
```bash
$ github_user='<my-github-username>'
$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
$ git remote add "$github_user" "https://github.com/$github_user/homebrew-cask"
```
3. Switch to a new branch (ie. `new-feature`), and work from there: `git checkout -b new-feature`
## Adding a Cask
Notice an application that's not in Homebrew-Cask yet? Make sure it's not yet in [Homebrew-Versions](https://github.com/caskroom/homebrew-versions) (can be searched from the Github repository page) or [Homebrew](https://github.com/Homebrew/homebrew) (can be searched with `brew search`). Mac App Store apps can't be installed via Homebrew-Cask, but check out [mas](https://github.com/argon/mas) for an alternative.
With a bit of work, you can create a Cask for it. [This document](doc/development/adding_a_cask.md) will walk you through creating a new Cask, testing it, and submitting it to us.
## Style guide
Some style guidelines:
* All Casks and code should be indented using two spaces (never tabs)
* There should not be any extraneous comments - the only comments that should be used are the ones explicitly defined in the [Cask Language Reference](doc/cask_language_reference)
* The stanza order and position of newlines is important to make things easier (See [Stanza order](doc/cask_language_reference/#stanza-order))
* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](doc/cask_language_reference/stanzas/version.md#version-methods))
* Test your cask using `brew cask audit/style` (See [testing](doc/development/adding_a_cask.md#testing-your-new-cask))
* Make one Pull Request per Cask change
* Squash commits after updating a Pull Request
* Use descriptive commit messages - mention app name and version (ie. `Upgrade Transmission.app to v2.82`)
Library/Homebrew/cask/README.md deleted 100644 → 0
+ 0
− 73
View file @ 0c3bb42a
# Homebrew-Cask
_“To install, drag this icon…” no more!_
Homebrew-Cask extends [Homebrew](http://brew.sh) and brings its elegance, simplicity, and speed to the installation and management of GUI macOS applications such as Google Chrome and Adium.
We do this by providing a friendly Homebrew-style CLI workflow for the administration of macOS applications distributed as binaries.
It’s implemented as a `homebrew` [external command](https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md) called `cask`.
[![Join the chat at https://gitter.im/caskroom/homebrew-cask](https://img.shields.io/badge/gitter-join%20chat-blue.svg)](https://gitter.im/caskroom/homebrew-cask)
## Let’s try it!
To start using Homebrew-Cask, you just need [Homebrew](http://brew.sh/) installed.
<img src="https://i.imgur.com/WYa2557.gif" width="450px" alt="Installing Atom (animated gif)">
Slower, now:
```
$ brew cask install atom
==> Satisfying dependencies
complete
==> Downloading https://github.com/atom/atom/releases/download/v1.8.0/atom-mac.zip
######################################################################## 100.0%
==> Verifying checksum for Cask atom
==> Moving App 'Atom.app' to '/Applications/Atom.app'
==> Symlinking Binary 'apm' to '/usr/local/bin/apm'
==> Symlinking Binary 'atom.sh' to '/usr/local/bin/atom'
🍺 atom was successfully installed!
```
And there we have it. Atom installed with one quick command: no clicking, no dragging, no dropping.
## Learn More
* Find basic documentation on using Homebrew-Cask in [USAGE.md](USAGE.md)
* Want to contribute a Cask? Awesome! See [CONTRIBUTING.md](CONTRIBUTING.md)
* Want to hack on our code? Also awesome! See [hacking.md](doc/development/hacking.md)
* More project-related details and discussion are available in the [documentation](doc)
## Reporting bugs
Like most pieces of software, Homebrew-Cask has bugs — and we are busy fixing them! If you find a new bug tell us about it, but before you do make sure the problem isn’t simply an outdated setup on your side, by following [this guide](doc/reporting_bugs/pre_bug_report.md).
If your issue persists, follow these instructions to the appropriate course of action:
* [A cask fails to install](doc/reporting_bugs/a_cask_fails_to_install.md)
* [`brew cask list` shows wrong information](doc/reporting_bugs/brew_cask_list_shows_wrong_information.md)
* [`uninstall` wrongly reports cask as not installed](doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md)
* [My problem isn’t listed][bug_report_template]
## Requests
* Start an issue on GitHub following one of these templates:
* [Feature request][feature_request_template]
* [Cask request][cask_request_template]
## Questions? Wanna chat?
We’re really rather friendly! Here are the best places to talk about the project:
* If none of the templates above is appropriate, [open an issue](https://github.com/caskroom/homebrew-cask/issues/new).
* Join us (and [caskbot](https://github.com/passcod/caskbot)) on IRC at `#homebrew-cask` on Freenode
* Join us on [Gitter](https://gitter.im/caskroom/homebrew-cask)
## License
Code is under the [BSD 2 Clause (NetBSD) license](LICENSE)
[bug_report_template]: https://github.com/caskroom/homebrew-cask/issues/new?title=Bug%20report%3A&body=Remember%20to%20follow%20the%20%5Bpre%20bug%20report%5D%28https%3A%2F%2Fgithub.com%2Fcaskroom%2Fhomebrew-cask%2Fblob%2Fmaster%2Fdoc%2Freporting_bugs%2Fpre_bug_report.md%29%20guide%20beforehand.%20Failure%20to%20do%20so%20might%20get%20your%20issue%20closed.%0A%0A%23%23%23%23%20Description%20of%20issue%0A%0A%5Binsert%20a%20detailed%20description%20of%20your%20issue%20here%5D%0A%0A%3Cdetails%3E%3Csummary%3EOutput%20of%20%60brew%20cask%20%3Ccommand%3E%20--verbose%60%3C%2Fsummary%3E%0A%0A%60%60%60%0A%5Bpaste%20output%20here%5D%0A%60%60%60%0A%3C%2Fdetails%3E%0A%0A%3Cdetails%3E%3Csummary%3EOutput%20of%20%60brew%20doctor%60%3C%2Fsummary%3E%0A%0A%60%60%60%0A%5Bpaste%20output%20here%5D%0A%60%60%60%0A%3C%2Fdetails%3E%0A%0A%3Cdetails%3E%3Csummary%3EOutput%20of%20%60brew%20cask%20doctor%60%3C%2Fsummary%3E%0A%0A%60%60%60%0A%5Bpaste%20output%20here%5D%0A%60%60%60%0A%3C%2Fdetails%3E%0A
[cask_request_template]: https://github.com/caskroom/homebrew-cask/issues/new?title=Cask%20request%3A&body=%23%23%23%20Cask%20details%0A%0A%28Please%20fill%20out%20as%20much%20as%20possible%29%0A%0A%2A%2AName%2A%2A%20-%0A%0A%2A%2AHomepage%2A%2A%20-%0A%0A%2A%2ALicense%2A%2A%20-%0A%0A%2A%2ADownload%20URL%2A%2A%20-%0A%0A%2A%2ADescription%2A%2A%20-%0A
[feature_request_template]: https://github.com/caskroom/homebrew-cask/issues/new?title=Feature%20request%3A&body=%23%23%23%20Description%20of%20feature%2Fenhancement%0A%0A%0A%0A%23%23%23%20Justification%0A%0A%0A%0A%23%23%23%20Example%20use%20case%0A%0A%0A%0A
Library/Homebrew/cask/USAGE.md deleted 100644 → 0
+ 0
− 230
View file @ 0c3bb42a
# How to Use Homebrew-Cask
## Getting Started
First ensure you have Homebrew version `0.9.5` or higher:
```bash
$ brew --version
0.9.5
```
## Frequently Used Commands
Homebrew-Cask is implemented as a subcommand of Homebrew. All Homebrew-Cask commands begin with `brew cask`. Homebrew-Cask has its own set of command verbs many of which are similar to Homebrew’s. The most frequently-used
commands are:
* `search` — searches all known Casks
* `install` — installs the given Cask
* `uninstall` — uninstalls the given Cask
## Searching for Casks
The `brew cask search` command accepts a series of substring arguments, and returns tokens representing matching Casks. Let’s see if there’s a Cask for Google Chrome:
```bash
$ brew cask search chrome
google-chrome
```
A `search` command with no search term will list all available Casks:
```bash
$ brew cask search
# <list of all available Casks>
```
## Installing Casks
The command `brew cask install` accepts a Cask token as returned by `brew cask search`. Let’s try to install Google Chrome:
```bash
$ brew cask install google-chrome
==> Downloading https://dl.google.com/chrome/mac/stable/GGRO/googlechrome.dmg
==> Moving App 'Google Chrome.app' to '/Applications/Google Chrome.app'
🍺 google-chrome was successfully installed!
```
## Uninstalling Casks
Easy peasy:
```bash
$ brew cask uninstall google-chrome
```
This will both uninstall the Cask and remove applications which were moved to `/Applications`.
To uninstall all versions of a Cask, use `--force`:
```bash
$ brew cask uninstall --force google-chrome
```
Note that `uninstall --force` is currently imperfect. See the man page for more information.
## Other Commands
* `info` — displays information about the given Cask
* `list` — with no args, lists installed Casks; given installed Casks, lists staged files
* `fetch` — downloads remote application files for the given Cask to the local cache (with `--force`, re-download even if already cached)
* `doctor` — checks for configuration issues
* `cleanup` — cleans up cached downloads (with `--outdated`, only cleans old downloads)
* `home` — opens the homepage of the given Cask; or with no arguments, the Homebrew-Cask project page
* `update` — a synonym for `brew update`
* `zap` — try to remove *all* files associated with a Cask (may include resources shared with other applications)
The following commands are for Cask authors:
* `audit` — verifies installability of Casks
* `cat` — dumps the given Cask to the standard output
* `create` — creates a Cask and opens it in an editor
* `edit` — edits the given Cask
The following aliases and abbreviations are provided for convenience:
* `ls` — `list`
* `-S` — `search`
* `rm`, `remove` — `uninstall`
* `up` — `update`
* `dr` — `doctor`
## Tab Completion
[Homebrew/homebrew-completions](https://github.com/Homebrew/homebrew-completions) supports `bash` and `fish` completions (only for `brew-cask` right now). Install them with:
```bash
$ brew install homebrew/completions/brew-cask-completion
```
For `zsh` completion support, simply run:
```bash
$ brew install zsh-completions
```
## Inspecting Installed Casks
List all installed Casks:
```bash
$ brew cask list
adium google-chrome onepassword
```
Show details about a specific Cask:
```bash
$ brew cask info caffeine
caffeine: 1.1.1
http://lightheadsw.com/caffeine/
Not installed
From: https://github.com/caskroom/homebrew-cask/blob/master/Casks/caffeine.rb
==> Name
Caffeine
==> Artifacts
Caffeine.app (app)
```
## Updating/Upgrading Casks
Since the Homebrew-Cask repository is a Homebrew Tap, you’ll pull down the latest Casks every time you issue the regular Homebrew command `brew update`. Currently, Homebrew-Cask cannot always detect if an application has been updated. You can force an update via the command `brew cask install --force`. We are working on improving this.
It is generally safe to run updates from within an application.
## Updating/Upgrading the Homebrew-Cask Tool
Homebrew [automatically taps and keeps Homebrew-Cask updated](https://github.com/caskroom/homebrew-cask/pull/15381). `brew update` is all that is required.
## Additional Taps (optional)
The primary Homebrew-Cask Tap includes most of the Casks that a typical user will be interested in. There are a few additional Taps where we store different kinds of Casks.
| Tap name | description |
| -------- | ----------- |
| [caskroom/versions](https://github.com/caskroom/homebrew-versions) | contains alternate versions of Casks (e.g. betas, nightly releases, old versions)
| [caskroom/fonts](https://github.com/caskroom/homebrew-fonts) | contains Casks that install fonts, which are kept separate so we can educate users about the different licensing landscape around font installation/usage
| [caskroom/eid](https://github.com/caskroom/homebrew-eid) | contains Casks that install electronic identity card software of various countries
You can tap any of the above with a `brew tap` command:
```bash
$ brew tap <tap_name>
```
after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap. `brew update` will automatically keep your new Tap up to date.
You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew cask` command. This will implicitly add the Tap if you have not previously added it with `brew tap`:
```bash
$ brew cask install caskroom/fonts/font-symbola
```
## Options
`brew cask` accepts a number of options:
* `--version`: print version and exit
* `--debug`: output debug information
* `--no-binaries`: skip symlinking executable binaries into `/usr/local/bin`
* `--require-sha`: abort installation of cask if no checksum is defined
You can also modify the default installation locations used when issuing `brew cask install`:
* `--caskroom=/my/path` determines where the actual applications will be located.
Default is `$(brew --repository)/Caskroom`
* `--appdir=/my/path` changes the path where the applications (above)
will be moved. Default is `/Applications`.
* `--prefpanedir=/my/path` changes the path for PreferencePanes.
Default is `~/Library/PreferencePanes`
* `--qlplugindir=/my/path` changes the path for Quicklook Plugins.
Default is `~/Library/QuickLook`
* `--fontdir=/my/path` changes the path for Fonts.
Default is `~/Library/Fonts`
* `--input_methoddir=/my/path` changes the path for Input Methods.
Default is `~/Library/Input Methods`
* `--screen_saverdir=/my/path` changes the path for Screen Savers.
Default is `~/Library/Screen Savers`
To make these settings persistent, you might want to add the following line to your `.bash_profile` or `.zshenv`:
```bash
# Specify your defaults in this environment variable
export HOMEBREW_CASK_OPTS="--appdir=~/Applications --caskroom=/etc/Caskroom"
```
Note that you still can override the environment variable `HOMEBREW_CASK_OPTS` by _explicitly_ providing options in the command line:
```bash
# Will force the Chrome app to be moved to /Applications
# even though HOMEBREW_CASK_OPTS specified ~/Applications
$ brew cask install --appdir="/Applications" google-chrome
```
## Advanced Searching
The default search algorithm is a lax substring approach, which does not use the command-line arguments exactly as given. If you need to specify a search more precisely, a single search argument enclosed in `/` characters will be taken as a Ruby regular expression:
```bash
$ brew cask search '/^google.c[a-z]rome$/'
google-chrome
```
## Other Ways to Specify a Cask
Most `brew cask` commands can accept a Cask token as an argument. As described above, the token on the command line can take the form of:
* A token as returned by `brew cask search`, _eg_: `google-chrome`.
* A fully-qualified token which includes the Tap, _eg_: `caskroom/fonts/font-symbola`.
`brew cask` also accepts three other forms as arguments:
* A path to a Cask file, _eg_: `/usr/local/Library/Taps/caskroom/homebrew-cask/Casks/google-chrome.rb`.
* A `curl`-retrievable URI to a Cask file, _eg_: `https://raw.githubusercontent.com/caskroom/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb`.
* A file in the current working directory, _eg_: `my-modfied-google-chrome.rb`. Note that matching Tapped Cask tokens will be preferred over this form when there is a conflict. To force the use of a Cask file in the current directory, specify a pathname with slashes, _eg_: `./google-chrome.rb`.
The last three forms are intended for users who wish to maintain private Casks.
## Taps
You can add Casks to your existing (or new) Taps: just create a directory named `Casks` inside your Tap, put your Cask files there, and everything will just work.
Library/Homebrew/cask/doc/cask_language_reference/all_stanzas.md deleted 100644 → 0
+ 0
− 58
View file @ 0c3bb42a
# All stanzas
## Required Stanzas
Each of the following stanzas is required for every Cask.
| name | multiple occurrences allowed? | value |
| ------------------ |------------------------------ | ----------- |
| `version` | no | application version; give value of `:latest` if versioned downloads are not offered
| `sha256` | no | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be suppressed by using the special value `:no_check` (see also [Checksum Stanza Details](stanzas/sha256.md))
| `url` | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />A [comment](stanzas/url.md#when-url-and-homepage-hostnames-differ-add-a-comment) should be added if the hostnames in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit.<br />See [URL Stanza Details](stanzas/url.md) for more information.
| `name` | yes | a string providing the full and proper name defined by the vendor (see also [Name Stanza Details](stanzas/name.md))
| `homepage` | no | application homepage; used for the `brew cask home` command
## At Least One Artifact Stanza Is Also Required
Each Cask must declare one or more *artifacts* (i.e. something to install).
| name | multiple occurrences allowed? | value |
| ------------------ |------------------------------ | ----------- |
| `app` | yes | relative path to an `.app` that should be moved into the `/Applications` folder on installation (see also [App Stanza Details](stanzas/app.md))
| `pkg` | yes | relative path to a `.pkg` file containing the distribution (see also [Pkg Stanza Details](stanzas/pkg.md))
| `binary` | yes | relative path to a Binary that should be linked into the `/usr/local/bin` folder on installation
| `colorpicker` | yes | relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation
| `font` | yes | relative path to a Font that should be linked into the `~/Library/Fonts` folder on installation
| `input_method` | yes | relative path to a Input Method that should be linked into the `~/Library/Input Methods` folder on installation
| `internet_plugin` | yes | relative path to a Service that should be linked into the `~/Library/Internet Plug-Ins` folder on installation
| `prefpane` | yes | relative path to a Preference Pane that should be linked into the `~/Library/PreferencePanes` folder on installation
| `qlplugin` | yes | relative path to a QuickLook Plugin that should be linked into the `~/Library/QuickLook` folder on installation
| `screen_saver` | yes | relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation
| `service` | yes | relative path to a Service that should be linked into the `~/Library/Services` folder on installation
| `audio_unit_plugin`| yes | relative path to an Audio Unit plugin that should be linked into the `~/Library/Audio/Components` folder on installation
| `vst_plugin` | yes | relative path to a VST Plugin that should be linked into the `~/Library/Audio/VST` folder on installation
| `vst3_plugin` | yes | relative path to a VST3 Plugin that should be linked into the `~/Library/Audio/VST3` folder on installation
| `suite` | yes | relative path to a containing directory that should be moved into the `/Applications` folder on installation (see also [Suite Stanza Details](stanzas/suite.md))
| `artifact` | yes | relative path to an arbitrary path that should be symlinked on installation. Must provide an absolute path as a `target` (example [alcatraz.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/alcatraz.rb#L12)). This is only for unusual cases. The `app` stanza is strongly preferred when linking `.app` bundles.
| `installer` | yes | describes an executable which must be run to complete the installation (see [Installer Stanza Details](stanzas/installer.md))
| `stage_only` | no | `true`. Assert that the Cask contains no activatable artifacts.
## Optional Stanzas
| name | multiple occurrences allowed? | value |
| ---------------------- |------------------------------ | ----------- |
| `uninstall` | yes | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details](stanzas/uninstall.md))
| `zap` | yes | additional procedures for a more complete uninstall, including user files and shared resources (see also [Zap Stanza Details](stanzas/zap.md))
| `appcast` | no | a URL providing an appcast feed to find updates for this Cask (see also [Appcast Stanza Details](stanzas/appcast.md))
| `depends_on` | yes | a list of dependencies and requirements for this Cask (see also [Depends_on Stanza Details](stanzas/depends_on.md))
| `conflicts_with` | yes | a list of conflicts with this Cask (*not yet functional* see also [Conflicts_with Stanza Details](stanzas/conflicts_with.md))
| `caveats` | yes | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Stanza Details](stanzas/caveats.md))
| `preflight` | yes | a Ruby block containing preflight install operations (needed only in very rare cases)
| `postflight` | yes | a Ruby block containing postflight install operations (see also [Postflight Stanza Details](stanzas/flight.md))
| `uninstall_preflight` | yes | a Ruby block containing preflight uninstall operations (needed only in very rare cases)
| `uninstall_postflight` | yes | a Ruby block containing postflight uninstall operations
| `accessibility_access` | no | `true` if the application should be granted accessibility access
| `container nested:` | no | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc.
| `container type:` | no | a symbol to override container-type autodetect. May be one of: `:air`, `:bz2`, `:cab`, `:dmg`, `:generic_unar`, `:gzip`, `:otf`, `:pkg`, `:rar`, `:seven_zip`, `:sit`, `:tar`, `:ttf`, `:xar`, `:zip`, `:naked`. (example [parse.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/parse.rb#L11))
| `gpg` | no | *stub: not yet functional.* (see also [GPG Stanza Details](stanzas/gpg.md))
| `auto_updates` | no | `true`. Assert the Cask artifacts auto-update. (Use if `Check for Updates…` or similar is present in app menu)
Library/Homebrew/cask/doc/cask_language_reference/readme.md deleted 100644 → 0
+ 0
− 172
View file @ 0c3bb42a
# Synopsis
## Casks Are Ruby Blocks
Each Cask is a Ruby block, beginning with a special header line. The Cask definition itself is always enclosed in a `do … end` block. Example:
```ruby
cask 'alfred' do
version '2.7.1_387'
sha256 'a3738d0513d736918a6d71535ef3d85dd184af267c05698e49ac4c6b48f38e17'
url "https://cachefly.alfredapp.com/Alfred_#{version}.zip"
name 'Alfred'
homepage 'https://www.alfredapp.com/'
app 'Alfred 2.app'
app 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
postflight do
suppress_move_to_applications key: 'suppressMoveToApplications'
end
end
```
## The Cask Language Is Declarative
Each Cask contains a series of stanzas (or “fields”) which *declare* how the software is to be obtained and installed. In a declarative language, the author does not need to worry about **order**. As long as all the needed fields are present, Homebrew-Cask will figure out what needs to be done at install time.
To make maintenance easier, the most-frequently-updated stanzas are usually placed at the top. But that’s a convention, not a rule.
Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby code. Lines within that block follow a procedural (order-dependent) paradigm.
## Conditional Statements
### Efficiency
Conditional statements are permitted, but only if they are very efficient.
Tests on the following values are known to be acceptable:
| value | examples
| ----------------------------|--------------------------------------
| `MacOS.version` | [macports.rb](https://github.com/caskroom/homebrew-cask/blob/9eae0af0daf9b55f81a3af010cca3b0b1272e2db/Casks/macports.rb#L4#L20), [coconutbattery.rb](https://github.com/caskroom/homebrew-cask/blob/2c801af44be29fff7f3cb2996455fce5dd95d1cc/Casks/coconutbattery.rb#L3#L17)
| `Hardware::CPU.is_32_bit?` | [vuescan.rb](https://github.com/caskroom/homebrew-cask/blob/655bfe48b41ae94cb81b1003182b8de5fa2995ef/Casks/vuescan.rb#L5#L9)
| `Hardware::CPU.is_64_bit?` | none, see [Always Fall Through to the Newest Case](#always-fall-through-to-the-newest-case)
### Version Comparisons
Tests against `MacOS.version` may use either symbolic names or version
strings with numeric comparison operators:
```ruby
if MacOS.version <= :mavericks # symbolic name
```
```ruby
if MacOS.version <= '10.9' # version string
```
The available symbols for macOS versions are: `:cheetah`, `:puma`, `:jaguar`, `:panther`, `:tiger`, `:leopard`, `:snow_leopard`, `:lion`, `:mountain_lion`, `:mavericks`, `:yosemite`, `:el_capitan`, and `:sierra`. The corresponding numeric version strings should given as major releases containing a single dot.
### Always Fall Through to the Newest Case
Conditionals should be constructed so that the default is the newest OS version or hardware type. When using an `if` statement, test for older versions, and then let the `else` statement hold the latest and greatest. This makes it more likely that the Cask will work without alteration when a new OS is released. Example (from [coconutbattery.rb](https://github.com/caskroom/homebrew-cask/blob/2c801af44be29fff7f3cb2996455fce5dd95d1cc/Casks/coconutbattery.rb)):
```ruby
if MacOS.version <= :tiger
# ...
elsif MacOS.version <= :snow_leopard
# ...
else
# ...
end
```
## Arbitrary Ruby Methods
In the exceptional case that the Cask DSL is insufficient, it is possible to define arbitrary Ruby variables and methods inside the Cask by creating a `Utils` namespace. Example:
```ruby
cask 'myapp' do
module Utils
def self.arbitrary_method
...
end
end
name 'MyApp'
version '1.0'
sha256 'a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92'
url "https://#{Utils.arbitrary_method}"
homepage 'https://www.example.com/'
...
end
```
This should be used sparingly: any method which is needed by two or more Casks should instead be rolled into the core. Care must also be taken that such methods be very efficient.
Variables and methods should not be defined outside the `Utils` namespace, as they may collide with Homebrew-Cask internals.
## Header Line Details
The first non-comment line in a Cask follows the form:
```ruby
cask '<cask-token>' do
```
[`<cask-token>`](token_reference.md) should match the Cask filename, without the `.rb` extension,
enclosed in single quotes.
The header line is not entirely strict Ruby: no comma is required after the Cask token.
There are currently some arbitrary limitations on Cask tokens which are in the process of being removed. The Travis bot will catch any errors during the transition.
## Stanza order
Having a common order for stanzas makes Casks easier to update and parse. Below is the the complete stanza sequence (no Cask will have all stanzas). The empty lines shown here are also important, as they help to visually delineate information.
```
version
sha256
url
appcast,
checkpoint: # shown here as it is required with `appcast`
name
homepage
gpg, key_id: # on same line, since first part is typically small
auto_updates
accessibility_access
conflicts_with
depends_on
container
suite
app
pkg
installer
binary
colorpicker
font
input_method
internet_plugin
prefpane
qlplugin
screen_saver
service
audio_unit_plugin
vst_plugin
vst3_plugin
artifact, target: # :target shown here as is required with `artifact`
stage_only
preflight
postflight
uninstall_preflight
uninstall_postflight
uninstall
zap
caveats
```
Note that every stanza that has additional parameters (`:symbols` after a `,`) shall have them on separate lines, one per line, in alphabetical order. Exceptions are `gpg` and `target:` (when not applied to `url`) which typically consist of short lines.
Library/Homebrew/cask/doc/cask_language_reference/stanzas/app.md deleted 100644 → 0
+ 0
− 43
View file @ 0c3bb42a
# app
In the simple case of a string argument to `app`, the source file is moved to the target `~/Applications` directory. For example:
```ruby
app 'Alfred 2.app'
```
moves the source to:
```bash
/Applications/Alfred 2.app
```
from a source file such as:
```bash
/usr/local/Caskroom/alfred/2.8.2_431/Alfred 2.app
```
## Renaming the Target
You can rename the target which appears in your `/Applications` directory by adding a `target:` key to `app`. Example (from [scala-ide.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/scala-ide.rb#L21)):
```ruby
app 'eclipse/Eclipse.app', target: 'Scala IDE.app'
```
## target: May Contain an Absolute Path
If `target:` has a leading slash, it is interpreted as an absolute path. The containing directory for the absolute path will be created if it does not already exist. Example (from [manopen.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/manopen.rb#L12)):
```ruby
artifact 'openman.1', target: '/usr/local/share/man/man1/openman.1'
```
## target: Works on Most Artifact Types
The `target:` key works similarly for most Cask artifacts, such as `app`, `binary`, `colorpicker`, `font`, `input_method`, `prefpane`, `qlplugin`, `service`, `suite`, and `artifact`.
## target: Should Only Be Used in Select Cases
Don’t use `target:` for aesthetic reasons, like removing version numbers (`app "Slack #{version}.app", target: 'Slack.app'`). With `app`, use it when it makes sense functionally and document your reason cleary in the Cask: was it [for clarity](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/imagemin.rb#L12); [for consistency](https://github.com/caskroom/homebrew-cask/blob/d2a6b26df69fc28c4d84d6f5198b2b652c2f414d/Casks/devonthink-pro-office.rb#L16); [to prevent conflicts](https://github.com/caskroom/homebrew-cask/blob/bd6dc1a64e0bdd35ba0e20789045ea023b0b6aed/Casks/flash-player-debugger.rb#L11#L12); [due to developer suggestion](https://github.com/caskroom/homebrew-cask/blob/ff3e9c4a6623af44b8a071027e8dcf3f4edfc6d9/Casks/kivy.rb#L12)? With `binary` you can take some extra liberties to be consistent with other command-line tools, like [changing case](https://github.com/caskroom/homebrew-cask/blob/6e4eb6ba58ca0d9e6d42a1d78856cc8a35cf5fce/Casks/diffmerge.rb#L11) or [removing an extension](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/filebot.rb#L12).
Library/Homebrew/cask/doc/cask_language_reference/stanzas/appcast.md deleted 100644 → 0
+ 0
− 23
View file @ 0c3bb42a
# appcast
The value of the `appcast` stanza is a string, holding the URL for an appcast which provides information on future updates.
## Required Appcast Parameters
| key | value |
| ------------- | ----------- |
| `checkpoint:` | a string holding a custom checksum of the most recent appcast which matches the current Cask versioning. Use `curl --compressed --location --user-agent 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/33.0.1750.152 Safari/537.36' "{{appcast_url}}" | sed 's|<pubDate>[^<]*</pubDate>||g' | shasum --algorithm 256` to calculate it.
Example: [`atom`](https://github.com/caskroom/homebrew-cask/blob/161f85b605e160ff96e7dd11732d85609e13dc51/Casks/atom.rb#L7L8)
There are a few different ways the `appcast` can be determined:
* If the app is distributed via GitHub releases, the `appcast` will be of the form `https://github.com/{{user}}/{{project}}/releases.atom`. (Example Cask: [`electron`](https://github.com/caskroom/homebrew-cask/blob/161f85b605e160ff96e7dd11732d85609e13dc51/Casks/electron.rb#L6L7))
* The popular update framework [Sparkle](https://sparkle-project.org/) generally uses the `SUFeedURL` property in `Contents/Info.plist` inside `.app` bundles. You can use the script [`find_sparkle_appcast`](https://github.com/caskroom/homebrew-cask/blob/master/developer/bin/find_sparkle_appcast) to add this automatically. (Example Cask: [`glyphs`](https://github.com/caskroom/homebrew-cask/blob/161f85b605e160ff96e7dd11732d85609e13dc51/Casks/glyphs.rb#L6L7))
* Sourceforge projects follow the form `https://downloads.sourceforge.net/projects/{{project_name}}/rss`. A more specific page can be used as needed, pointing to a specific directory structure: `https://sourceforge.net/projects/{{project_name}}/rss?path=/{{path_here}}`. (Example Cask: [`seashore`](https://github.com/caskroom/homebrew-cask/blob/bcff548278a6776fc57439603442a8b23c76bd8b/Casks/seashore.rb#L6L7))
* HockeyApp URLs are of the form `https://rink.hockeyapp.net/api/2/apps/HEXADECIMAL_STRING<SOMETHING_ELSE>`. For the `appcast`, remove `<SOMETHING_ELSE>` (ending up with `https://rink.hockeyapp.net/api/2/apps/HEXADECIMAL_STRING`. (Example Cask: [`iconjar`](https://github.com/caskroom/homebrew-cask/blob/bcff548278a6776fc57439603442a8b23c76bd8b/Casks/iconjar.rb#L7L8))
* An appcast can be any URL hosted by the app’s developer that changes every time a new release is out (e.g. a changelog HTML page). (Example Cask: [`shortcat`](https://github.com/caskroom/homebrew-cask/blob/161f85b605e160ff96e7dd11732d85609e13dc51/Casks/shortcat.rb#L6L7))
Library/Homebrew/cask/doc/cask_language_reference/stanzas/caveats.md deleted 100644 → 0
+ 0
− 53
View file @ 0c3bb42a
# caveats
Sometimes there are particularities with the installation of a piece of software that cannot or should not be handled programatically by Homebrew-Cask. In those instances, `caveats` is the way to inform the user. Information in `caveats` is displayed when a cask is invoked with either `install` or `info`.
To avoid flooding users with too many messages (thus desensitising them to the important ones), `caveats` should be used sparingly and exclusively for installation-related matters. If you’re not sure a `caveat` you find pertinent is installation-related or not, ask a maintainer. As a general rule, if your case isn’t already covered in our comprehensive [`caveats Mini-DSL`](#caveats-mini-dsl), it’s unlikely to be accepted.
## caveats as a String
When `caveats` is a string, it is evaluated at compile time. The following methods are available for interpolation if `caveats` is placed in its customary position at the end of the Cask:
| method | description |
| ------------------ | ----------- |
| `token` | the Cask token
| `version` | the Cask version
| `homepage` | the Cask homepage
| `caskroom_path` | the containing directory for all staged Casks, typically `/usr/local/Caskroom` (only available with block form)
| `staged_path` | the staged location for this Cask, including version number, *eg* `/usr/local/Caskroom/adium/1.5.10` (only available with block form)
Example:
```ruby
caveats "Using #{token} is hazardous to your health."
```
## caveats as a Block
When `caveats` is a Ruby block, evaluation is deferred until install time. Within a block you may refer to the `@cask` instance variable, and invoke any method available on `@cask`.
## caveats Mini-DSL
There is a mini-DSL available within `caveats` blocks.
The following methods may be called to generate standard warning messages:
| method | description |
| --------------------------------- | ----------- |
| `path_environment_variable(path)` | users should make sure `path` is in their `$PATH` environment variable
| `zsh_path_helper(path)` | zsh users must take additional steps to make sure `path` is in their `$PATH` environment variable
| `depends_on_java(version)` | users should make sure they have the specified version of java installed. `version` can be exact (e.g. `6`), a minimum (e.g. `7+`), or omitted (when any version works).
| `logout` | users should log out and log back in to complete installation
| `reboot` | users should reboot to complete installation
| `files_in_usr_local` | the Cask installs files to `/usr/local`, which may confuse Homebrew
| `discontinued` | all software development has been officially discontinued upstream
| `free_license(web_page)` | users may get an official license to use the software at `web_page`
| `malware(radar_number)` | app has been reported to bundle malware. See [the FAQ](https://github.com/caskroom/homebrew-cask/blob/master/doc/faq/apps_with_malware.md) for the necessary steps.
Example:
```ruby
caveats do
path_environment_variable '/usr/texbin'
end
```
Library/Homebrew/cask/doc/cask_language_reference/stanzas/conflicts_with.md deleted 100644 → 0
+ 0
− 14
View file @ 0c3bb42a
# conflicts_with
`conflicts_with` is used to declare conflicts that keep a Cask from installing or working correctly.
Several keys are accepted by `conflicts_with`, but none of them are yet enforced by the backend implementation. It is fine to proactively add `conflicts_with` stanzas to Casks in anticipation of future backend support; they are currently just a type of structured comment.
| key | description |
| ---------- | ----------- |
| `formula:` | *stub - not yet functional*
| `cask:` | *stub - not yet functional*
| `macos:` | *stub - not yet functional*
| `arch:` | *stub - not yet functional*
| `x11:` | *stub - not yet functional*
| `java:` | *stub - not yet functional*
Library/Homebrew/cask/doc/cask_language_reference/stanzas/depends_on.md deleted 100644 → 0
+ 0
− 109
View file @ 0c3bb42a
# depends_on
`depends_on` is used to declare dependencies and requirements for a Cask.
`depends_on` is not consulted until `install` is attempted.
## depends_on cask:
The value should be another Cask token, needed by the current Cask.
Example use: [`SSHFS`](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/sshfs.rb#L12) depends on OSXFUSE:
```ruby
depends_on cask: 'osxfuse'
```
## depends_on formula:
The value should name a Homebrew Formula needed by the Cask.
Example use: some distributions are contained in archive formats such as `7z` which are not supported by stock Apple tools. For these cases, a more capable archive reader may be pulled in at install time by declaring a dependency on the Homebrew Formula `unar`:
```ruby
depends_on formula: 'unar'
```
## depends_on macos:
### Requiring an Exact macOS Release
The value for `depends_on macos:` may be a symbol, string, or an array, listing the exact compatible macOS releases.
The available values for macOS releases are:
| symbol | corresponding string
| -------------------|----------------------
| `:cheetah` | `'10.0'`
| `:puma` | `'10.1'`
| `:jaguar` | `'10.2'`
| `:panther` | `'10.3'`
| `:tiger` | `'10.4'`
| `:leopard` | `'10.5'`
| `:snow_leopard` | `'10.6'`
| `:lion` | `'10.7'`
| `:mountain_lion` | `'10.8'`
| `:mavericks` | `'10.9'`
| `:yosemite` | `'10.10'`
| `:el_capitan` | `'10.11'`
| `:sierra` | `'10.12'`
Only major releases are covered (version numbers containing a single dot). The symbol form is preferred for readability. The following are all valid ways to enumerate the exact macOS release requirements for a Cask:
```ruby
depends_on macos: :yosemite
depends_on macos: [:mavericks, :yosemite]
depends_on macos: '10.9'
depends_on macos: ['10.9', '10.10']
```
### Setting a Minimum macOS Release
`depends_on macos:` can also accept a string starting with a comparison operator such as `>=`, followed by an macOS release in the form above. The following are both valid expressions meaning “at least macOS 10.9”:
```ruby
depends_on macos: '>= :mavericks'
depends_on macos: '>= 10.9'
```
A comparison expression cannot be combined with any other form of `depends_on macos:`.
## depends_on arch:
The value for `depends_on arch:` may be a symbol or an array of symbols, listing the hardware compatibility requirements for a Cask. The requirement is satisfied at install time if any one of multiple `arch:` value matches the user’s hardware.
The available symbols for hardware are:
| symbol | meaning |
| ---------- | -------------- |
| `:i386` | 32-bit Intel |
| `:x86_64` | 64-bit Intel |
| `:ppc_7400`| 32-bit PowerPC |
| `:ppc_64` | 64-bit PowerPC |
| `:intel` | Any Intel |
| `:ppc` | Any PowerPC |
The following are all valid expressions:
```ruby
depends_on arch: :x86_64
depends_on arch: [:x86_64] # same meaning as above
depends_on arch: :intel
depends_on arch: [:i386, :x86_64] # same meaning as above
```
Since PowerPC hardware is no longer common, the expression most frequently needed will be:
```ruby
depends_on arch: :x86_64
```
## All depends_on Keys
| key | description |
| ---------- | ----------- |
| `formula:` | a Homebrew Formula
| `cask:` | a Cask token
| `macos:` | a symbol, string, array, or comparison expression defining macOS release requirements
| `arch:` | a symbol or array defining hardware requirements
| `x11:` | a Boolean indicating a dependency on X11
| `java:` | *stub - not yet functional*
Library/Homebrew/cask/doc/cask_language_reference/stanzas/flight.md deleted 100644 → 0
+ 0
− 24
View file @ 0c3bb42a
# \*flight
## Evaluation of Blocks is Always Deferred
The Ruby blocks defined by `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` are not evaluated until install time or uninstall time. Within a block, you may refer to the `@cask` instance variable, and invoke any method available on `@cask`.
## \*flight Mini-DSL
There is a mini-DSL available within these blocks.
The following methods may be called to perform standard tasks:
| method | availability | description |
| ----------------------------------------- | ------------------------------------------------ | ----------- |
| `plist_set(key, value)` | `preflight`, `postflight`, `uninstall_preflight` | set a value in the `Info.plist` file for the app bundle. Example: [`rubymine.rb`](https://github.com/caskroom/homebrew-cask/blob/c5dbc58b7c1b6290b611677882b205d702b29190/Casks/rubymine.rb#L12)
| `set_ownership(paths)` | `preflight`, `postflight`, `uninstall_preflight` | set user and group ownership of `paths`. Example: [`unifi-controller.rb`](https://github.com/caskroom/homebrew-cask/blob/8a452a41707af6a661049da6254571090fac5418/Casks/unifi-controller.rb#L13)
| `set_permissions(paths, permissions_str)` | `preflight`, `postflight`, `uninstall_preflight` | set permissions in `paths` to `permissions_str`. Example: [`docker-machine.rb`](https://github.com/caskroom/homebrew-cask/blob/8a452a41707af6a661049da6254571090fac5418/Casks/docker-machine.rb#L16)
| `suppress_move_to_applications` | `postflight` | suppress a dialog asking the user to move the app to the `/Applications` folder. Example: [`github.rb`](https://github.com/caskroom/homebrew-cask/blob/c5dbc58b7c1b6290b611677882b205d702b29190/Casks/github.rb#L13)
`plist_set` currently has the limitation that it only operates on the bundle indicated by the first `app` stanza (and the Cask must contain an `app` stanza).
`set_ownership(paths)` defaults user ownership to the current user and group ownership to `staff`. These can be changed by passing in extra options: `set_ownership(paths, user: 'user', group: 'group')`.
`suppress_move_to_applications` optionally accepts a `:key` parameter for apps which use a nonstandard `defaults` key. Example: [`alfred.rb`](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/alfred.rb#L16).
Library/Homebrew/cask/doc/cask_language_reference/stanzas/gpg.md deleted 100644 → 0
+ 0
− 11
View file @ 0c3bb42a
# gpg Stanza Details
**This is a stub for upcoming functionality, and is not fully documented**.
The `gpg` stanza contains signature information for GPG-signed distributions. The form is:
```ruby
gpg <signature>, <parameter>: <value>
```
where `<parameter>` is one of `key_id:` or `key_url:`, and `<signature>` points to the detached signature of the distribution. Commonly, the signature follows the `url` value. Example: [libreoffice.rb](https://github.com/caskroom/homebrew-cask/blob/42abacc85798d8c0b8d3f47c70b62ee65ce5ceaa/Casks/libreoffice.rb#L16#L17).
Library/Homebrew/cask/doc/cask_language_reference/stanzas/installer.md deleted 100644 → 0
+ 0
− 33
View file @ 0c3bb42a
# installer
This stanza must always be accompanied by [`uninstall`](uninstall.md).
The `installer` stanza takes a series of key-value pairs, the first key of which must be `manual:` or `script:`.
## installer manual:
`installer manual:` takes a single string value, describing a GUI installer which must be run by the user at a later time. The path may be absolute, or relative to the Cask. Example (from [little-snitch.rb](https://github.com/caskroom/homebrew-cask/blob/818047bf488be92923c8770ef3df8007a0db7704/Casks/little-snitch.rb#L10)):
```ruby
installer manual: 'Little Snitch Installer.app'
```
## installer script:
`installer script:` introduces a series of key-value pairs describing a command which will automate completion of the install. The form is similar to `uninstall script:`:
| key | value
| ----------------|------------------------------
| `script:` | path to an install script to be run via `sudo`. (Required first key.)
| `args:` | array of arguments to the install script
| `input:` | array of lines of input to be sent to `stdin` of the script
| `must_succeed:` | set to `false` if the script is allowed to fail
| `sudo:` | set to `false` if the script does not need `sudo`
The path may be absolute, or relative to the Cask. Example (from [adobe-air.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/adobe-air.rb#L10-#L12)):
```ruby
installer script: 'Adobe AIR Installer.app/Contents/MacOS/Adobe AIR Installer',
args: %w[-silent],
sudo: true
```
Library/Homebrew/cask/doc/cask_language_reference/stanzas/name.md deleted 100644 → 0
+ 0
− 9
View file @ 0c3bb42a
# name
`name` accepts a UTF-8 string defining the full name of the software, and is used to help with searchability and disambiguation. It can be repeated multiple times if there are useful alternative names.
Its first instance should use the latin alphabet, include the software vendor’s name, and be as verbose as possible while still making sense.
A good example is [`pycharm-ce`](https://github.com/caskroom/homebrew-cask/blob/fc05c0353aebb28e40db72faba04b82ca832d11a/Casks/pycharm-ce.rb#L6#L7). `Jetbrains PyCharm Community Edition` makes sense even though it is likely never referenced as such anywhere, but `Jetbrains PyCharm Community Edition CE` doesn’t, hence why it has a second line. Another example are casks whose original names do not use the latin alphabet, like [`cave-story`](https://github.com/caskroom/homebrew-cask/blob/0fe48607f5656e4f1de58c6884945378b7e6f960/Casks/cave-story.rb#L7#L9).
Note that `brew cask search` and `brew cask list` are not yet capable of using the information stored in the `name` stanza.
\ No newline at end of file
Library/Homebrew/cask/doc/cask_language_reference/stanzas/pkg.md deleted 100644 → 0
+ 0
− 19
View file @ 0c3bb42a
# pkg
This stanza must always be accompanied by [`uninstall`](uninstall.md)
The first argument to the `pkg` stanza should be a relative path to the `.pkg` file to be installed. For example:
```ruby
pkg 'Unity.pkg'
```
Subsequent arguments to `pkg` are key/value pairs which modify the install process. Currently supported keys are:
* `allow_untrusted:` — pass `-allowUntrusted` to `/usr/sbin/installer`
Example (from [alinof-timer.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/alinof-timer.rb#L10)):
```ruby
pkg 'AlinofTimer.pkg', allow_untrusted: true
```
Library/Homebrew/cask/doc/cask_language_reference/stanzas/sha256.md deleted 100644 → 0
+ 0
− 17
View file @ 0c3bb42a
# sha256
## Calculating the SHA256
The `sha256` value is usually calculated by the command:
```bash
$ shasum -a 256 <file>
```
## Special Value `:no_check`
The special value `sha256 :no_check` is used to turn off SHA checking whenever checksumming is impractical due to the upstream configuration.
`version :latest` requires `sha256 :no_check`, and this pairing is common. However, `sha256 :no_check` does not require `version :latest`.
We use a checksum whenever possible.
\ No newline at end of file
Library/Homebrew/cask/doc/cask_language_reference/stanzas/suite.md deleted 100644 → 0
+ 0
− 11
View file @ 0c3bb42a
# suite
Some distributions provide a suite of multiple applications, or an application with required data, to be installed together in a subdirectory of `/Applications`.
For these Casks, use the `suite` stanza to define the directory containing the application suite. Example (from [sketchup.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/sketchup.rb#L12)):
```ruby
suite 'SketchUp 2016'
```
The value of `suite` is never an `.app` bundle, but a plain directory.
Library/Homebrew/cask/doc/cask_language_reference/stanzas/uninstall.md deleted 100644 → 0
+ 0
− 199
View file @ 0c3bb42a
# uninstall
IF YOU CANNOT DESIGN A WORKING `UNINSTALL` STANZA, PLEASE SUBMIT YOUR CASK ANYWAY. The maintainers will help you write an `uninstall` stanza, just ask!
## uninstall pkgutil: Is The Easiest and Most Useful
`pkgutil:` is the easiest and most useful `uninstall` directive. See [Uninstall Key pkgutil:](#uninstall-key-pkgutil).
## uninstall Is Required for Casks That Install a pkg or installer manual:
For most Casks, uninstall actions are determined automatically, and an explicit `uninstall` stanza is not needed. However, a Cask which uses the `pkg` or `installer manual:` stanzas will **not** know how to uninstall correctly unless an `uninstall` stanza is given.
So, while the Cask language does not enforce the requirement, it is much better for end-users if every `pkg` and `installer manual:` has a corresponding `uninstall`.
The `uninstall` stanza is available for non-`pkg` Casks, and is useful for a few corner cases. However, the documentation below concerns the typical case of using `uninstall` to define procedures for a `pkg`.
## There Are Multiple Uninstall Techniques
Since `pkg` installers can do arbitrary things, different techniques are needed to uninstall in each case. You may need to specify one, or several, of the following key/value pairs as arguments to `uninstall`.
## Summary of Keys
* `early_script:` (string or hash) - like `script:`, but runs early (for special cases, best avoided)
* `launchctl:` (string or array) - ids of `launchctl` jobs to remove
* `quit:` (string or array) - bundle ids of running applications to quit
* `signal:` (array of arrays) - signal numbers and bundle ids of running applications to send a Unix signal to (used when `quit:` does not work)
* `login_item:` (string or array) - names of login items to remove
* `kext:` (string or array) - bundle ids of kexts to unload from the system
* `pkgutil:` (string, regexp or array of strings and regexps) - strings or regexps matching bundle ids of packages to uninstall using `pkgutil`
* `script:` (string or hash) - relative path to an uninstall script to be run via sudo; use hash if args are needed
- `executable:` - relative path to an uninstall script to be run via sudo (required for hash form)
- `args:` - array of arguments to the uninstall script
- `input:` - array of lines of input to be sent to `stdin` of the script
- `must_succeed:` - set to `false` if the script is allowed to fail
- `sudo:` - set to `false` if the script does not need `sudo`
* `delete:` (string or array) - single-quoted, absolute paths of files or directory trees to remove. `delete:` should only be used as a last resort. `pkgutil:` is strongly preferred.
* `rmdir:` (string or array) - single-quoted, absolute paths of directories to remove if empty
* `trash:` (string or array) - currently a synonym for `delete:`. In the future this will cause files to be moved to the Trash.
Each `uninstall` technique is applied according to the order above. The order in which `uninstall` keys appear in the Cask file is ignored.
For assistance filling in the right values for `uninstall` keys, there are several helper scripts found under `developer/bin` in the Homebrew-Cask repository. Each of these scripts responds to the `-help` option with additional documentation.
The easiest way to work out an `uninstall` stanza is on a system where the `pkg` is currently installed and operational. To operate on an uninstalled `pkg` file, see [Working With a pkg File Manually](#working-with-a-pkg-file-manually), below.
## uninstall Key pkgutil:
This is the most useful uninstall key. `pkgutil:` is often sufficient to completely uninstall a `pkg`, and is strongly preferred over `delete:`.
IDs for the most recently-installed packages can be listed using the command:
```bash
$ ./developer/bin/list_recent_pkg_ids
```
`pkgutil:` also accepts a regular expression match against multiple package IDs. The regular expressions are somewhat nonstandard. To test a `pkgutil:` regular expression against currently-installed packages, use the command:
```bash
$ ./developer/bin/list_pkg_ids_by_regexp <regular-expression>
```
## List Files Associated With a pkg Id
Once you know the ID for an installed package, (above), you can list all files on your system associated with that package ID using the macOS command:
```bash
$ pkgutil --files <package.id.goes.here>
```
Listing the associated files can help you assess whether the package included any `launchctl` jobs or kernel extensions (kexts).
## uninstall Key launchctl:
IDs for currently loaded `launchctl` jobs can be listed using the command:
```bash
$ ./developer/bin/list_loaded_launchjob_ids
```
IDs for all installed `launchctl` jobs can be listed using the command:
```bash
$ ./developer/bin/list_installed_launchjob_ids
```
## uninstall Key quit:
Bundle IDs for currently running Applications can be listed using the command:
```bash
$ ./developer/bin/list_running_app_ids
```
Bundle IDs inside an Application bundle on disk can be listed using the command:
```bash
$ ./developer/bin/list_ids_in_app </path/to/application.app>
```
## uninstall Key signal:
`signal:` should only be needed in the rare case that a process does not respond to `quit:`.
Bundle IDs for `signal:` targets may be obtained as for `quit:`. The value for `signal:` is an array-of-arrays, with each cell containing two elements: the desired Unix signal followed by the corresponding bundle ID.
The Unix signal may be given in numeric or string form (see the `kill` man page for more details).
The elements of the `signal:` array are applied in order, only if there is an existing process associated the bundle ID, and stopping when that process terminates. A bundle ID may be repeated to send more than one signal to the same process.
It is better to use the least-severe signals which are sufficient to stop a process. The `KILL` signal in particular can have unwanted side-effects.
An example, with commonly-used signals in ascending order of severity:
```ruby
uninstall signal: [
['TERM', 'fr.madrau.switchresx.daemon'],
['QUIT', 'fr.madrau.switchresx.daemon'],
['INT', 'fr.madrau.switchresx.daemon'],
['HUP', 'fr.madrau.switchresx.daemon'],
['KILL', 'fr.madrau.switchresx.daemon'],
]
```
Note that when multiple running processes match the given Bundle ID, all matching processes will be signaled.
Unlike `quit:` directives, Unix signals originate from the current user, not from the superuser. This is construed as a safety feature, since the superuser is capable of bringing down the system via signals. However, this inconsistency may also be considered a bug, and should be addressed in some fashion in a future version.
## uninstall key login_item:
Login items associated with an Application bundle on disk can be listed using the command:
```bash
$ ./developer/bin/list_login_items_for_app </path/to/application.app>
```
Note that you will likely need to have opened the app at least once for any login items to be present.
## uninstall Key kext:
IDs for currently loaded kernel extensions can be listed using the command:
```bash
$ ./developer/bin/list_loaded_kext_ids
```
IDs inside a kext bundle you have located on disk can be listed using the command:
```bash
$ ./developer/bin/list_id_in_kext </path/to/name.kext>
```
## uninstall Key delete:
`delete:` should only be used as a last resort, if other `uninstall` methods are insufficient.
Arguments to `uninstall delete:` should be static, single-quoted, absolute paths.
* Only single quotes should be used.
* Double-quotes should not be used. `ENV['HOME']` and other variables
should not be interpolated in the value.
* Basic tilde expansion is performed on paths, i.e., leading `~` is expanded to the home directory.
* Only absolute paths should be given.
* No glob expansion is performed (*eg* `*` characters are literal), though glob expansion is a desired future feature.
To remove user-specific files, use the `zap` stanza.
## uninstall Key trash:
*stub* - currently a synonym for `delete:`. In the future this will cause files to be moved to the Trash. It is best not to use this stub until it gains the proper functionality.
## Working With a pkg File Manually
Advanced users may wish to work with a `pkg` file manually, without having the package installed.
A list of files which may be installed from a `pkg` can be extracted using the command:
```bash
$ ./developer/bin/list_payload_in_pkg </path/to/my.pkg>
```
Candidate application names helpful for determining the name of a Cask may be extracted from a `pkg` file using the command:
```bash
$ ./developer/bin/list_apps_in_pkg </path/to/my.pkg>
```
Candidate package IDs which may be useful in a `pkgutil:` key may be extracted from a `pkg` file using the command:
```bash
$ ./developer/bin/list_ids_in_pkg </path/to/my.pkg>
```
A fully manual method for finding bundle ids in a package file follows:
1. Unpack `/path/to/my.pkg` (replace with your package name) with `pkgutil --expand /path/to/my.pkg /tmp/expanded.unpkg`.
2. The unpacked package is a folder. Bundle ids are contained within files named `PackageInfo`. These files can be found with the command `find /tmp/expanded.unpkg -name PackageInfo`.
3. `PackageInfo` files are XML files, and bundle ids are found within the `identifier` attributes of `<pkg-info>` tags that look like `<pkg-info ... identifier="com.oracle.jdk7u51" ... >`, where extraneous attributes have been snipped out and replaced with ellipses.
4. Kexts inside packages are also described in `PackageInfo` files. If any kernel extensions are present, the command `find /tmp/expanded.unpkg -name PackageInfo -print0 | xargs -0 grep -i kext` should return a `<bundle id>` tag with a `path` attribute that contains a `.kext` extension, for example `<bundle id="com.wavtap.driver.WavTap" ... path="./WavTap.kext" ... />`.
5. Once bundle ids have been identified, the unpacked package directory can be deleted.
Library/Homebrew/cask/doc/cask_language_reference/stanzas/url.md deleted 100644 → 0
+ 0
− 132
View file @ 0c3bb42a
# url
## HTTPS URLs are Preferred
If available, an HTTPS URL is preferred. A plain HTTP URL should only be used in the absence of a secure alternative.
## Additional HTTP/S URL Parameters
When a plain URL string is insufficient to fetch a file, additional information may be provided to the `curl`-based downloader, in the form of key/value pairs appended to `url`:
| key | value |
| ------------------ | ----------- |
| `using:` | the symbol `:post` is the only legal value
| `cookies:` | a hash of cookies to be set in the download request
| `referer:` | a string holding the URL to set as referrer in the download request
| `user_agent:` | a string holding the user agent to set for the download request. Can also be set to the symbol `:fake`, which will use a generic Browser-like user agent string. We prefer `:fake` when the server does not require a specific user agent.
| `data:` | a hash of parameters to be set in the POST request
Example of using `cookies:`: [java.rb](https://github.com/caskroom/homebrew-cask/blob/472930df191d66747a57d5c96c0d00511d56e21b/Casks/java.rb#L5#L8)
Example of using `referer:`: [rrootage.rb](https://github.com/caskroom/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/rrootage.rb#L5)
## When URL and Homepage Hostnames Differ, Add a Comment
When the hostnames of `url` and `homepage` differ, the discrepancy should be documented with a comment of the form:
```
# URL_SECTION was verified as official when first introduced to the cask
```
Where `URL_SECTION` is the smallest possible portion of the URL that uniquely identifies the app or vendor. Examples can be seen in [`airfoil.rb`](https://github.com/caskroom/homebrew-cask/blob/1666993ee93e2a43f00a4dfc3c727da7c0b5ada9/Casks/airfoil.rb#L5), [`knockknock.rb`](https://github.com/caskroom/homebrew-cask/blob/6645a6090d1cb8fc026f243a47048749b31c32bf/Casks/knockknock.rb#L5), [`lightpaper.rb`](https://github.com/caskroom/homebrew-cask/blob/7a75f4e84c01bf192bd55f251b96cf2c1e086281/Casks/lightpaper.rb#L5), [`airtool.rb`](https://github.com/caskroom/homebrew-cask/blob/355211a8a3ea54046ae45022bcf71980bd2d5432/Casks/airtool.rb#L5), [`screencat.rb`](https://github.com/caskroom/homebrew-cask/blob/5fc818752c30c156c00f79b04b66406189ab2f30/Casks/screencat.rb#L5), [`0ad.rb`](https://github.com/caskroom/homebrew-cask/blob/7a75f4e84c01bf192bd55f251b96cf2c1e086281/Casks/0ad.rb#L5).
These comments must be added so a user auditing the cask knows the URL was verified by the Homebrew-Cask team as the one provided by the vendor, even though it may look unofficial or suspicious. It is our responsibility as Homebrew-Cask maintainers to verify both the `url` and `homepage` information when first added (or subsequently modified, apart from versioning).
The comment doesn’t mean you should trust the source blindly, but we only approve casks in which users can easily verify its authenticity with basic means, such as checking the official homepage or public repository. occasionally, slightly more elaborate techniques may be used, such as inspecting an [`appcast`](appcast.md) we established as official. Cases where such quick verifications aren’t possible (e.g. when the download URL is behind a registration wall) are [treated in a stricter manner](../../development/adding-a-cask.md#unofficial-vendorless-and-walled-builds).
## Difficulty Finding a URL
Web browsers may obscure the direct `url` download location for a variety of reasons. Homebrew-Cask supplies a script which can read extended file attributes to extract the actual source URL for most files downloaded by a browser on macOS. The script usually emits multiple candidate URLs; you may have to test each of them:
```bash
$ $(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/list_url_attributes_on_file <file>
```
## Subversion URLs
In rare cases, a distribution may not be available over ordinary HTTP/S. Subversion URLs are also supported, and can be specified by appending the following key/value pairs to `url`:
| key | value |
| ------------------ | ----------- |
| `using:` | the symbol `:svn` is the only legal value
| `revision:` | a string identifying the subversion revision to download
| `trust_cert:` | set to `true` to automatically trust the certificate presented by the server (avoiding an interactive prompt)
## SourceForge/OSDN URLs
SourceForge and OSDN (formerly SourceForge.JP) projects are common ways to distribute binaries, but they provide many different styles of URLs to get to the goods.
We prefer URLs of this format:
```
https://downloads.sourceforge.net/{{project_name}}/{{filename}}.{{ext}}
```
Or, if it’s from [OSDN](https://osdn.jp/):
```
http://{{subdomain}}.osdn.jp/{{project_name}}/{{release_id}}/{{filename}}.{{ext}}
```
`{{subdomain}}` is typically of the form `dl` or `{{user}}.dl`.
If these formats are not available, and the application is macOS-exclusive (otherwise a command-line download defaults to the Windows version) we prefer the use of this format:
```
https://sourceforge.net/projects/{{project_name}}/files/latest/download
```
## Personal Hosting Such as Dropbox
URLs from dropbox.com or cl.ly/cloudapp.com are not readily distinguishable as being controlled by the original software vendor. These URLs should be used only when given as such on the official project website.
Also make sure to give the URL for the binary download itself, rather than a preview page. (See <https://www.dropbox.com/help/201/en>.)
## Some Providers Block Command-line Downloads
Some hosting providers actively block command-line HTTP clients. Such URLs cannot be used in Casks.
Some providers do not actively block command-line HTTP clients but use URLs that change periodically, or even on each visit (example: FossHub). For those, see section [URLs that Change on Every Visit](#urls-that-change-on-every-visit).
## Vendor URLs Are Preferred
When possible, it is best to use a download URL from the original developer or vendor, rather than an aggregator such as `macupdate.com`.
## URLs that Change on Every Visit
Some providers use disposable URLs, which a Cask author cannot know in advance. Such URLs may change daily, or on every visit, and sometimes need to be dynamically obtained from a landing site.
### The Problem
In theory, one can write arbitrary Ruby code right in the Cask definition to fetch and construct a disposable URL.
However, this typically involves an HTTP/S round trip to a landing site, which may take a long time. Because of the way Homebrew-Cask loads and parses Casks, it is not acceptable that such expensive operations be performed directly in the body of a Cask definition.
### Using a Block to Defer Code Execution
Similar to the `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` blocks, the `url` stanza offers an optional _block syntax_:
```rb
url do
# No known stable URL; fetching disposable URL from landing site
open('https://example.com/app/landing') do |landing_page|
content = landing_page.read
parse(content) # => https://example.com/download?23309800482283
end
end
```
The block is only evaluated when needed, for example on download time or when auditing a Cask.
Inside a block, you may safely do things such as HTTP/S requests that may take a long time to execute. You may also refer to the `@cask` instance variable, and invoke any method available on `@cask`.
The block will be called immediately before downloading; its result value will be assumed to be a `String` and subsequently used as a download URL.
You can use the `url` stanza with either a direct argument or a block but not with both.
Example for using the block syntax: [audacity.rb](https://github.com/caskroom/homebrew-cask/blob/c389d9ccbb46d30b6ac1cbdbadf49591ca8ff6cd/Casks/audacity.rb#L5-L15)
### Mixing Additional URL Parameters With the Block Syntax
In rare cases, you might need to set URL parameters like `cookies` or `referer` while also using the block syntax.
This is possible by returning a two-element array as a block result. The first element of the array must be the download URL; the second element must be a `Hash` containing the parameters.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment