NixOS/nix.dev
NixOS/nix.dev
1
0
Fork 0
mirror of https://github.com/NixOS/nix.dev.git synced 2024-10-18 14:32:43 -04:00
Code Activity

Merge pull request #737 from wamirez/move-faqs-flakes

Browse source 
Move FAQ on flakes
This commit is contained in:
Valentin Gagarin 2023-10-05 17:03:25 +02:00 committed by GitHub
parent 09c9c509bf 47d03a8e3b
commit 08f7eee12e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 50 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
source/concepts/faq.md Normal file
View file

@ -0,0 +1,48 @@
# Frequentl Asked Questions
## Why are flakes controversial?
Originally proposed in [RFC 49](https://github.com/NixOS/rfcs/pull/49), flakes have been in development since 2019.
Nix introduced the implementation as its first [experimental feature] in 2021.
The subject is considered controversial among Nix users and developers in terms of design, development processes, and community governance.
In particular:
- The RFC was closed without conclusion, and some design and implementation issues are not yet resolved.
Examples include the notion of a global [flake registry], the [impossibility of parameterising flakes](https://github.com/NixOS/nix/issues/2861), and the [new command line interface and flakes being closely tied to each other](https://discourse.nixos.org/t/2023-03-06-nix-team-meeting-minutes-38/26056#cli-stabilisation-announcement-draft-4).
- The original implementation introduced [regressions](https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257) in the [Nix 2.4 release](https://nixos.org/manual/nix/stable/release-notes/rl-2.4.html), breaking some stable functionality without a [major version](https://semver.org/) increment.
- New Nix users were and still are encouraged by various individuals to adopt flakes despite there being no concrete plan or timeline for stabilisation.
This led to a situation where the stable interface was only sparsely maintained for multiple years, and repeatedly suffered breakages due to ongoing development.
Meanwhile, the new interface was adopted widely enough for evolving its design without negatively affecting users to become very challenging.
As of the [2022 community survey](https://discourse.nixos.org/t/2022-nix-survey-results/18983), more than half of the user base, a third of which were relative beginners, relied on experimental features.
{term}`Nixpkgs` as a contrasting example, while featuring a `flake.nix` for compatibility, does not depend on Nix experimental features in its code base.
## Should I enable flakes?
You have to judge for yourself based on your needs.
[Flakes](https://nix.dev/concepts/flakes) and the `nix` command suite bring multiple improvements that are relevant for both software users and package authors:
- The new command-line interface, together with flakes, makes dealing with existing packages significantly more convenient.
- The constraints imposed on flakes strengthen reproducibility by default, and enable various performance improvements when interacting with a large Nix package repository like {term}`Nixpkgs`.
- Flake references allow for easier handling of version upgrades for existing packages or project dependencies.
- The [flake schema](https://nixos.wiki/wiki/Flakes#Flake_schema) helps with composing Nix projects from multiple sources in an orderly fashion.
Other than that, and below the surface of the flake schema, Nix and the Nix language work exactly the same in both cases.
In principle, the same level of reproducibility can be achieved with or without flakes.
In particular, the process of adding software to {term}`Nixpkgs` or maintaining {term}`NixOS` modules and configurations is not affected by flakes at all.
Both paradigms have their own set of unique concepts and support tooling that have to be learned, with varying ease of use, implementation quality, and support status.
At the moment, neither the stable nor the experimental interface is clearly superior to the other in all aspects.
While flakes reduce complexity in some regards, they also introduce additional concepts and you will have to learn more about the system to fully understand how it works.
There are downsides to relying on [experimental features](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-experimental-features) in general:
- Interfaces and behaviour of experimental features could still be changed by Nix developers.
This may require you to adapt your code at some point in the future, which will be more effort when it has grown in complexity.
Currently there is no agreed-upon plan or timeline for stabilising flakes.
- The [Nix maintainer team](https://nixos.org/community/teams/nix.html) focuses on fixing bugs and regressions in stable interfaces, supporting well-understood use cases, as well as improving the internal design and overall contributor experience in order to ease future development.
Improvements to experimental features have a low priority.
- The [Nix documentation team](https://nixos.org/community/teams/documentation.html) focuses on improving documentation and learning materials for stable features and common principles.
When using flakes, you will have to rely more heavily on user-to-user support, third-party documentation, and the source code.

19
source/concepts/flakes.md
View file

@ -1,7 +1,5 @@
# Flakes
## What are flakes?
What is usually referred to as "flakes" is:
- A policy for managing dependencies between {term}`Nix expression`s.
- An [experimental feature] in Nix, implementing that policy and supporting functionality.
@ -41,20 +39,3 @@ Nix handles flakes differently than regular {term}`Nix file`s in the following w
It means full reproducibility of a Nix expression, and, by extension, the resulting build instructions by default, but also prohibits parameterisation of results by consumers.
## Why are flakes controversial?
Originally proposed in [RFC 49](https://github.com/NixOS/rfcs/pull/49), flakes have been in development since 2019.
Nix introduced the implementation as its first [experimental feature] in 2021.
The subject is considered controversial among Nix users and developers in terms of design, development processes, and community governance.
In particular:
- The RFC was closed without conclusion, and some design and implementation issues are not yet resolved.
Examples include the notion of a global [flake registry], the [impossibility of parameterising flakes](https://github.com/NixOS/nix/issues/2861), and the [new command line interface and flakes being closely tied to each other](https://discourse.nixos.org/t/2023-03-06-nix-team-meeting-minutes-38/26056#cli-stabilisation-announcement-draft-4).
- The original implementation introduced [regressions](https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257) in the [Nix 2.4 release](https://nixos.org/manual/nix/stable/release-notes/rl-2.4.html), breaking some stable functionality without a [major version](https://semver.org/) increment.
- New Nix users were and still are encouraged by various individuals to adopt flakes despite there being no concrete plan or timeline for stabilisation.
This led to a situation where the stable interface was only sparsely maintained for multiple years, and repeatedly suffered breakages due to ongoing development.
Meanwhile, the new interface was adopted widely enough for evolving its design without negatively affecting users to become very challenging.
As of the [2022 community survey](https://discourse.nixos.org/t/2022-nix-survey-results/18983), more than half of the user base, a third of which were relative beginners, relied on experimental features.
{term}`Nixpkgs` as a contrasting example, while featuring a `flake.nix` for compatibility, does not depend on Nix experimental features in its code base.

3
source/concepts/index.md
View file

@ -7,5 +7,6 @@ These sections contains explanations of history and ideas in the Nix ecosystem.
:glob:
:maxdepth: 2
*
flakes.md
faq.md
```

29
source/recipes/faq.md
View file

@ -2,35 +2,6 @@
## Nix
### Should I enable flakes?
You have to judge for yourself based on your needs.
Flakes and the `nix` command suite bring multiple improvements that are relevant for both software users and package authors:
- The new command line interface, together with flakes, makes dealing with existing packages significantly more convenient.
- The constraints imposed on flakes strengthen reproducibility by default, and enable various performance improvements when interacting with a large Nix package repository like {term}`Nixpkgs`.
- Flake references allow for easier handling of version upgrades for existing packages or project dependencies.
- The flake schema helps with composing Nix projects from multiple sources in an ordered fashion.
Other than that, and below the surface of the flake schema, Nix and the Nix language work exactly the same in both cases.
In principle, the same level of reproducibility can be achieved with or without flakes.
In particular, the process of adding software to {term}`Nixpkgs` or maintaining {term}`NixOS` modules and configurations is not affected by flakes at all.
Both paradigms have their own set of unique concepts and support tooling that have to be learned, with varying ease of use, implementation quality, and support status.
At the moment, neither the stable nor the experimental interface is clearly superior to the other in all aspects.
While flakes reduce complexity in some regards, they introduce additional concepts and you will have to learn more about the system to fully understand how it works.
There are downsides to relying on [experimental features](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-experimental-features) in general:
- Interfaces and behavior of experimental features could still be changed by Nix developers.
This may require you to adapt your code at some point in the future, which will be more effort when it has grown in complexity.
Currently there is no agreed-upon plan or timeline for stabilising flakes.
- The [Nix maintainer team](https://nixos.org/community/teams/nix.html) focuses on fixing bugs and regressions in stable interfaces, supporting well-understood use cases, as well as improving the internal design and overall contributor experience in order to ease future development.
Improvements to experimental features have low priority.
- The [Nix documentation team](https://nixos.org/community/teams/documentation.html) focuses on improving documentation and learning materials for stable features and common principles.
Using flakes, you will have to rely more heavily on user-to-user support, third-party documentation, and the source code.
### How do I add a new binary cache?
Using NixOS (≥ 22.05):