Skip to content

Latest commit

 

History

History
54 lines (39 loc) · 3.19 KB

caveats.md

File metadata and controls

54 lines (39 loc) · 3.19 KB
Raw

caveats

Sometimes there are particularities with the installation of a piece of software that cannot or should not be handled programmatically 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, 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: /usr/local/Caskroom/{{token}}/{{version}} (only available with block form)

Example:

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.
kext users may need to enable their kexts in System Preferences → Security & Privacy → General.
license 'web_page'               software has a usage license at web_page.

Example:

caveats do
  path_environment_variable '/usr/texbin'
end