Cabal: RFC: Rename `dist-newstyle/` for 3.2

[hvr]

NB: I want to emphasize, this is about the default folder name which the user can always override in their ~/.cabal/config, (in future) via cabal.project, or via CLI; tooling must not assume the folder to be named in a certain way unless it either a) forces a specific folder name or b) infers the currently active name (ideally by querying cabal)

---

When cabal new-build premiered in cabal 1.24, the provisional name dist-newstyle/ for the new-build specific dist/ folder (i.e. the default --builddir) was chosen in order to reduce the likelihood of old-build / new-build stepping on each others toes when mixing the command families.

However, now the time has come (since cabal 3.0 will be disruptive anyway by changing what cabal build means in the UI -- NB: #5800 switch defaults to v2 got merged to master already!) to rename the dist-newstyle to its final name;

Ideally the name should be reasonably short (to reduce risk of PATH_MAX issues as well make the output less noisy) and it should be a name that is reasonably unlikely to clash with filenames users would want to place into their cabal package folders.

So here's some ideas to start the bikeshedding:

• dist/
• dist.v2/ (or dist-v2/ or v2-dist/)
• builddir/
• dist/v2 (suggested in https://github.com/haskell/cabal/issues/5731#issuecomment-452208621)

Prefixing with a . would reduce the likelihood of clashes as well as get them out of sight for unix shell users:

• .dist/
• .build/
• .builddir/
• .cabal/

For Windows, the above could instead use _s (this scheme is somewhat popular in the Python ecosystem iirc):

• _dist/
• _build/
• _builddir/
• _cabal/

PS: Additional things to consider:

• @23Skidoo brought up that people will have to modify their .gitignores
• dist might be considered a misnomer as dist/ isn't so much about generating artifacts for distribution but it's really more about being a build dir (NB: it can be controlled by the --builddir flag! There is no --distdir flag) where cabal stores its caches and compile output (and also sdists); it's not clear why dist/ was chosen as the default builddir originally many years ago
• cabal v2-sdist all currently places its files into dist-newstyle/sdist/*.tar.gz
• Tooling that needs to locate the --builddir folder needs to take into account that the default builddir can be tweaked via ~/.cabal/config and so either needs to query the current default builddir (we might need a cabal path ... command or something) or if it invokes cabal set it explicitly via --builddir

[typedrat]

+1 for dist/ or v2-dist/, with our current dist/ becoming v1-dist/.

[phadej]

I'm strongly against anything without dist prefix.

Somehow

dist-*

.gitignore is prettier than variants (IMHO). (I do also use a lot of custom named, yet dist-something matching --builddirs ).

[23Skidoo]

How about dist/v2?

[Mistuke]

Personally I prefer .build as I never really understood why it's called a dist, always been rather confusing especially since cabal sdist doesn't put things in dist (off the top of my head). Though I'm fine with dist/v2/ and dist/2/

[fommil]

I prefer dist (or something under it) so that existing .gitignore configurations continue to work and we don't clash with any directory names that anybody may be using in their projects.

If breaking is acceptable, I prefer .cabal

[23Skidoo]

.cabal would clash with ~/.cabal, I'd prefer something like .cabal-build or .cabal-work if we were to ditch dist.

[hvr]

.cabal would clash with ~/.cabal

btw, why is that a problem? what scenario are you worried about?

[23Skidoo]

Someone running cabal clean in the home directory for example.

[hvr]

I see... btw, that can already cause problems if you configure builddir: .cabal yourself in ~/.cabal/config...

Even if we don't go for builddir: .cabal we should IMO add some sanity check to cabal which checks for whether builddir points to the basedir of CABAL_CONFIG's current path, unless there's a legitimate scenario where you'd want to place your cabal config file into cabal's work folder.

btw, we could also go for a folder .cbl (would be as short as dist), or a versioned .cabal3 or ._cabal (so weirdly named it surely won't clash with anything) :-)

[23Skidoo]

btw, that can already cause problems if you configure builddir: .cabal yourself in ~/.cabal/config...

Yeah, but most people stick to defaults. Agreed that more sanity checking is never bad.

[chshersh]

I would like to add couple thoughts to the discussion. I don't think that having different names for Linux and Windows is a good idea. This will make harder for people to help beginners, because you can't just tell _look at this directory_. Also, I don't think that .cabal is a good name. I usually refer to package-name.cabal file as simply _.cabal file_ by referring to the extension and omitting name of the package. Having .cabal directory will complicate things.

P.S. Sorry, fat-fingered

[aloiscochard]

Just wanted to chime in to voice my opinion.

I don't think adding a platform specific prefix makes any sense, as I don't think that increase the user experience.

Good tools do not rely on platform specific prefixes but rather read .gitignore to give programmer a good UX. I have in mind vim or fzf for example, I'm sure you can find plenty others.

Based on that, I would prefer if we remain backward compatible as pointed out by @fommil.

If for a change, I vote for target, simply because it used by cargo (Rust) and sbt (Scala) and having consistency among the build tools is better to me than any other arguments shown here.

[hvr]

We should really come to an agreement soon regarding which default to pick for the foldername; given it's merely a default name picked in case the user didn't set anything else in their ~/.cabal.config, it shouldn't matter much (and I really hope tooling won't make the bad assumption the folder to be always named dist or whatever default we pick it to be).

So it seems to me like sticking with the (in my opinion) misnamed dist folder name is still among the favorite choices (judging from the upvotes at https://github.com/haskell/cabal/issues/5731#issuecomment-452208621)

...but there's also a new interesting suggestion to use the folder name target (as used by sbt and cargo, which appears to have a --target-dir flag). The only downside I can see about this is if there'd be incentive to use sbt/rust/cabal in the same base-folder; but I think those cases are fairly rare, and if you need this you can always configure a different folder name via --builddir=....

So I propose to start voting on concrete choices; I'll create a couple comments with concrete suggestions to vote upon via emoji up/down votes; if you don't agree with the choices, feel free to add your own concrete suggestion following the same format.

---

PS: There's one minor flaw with dist/v2 in terms of v1/v2 isolation -- cabal v1-clean would currently remove it as well; we could probably tweak v1-clean in cabal 3.0 to leave dist/v2 unharmed; also, should cabal v2-clean remove only dist/v2 or also dist (maybe only if it ends up being empty?)

[hvr]

VOTE: dist/v2 (as suggested already at https://github.com/haskell/cabal/issues/5731#issuecomment-452208621)

[hvr]

VOTE: target (as suggested in https://github.com/haskell/cabal/issues/5731#issuecomment-493737909)

[hvr]

VOTE: dist (i.e. no subfolder for versioning; no explicit support for mixing v1-* and v2-* style commands)

[chris-martin]

It's funny I just happened to come across this discussion right after watching Lukas Eder's talk on API design mistakes - https://youtu.be/NJpQVIZhIYk?t=1236

I have to restrain myself - it doesn't matter that much, and the impact on the users is horrible. Changing the API is easy, for the ones that maintain them. You have to change the documentation... you have think of external documentation as well, if you're building a public product that is used by everyone, well, you're not gonna update Stack Overflow. For what, for a change of name? That's not worth it.

The addition of dist-newstyle was an additional thing to ignore in IntelliJ, gitignore, etc. I'd rather see nothing change than get whatever name is my favorite choice of name at the moment. dist is the only directory that likely every repo with a Haskell project already gitignores, so dist or a subdirectory of dist is the best default.

[phadej]

I'm closing this as wont do. dist-newstyle is already hardcoded in places where it would cause pain to change (e.g. packaging scripts of alex, cabal-plan source etc.).

Changing the directory at this point will make a lot of people not following cabal-install development closely quite unhappy.

[23Skidoo]

:-(
I'd still like to make this change, even if it causes some short-term pain.

[phadej]

@23Skidoo not for 3.0

[23Skidoo]

Sure, it can wait until 3.2.

[chshersh]

If you care about this change affecting people who don't carefully follow Cabal development, you can announce it in advance on Reddit, Twitter, Discourse, Discord, Facebook and other Haskell sub-communities. With this approach, everyone will be aware of this breaking change. And you can even get more feedback.

[hvr]

let's tenatively schedule this for 3.2 as per https://github.com/haskell/cabal/issues/5731#issuecomment-524593331

Btw, if had renamed it as planned for 3.0, we would have eschewed the likes of #6163 and #6099 in cabal 3.0

[phadej]

Now it's the time to make decision on this. I'll move the target to 3.4 on December 5th 2019, if there's no decision before that.

[phadej]

December 5th have passed. Moving to 3.4

[emilypi]

Since we've started committing to removing the v1-legacy code, it doesn't make much sense to refer to a v2 suffix or path. The same is true of commands. How many versions were planned before phasing out the v1-* and v2-* cruft and settling on v2 as standard? It seems a bit out of place at this point. Or at the very least, it seems like a confusion in direction.

[szabi]

I'd really +1 for prefixing the new default with ., be it .dist or .build or whatever ultimately.

This would make CLI tools like ls, tree or even rg which follow the convention to ignore .* files by default and include them only when requested so much more usable. tree is really not that useful right now, as its output to get an overview of the project structure is littered with the subtree of dist-newstyle.

[szabi]

given it's merely a default name picked in case the user didn't set anything else in their ~/.cabal.config, it shouldn't matter much

This default cannot be overridden, see https://github.com/haskell/cabal/issues/5271, only by explicitly using --builddir= on the command line every time.

[phadej]

I'm tempted to close this issue as it seems to not move anywhere. Optimistically remilestoning for 3.6