diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index d57f0e2b97..e2e3352b99 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -166,23 +166,23 @@ Fill in the following stanzas for your cask: | name | value | | ------------------ | ----------- | -| `version` | application version -| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [`sha256` Stanza Details](Cask-Cookbook.md#stanza-sha256)) -| `url` | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [`verified` parameter](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit. -| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [`name` Stanza Details](Cask-Cookbook.md#stanza-name)) -| `desc` | one-line description of the software (see [`desc` Stanza Details](Cask-Cookbook.md#stanza-desc)) -| `homepage` | application homepage; used for the `brew home` command -| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [`app` Stanza Details](Cask-Cookbook.md#stanza-app)) +| `version` | application version | +| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [`sha256` Stanza Details](Cask-Cookbook.md#stanza-sha256)) | +| `url` | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [`verified` parameter](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit. | +| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [`name` Stanza Details](Cask-Cookbook.md#stanza-name)) | +| `desc` | one-line description of the software (see [`desc` Stanza Details](Cask-Cookbook.md#stanza-desc)) | +| `homepage` | application homepage; used for the `brew home` command | +| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [`app` Stanza Details](Cask-Cookbook.md#stanza-app)) | Other commonly used stanzas are: | name | value | | ------------------ | ----------- | -| `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) -| `pkg` | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg)) -| `caveats` | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) -| `uninstall` | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall)) -| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) +| `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) | +| `pkg` | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg)) | +| `caveats` | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) | +| `uninstall` | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall)) | +| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) | Additional [`artifact` stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional Stanzas](Cask-Cookbook.md#optional-stanzas). diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index cfc71eb82c..7fc3af17fe 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -107,12 +107,12 @@ Each of the following stanzas is required for every cask. | name | multiple occurrences allowed? | value | | ---------------------------- | :---------------------------: | ----- | -| [`version`](#stanza-version) | no | Application version. -| [`sha256`](#stanza-sha256) | no | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. -| [`url`](#stanza-url) | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application. A [comment](#when-url-and-homepage-domains-differ-add-verified) should be added if the domains in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit. -| [`name`](#stanza-name) | yes | String providing the full and proper name defined by the vendor. -| [`desc`](#stanza-desc) | no | One-line description of the cask. Shown when running `brew info`. -| `homepage` | no | Application homepage; used for the `brew home` command. +| [`version`](#stanza-version) | no | Application version. | +| [`sha256`](#stanza-sha256) | no | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. | +| [`url`](#stanza-url) | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application. A [comment](#when-url-and-homepage-domains-differ-add-verified) should be added if the domains in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit. | +| [`name`](#stanza-name) | yes | String providing the full and proper name defined by the vendor. | +| [`desc`](#stanza-desc) | no | One-line description of the cask. Shown when running `brew info`. | +| `homepage` | no | Application homepage; used for the `brew home` command. | ### At least one artifact stanza is also required @@ -120,47 +120,47 @@ Each cask must declare one or more *artifacts* (i.e. something to install). | name | multiple occurrences allowed? | value | | -------------------------------- | :---------------------------: | ----- | -| [`app`](#stanza-app) | yes | Relative path to an `.app` that should be moved into the `/Applications` folder on installation. -| [`suite`](#stanza-suite) | yes | Relative path to a containing directory that should be moved into the `/Applications` folder on installation. -| [`pkg`](#stanza-pkg) | yes | Relative path to a `.pkg` file containing the distribution. -| [`installer`](#stanza-installer) | yes | Describes an executable which must be run to complete the installation. -| [`binary`](#stanza-binary) | yes | Relative path to a Binary that should be linked into the `$(brew --prefix)/bin` folder on installation. -| `manpage` | yes | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/usr/local/share/man/man3` for `my_app.3`. -| `colorpicker` | yes | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation. -| `dictionary` | yes | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation. -| `font` | yes | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation. -| `input_method` | yes | Relative path to an Input Method that should be moved into the `~/Library/Input Methods` folder on installation. -| `internet_plugin` | yes | Relative path to an Internet Plugin that should be moved into the `~/Library/Internet Plug-Ins` folder on installation. -| `keyboard_layout` | yes | Relative path to a Keyboard Layout that should be moved into the `/Library/Keyboard Layouts` folder on installation. -| `prefpane` | yes | Relative path to a Preference Pane that should be moved into the `~/Library/PreferencePanes` folder on installation. -| `qlplugin` | yes | Relative path to a QuickLook Plugin that should be moved into the `~/Library/QuickLook` folder on installation. -| `mdimporter` | yes | Relative path to a Spotlight Metadata Importer that should be moved into the `~/Library/Spotlight` folder on installation. -| `screen_saver` | yes | Relative path to a Screen Saver that should be moved into the `~/Library/Screen Savers` folder on installation. -| `service` | yes | Relative path to a Service that should be moved into the `~/Library/Services` folder on installation. -| `audio_unit_plugin` | yes | Relative path to an Audio Unit Plugin that should be moved into the `~/Library/Audio/Components` folder on installation. -| `vst_plugin` | yes | Relative path to a VST Plugin that should be moved into the `~/Library/Audio/VST` folder on installation. -| `vst3_plugin` | yes | Relative path to a VST3 Plugin that should be moved into the `~/Library/Audio/VST3` folder on installation. -| `artifact` | yes | Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a `target`. (Example: [free-gpgmail.rb](https://github.com/Homebrew/homebrew-cask/blob/b3c438d608d9702380edf10d5495e0727cf17108/Casks/f/free-gpgmail.rb#L44)) This is only for unusual cases; the `app` stanza is strongly preferred when moving `.app` bundles. -| `stage_only` | no | `true`. Asserts that the cask contains no activatable artifacts. +| [`app`](#stanza-app) | yes | Relative path to an `.app` that should be moved into the `/Applications` folder on installation. | +| [`suite`](#stanza-suite) | yes | Relative path to a containing directory that should be moved into the `/Applications` folder on installation. | +| [`pkg`](#stanza-pkg) | yes | Relative path to a `.pkg` file containing the distribution. | +| [`installer`](#stanza-installer) | yes | Describes an executable which must be run to complete the installation. | +| [`binary`](#stanza-binary) | yes | Relative path to a Binary that should be linked into the `$(brew --prefix)/bin` folder on installation. | +| `manpage` | yes | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/usr/local/share/man/man3` for `my_app.3`. | +| `colorpicker` | yes | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation. | +| `dictionary` | yes | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation. | +| `font` | yes | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation. | +| `input_method` | yes | Relative path to an Input Method that should be moved into the `~/Library/Input Methods` folder on installation. | +| `internet_plugin` | yes | Relative path to an Internet Plugin that should be moved into the `~/Library/Internet Plug-Ins` folder on installation. | +| `keyboard_layout` | yes | Relative path to a Keyboard Layout that should be moved into the `/Library/Keyboard Layouts` folder on installation. | +| `prefpane` | yes | Relative path to a Preference Pane that should be moved into the `~/Library/PreferencePanes` folder on installation. | +| `qlplugin` | yes | Relative path to a QuickLook Plugin that should be moved into the `~/Library/QuickLook` folder on installation. | +| `mdimporter` | yes | Relative path to a Spotlight Metadata Importer that should be moved into the `~/Library/Spotlight` folder on installation. | +| `screen_saver` | yes | Relative path to a Screen Saver that should be moved into the `~/Library/Screen Savers` folder on installation. | +| `service` | yes | Relative path to a Service that should be moved into the `~/Library/Services` folder on installation. | +| `audio_unit_plugin` | yes | Relative path to an Audio Unit Plugin that should be moved into the `~/Library/Audio/Components` folder on installation. | +| `vst_plugin` | yes | Relative path to a VST Plugin that should be moved into the `~/Library/Audio/VST` folder on installation. | +| `vst3_plugin` | yes | Relative path to a VST3 Plugin that should be moved into the `~/Library/Audio/VST3` folder on installation. | +| `artifact` | yes | Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a `target`. (Example: [free-gpgmail.rb](https://github.com/Homebrew/homebrew-cask/blob/b3c438d608d9702380edf10d5495e0727cf17108/Casks/f/free-gpgmail.rb#L44)) This is only for unusual cases; the `app` stanza is strongly preferred when moving `.app` bundles. | +| `stage_only` | no | `true`. Asserts that the cask contains no activatable artifacts. | ### Optional stanzas | name | multiple occurrences allowed? | value | | ------------------------------------------ | :---------------------------: | ----- | -| [`uninstall`](#stanza-uninstall) | yes | Procedures to uninstall a cask. Optional unless the `pkg` stanza is used. -| [`zap`](#stanza-zap) | yes | Additional procedures for a more complete uninstall, including user files and shared resources. -| [`depends_on`](#stanza-depends_on) | yes | List of dependencies and requirements for this cask. -| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask (*not yet functional*). -| [`caveats`](#stanza-caveats) | yes | String or Ruby block providing the user with cask-specific information at install time. -| [`livecheck`](#stanza-livecheck) | no | Ruby block describing how to find updates for this cask. Supersedes `appcast`. -| `preflight` | yes | Ruby block containing preflight install operations (needed only in very rare cases). -| [`postflight`](#stanza-flight) | yes | Ruby block containing postflight install operations. -| `uninstall_preflight` | yes | Ruby block containing preflight uninstall operations (needed only in very rare cases). -| `uninstall_postflight` | yes | Ruby block containing postflight uninstall operations. -| [`language`](#stanza-language) | required | Ruby block, called with language code parameters, containing other stanzas and/or a return value. -| `container nested:` | no | Relative path to an inner container that must be extracted before moving on with the installation. This allows for support of `.dmg` inside `.tar`, `.zip` inside `.dmg`, etc. (Example: [blocs.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/b/blocs.rb#L17-L19)) -| `container type:` | no | 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/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/p/parse.rb#L10)) -| `auto_updates` | no | `true`. Asserts that the cask artifacts auto-update. Use if `Check for Updates…` or similar is present in an app menu, but not if it only opens a webpage and does not do the download and installation for you. +| [`uninstall`](#stanza-uninstall) | yes | Procedures to uninstall a cask. Optional unless the `pkg` stanza is used. | +| [`zap`](#stanza-zap) | yes | Additional procedures for a more complete uninstall, including user files and shared resources. | +| [`depends_on`](#stanza-depends_on) | yes | List of dependencies and requirements for this cask. | +| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask (*not yet functional*). | +| [`caveats`](#stanza-caveats) | yes | String or Ruby block providing the user with cask-specific information at install time. | +| [`livecheck`](#stanza-livecheck) | no | Ruby block describing how to find updates for this cask. Supersedes `appcast`. | +| `preflight` | yes | Ruby block containing preflight install operations (needed only in very rare cases). | +| [`postflight`](#stanza-flight) | yes | Ruby block containing postflight install operations. | +| `uninstall_preflight` | yes | Ruby block containing preflight uninstall operations (needed only in very rare cases). | +| `uninstall_postflight` | yes | Ruby block containing postflight uninstall operations. | +| [`language`](#stanza-language) | required | Ruby block, called with language code parameters, containing other stanzas and/or a return value. | +| `container nested:` | no | Relative path to an inner container that must be extracted before moving on with the installation. This allows for support of `.dmg` inside `.tar`, `.zip` inside `.dmg`, etc. (Example: [blocs.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/b/blocs.rb#L17-L19)) | +| `container type:` | no | 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/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/p/parse.rb#L10)) | +| `auto_updates` | no | `true`. Asserts that the cask artifacts auto-update. Use if `Check for Updates…` or similar is present in an app menu, but not if it only opens a webpage and does not do the download and installation for you. | ## Stanza descriptions @@ -249,11 +249,11 @@ When `caveats` is a string, it is evaluated at compile time. The following metho | method | description | | ------------------ | ----------- | -| `token` | the cask token -| `version` | the cask version -| `homepage` | the cask homepage -| `caskroom_path` | the containing directory for this cask: `$(brew --caskroom)/` (only available with block form) -| `staged_path` | the staged location for this cask, including version number: `$(brew --caskroom)//` (only available with block form) +| `token` | the cask token | +| `version` | the cask version | +| `homepage` | the cask homepage | +| `caskroom_path` | the containing directory for this cask: `$(brew --caskroom)/` (only available with block form) | +| `staged_path` | the staged location for this cask, including version number: `$(brew --caskroom)//` (only available with block form) | Example: @@ -273,18 +273,18 @@ 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). -| `requires_rosetta` | The cask requires Rosetta 2 for it to run on Apple Silicon. -| `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. -| `kext` | Users may need to enable their kexts in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → General* in earlier macOS versions). -| `unsigned_accessibility` | Users will need to re-enable the app on each update in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → Privacy* in earlier macOS versions) as it is unsigned. -| `license "web_page"` | Users may find the software's usage license at `web_page`. -| `free_license "web_page"` | Users may obtain an official license to use the software at `web_page`. +| `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). | +| `requires_rosetta` | The cask requires Rosetta 2 for it to run on Apple Silicon. | +| `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. | +| `kext` | Users may need to enable their kexts in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → General* in earlier macOS versions). | +| `unsigned_accessibility` | Users will need to re-enable the app on each update in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → Privacy* in earlier macOS versions) as it is unsigned. | +| `license "web_page"` | Users may find the software's usage license at `web_page`. | +| `free_license "web_page"` | Users may obtain an official license to use the software at `web_page`. | Example: @@ -378,9 +378,9 @@ The available symbols for hardware are: | symbol | meaning | | ---------- | -------------- | -| `:x86_64` | 64-bit Intel -| `:intel` | 64-bit Intel -| `:arm64` | Apple Silicon +| `:x86_64` | 64-bit Intel | +| `:intel` | 64-bit Intel | +| `:arm64` | Apple Silicon | The following are all valid expressions: @@ -395,11 +395,11 @@ depends_on arch: :arm64 | key | description | | ---------- | ----------- | -| `formula:` | Homebrew formula -| `cask:` | cask token -| `macos:` | symbol, array, or string comparison expression defining macOS release requirements -| `arch:` | symbol or array defining hardware requirements -| `java:` | *stub - not yet functional* +| `formula:` | Homebrew formula | +| `cask:` | cask token | +| `macos:` | symbol, array, or string comparison expression defining macOS release requirements | +| `arch:` | symbol or array defining hardware requirements | +| `java:` | *stub - not yet functional* | ### Stanza: `desc` @@ -481,8 +481,8 @@ The following methods may be called to perform standard tasks: | method | availability | description | | ----------------------------------------- | ------------------------------------------------ | ----------- | -| `set_ownership(paths)` | `preflight`, `postflight`, `uninstall_preflight` | Set user and group ownership of `paths`. (Example: [docker-toolbox.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/d/docker-toolbox.rb#L42)) -| `set_permissions(paths, permissions_str)` | `preflight`, `postflight`, `uninstall_preflight` | Set permissions in `paths` to `permissions_str`. (Example: [ngrok.rb](https://github.com/Homebrew/homebrew-cask/blob/41d91ff669d85343175202adf568e2328486205f/Casks/n/ngrok.rb#L30)) +| `set_ownership(paths)` | `preflight`, `postflight`, `uninstall_preflight` | Set user and group ownership of `paths`. (Example: [docker-toolbox.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/d/docker-toolbox.rb#L42)) | +| `set_permissions(paths, permissions_str)` | `preflight`, `postflight`, `uninstall_preflight` | Set permissions in `paths` to `permissions_str`. (Example: [ngrok.rb](https://github.com/Homebrew/homebrew-cask/blob/41d91ff669d85343175202adf568e2328486205f/Casks/n/ngrok.rb#L30)) | `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")`. (Example: [hummingbird.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/h/hummingbird.rb#L24)) @@ -506,11 +506,11 @@ installer manual: "RubyMotion Installer.app" | key | value | | --------------- | ----- | -| `executable:` | path to an install script to be run -| `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 `true` if the script needs *sudo* +| `executable:` | path to an install script to be run | +| `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 `true` if the script needs *sudo* | The path may be absolute, or relative to the cask. Example (from [miniforge.rb](https://github.com/Homebrew/homebrew-cask/blob/864f623e2cd17dbde5987a7b3923fdb0b4ac9ee5/Casks/m/miniforge.rb#L23-L26)): @@ -921,13 +921,13 @@ When a plain URL string is insufficient to fetch a file, additional information | key | value | | ------------------ | ----------- | -| `verified:` | string repeating the beginning of `url`, for [verification purposes](#when-url-and-homepage-domains-differ-add-verified) -| `using:` | the symbols `:post` and `:homebrew_curl` are the only legal values -| `cookies:` | hash of cookies to be set in the download request (Example: [oracle-jdk-javadoc.rb](https://github.com/Homebrew/homebrew-cask/blob/326c44e93aeb8d4dd73acea14a99ae215c75fdd6/Casks/o/oracle-jdk-javadoc.rb#L5-L8)) -| `referer:` | string holding the URL to set as referer in the download request (Example: [firealpaca.rb](https://github.com/Homebrew/homebrew-cask/blob/c4b3f0742e044ae2a6e114eb6b90068763d0d12b/Casks/f/firealpaca.rb#L5-L6)) -| `header:` | string or array of strings holding the header(s) to set for the download request (Example: [pull-6545](https://github.com/Homebrew/brew/pull/6545#issue-503302353), [issue-15590](https://github.com/Homebrew/brew/issues/15590#issue-1774825542)) -| `user_agent:` | 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:` | hash of parameters to be set in the POST request (Example: [segger-jlink.rb](https://github.com/Homebrew/homebrew-cask/blob/38ac55614f146d68ae317594f0c119e9acbd7c9e/Casks/s/segger-jlink.rb#L6-L11)) +| `verified:` | string repeating the beginning of `url`, for [verification purposes](#when-url-and-homepage-domains-differ-add-verified) | +| `using:` | the symbols `:post` and `:homebrew_curl` are the only legal values | +| `cookies:` | hash of cookies to be set in the download request (Example: [oracle-jdk-javadoc.rb](https://github.com/Homebrew/homebrew-cask/blob/326c44e93aeb8d4dd73acea14a99ae215c75fdd6/Casks/o/oracle-jdk-javadoc.rb#L5-L8)) | +| `referer:` | string holding the URL to set as referer in the download request (Example: [firealpaca.rb](https://github.com/Homebrew/homebrew-cask/blob/c4b3f0742e044ae2a6e114eb6b90068763d0d12b/Casks/f/firealpaca.rb#L5-L6)) | +| `header:` | string or array of strings holding the header(s) to set for the download request (Example: [pull-6545](https://github.com/Homebrew/brew/pull/6545#issue-503302353), [issue-15590](https://github.com/Homebrew/brew/issues/15590#issue-1774825542)) | +| `user_agent:` | 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:` | hash of parameters to be set in the POST request (Example: [segger-jlink.rb](https://github.com/Homebrew/homebrew-cask/blob/38ac55614f146d68ae317594f0c119e9acbd7c9e/Casks/s/segger-jlink.rb#L6-L11)) | #### When URL and homepage domains differ, add `verified:` @@ -951,9 +951,9 @@ In rare cases, a distribution may not be available over ordinary HTTP/S. Subvers | key | value | | ------------------ | ----------- | -| `using:` | the symbol `:svn` is the only legal value -| `revision:` | 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) +| `using:` | the symbol `:svn` is the only legal value | +| `revision:` | 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) | #### Git URLs @@ -961,11 +961,11 @@ Artifacts also may be distributed via Git repositories. URLs that end in `.git` | key | value | | ------------------ | ----------- | -| `using:` | the symbol `:git` is the only legal value -| `tag:` | string identifying the Git tag to download -| `revision:` | string identifying the Git revision to download -| `branch:` | string identifying the Git branch to download -| `only_path:` | path within the repository to limit the checkout to. If only a single directory of a large repository is required, using this option can significantly speed up downloads. If provided, artifact paths are relative to this path. (Example: [font-geo.rb](https://github.com/Homebrew/homebrew-cask-fonts/blob/bac691e1d7b5bd7372e7e0befae989a3ff7ad449/Casks/font-geo.rb#L5-L8)) +| `using:` | the symbol `:git` is the only legal value | +| `tag:` | string identifying the Git tag to download | +| `revision:` | string identifying the Git revision to download | +| `branch:` | string identifying the Git branch to download | +| `only_path:` | path within the repository to limit the checkout to. If only a single directory of a large repository is required, using this option can significantly speed up downloads. If provided, artifact paths are relative to this path. (Example: [font-geo.rb](https://github.com/Homebrew/homebrew-cask-fonts/blob/bac691e1d7b5bd7372e7e0befae989a3ff7ad449/Casks/font-geo.rb#L5-L8)) | #### SourceForge/OSDN URLs @@ -1064,16 +1064,16 @@ The examples above can become hard to read, however. Since many of these changes | method | input | output | | ------------------------ | ------------------ | ------------------ | -| `major` | `1.2.3-a45,ccdd88` | `1` -| `minor` | `1.2.3-a45,ccdd88` | `2` -| `patch` | `1.2.3-a45,ccdd88` | `3-a45` -| `major_minor` | `1.2.3-a45,ccdd88` | `1.2` -| `major_minor_patch` | `1.2.3-a45,ccdd88` | `1.2.3-a45` -| `minor_patch` | `1.2.3-a45,ccdd88` | `2.3-a45` -| `before_comma` | `1.2.3-a45,ccdd88` | `1.2.3-a45` -| `after_comma` | `1.2.3-a45,ccdd88` | `ccdd88` -| `dots_to_hyphens` | `1.2.3-a45,ccdd88` | `1-2-3-a45,ccdd88` -| `no_dots` | `1.2.3-a45,ccdd88` | `123-a45,ccdd88` +| `major` | `1.2.3-a45,ccdd88` | `1` | +| `minor` | `1.2.3-a45,ccdd88` | `2` | +| `patch` | `1.2.3-a45,ccdd88` | `3-a45` | +| `major_minor` | `1.2.3-a45,ccdd88` | `1.2` | +| `major_minor_patch` | `1.2.3-a45,ccdd88` | `1.2.3-a45` | +| `minor_patch` | `1.2.3-a45,ccdd88` | `2.3-a45` | +| `before_comma` | `1.2.3-a45,ccdd88` | `1.2.3-a45` | +| `after_comma` | `1.2.3-a45,ccdd88` | `ccdd88` | +| `dots_to_hyphens` | `1.2.3-a45,ccdd88` | `1-2-3-a45,ccdd88` | +| `no_dots` | `1.2.3-a45,ccdd88` | `123-a45,ccdd88` | Similar to `dots_to_hyphens`, we provide methods for all logical permutations of `{dots,hyphens,underscores}_to_{dots,hyphens,underscores}`. The same applies to `no_dots` in the form of `no_{dots,hyphens,underscores}`, with an extra `no_dividers` that applies all these at once. @@ -1343,13 +1343,13 @@ The token is also given in the header line for each cask. These illustrate most of the rules for generating a token: -App Name on Disk | Simplified App Name | Cask Token | Filename ------------------------|---------------------|------------------|---------------------- -`Audio Hijack Pro.app` | Audio Hijack Pro | audio-hijack-pro | `audio-hijack-pro.rb` -`VLC.app` | VLC | vlc | `vlc.rb` -`BetterTouchTool.app` | BetterTouchTool | bettertouchtool | `bettertouchtool.rb` -`LPK25 Editor.app` | LPK25 Editor | lpk25-editor | `lpk25-editor.rb` -`Sublime Text 2.app` | Sublime Text | sublime-text | `sublime-text.rb` +| App Name on Disk | Simplified App Name | Cask Token | Filename | +|------------------------|---------------------|------------------|----------------------| +| `Audio Hijack Pro.app` | Audio Hijack Pro | audio-hijack-pro | `audio-hijack-pro.rb` | +| `VLC.app` | VLC | vlc | `vlc.rb` | +| `BetterTouchTool.app` | BetterTouchTool | bettertouchtool | `bettertouchtool.rb` | +| `LPK25 Editor.app` | LPK25 Editor | lpk25-editor | `lpk25-editor.rb` | +| `Sublime Text 2.app` | Sublime Text | sublime-text | `sublime-text.rb` | #### Tap-specific cask token examples diff --git a/docs/External-Commands.md b/docs/External-Commands.md index c436546bab..2c3d2e2306 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -28,11 +28,11 @@ An executable script for a command named `extcmd` should be named `brew-extcmd`. | variable | description | | ---------------------- | ----------- | -| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. -| `HOMEBREW_PREFIX` | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. -| `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise. -| `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code. -| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory. +| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. | +| `HOMEBREW_PREFIX` | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. | +| `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise. | +| `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code. | +| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory. | ## Providing `--help` diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 7255e0bc80..2a482adf7d 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -9,21 +9,21 @@ A *formula* is a package definition written in Ruby. It can be created with `bre | term | description | example | | -------------------- | ------------------------------------------------------------------------- | ------- | -| **formula** | Homebrew package definition that builds from upstream sources | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` -| **cask** | Homebrew package definition that installs macOS native applications | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/b/bar.rb` -| **prefix** | path in which Homebrew is installed | `/usr/local` -| **keg** | installation destination directory of a given **formula** version | `/usr/local/Cellar/foo/0.1` -| **rack** | directory containing one or more versioned **kegs** | `/usr/local/Cellar/foo` -| **keg-only** | a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/o/openjdk.rb) formula -| **opt prefix** | a symlink to the active version of a **keg** | `/usr/local/opt/foo` -| **Cellar** | directory containing one or more named **racks** | `/usr/local/Cellar` -| **Caskroom** | directory containing one or more named **casks** | `/usr/local/Caskroom` -| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository | [`brew alias`](https://github.com/Homebrew/homebrew-aliases) -| **tap** | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` -| **bottle** | pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources | `qt--6.5.1.ventura.bottle.tar.gz` -| **tab** | information about a **keg**, e.g. whether it was poured from a **bottle** or built from source | `/usr/local/Cellar/foo/0.1/INSTALL_RECEIPT.json` -| **Brew Bundle** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` -| **Brew Services** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-services) to manage services | `brew services start myservice` +| **formula** | Homebrew package definition that builds from upstream sources | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` | +| **cask** | Homebrew package definition that installs macOS native applications | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/b/bar.rb` | +| **prefix** | path in which Homebrew is installed | `/usr/local` | +| **keg** | installation destination directory of a given **formula** version | `/usr/local/Cellar/foo/0.1` | +| **rack** | directory containing one or more versioned **kegs** | `/usr/local/Cellar/foo` | +| **keg-only** | a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/o/openjdk.rb) formula | +| **opt prefix** | a symlink to the active version of a **keg** | `/usr/local/opt/foo` | +| **Cellar** | directory containing one or more named **racks** | `/usr/local/Cellar` | +| **Caskroom** | directory containing one or more named **casks** | `/usr/local/Caskroom` | +| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository | [`brew alias`](https://github.com/Homebrew/homebrew-aliases) | +| **tap** | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` | +| **bottle** | pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources | `qt--6.5.1.ventura.bottle.tar.gz` | +| **tab** | information about a **keg**, e.g. whether it was poured from a **bottle** or built from source | `/usr/local/Cellar/foo/0.1/INSTALL_RECEIPT.json` | +| **Brew Bundle** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` | +| **Brew Services** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-services) to manage services | `brew services start myservice` | ## An introduction @@ -668,16 +668,16 @@ Homebrew offers these anonymous download strategies. | `:using` value | download strategy | | ---------------- | ----------------------------- | -| `:bzr` | `BazaarDownloadStrategy` -| `:curl` | `CurlDownloadStrategy` -| `:cvs` | `CVSDownloadStrategy` -| `:fossil` | `FossilDownloadStrategy` -| `:git` | `GitDownloadStrategy` -| `:hg` | `MercurialDownloadStrategy` -| `:homebrew_curl` | `HomebrewCurlDownloadStrategy` -| `:nounzip` | `NoUnzipCurlDownloadStrategy` -| `:post` | `CurlPostDownloadStrategy` -| `:svn` | `SubversionDownloadStrategy` +| `:bzr` | `BazaarDownloadStrategy` | +| `:curl` | `CurlDownloadStrategy` | +| `:cvs` | `CVSDownloadStrategy` | +| `:fossil` | `FossilDownloadStrategy` | +| `:git` | `GitDownloadStrategy` | +| `:hg` | `MercurialDownloadStrategy` | +| `:homebrew_curl` | `HomebrewCurlDownloadStrategy` | +| `:nounzip` | `NoUnzipCurlDownloadStrategy` | +| `:post` | `CurlPostDownloadStrategy` | +| `:svn` | `SubversionDownloadStrategy` | If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it with the `:using` option: @@ -749,32 +749,32 @@ Generally we'd rather you were specific about which files or directories need to | name | default path | example | | --------------------- | ---------------------------------------------- | ------- | -| **`HOMEBREW_PREFIX`** | output of `$(brew --prefix)` | `/usr/local` -| **`prefix`** | `#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}` | `/usr/local/Cellar/foo/0.1` -| **`opt_prefix`** | `#{HOMEBREW_PREFIX}/opt/#{name}` | `/usr/local/opt/foo` -| **`bin`** | `#{prefix}/bin` | `/usr/local/Cellar/foo/0.1/bin` -| **`doc`** | `#{prefix}/share/doc/#{name}` | `/usr/local/Cellar/foo/0.1/share/doc/foo` -| **`include`** | `#{prefix}/include` | `/usr/local/Cellar/foo/0.1/include` -| **`info`** | `#{prefix}/share/info` | `/usr/local/Cellar/foo/0.1/share/info` -| **`lib`** | `#{prefix}/lib` | `/usr/local/Cellar/foo/0.1/lib` -| **`libexec`** | `#{prefix}/libexec` | `/usr/local/Cellar/foo/0.1/libexec` -| **`man`** | `#{prefix}/share/man` | `/usr/local/Cellar/foo/0.1/share/man` -| **`man[1-8]`** | `#{prefix}/share/man/man[1-8]` | `/usr/local/Cellar/foo/0.1/share/man/man[1-8]` -| **`sbin`** | `#{prefix}/sbin` | `/usr/local/Cellar/foo/0.1/sbin` -| **`share`** | `#{prefix}/share` | `/usr/local/Cellar/foo/0.1/share` -| **`pkgshare`** | `#{prefix}/share/#{name}` | `/usr/local/Cellar/foo/0.1/share/foo` -| **`elisp`** | `#{prefix}/share/emacs/site-lisp/#{name}` | `/usr/local/Cellar/foo/0.1/share/emacs/site-lisp/foo` -| **`frameworks`** | `#{prefix}/Frameworks` | `/usr/local/Cellar/foo/0.1/Frameworks` -| **`kext_prefix`** | `#{prefix}/Library/Extensions` | `/usr/local/Cellar/foo/0.1/Library/Extensions` -| **`zsh_function`** | `#{prefix}/share/zsh/site-functions` | `/usr/local/Cellar/foo/0.1/share/zsh/site-functions` -| **`fish_function`** | `#{prefix}/share/fish/vendor_functions` | `/usr/local/Cellar/foo/0.1/share/fish/vendor_functions` -| **`bash_completion`** | `#{prefix}/etc/bash_completion.d` | `/usr/local/Cellar/foo/0.1/etc/bash_completion.d` -| **`zsh_completion`** | `#{prefix}/share/zsh/site-functions` | `/usr/local/Cellar/foo/0.1/share/zsh/site-functions` -| **`fish_completion`** | `#{prefix}/share/fish/vendor_completions.d` | `/usr/local/Cellar/foo/0.1/share/fish/vendor_completions.d` -| **`etc`** | `#{HOMEBREW_PREFIX}/etc` | `/usr/local/etc` -| **`pkgetc`** | `#{HOMEBREW_PREFIX}/etc/#{name}` | `/usr/local/etc/foo` -| **`var`** | `#{HOMEBREW_PREFIX}/var` | `/usr/local/var` -| **`buildpath`** | temporary directory somewhere on your system | `/private/tmp/[formula-name]-0q2b/[formula-name]` +| **`HOMEBREW_PREFIX`** | output of `$(brew --prefix)` | `/usr/local` | +| **`prefix`** | `#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}` | `/usr/local/Cellar/foo/0.1` | +| **`opt_prefix`** | `#{HOMEBREW_PREFIX}/opt/#{name}` | `/usr/local/opt/foo` | +| **`bin`** | `#{prefix}/bin` | `/usr/local/Cellar/foo/0.1/bin` | +| **`doc`** | `#{prefix}/share/doc/#{name}` | `/usr/local/Cellar/foo/0.1/share/doc/foo` | +| **`include`** | `#{prefix}/include` | `/usr/local/Cellar/foo/0.1/include` | +| **`info`** | `#{prefix}/share/info` | `/usr/local/Cellar/foo/0.1/share/info` | +| **`lib`** | `#{prefix}/lib` | `/usr/local/Cellar/foo/0.1/lib` | +| **`libexec`** | `#{prefix}/libexec` | `/usr/local/Cellar/foo/0.1/libexec` | +| **`man`** | `#{prefix}/share/man` | `/usr/local/Cellar/foo/0.1/share/man` | +| **`man[1-8]`** | `#{prefix}/share/man/man[1-8]` | `/usr/local/Cellar/foo/0.1/share/man/man[1-8]` | +| **`sbin`** | `#{prefix}/sbin` | `/usr/local/Cellar/foo/0.1/sbin` | +| **`share`** | `#{prefix}/share` | `/usr/local/Cellar/foo/0.1/share` | +| **`pkgshare`** | `#{prefix}/share/#{name}` | `/usr/local/Cellar/foo/0.1/share/foo` | +| **`elisp`** | `#{prefix}/share/emacs/site-lisp/#{name}` | `/usr/local/Cellar/foo/0.1/share/emacs/site-lisp/foo` | +| **`frameworks`** | `#{prefix}/Frameworks` | `/usr/local/Cellar/foo/0.1/Frameworks` | +| **`kext_prefix`** | `#{prefix}/Library/Extensions` | `/usr/local/Cellar/foo/0.1/Library/Extensions` | +| **`zsh_function`** | `#{prefix}/share/zsh/site-functions` | `/usr/local/Cellar/foo/0.1/share/zsh/site-functions` | +| **`fish_function`** | `#{prefix}/share/fish/vendor_functions` | `/usr/local/Cellar/foo/0.1/share/fish/vendor_functions` | +| **`bash_completion`** | `#{prefix}/etc/bash_completion.d` | `/usr/local/Cellar/foo/0.1/etc/bash_completion.d` | +| **`zsh_completion`** | `#{prefix}/share/zsh/site-functions` | `/usr/local/Cellar/foo/0.1/share/zsh/site-functions` | +| **`fish_completion`** | `#{prefix}/share/fish/vendor_completions.d` | `/usr/local/Cellar/foo/0.1/share/fish/vendor_completions.d` | +| **`etc`** | `#{HOMEBREW_PREFIX}/etc` | `/usr/local/etc` | +| **`pkgetc`** | `#{HOMEBREW_PREFIX}/etc/#{name}` | `/usr/local/etc/foo` | +| **`var`** | `#{HOMEBREW_PREFIX}/var` | `/usr/local/var` | +| **`buildpath`** | temporary directory somewhere on your system | `/private/tmp/[formula-name]-0q2b/[formula-name]` | These can be used, for instance, in code such as: @@ -937,24 +937,24 @@ This table lists the options you can set within a `service` block. The `run` or | method | default | macOS | Linux | description | | ----------------------- | ------------ | :---: | :---: | ----------- | -| `run` | - | yes | yes | command to execute: an array with arguments or a path -| `run_type` | `:immediate` | yes | yes | type of service: `:immediate`, `:interval` or `:cron` -| `interval` | - | yes | yes | controls the start interval, required for the `:interval` type -| `cron` | - | yes | yes | controls the trigger times, required for the `:cron` type -| `keep_alive` | `false` | yes | yes | [sets contexts](#keep_alive-options) in which the service will keep the process running -| `launch_only_once` | `false` | yes | yes | whether the command should only run once -| `require_root` | `false` | yes | yes | whether the service requires root access -| `environment_variables` | - | yes | yes | hash of variables to set -| `working_dir` | - | yes | yes | directory to operate from -| `root_dir` | - | yes | yes | directory to use as a chroot for the process -| `input_path` | - | yes | yes | path to use as input for the process -| `log_path` | - | yes | yes | path to write `stdout` to -| `error_log_path` | - | yes | yes | path to write `stderr` to -| `restart_delay` | - | yes | yes | number of seconds to delay before restarting a process -| `process_type` | - | yes | no-op | type of process to manage: `:background`, `:standard`, `:interactive` or `:adaptive` -| `macos_legacy_timers` | - | yes | no-op | timers created by `launchd` jobs are coalesced unless this is set -| `sockets` | - | yes | no-op | socket that is created as an accesspoint to the service -| `name` | - | yes | yes | a hash with the `launchd` service name on macOS and/or the `systemd` service name on Linux +| `run` | - | yes | yes | command to execute: an array with arguments or a path | +| `run_type` | `:immediate` | yes | yes | type of service: `:immediate`, `:interval` or `:cron` | +| `interval` | - | yes | yes | controls the start interval, required for the `:interval` type | +| `cron` | - | yes | yes | controls the trigger times, required for the `:cron` type | +| `keep_alive` | `false` | yes | yes | [sets contexts](#keep_alive-options) in which the service will keep the process running | +| `launch_only_once` | `false` | yes | yes | whether the command should only run once | +| `require_root` | `false` | yes | yes | whether the service requires root access | +| `environment_variables` | - | yes | yes | hash of variables to set | +| `working_dir` | - | yes | yes | directory to operate from | +| `root_dir` | - | yes | yes | directory to use as a chroot for the process | +| `input_path` | - | yes | yes | path to use as input for the process | +| `log_path` | - | yes | yes | path to write `stdout` to | +| `error_log_path` | - | yes | yes | path to write `stderr` to | +| `restart_delay` | - | yes | yes | number of seconds to delay before restarting a process | +| `process_type` | - | yes | no-op | type of process to manage: `:background`, `:standard`, `:interactive` or `:adaptive` | +| `macos_legacy_timers` | - | yes | no-op | timers created by `launchd` jobs are coalesced unless this is set | +| `sockets` | - | yes | no-op | socket that is created as an accesspoint to the service | +| `name` | - | yes | yes | a hash with the `launchd` service name on macOS and/or the `systemd` service name on Linux | For services that are kept alive after starting you can use the default `run_type`: