Homebrew-cask: Homebrew/Homebrew Cask deduplication and naming guidelines

[adidalal]

This issue has cropped up in a few places before, and seems to still be unresolved.

There are a few apps that have both a Formula and a Cask, and in the interest of deduplication, there's an ongoing effort to remove one in favor of the other.

However, it is my strong opinion that favoring one over the other is incorrect, and there are legitimate use cases for having both a Formula, and a Cask for the same application.

These include:

• Preference of vendor-provided builds/binary
• Ability to use pre-compiled builds (instead of building from source)
• Differing functionality in the two (ie. one includes a GUI)

Therefore, this issue aims to discuss and implement a formal naming scheme for such cases, so that there does not need to be the same discussion every time a user brings up a previously removed Cask for re-inclusion.

A starting point for naming: "If a application is not identical or has additional functionality as compared to the homebrew Formula, the Cask should be named with a -app or -gui suffix." (the token reference would be changed accordingly)

Examples/relevant issues:
https://github.com/caskroom/homebrew-cask/pull/24232
https://github.com/caskroom/homebrew-cask/pull/23584
https://github.com/caskroom/homebrew-cask/pull/23973

I'd like to specifically invite @vitorgalvao and @MikeMcQuaid into this discussion, as they have been active in this regard, but also other users, if they have thoughts one way or another.

[MikeMcQuaid]

Preference of vendor-provided builds/binary

I think this is valid but should be provided by non-official taps.

Ability to use pre-compiled builds (instead of building from source)

Homebrew provides pre-compiled builds so not sure I understand this.

Differing functionality in the two (ie. one includes a GUI)

I agree with this. In most of these cases the upstream projects have had a different name e.g. foo.app in which case I'm fine with us having both if the names don't collide.

A starting point for naming: "If a application is not identical or has additional functionality as compared to the homebrew Formula, the Cask should be named with a -app or -gui suffix." (the token reference would be changed accordingly)

👍

[BenjaminHCCarr]

This at least forked from a discussion @adidalal and I were having. Not all packages have binaries.
MAS - The mac app store CLI interface does not:
https://github.com/Homebrew/homebrew-core/blob/master/Formula/mas.rb

This formula also requires full XCode.app to build (though I can't figure out why), I can download the release from https://github.com/argon/mas and it works find, but as I have CommandLineTools and not XCode.app, I can't build this formula. If you're mostly doing #FOSS and #CLI stuff there is no reason for XCode.app and it's multiple gigabytes, and monothlithic updates! Between Command Line Tools and the more up to date @Homebrew if you aren't doing swift or iOS why install?

If you're on an modern intel Mac laptop, you are locked into your original SSD and RAM, I don't want to "spend" at least 8GB of 256 on XCode, particularly that at run time it often doubles in size, that's about 6% of my total drive.

I think, particularly with the re head, we need a convention. Some packages already occur as casks and formulas, some have been move from casks to formulas, and some are one or the other.

A very stupid simpe solution would be to append: [formula]-cask.rb, there for you would get the formula first in completon, but could easily install a cask if that is what you desire.

[MikeMcQuaid]

This formula also requires full XCode.app to build (though I can't figure out why), I can download the release from https://github.com/argon/mas and it works find, but as I have CommandLineTools and not XCode.app, I can't build this formula. If you're mostly doing #FOSS and #CLI stuff there is no reason for XCode.app and it's multiple gigabytes, and monothlithic updates! Between Command Line Tools and the more up to date @Homebrew if you aren't doing swift or iOS why install?

Because the CLT doesn't provide xcodebuild.

MAS - The mac app store CLI interface does not:
https://github.com/Homebrew/homebrew-core/blob/master/Formula/mas.rb

Homebrew distributes a binary package for this for El Capitan, as noted there.

[vitorgalvao]

Preference of vendor-provided builds/binary

I think this is valid but should be provided by non-official taps.

No objection. I lean heavily towards having as few duplicates as possible, and sacrificing one of the versions when the difference is too small. See the image on the bottom of https://github.com/caskroom/homebrew-cask/issues/15603#issuecomment-225932164:

I think, particularly with the re head, we need a convention.

There is a convention in progress. Half of https://github.com/caskroom/homebrew-cask/issues/15603 is about that. Start with https://github.com/caskroom/homebrew-cask/issues/15603#issuecomment-223381890 and go down.

A very stupid simpe solution would be to append: [formula]-cask.rb

I don’t like that particular appendage, as it isn’t descriptive of why it exists.

Since this problem will (hopefully) occur rarely, having a few documented exceptions that use -app seems like a fast solution that should not cause problems in the future. I prefer -app to -gui precisely because -app directly contradicts the token reference. This not only gives the user an immediate clue if they know the rule, it will prevent other rule collisions. This preference applies wether the GUI is a .app (if that ever happens) or not, for consistency.

However, I also think the reverse should be true and HB should add -cli (or whatever is found appropriate, though similar rules for both are a plus to users and maintainers) when appropriate.

Examples: corectl should (and was) disambiguated by HBC since it seems to be primarily a CLI app, and only then a GUI (right at the top of the README, they mention installation via HB). Same goes for sickbeard (at least at the moment). transmission, on the other hand, is primarily a GUI app and popular as such, the CLI is in support of the GUI and as such should instead be renamed by HB.

So as for the rule itself, my proposal is to add -app when appropriate, and add a note about that to the token reference. Also for the converse rule to be added to HB, and we discuss who adds the suffix on a case-by-case basis.

All that said, every case still needs to be taken into account regarding if the app and cli versions are different enough to warrant having them both (in the case of https://github.com/caskroom/homebrew-cask/pull/24232, I don’t think it does).

[MikeMcQuaid]

Also for the converse rule to be added to HB, and we discuss who adds the suffix on a case-by-case basis.

I don't think Homebrew will be doing this, I'm afraid. Almost all our formulae are CLI-only so that seems redundant.

[adidalal]

We will then have to have duplicate token names, as transmission-app, for example, doesn't make any sense either (for the same reason)

brew install transmission - CLI app
brew cask install transmission - GUI app

We could add in a caveat about the existence of the other version (I believe HB already does this for a few apps, I remember ngrok as one)

[MikeMcQuaid]

Yeh, we do with transmission and I'm definitely up for doing this more widely too 👍

[vitorgalvao]

But if we agree to have a duplicate token with transmission, why is corectl different?

[MikeMcQuaid]

https://github.com/TheNewNormal/corectl vs. https://github.com/TheNewNormal/corectl.app

[vitorgalvao]

At first, I thought that could cement the rule: “If a Homebrew formula and a Homebrew-Cask cask both exist with the same token and they both refer to the same app — respectively a CLI a GUI — and the GUI app is simply a wrapper on the CLI tool but has been decided to provide enough value to warrant the inclusion of both the formula and the cask, the cask will have the -app suffix”. The more I think about it, though, the more unsure I am that is clear to users.

What I don’t get is this:

I think my main issue is the naming that (repeatedly) makes two projects that are different seem to be the same project, even when created by different authors.

Yes, they both have different authors, but they’re both on the same organisation and one is a wrapper on the work of the other. They are in every way related (it’s no longer unofficial it it belongs to the same organisation). I fail to see why corectl is a problem and transmission is not. I also don’t get how any user will understand why one of those cases has a suffix and the other not. I don’t get it, and I’m supposed to be writing a rule to clarify the difference.

Perhaps it helps if I clarify that I strongly disagree with this:

"Power users" is more the target audience of Homebrew Cask; it's generally a subset of existing Homebrew users who want a more CLI-heavy workflow.

I disagree because I know from users themselves this is not the case (not enough to generalise on it, anyway). There’s a significant amount of users that use HBC and not HB. Many of them aren’t even CLI-savy — they know just enough to know HBC is useful for them (repeated installations, and the like) and don’t care about the rest.

[MikeMcQuaid]

Yes, they both have different authors, but they’re both on the same organisation and one is a wrapper on the work of the other. They are in every way related (it’s no longer unofficial it it belongs to the same organisation).

They are separate projects, though. One encompasses the other (as does almost every GUI that wraps CLI behaviour). In Homebrew we name projects based on what upstreams call them. In this case it's pretty clear (to me at least) that these projects are named differently. In the cases they are named the same (e.g. Transmission) there's more debate to me.

I don’t get it, and I’m supposed to be writing a rule to clarify the difference.

Personally I think rules are part of the problem here. Recommendations are a better idea; almost every example we come up with will have a counterexample where it doesn't make sense.

[MikeMcQuaid]

Personally I think rules are part of the problem here. Recommendations are a better idea; almost every example we come up with will have a counterexample where it doesn't make sense.

To elaborate a bit on this: I think the situation where there's a rule saying "never use -app in the name" even when upstream calls the project corectl.app means that we end up in a pickle. I'd propose "use whatever name upstream uses (including -app or -gui if they specify that)" and we can discuss individual cases if we feel there's a confusion between Homebrew and Cask.

[vitorgalvao]

Problem is recommendations aren’t enough for us. We know because we lived with them, and this repo was an absolute mess. It took a lot of work to end deduplication inside the main repo. HB is more strict about what it allows while HBC is more lenient (and I believe those are the right decisions for each). Making clear rules was the only way to end the pickle we were in, and even so we still get wrong submissions (that do not follow the token reference, even if the submitter ticks the box saying they read it).

“whatever name upstream uses” is something that does not exist. Upstream frequently uses two, three, and sometimes more different names (with varying degrees of capitalisation, spaces between words, added or removed names) for the same application on the same website, and sometimes even on the same page! I wish I were joking, but I’m not.

corectl.app is a particularly bad case. Why would a user ever consider .app to be part of the name? Every app bundle ends in .app, and almost none consider that an official part of their name.

Simply put, recommendations is something we know we cannot have, we need to have clear rules. Exceptions are fine, but it also needs to be clear when they are to be used.

[MikeMcQuaid]

corectl.app is a particularly bad case. Why would a user ever consider .app to be part of the name? Every app bundle ends in .app, and almost none consider that an official part of their name.

Whether a user would or not: upstream refer to it as Corectl App or Corectl.app in every place on their homepage (the GitHub repo).

“whatever name upstream uses” is something that does not exist. Upstream frequently uses two, three, and sometimes more different names (with varying degrees of capitalisation, spaces between words, added or removed names) for the same application on the same website, and sometimes even on the same page! I wish I were joking, but I’m not.

In that case: I'd say pick from _one_ of the names they use rather than making up your own.

[BenjaminHCCarr]

I think discussion exactly outlines why a convention is needed (and @vitorgalvao thanks for your help with my first formula with a wrong token). But the mas example:
https://github.com/argon/mas
when compiled by xcodebuild (thank @MikeMcQuaid) is a compiled command line application.

Maybe part of the solution is to push people from Caskroom (sorry) to:
https://github.com/Homebrew/homebrew-gui
https://github.com/Homebrew/homebrew-binary (which was deprecated, but maybe not for the right reasons with the merging of casks)

Or push for more testing of bottles..... I'm not on El Cap due to a needed legacy application for biological research, so I don't pull the binary with the mas formula. Interestingly the mas release binary runs fine on multiple older versions os OSX.
So: bottle do .... => :el_capitan
means I skip what is likely a working binary.

Is it possible to ask HB to expand Travis (which I am sure is already severely over tasked) to see if a binary segfaults on older platforms? I know this isn't perfect, but seeing as it would be automatic it might be a bandaid (I know we hate bandaids).

In this case the formula is just calling "mas-cli.xcodeproj" which is in tree, so one would think that the binary requirements of the project would be the same as those in homebrew. I have not written a bottle formula for HB, I'm being very lazy, but also very tired, so something is compiling the binary, I would assume other than the maintainer as that would allow subterfuge and injection.

With my apple MBP "appliance" I can't upgrade anything, and if each dataset is ~16GB, then 256G goes quickly (and yes I have a mSD card in the SD slot already, for non active data).

[MikeMcQuaid]

I'm not on El Cap due to a needed legacy application for biological research

It may be worth creating an OS X VM with e.g. VMware Fusion and running it there. Yosemite will stop getting Xcode updates soon and will stop getting binary packages in about a year.

Interestingly the mas release binary runs fine on multiple older versions os OSX.

This is regrettable and something we'd like to handle better but can't really yet, unfortunately. We assume binaries are tied to a single platform as we don't have a good way of specifying that they can be reused but you can't build from source on that version.

[BenjaminHCCarr]

will when I install XCode.app to test it compiles fine, it's just that XCode is so big, doesn't delta update, etc. that I can't "waste" 8-16GB of my locked in 256 on XCode, when the command line package serves all of my needs.

I'm not a fan of the XCode gui, I use RStudio and Eclipse, but more likely to use atom.app to edit code other than R and then run it in terminal or .venv. I don't do gui stuff 98% of the time. But you are right, the VM is reasonable to this particular problem.

[RandomDSdevel]

For the GUI parts of programs that rely mostly on CLIs, why couldn't the casks for the GUI parts just add a suffix describing what kind of GUI extension the cask adds to the corresponding formula's installed resource's CLI? For example, casks that install menu extras could end with -menuextra, -menu-extra, -menu_extra, or something like that.

[vitorgalvao]

@RandomDSdevel Because it would require users to know all that and interpret each case in their heads. Many of our users (and even contributors! We have many whose first code contribution is to HBC) are not technical, and making such a rule would lead to the aforementioned mess on the repo.

The rule may also not be consistent with itself, e.g. in cases where the CLI can’t even be added to HB, but can be in HBC.

Bottom line is we need our naming to be predictable. This is not a supposition, but something we know, because we lived (including me personally) through the alternative.

[RandomDSdevel]

@vitorgalvao: Aw, scrap. Well, it was worth a thought, even if it was only a half-baked one. (😆.)

[nixpulvis]

I've been giving a lot of thought as of late to the namespace. We've been down this road before, and we have many partial solutions or incomplete solutions but let's not ignore the learning. Here we are trying to solve a lot of these problems with conventions like-app as possible my favorite of the bunch ATM.

Today, for example, these are the two options for installing docker:

brew install docker
brew cask install docker

I actually _almost_ like this. But the issue is fundamental to cask itself.

First of all it's a stupid name, sorry but it's true. Cask installing something makes no sense. I actually just tried to tell a someone about brew cask ... and they typed brew casc ... a few times. This is a tangible indication for me that this is a bad choice of name for something as fundamental as installing software onto a computer.

The name is even more obviously wrong when we start thinking about how we use it. When I'm writing a shell command, I'm effectively an LL grammar producer (that's the beauty of the pipe right?) Anyway, if I'm creating a command to install something, I'd want to right down brew install ruby for example, because that is the thought I had that led me to the shell. Now the question of if something is an App or a Cask or a whatever is interesting, but not always decidable. Docker was a prefect example for me today.

Ok so let see what a system might look like:

# path := <formula>
#       | ("::" <formula>).*
brew install <path>

# Examples
brew install ruby  # Installs a local ruby, could fallback on global to maintain backwards compatibility.
brew install ::ruby  # Installs a global ruby.
brew install docker
brew install docker::app
brew install nixpulvis::some_personal_stuff

I'm thinking through a lot of this while I type it on a bus, so sorry is there are mistake in spelling or whatever.

P.S. A less ambitious solution could be as simple as renaming cask to app.

[MikeMcQuaid]

brew install docker::app

We're unlikely to do anything like that that doesn't have some way of signalling "you are not installing open-source software".

[nixpulvis]

I still think it should ideally go brew install ... but I can see your point about wanting more separation for OSS.

[vitorgalvao]

P.S. A less ambitious solution could be as simple as renaming cask to app.

HBC also installs fonts (over 1000 of them), prefpanes, internet plugins, and a bunch of other things, _including CLI-only programs_. Calling it app would not only be reductive, it would be inaccurate.

just tried to tell a someone about brew cask ... and they typed brew casc ... a few times. This is a tangible indication for me that this is a bad choice of name

I profusely disagree that’s a tangible indication of anything — it’s simply an anecdote. It’s the only case I ever heard of it, and it’s not like that person will keep forgetting forever. They learnt once how it’s written, and that’s it. It seems to me like that single case is being blown way out of proportion. It’s not like apt-get, yum, nix, whatever else, are great intuitive names. You do need to learn them, just like any other CLI tool. xdsgrxazs would be a problematic name, cask far from it.

I’m neutral on the name. I wasn’t the one to invent it, but I understand why it was chosen: to continue the beer-related nomenclature — which is (was?) being discussed on HB’s main repo as a potential issue for new users, since it can make web searching harder.

Furthermore, HBC is too well known already. Just like Homebrew had (has?) a note about the naming being too generic but it being too late to change it, so it is with Homebrew-Cask. I see no benefit in changing the name, but a lot of confusion.

In the end, what you type after brew isn’t the problem. HBC doesn’t install formulas, it installs casks. They are named differently because they are built differently with different goals and capabilities. Replacing cask before with ::app after doesn’t resolve the issue.

All that said, if you personally think that solution would work for yourself or when teaching others, you might like to know it already works. Do brew install caskroom/cask/docker, for example, and it works.

[nixpulvis]

I think what I'm really getting at is that there are two install terms with different semantics. Granted yes, one comes after a word cask, still confusing. English is plagued with things like this, and some people like myself hate that, others do not.

In hindsight I should re-read my issues for tone, as I see how bad it was now. I was trying to provide a motivation for the issue, and a description of the problem. When I say cask is a bad name, I should be much more clear. It's not bad, it's just an indication of a problem with the model. In this case the fact that my one true macOS installer is really two.

[vitorgalvao]

I think what I'm really getting at is that there are two install terms with different semantics.
(…)
my one true macOS installer is really two.

Agreed (also, for some reason I find that last sentence funny, and it is true). But they come from two different pieces of software with different goals, hence the confusion. HBC stood on the shoulders of HB for some infrastructure, but eventually realised they have such important differences, we even considered splitting up completely from HB (didn’t help we had a few major breakages in a short amount of time due to changes in HB).

In the end, we decided on the opposite solution and merge even further, which is where we’re at now. However, we’re still like two different pieces of software, and that isn’t easy to undo. Hopefully, with our deduplication efforts and by making the line that differentiates us clearer (be it with naming rules or whatever else), in time this confusion will happen less and less.

In hindsight I should re-read my issues for tone, as I see how bad it was now.

Not at all! And if I made it seem like I was in any way angered by your comment, you can be sure that wasn’t the case. I disagree completely with your idea, yes, but your tone was absolutely respectful. When reading a comment, I always imagine it being written with a genuine smile. That way, there’s less ambiguity, and any that still remains is skewed positively. Only when it’s impossible to read a comment in a good way do I know its intentions were negative (when someone directly insults us or displays unfounded obvious sarcasm, for example).

Over time, I’ve seen and been target of many unfairly rude and abusive users. You were definitely not one of them!

[nixpulvis]

First of all that's for the response.

Second, yea I get the reason we are where we are. And I do understand that there are core differences between cask and no cask, but the interface is just plain weird to me right now. I could see brew install cask ... even being better simple because it would force the knowledge/memory to use cask at the correct time. Plus having cask be a reserved word to Homebrew doesn't seem like a bad idea. I'm not at my computer now, but the thought that brew installl cask actually installs something scares me a bit.

[nixpulvis]

$ brew info qt5
...
.app bundles were installed.
Run `brew linkapps qt5` to symlink these to /Applications.

Seems like some formulas are using linkapps which I didn't even know existed (sorry if it's well known). Is this legacy?

[vitorgalvao]

@nixpulvis Those are still a necessity (e.g. mpv can produce an app bundle, but they don’t distribute them so HBC cannot have them, HB needs to be the one to build them).

See https://github.com/Homebrew/brew-evolution/pull/3 for a relevant discussion.

[MikeMcQuaid]

@nixpulvis @vitorgalvao That's something we plan to remove at some point.