haskell
s/nix style/v2-build/ in the documentation
I conjecture that mentioning Nix only adds confusion. Almost all people I know use v2-build (well actually they use new-build, but maybe v2-build is a bit better).
E.g.
- One of the primary innovations of Nix-style local builds is the distinction between local packages, which users edit and recompile and must be built per-project, versus external packages, which can be cached across projects.
- One of the primary innovations of
v2-buildlocal builds is the distinction between local packages, which users edit and recompile and must be built per-project, versus external packages, which can be cached across projects.
An example of confusion: Nix store can (and does) mean /nix/store for a lot of people.
+1, but it should also mention the other temporary names (nix-style local builds, new-*) so that at least it shows up in searches
But do we want to keep referring to v2-build forever? I assumed we'd phase out the term v2-build to become cabal build, at which point referring to it as v2-build will be more confusing than using the term we've been advertising this feature ever since cabal 1.24 (the term "new-build" and "v2-build" have been rather ephemeral in contrast to the term "nix-style local builds" which has been a constant throughtout time). And I've myself been referring to new-build and v2-build frequently also as "Nix-style" where it made sense (specifically when talking about the nix-style store)
I for one intend to keep referring to "Nix-style {store,hash,build}" (with an emphasis on "-style") where I refer to the concept related to the Nix-style store/hashes, as well as start to slowly phase out my use of "new-build" and "v2-build" in favor of just saying cabal {build,install,*} when I intend to refer to specific commands over the next couple years. In fact, I think it'll cause a lot more confusion to keep talking about the transitional v2-build or new-build terms after cabal 3.0, which is supposed to make the new-* and v2-* prefixes merely a historical artifact which a newcomer coming to cabal 3.0 ought not even need to know about!
I think @hvr did veto this. Nix-style it is.
For the future: don't use number, nor new, not foo-like "relative" references. Find some fancy word, the first thing you'll pick will stick.
Actually no.
https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html starts with
Nix-style local builds are a new build system implementation inspired by Nix. The Nix-style local build system is commonly called “v2-build” for short.
That needs to be changed in the way or another. Either
- we avoid "v2-build" and use nix-style in non-command-name context
- or "v2-build" is used in place of informal "nix-style"
Having consistent language would make documentation more polished almost for free.
well, note that
... commonly called “v2-build” for short....
was changed into that wording (back then still for new-build; the rename to v2-build was more recent) in 2017 via c6928316a5f72b4c4f367f157f1e8dafe71c13ea with the express intent to
The goal is to deemphasize calling it "new-build" and push "Nix-style Local Builds" instead, as the former name only makes sense while the old system is the default
-``cabal new-build``, also known as Nix-style local builds, is a new
-command inspired by Nix that comes with cabal-install 1.24. Nix-style
-local builds combine the best of non-sandboxed and sandboxed Cabal:
+Nix-style local builds are a new build system implementation inspired by Nix.
+The Nix-style local build system is commonly called "new-build" for short after the ``cabal new-*`` family of commands that control it.
+However those names are only temporary until Nix-style local builds becomes the default.
and also note specifically
However those names are only temporary until Nix-style local builds becomes the default.
Sorry, let me rephrase:
Nix-style local builds have become the default, so some more editing is needed there
Adding my 2c as requested by #haskell (and my apologies, it really is 2c or less, I'm not here to work on this). While they arose for understandable reasons, nowadays both "nix-style" and "v2-build" just create confusion for non-experts:
- v1 vs v2 baked prominently into UI for a long time was always going to be confusing
- nix-style is increasingly confusing as it has nothing to do with the 3+ ways of using cabal with actual nix.
IMHO it would be good for cabal if they were both discontinued ASAP (this issue was mainly about removing the "nix style" term). It would take 1. sustained consistent effort across all docs/uis/fora, and 2. a new replacement term that is sticky and liked by both the devs and new users.
I think "v1-style build" covers two build/package management strategies:
- the first: "global", "shared", "user-wide" ?
- the second: "sandboxed", "per-project without sharing"
And "v2/nix style" covers:
- the third: could be called "hermetic", "isolated", "self-contained" (but those also describe 2), "per-project with sharing", "reproducible", "reusable", "immutable"...
i was suggesting neutral terms might be "packagedb-style builds" (for v1) and "store-style builds" (for v2) since this refers to where the packages live, rather than any descriptors of how stuff works.
packagedb vs store is informative to cabal developers, but not to users.
Ultimately it needs to be three easy words for the three cases. Currently I'd favour
- "global" (everything's in one big package db, packages can be mutated causing conflicts)
- "sandboxed" (each project has it's own private package db)
- "immutable" (global and private package dbs are used, packages are never mutated)
Agreed about getting rind of "nix". I think the "sandboxed" style is completely removed, right? No longer possible. So, nothing wrong with the term, but it should probably never appear in docs nor codebase (outside old release notes).
The "v1 style", "v2 style" naming has the advantage that there still are, and will be for at least a few months, "v1-" and "v2-" prefixes in command names. There is also the pair "" and "new-", but the first element of the pair is ambiguous.
There is a slight ambiguity with "global", because we are actively working on bringing it back using v2- machinery, because some use cases require it (the tool cabal-env and the idiom of cabal exec cabal foo are partial solutions). So we'd like to enable "global" style usage without the "v1" style commands and the heaps of legacy code behind them.
Came here looking for exactly this issue, because the "Nix" terminology nags at me every time I read the Cabal docs.
This specific issue was about the terminology for "v2-build", but is there general agreement that we should eliminate the "Nix" analogy in general? For example we have an entire section called "3. How to build locally like in Nix". I think the docs could be much more helpful if we don't assume any Nix knowledge.
Would someone accept a PR if I did some editing?
I'm strongly in favor, especially internally as NixStyle for v2-related stuff always throws me off. I hope that doesn't leak into the Cabal library, though, because that would pretty well shoot this down as a massive API break.
@simonmar I think the majority if not totality of currently active Cabal maintainers would like to see the nix analogy go or contained (I imagine a little page in the manual that can discuss it). The issue is: it's not easy to implement even if we limit the scope to the manual (which we should: no one would like API changes just for naming). So, this ticket needs a motivated volunteer willing to put some real work in it.
see the nix analogy go or contained (I imagine a little page in the manual that can discuss it).
I think all that needs to be said is that it's inspired by Nix's store. Anything else might also imply other aspects of Nix; for example, cabal files are a far cry from being Nix derivations.