Official NixOS Wiki

Flakes: Difference between revisions

← Older editNewer edit →
VisualWikitext
Jopejoe1 (talk | contribs)
trusted
132 edits
Improve translation support
Jopejoe1 (talk | contribs)
trusted
132 edits
Marked this version for translation
Line 12: Line 12:
* A [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html#description flake] refers to a file-system tree whose root directory contains the Nix file specification called <code>flake.nix</code>.
* A [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html#description flake] refers to a file-system tree whose root directory contains the Nix file specification called <code>flake.nix</code>.


<!--T:141-->
* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.
* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.


<!--T:142-->
*  Flakes introduce a [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references URL-like syntax] for specifying remote sources.
*  Flakes introduce a [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references URL-like syntax] for specifying remote sources.


<!--T:143-->
* To simplify the long URL syntax with shorter names, [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html flakes uses a registry] of symbolic identifiers.
* To simplify the long URL syntax with shorter names, [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html flakes uses a registry] of symbolic identifiers.


<!--T:144-->
* Flakes also allow for locking references and versions that can then be queried and updated programmatically.
* Flakes also allow for locking references and versions that can then be queried and updated programmatically.


<!--T:145-->
* An [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html experimental command-line interface] accepts flake references for expressions that build, run, and deploy packages.
* An [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html experimental command-line interface] accepts flake references for expressions that build, run, and deploy packages.


Line 78: Line 83:
{{Warning | Since contents of flake files are copied to the world-readable Nix store folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}
{{Warning | Since contents of flake files are copied to the world-readable Nix store folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}


<!--T:21-->
====Git WARNING==== <!--T:21-->
====Git WARNING====


<!--T:146-->
For flakes in git repos, only files in the working tree will be copied to the store.
For flakes in git repos, only files in the working tree will be copied to the store.


Line 111: Line 116:
* <code>description</code> is a string describing the flake.
* <code>description</code> is a string describing the flake.


<!--T:147-->
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.


<!--T:148-->
* <code>outputs</code> is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set whose schema is described below.
* <code>outputs</code> is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set whose schema is described below.


<!--T:149-->
* <code>nixConfig</code> is an attribute set of values which reflect the [https://nixos.org/manual/nix/stable/command-ref/conf-file.html values given to nix.conf]. This can extend the normal behavior of a user's nix experience by adding flake-specific configuration, such as a binary cache.
* <code>nixConfig</code> is an attribute set of values which reflect the [https://nixos.org/manual/nix/stable/command-ref/conf-file.html values given to nix.conf]. This can extend the normal behavior of a user's nix experience by adding flake-specific configuration, such as a binary cache.


Line 122: Line 130:
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].


<!--T:150-->
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].


Line 166: Line 175:
<translate>
<translate>


<!--T:42-->
=== Output schema === <!--T:42-->
=== Output schema ===


<!--T:151-->
This is described in the nix package manager [https://github.com/NixOS/nix/blob/master/src/nix/flake-check.md src/nix/flake-check.md].
This is described in the nix package manager [https://github.com/NixOS/nix/blob/master/src/nix/flake-check.md src/nix/flake-check.md].


Line 180: Line 189:
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"


<!--T:152-->
* <code><name></code> is an attribute name like "hello".
* <code><name></code> is an attribute name like "hello".


<!--T:153-->
* <code><flake></code> is a flake name like "nixpkgs".
* <code><flake></code> is a flake name like "nixpkgs".


<!--T:154-->
* <code><store-path></code> is a <code>/nix/store..</code> path
* <code><store-path></code> is a <code>/nix/store..</code> path


Line 239: Line 251:
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.


<!--T:49-->
==== nix run ==== <!--T:49-->
==== nix run ====


<!--T:155-->
When output <code>apps.<system>.myapp</code> is not defined, <code>nix run myapp</code> runs <code><packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)></code>
When output <code>apps.<system>.myapp</code> is not defined, <code>nix run myapp</code> runs <code><packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)></code>


Line 309: Line 321:
* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.
* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.


<!--T:156-->
* builtins.currentSystem is non-hermetic and impure. This can usually be avoided by passing the system (i.e., x86_64-linux) explicitly to derivations requiring it.
* builtins.currentSystem is non-hermetic and impure. This can usually be avoided by passing the system (i.e., x86_64-linux) explicitly to derivations requiring it.


<!--T:157-->
* Imports from channels like <code><nixpkgs></code> can be made pure by instead importing from the <code>output</code> function in <code>flake.nix</code>, where the arguments provide the store path to the flake's inputs:
* Imports from channels like <code><nixpkgs></code> can be made pure by instead importing from the <code>output</code> function in <code>flake.nix</code>, where the arguments provide the store path to the flake's inputs:


Line 359: Line 373:
<translate>
<translate>


<!--T:158-->
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:


Line 377: Line 392:
<translate>
<translate>


<!--T:159-->
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:


Line 621: Line 637:
<translate>
<translate>


<!--T:160-->
If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:
If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:


Line 709: Line 726:
Refer to [[Unfree software|Unfree Software]].
Refer to [[Unfree software|Unfree Software]].


<!--T:131-->
== Development tricks == <!--T:131-->
== Development tricks ==


=== Build a package added in a PR ===
=== Build a package added in a PR === <!--T:161-->


</translate>
</translate>
Line 720: Line 736:
<translate>
<translate>


<!--T:162-->
this allows building a package that has not yet been added to nixpkgs.
this allows building a package that has not yet been added to nixpkgs.


Line 731: Line 748:
<translate>
<translate>


<!--T:163-->
this allows building a package that has not yet been added to nixpkgs.
this allows building a package that has not yet been added to nixpkgs.


=== How to add a file locally in git but not include it in commits ===
=== How to add a file locally in git but not include it in commits === <!--T:164-->


<!--T:133-->
<!--T:133-->
Line 745: Line 763:
<translate>
<translate>


<!--T:135-->
=== Rapid iteration of a direct dependency === <!--T:135-->
=== Rapid iteration of a direct dependency ===


<!--T:165-->
One common pain point with using Nix as a development environment is the need to completely rebuild dependencies and re-enter the dev shell every time they are updated. The <code>nix develop --redirect <flake> <directory></code> command allows you to provide a mutable dependency to your shell as if it were built by Nix.
One common pain point with using Nix as a development environment is the need to completely rebuild dependencies and re-enter the dev shell every time they are updated. The <code>nix develop --redirect <flake> <directory></code> command allows you to provide a mutable dependency to your shell as if it were built by Nix.


Line 763: Line 781:
<translate>
<translate>


<!--T:166-->
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':


Line 774: Line 793:
<translate>
<translate>


<!--T:167-->
If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the <code>--inputs-from .</code> flag. If all worked well you should be able to <code>buildPhase && installPhase</code> when the dependency changes and rebuild your consumer with the new version ''without'' exiting the development shell.
If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the <code>--inputs-from .</code> flag. If all worked well you should be able to <code>buildPhase && installPhase</code> when the dependency changes and rebuild your consumer with the new version ''without'' exiting the development shell.


Line 781: Line 801:
* [https://nix.dev/concepts/flakes Flakes] - nix.dev
* [https://nix.dev/concepts/flakes Flakes] - nix.dev


<!--T:168-->
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification


<!--T:169-->
* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)
* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)


<!--T:170-->
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.


<!--T:171-->
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)


<!--T:172-->
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes


<!--T:173-->
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)


<!--T:174-->
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (Eelco Dolstra, 2020)


<!--T:175-->
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)


<!--T:176-->
* [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html Nix flake command reference manual] - Many additional details about flakes, and their parts.
* [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html Nix flake command reference manual] - Many additional details about flakes, and their parts.


<!--T:177-->
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020)
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020)


<!--T:178-->
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]


<!--T:179-->
* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]
* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]


<!--T:180-->
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]


<!--T:181-->
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]


Retrieved from "https://wiki.nixos.org/wiki/Flakes"