Merge pull request #6138 from rolandwalker/doc_dsl_depends_on

docs, error msgs, tests for depends_on :formula
Homebrew · Sep 12, 2014 · 431dd46 · 431dd46
2 parents 9e4b4d6 + dfcbd71
commit 431dd46
Show file tree

Hide file tree

Showing 8 changed files with 60 additions and 24 deletions.
diff --git a/doc/CASK_LANGUAGE_REFERENCE.md b/doc/CASK_LANGUAGE_REFERENCE.md
@@ -15,6 +15,7 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases.
  * [URL Stanza Details](#url-stanza-details)
  * [Link Stanza Details](#link-stanza-details)
  * [Pkg Stanza Details](#pkg-stanza-details)
+ * [Depends_on Stanza Details](#depends_on-stanza-details)
  * [Uninstall Stanza Details](#uninstall-stanza-details)
  * [Arbitrary Ruby Methods](#arbitrary-ruby-methods)
  * [Revisions to the Cask DSL](#revisions-to-the-cask-dsl)
@@ -93,7 +94,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
 | ---------------------- |------------------------------ | ----------- |
 | `uninstall`            | yes                           | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details](#uninstall-stanza-details))
 | `nested_container`     | yes                           | 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.
-| `depends_on_formula`   | yes                           | a list of Homebrew Formulae upon which this Cask depends
+| `depends_on`           | yes                           | a list of dependencies required by this Cask (see also [Depends_on Stanza Details](#depends_on-stanza-details))
 | `caveats`              | yes                           | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Stanza Details](#caveats-stanza-details))
 | `preflight`            | yes                           | a Ruby block containing preflight install operations (needed only in very rare cases)
 | `postflight`           | yes                           | a Ruby block containing postflight install operations
@@ -106,14 +107,15 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
 
 The following stanzas are no longer in use.
 
-| name                | multiple occurrences allowed? | meaning     |
-| ------------------- |------------------------------ | ----------- |
-| `no_checksum`       | no                            | an obsolete alternative to `sha256 :no_check`
-| `before_install`    | yes                           | an obsolete alternative to `preflight`
-| `after_install`     | yes                           | an obsolete alternative to `postflight`
-| `before_uninstall`  | yes                           | an obsolete alternative to `uninstall_preflight`
-| `after_uninstall`   | yes                           | an obsolete alternative to `uninstall_postflight`
-| `install`           | yes                           | an obsolete alternative to `pkg`
+| name                 | multiple occurrences allowed? | meaning     |
+| -------------------- |------------------------------ | ----------- |
+| `no_checksum`        | no                            | an obsolete alternative to `sha256 :no_check`
+| `before_install`     | yes                           | an obsolete alternative to `preflight`
+| `after_install`      | yes                           | an obsolete alternative to `postflight`
+| `before_uninstall`   | yes                           | an obsolete alternative to `uninstall_preflight`
+| `after_uninstall`    | yes                           | an obsolete alternative to `uninstall_postflight`
+| `install`            | yes                           | an obsolete alternative to `pkg`
+| `depends_on_formula` | yes                           | an obsolete alternative to `depends_on :formula`
 
 
 ## Conditional Statements
@@ -357,6 +359,32 @@ Example:
 pkg 'Soundflower.pkg', :allow_untrusted => true
 ```
 
+## Depends_on Stanza Details
+
+`depends_on` is used to declare dependencies required to install a Cask
+or to execute its contents.
+
+For example, 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'
+```
+
+While several keys are accepted by `depends_on`, `:formula` is the only
+key with working functionality at the time of writing.
+
+| key        | description |
+| ---------- | ----------- |
+| `:formula` | A Homebrew Formula
+| `: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*
+
 
 ## Uninstall Stanza Details
 

diff --git a/doc/cask_language_deltas.md b/doc/cask_language_deltas.md
@@ -31,19 +31,27 @@ This notice will be removed for the final form.**
 
 ## Additions (1.0)
 
-**Stub!**
+ * `depends_on :cask`
+   * stub - not yet functional
+ * `depends_on :macos`
+   * stub - not yet functional
+ * `depends_on :arch`
+   * stub - not yet functional
+ * `depends_on :x11`
+   * stub - not yet functional
+ * `depends_on :java`
+   * stub - not yet functional
 
 
 ## Renames (1.0)
 
-| old stanza name    | new stanza name
-| -------------------|----------------
-| `before_install`   | `preflight`
-| `after_install`    | `postflight`
-| `before_uninstall` | `uninstall_preflight`
-| `after_uninstall`  | `uninstall_postflight`
-| `install`          | `pkg`
-
+| old form              | new form
+| --------------------- |----------------
+| `before_install`      | `preflight`
+| `after_install`       | `postflight`
+| `before_uninstall`    | `uninstall_preflight`
+| `after_uninstall`     | `uninstall_postflight`
+| `depends_on_formula`  | `depends_on :formula`
 
 ## All Supported Stanzas (1.0)
 

diff --git a/lib/cask/container/cab.rb b/lib/cask/container/cab.rb
@@ -11,7 +11,7 @@ def self.me?(criteria)
   def extract
     cabextract = HOMEBREW_PREFIX.join('bin/cabextract')
     if ! Pathname.new(cabextract).exist?
-      raise CaskError.new "Expected to find cabextract executable. Cask '#{@cask}' must add: depends_on_formula 'cabextract'"
+      raise CaskError.new "Expected to find cabextract executable. Cask '#{@cask}' must add: depends_on :formula => 'cabextract'"
     end
     Dir.mktmpdir do |staging_dir|
       @command.run!(cabextract, :args => ['-d', staging_dir, '--', @path])

diff --git a/lib/cask/container/generic_unar.rb b/lib/cask/container/generic_unar.rb
@@ -9,7 +9,7 @@ def self.me?(criteria)
   def extract
     unar = HOMEBREW_PREFIX.join('bin/unar')
     if ! Pathname.new(unar).exist?
-      raise CaskError.new "Expected to find unar executable. Cask #{@cask} must add: depends_on_formula 'unar'"
+      raise CaskError.new "Expected to find unar executable. Cask #{@cask} must add: depends_on :formula => 'unar'"
     end
     Dir.mktmpdir do |staging_dir|
       @command.run!(unar, :args => ['-q', '-D', '-o', staging_dir, '--', @path])

diff --git a/test/support/Casks/cab-container.rb b/test/support/Casks/cab-container.rb
@@ -3,6 +3,6 @@ class CabContainer < TestCask
   homepage 'http://example.com/cab-container'
   version '1.2.3'
   sha256 '192d0cf6b727473f9ba0f55cec793ee2a8f7113c5cfe9d49e05a087436c5efe2'
-  depends_on_formula 'cabextract'
+  depends_on :formula => 'cabextract'
   link 'cabcontainer/Application.app'
 end
diff --git a/test/support/Casks/rar-container.rb b/test/support/Casks/rar-container.rb
@@ -3,6 +3,6 @@ class RarContainer < TestCask
   homepage 'http://example.com/rar-container'
   version '1.2.3'
   sha256 '35fb13fb13e6aefc38b60486627eff6b6b55b2f99f64bf47938530c6cf9e0a0f'
-  depends_on_formula 'unar'
+  depends_on :formula => 'unar'
   link 'rarcontainer/Application.app'
 end
diff --git a/test/support/Casks/sevenzip-container.rb b/test/support/Casks/sevenzip-container.rb
@@ -3,6 +3,6 @@ class SevenzipContainer < TestCask
   homepage 'http://example.com/sevenzip-container'
   version '1.2.3'
   sha256 '1550701e7848fcb94f5b0085cca527083a8662ddeb8c0a7bc5af6bd145797cc1'
-  depends_on_formula 'unar'
+  depends_on :formula => 'unar'
   link 'sevenzipcontainer/Application.app'
 end
diff --git a/test/support/Casks/stuffit-container.rb b/test/support/Casks/stuffit-container.rb
@@ -3,6 +3,6 @@ class StuffitContainer < TestCask
   homepage 'http://www.tobias-jung.de/seekingprofont/'
   version '1.2.3'
   sha256 '892b6d49a98c546381d41dec9b0bbc04267ac008d72b99755968d357099993b7'
-  depends_on_formula 'unar'
+  depends_on :formula => 'unar'
   link 'sheldonmac/v1.0'
 end