RFC: Rename dist-newstyle/

[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 RFC: Rename dist-newstyle/ #5731 (comment))

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
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 #5731 (comment))

...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 #5731 (comment))

[hvr]

VOTE: target (as suggested in #5731 (comment))

[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.

[andreasabel]

Personally, I'd block this on both #5271 (and un-hard-wiring the directory name in all other places in the codebase)

I agree.
However, I'd leave the default as is now (dist-newstyle). Maybe a silly name, but now tools (e.g. my cabal-clean) are relying on it, and it's too late to change it.
If there should be a (de-facto) standard across build tools, this would be a reason to conform it, but I do not see one yet (?) ...

[orome]

On macOS, if this must be located in ~ rather than ~/Library, then it should be hidden — i.e. renamed to start with a ..

[andreasabel]

Another argument for keeping the current name is that probably thousands of .gitignore files in Haskell projects contain an entry /dist-newstyle/ or similar.

I follow @phadej 's suggestion and close this because I really think the ship has sailed on that one.

[mouse07410]

In short: do not rename.

Rather silly idea.

[ulysses4ever]

I agree with closing. A change would be a disruption with no benefit.

[georgefst]

😢

Since it's purely aesthetic, I'll reluctantly concede. To be honest, it always seemed too late once 3.0 was out (or maybe even earlier - IIRC v2- commands were widely used as soon as they were added). But it is rather unfortunate that we're saddled with such a silly name. I know we like to avoid success at all costs, but polish does matter and these little things can add up and affect perceptions. I'll continue to wince a little every time I see or type dist-newstyle.

[jneira]

and there is a small advantage: it is more probable to not reach the windows path limit
I guess some packages uploaded before v2 chose its name to not reach it

[orome]

It could be called anything, but if it's going to be in ~ on macOS, it should be hidden by default. Our policies here delete it along with any other visible cruft in ~ as part of routine maintenance.

[andreasabel]

@orome: Isn't there a misunderstanding? The discussion here is not about ~/.cabal.
What is the scenario that dist-newstyle ends up directly under ~?

[orome]

What is the scenario that dist-newstyle ends up directly under ~?

That's where I see it. If it were under ~/.cabal there would be no issue.

[emilypi]

Except then you've got package build data bleeding into the home user space and it severely overcomplicates things, because you also need a project directory indexing convention and it mixes concerns with other install/caching objects. I'd be extremely opposed to that.

[orome]

@emilypi Not sure what you mean. Should I be seeing it under ~ or should I be using it under ~/.cabal It shouldn't be under ~ (at least not if it's visible), I agree. But it is. I have no idea why. I've done everything by the book.

[emilypi]

@orome: I'm not sure what you're referring to at this point. You need to clarify what you mean by "seeing it". What's "it"? dist-newstyle? If so, defaulting to building dist-newstyle objects in ~ never been the specification unless you're building a project from a .cabal file specified in ~. In which case, stop that if you don't like it - you're specifiying the project root to be ~! The convention is that dist-newstyle always occurs in the project root namespace, which doesn't require ~ to function: it can be in / for all Cabal cares. As long as that's the project root specified by the build file. dist-newstyle objects always default to being built relative to the project root.

[orome]

@emilypi I'm not so sure myself. All I know is that it appears when I run cabal update in ~. If that's not what I'm supposed to do for user global, then where should I be running it? If it is, then that's the problem: it should not add a visible file there.

[andreasabel]

@orome: The problem you describe is discussed there:

• cabal update creates dist-newstyle folder in $PWD #8589

Here it is only about the naming of dist-newstyle, which of course should not end up in ~ in usual circumstances.

[emilypi]

Aha! Glad we dug down into your issue @orome.

[jeltsch]

I’ve been seeing the naming dist-newstyle as an issue for quite a long time, but I’ve found this GitHub issue only now. Interesting to skim through the comments.

An argument that has been brought forward several times is more or less that a change of this name would cause too much effort for thousands of packages for a purely cosmetic change. I don’t really share this argument, for two reasons:

• The changes would be spread across many projects and developers, so that the effort per project or person would be rather small.
• Cosmetics or, more general, beauty is important.
• It’s not only about cosmetics but also about comprehensibility. The name dist-newstyle gives completely wrong suggestions, as it essentially implies that the contents of this directory are about distribution and that they belong to a specific style that is still new.

So I still see a change in naming of said directory worth considering. For the time being, I’ll at least create my own little corner of beauty on my laptop with a wrapper script that invokes cabal --builddir=.build-products "$@".

[andreasabel]

Note that renaming dist-newstyle would essentially force third-party tools to support both dist-newstyle and the new name because not all of the world switches cabal version in a single moment (you'll have years of transition...).

@jeltsch wrote:

• The changes would be spread across many projects and developers, so that the effort per project or person would be rather small.

So you would impose this busy-work on all these projects and developers for the sake of removing a wart that violates your sense of aesthetics?

I’ll at least create my own little corner of beauty on my laptop with a wrapper script that invokes cabal --builddir=.build-products "$@".

I think this is the way to go until a majority does so as well, and then this majority can collect the funds to pay for the cosmetic surgery.

Sorry to put it so bluntly.

[jeltsch]

for the sake of removing a wart that violates your sense of aesthetics

the cosmetic surgery

In my previous comment, I argued precisely why this is not just a cosmetic issue and also why this is not just a personal issue of mine (there are objective reasons against the name dist-newstyle).

Sorry to put it so bluntly.

Feel free to react bluntly, but please read carefully the message you react to. 🙂

[mouse07410]

IMHO, there are great many places and efforts that works benefit the community far more than this (IMHO, misguided) suggestion. I'm strongly against it.

Besides, I don't see how a change on a project would be cheaper if it impacts/hurts not a few but many - e.g., if you break a leg, would you feel any less pain if you knew that 10000 of other developers suffered the same?

Finally, yes - I agree: it would be good for everybody to read carefully what they're responding to. That includes the author of the previous comment.