Roadmap: Rationalizing and Extending the Cask DSL (DSL 1.0)

Question

Roadmap: Rationalizing and Extending the Cask DSL (DSL 1.0)

rolandwalker opened this issue 10 years ago · comments

Background

Some of you may have noticed that #3066 works, but has been sitting unmerged
for a long time. The reason I pressed "pause" on that PR was the realization
that storing Cask files as metadata (while appealingly simple) would mean that
we need to keep backwards-compatibility with the DSL essentially forever.

We could still add stanzas or keys, but it would become difficult to remove
anything, because we would need to be able to load arbitrarily old metadata-Casks.

Recently, we did make substantial changes to the DSL (including the removal
of stanzas) all of which was accomplished pretty much glitch-free. (#2931, #4264,
#4257, #4689). The process goes something like this (duplicated in Tracker below):

push forward-compatible code, but do not document
cut a release
wait 6 weeks
document
- explain new DSL forms
- deprecate old DSL forms
amend Casks
wait a few more weeks
delete backward-compatible code
delete backward-looking documentation

Argument

Like most successful things, the Cask DSL has grown incrementally over time
and was not always planned. This seems like a good moment to review and
rationalize the DSL (before merging #3066 or something like it).

As with #4678, this is only a draft, and will be edited in-place.

Goals

keep things friendly toward first-time Cask authors
make things even more friendly toward first-time Cask authors
enabling tech for brew cask upgrade
remove everything we aren't committed to keeping
batch multiple DSL changes together, so we aren't always in a wait-6-weeks/amend-Casks loop

Proposed DSL Changes

Tracker

This tracker ignores new functionality such as implementing gpg on the backend or adding zap stanzas to Casks. The purpose is tracking the stabilization of Cask DSL 1.0 (purely as a language) and when we can merge #3066.

References

This is a tracking issue referred to in #4678 , the roadmap for brew cask upgrade

There is a followup tracker at #7683.

Vítor Galvão · Answer 1 · Thu Jun 05 2014 19:29:48 GMT+0800 (China Standard Time)

We also need a stanza for after copying is implemented, to deal with special cases.

fanquake · Answer 2 · Thu Jun 05 2014 20:08:02 GMT+0800 (China Standard Time)

Will need to read through this tomorrow when I get a chance

Roland Walker · Answer 3 · Thu Jun 05 2014 21:43:34 GMT+0800 (China Standard Time)

@fanquake take your time, there is no hurry.

Roland Walker · Answer 4 · Thu Jun 05 2014 22:11:32 GMT+0800 (China Standard Time)

I guess I forgot to prioritize these. The important removal in my view is install. The important addition is app. The rest are under the category of "easier to make changes all at once than to parcel them out".

@vitorgalvao would that work as an option copy do ... end block? I.e. we add an extensible option keyword?

Also paging @phinze.

Vítor Galvão · Answer 5 · Thu Jun 05 2014 22:30:27 GMT+0800 (China Standard Time)

I don’t think we’d need a block. I was envisioning it simply as an optional stanza, since it won’t need extra options (this is really the only part with different needs in linking and copying), and should be needed sparingly. Something like (using gridwars as the example)

class Gridwars < Cask
  url 'http://gridwars.marune.de/bin/gridwars_osx_x86.zip'
  homepage 'http://gridwars.marune.de/'
  version '9.3.2006'
  sha256 '39694d6d7f7af1a25818d10dbd811d0309562622f91f43f71d8b217bccdb03fb'
  app 'gridwars_osx_x86/gridwars.app'
  copy 'gridwars_osx_x86'
end

copy is a verb, so we might want to change that.

Roland Walker · Answer 6 · Sat Jun 14 2014 22:37:36 GMT+0800 (China Standard Time)

@vitorgalvao I'm almost done with these proposals, except for your suggested copy, which I didn't entirely grasp.

Does copy always take a single argument?
Is it possible that the same need is covered by the suite stanza, coupled with a future --copy option? suite 'gridwars_osx_x86' would mean: "create ~/Applications/gridwars_osx_x86", whether by linking or copying.

Vítor Galvão · Answer 7 · Sat Jun 14 2014 23:37:22 GMT+0800 (China Standard Time)

Yes. As per your second point, suite seems like it will do it.

Roland Walker · Answer 8 · Sun Jun 15 2014 03:53:20 GMT+0800 (China Standard Time)

@caskroom/maintainers, all specific DSL proposals given above now have corresponding PRs.

Edit: as of 23 Jun 14, this includes new additions to the above.

Vítor Galvão · Answer 9 · Tue Nov 18 2014 07:05:36 GMT+0800 (China Standard Time)

@rolandwalker Just to clarify, how are you envisioning suite working? Looking through the documentation, it might be going in a slightly different direction than what I was thinking. Let’s take gridwars.rb as the example. Its zip contains a gridwars_osx_x86 directory, with gridwars.app and other assets (needed for the game to actually run) inside it. Since copying is to not be considered a stanza anymore (which I think is a good decision) here’s how I am envisioning suite:

app and suite are not mutually exclusive. An app can have either, neither (cases of pkg, or installer, for example), or both.
If only app or only suite are present, they’ll do the same: link or copy (when that’s implemented) their arguments to the applicable location.
If both app and suite are present, then they’ll work differently when linking or copying. When linking, only app will be considered¹; when copying, only suite will be considered¹.

So gridwars.rb, under this example, would become

cask :v1 => 'gridwars' do
  version '9.3.2006'
  sha256 '39694d6d7f7af1a25818d10dbd811d0309562622f91f43f71d8b217bccdb03fb'

  url 'http://gridwars.marune.de/bin/gridwars_osx_x86.zip'
  homepage 'http://gridwars.marune.de/'
  license :unknown

  app 'gridwars_osx_x86/gridwars.app'
  suite 'gridwars_osx_x86'
end

while apps like sketchup.rb (uses suite) and acorn.rb (uses app) would remain as they are, since copying or linking them should yield the same result.

¹ It works since the link is still accessing the app in the directory with every other resource that might be needed.
² It needs to be this way, since copying only the app would break the application.

Roland Walker · Answer 10 · Tue Nov 18 2014 20:25:10 GMT+0800 (China Standard Time)

@vitorgalvao, hmm, I think the implicit change in behavior described above would be unpredictable to both end-users and Cask authors.

However, there is a need describe the apps that are within a suite for other reasons, such as determining the runtime version number.

And I'm definitely in favor of giving control to end-users who prefer a flat Applications folder, or a hierarchical one. We just need to define a good interface for that. What about a command-line option and corresponding config-file option? I'm not saying this is a good choice of name, but

$ brew cask install --appfolder gridwars

Vítor Galvão · Answer 11 · Tue Nov 18 2014 22:57:05 GMT+0800 (China Standard Time)

@rolandwalker I’m not so much thinking about control, but breakage. In the gridwars example, linking only the app bundle (the current behaviour) makes a lot of sense because you don’t care about whatever else is in that directory, and having to navigate to it doesn’t make sense (you just want to execute the game, anyway). However, having the whole directory is a necessity when copying, because without it the game won’t run.

When I asked “how are you envisioning suite working”, it was the wrong question. What I should ask is “how are you envisioning copying working?” It’s fine if you’re just thinking “grab whatever is in app or suite and copy instead of linking”, but then why have suite at all? Then it’s just there for semantics, but that could’ve been solved by keeping link around and using it in app bundles or directories as needed. As it stands, I see no compelling reason for both app and suite to exist: they’re just doing the same.

Having a command-line option won’t work, because then we’re putting the burden on the user of knowing how the cask is structured. It’s safe to assume that once we have copying implemented, users will be divided between the ones that do one or the other exclusively. It doesn’t make sense for the copying user (that likely will have that option set in one of the shell’s startup files) to have to think “oh, in this articular cask I need to give this specific flag, or else it’ll break”. Even us wouldn’t be able to remember.

Caleb Xu · Answer 12 · Thu Dec 11 2014 09:56:38 GMT+0800 (China Standard Time)

At last, glad to see this is through.