If available, an HTTPS URL is preferred. A plain HTTP URL should only be used in the absence of a secure alternative.
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 |
header: |
a string holding the header to set for 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
Example of using referer:: rrootage.rb
Example of using header:: issue-325182724
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, knockknock.rb, lightpaper.rb, airtool.rb, screencat.rb, 0ad.rb.
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 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.
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:
$ $(brew --repository)/Library/Taps/homebrew/homebrew-cask/developer/bin/list_url_attributes_on_file <file>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 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:
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
Some hosting providers actively block command-line HTTP clients. Such URLs cannot be used in Casks.
Other providers may use URLs that change periodically, or even on each visit (example: FossHub). While some cases could be circumvented, they tend to occur when the vendor is actively trying to prevent automated downloads, so we prefer to not add those casks to the main repository.
Some casks—notably nightlies—have versioned download URLs but are updated so often that they become impractical to keep current with the usual process. For those, we want to dynamically determine url.
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 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.
Similar to the preflight, postflight, uninstall_preflight, and uninstall_postflight blocks, the url stanza offers an optional block syntax:
url do
require 'open-uri'
# No known stable URL; fetching disposable URL from landing site
URI('https://example.com/app/landing').open do |landing_page|
content = landing_page.read
parse(content) # => https://example.com/download?23309800482283
end
endThe 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: vlc-nightly.rb
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.