Derivations: Difference between revisions

Line 13:

Derivations can be written manually using the <code>derivation</code> function; this is the most fundamental way in which they can be defined. However, since this low-level function is quite simple, building derivations this way can easily become unwieldy and repetitive. To aid in the process of creating derivations, [[Nixpkgs]] contains [https://nixos.org/manual/nixpkgs/unstable/#chap-stdenv the standard environment] (also known as the <code>stdenv</code>), which provides a set of utility functions for the most common derivation types (e.g. a [[Python libraries|Python package]], a shell script, a [[Docker]] container, etc.)

== ~~Getting Started~~ ==

== Writing a derivation ==

~~Derivations take an input and produce an output through a series of steps. For~~ most ~~packages, the inputs refer~~ to the ~~source files~~, the ~~steps refer to the compilation process and~~ are ~~called [[Derivations#Phases|phases]], and~~ the ~~outputs refer~~ to ~~finalized executable binaries written to some file/directory~~. ~~This sequence of events can be well described within a standard environment~~.

The most fundamental way to create a derivation is using the built-in <code>derivation</code> function. While you'll rarely write derivations this way in practice, understanding the low-level mechanics helps clarify what higher-level tools are doing for you. An example is provided in the first subsection. While it wouldn't be feasible to write every single derivation in this way, working through an example is an important step in one's Nix ecosystem journey. The latter subsections include more ''production-ready'' examples using the higher level utilities available in the ecosystem.

=== src ===

Regardless of how they're built, derivations take an ''input'' and produce an ''output'' through a series of ''steps''. For most packages, the inputs refer to the source files, the steps refer to the compilation process and are called [[Derivations#Phases|phases]], and the outputs refer to finalized executable binaries written to some file/directory. This sequence of events can be well described within a standard environment, which the latter sections address.

=== Low-level derivations ===

As mentioned above, writing derivations in this manner can quickly become unwieldy and unfeasible. However, in order to understand why, do check out the main article above to follow the process of writing a derivation while hitting every hurdle that you might hit when building one yourself. Doing so is the best way to understand conceptually how derivations operate. You can see what a well defined low-level derivation might look like, in this case simply creating a script that displays the message ''"Hello, world!"'':

{{File|example.nix|nix|<nowiki>let

pkgs = import <nixpkgs> {};

in

derivation {

name = "hello-world";

system = builtins.currentSystem;

builder = "${pkgs.bash}/bin/bash";

args = [ "-c" ''

echo 'echo "Hello, World!"' > $out

'' ];

}</nowiki>}}

=== Standard environment derivations ===

==== src ====

This attribute points towards the inputs used within the derivation. This can be source code, but it can also be a pre-build binary. Usually depending on what the source is, a special series of steps is done to ensure its correctness in a Nix environment.

Line 34:

Line 53:

</syntaxhighlight>

=== out ===

==== out ====

Unlike <code>src</code>, this is not an attribute you set but rather an environment variable which points to the finalized location of the derivation's contents. The actual directory of <code>$out</code> is an implementation detail abstracted away by Nix and the stdenv builder. Anything placed within <code>$out</code> will then be part of the final derivation. This follows an FHS-inspired like structure, where <code>$out/bin</code> contains binaries, <code>$out/lib</code> contains shared objects, <code>$out/include</code> contains headers, and so forth. These paths will become part of the derivation and are the resulting entries within the <code>/nix/store</code>.<blockquote>This attribute must point to either a file or directory, even if they are empty! Failure to create this path will result in the builder failing the entire build process.</blockquote>

Line 49:

Line 69:

</syntaxhighlight>

=== meta ===

==== meta ====

Unlike the previous two, this attribute has no significant relevance to building and largely contains a loose set of attributes useful with the context of Nixpkgs. Therefore, if you're writing a derivation that is not intended for Nixpkgs, this entire attribute set can be safely omitted.

@@ Line 13: / Line 13: @@
 Derivations can be written manually using the <code>derivation</code> function; this is the most fundamental way in which they can be defined. However, since this low-level function is quite simple, building derivations this way can easily become unwieldy and repetitive. To aid in the process of creating derivations, [[Nixpkgs]] contains [https://nixos.org/manual/nixpkgs/unstable/#chap-stdenv the standard environment] (also known as the <code>stdenv</code>), which provides a set of utility functions for the most common derivation types (e.g. a [[Python libraries|Python package]], a shell script, a [[Docker]] container, etc.)
-== Getting Started ==
+== Writing a derivation ==
-Derivations take an input and produce an output through a series of steps. For most packages, the inputs refer to the source files, the steps refer to the compilation process and are called [[Derivations#Phases|phases]], and the outputs refer to finalized executable binaries written to some file/directory. This sequence of events can be well described within a standard environment.
+The most fundamental way to create a derivation is using the built-in <code>derivation</code> function. While you'll rarely write derivations this way in practice, understanding the low-level mechanics helps clarify what higher-level tools are doing for you. An example is provided in the first subsection. While it wouldn't be feasible to write every single derivation in this way, working through an example is an important step in one's Nix ecosystem journey. The latter subsections include more ''production-ready'' examples using the higher level utilities available in the ecosystem.
-=== src ===
+Regardless of how they're built, derivations take an ''input'' and produce an ''output'' through a series of ''steps''. For most packages, the inputs refer to the source files, the steps refer to the compilation process and are called [[Derivations#Phases|phases]], and the outputs refer to finalized executable binaries written to some file/directory. This sequence of events can be well described within a standard environment, which the latter sections address.
+=== Low-level derivations ===
+{{Main|Low-level derivations}}
+As mentioned above, writing derivations in this manner can quickly become unwieldy and unfeasible. However, in order to understand why, do check out the main article above to follow the process of writing a derivation while hitting every hurdle that you might hit when building one yourself. Doing so is the best way to understand conceptually how derivations operate. You can see what a well defined low-level derivation might look like, in this case simply creating a script that displays the message ''"Hello, world!"'':
+{{File|example.nix|nix|<nowiki>let
+  pkgs = import <nixpkgs> {};
+in
+derivation {
+  name = "hello-world";
+  system = builtins.currentSystem;
+  builder = "${pkgs.bash}/bin/bash";
+  args = [ "-c" ''
+    echo 'echo "Hello, World!"' > $out
+  '' ];
+}</nowiki>}}
+=== Standard environment derivations ===
+==== src ====
 This attribute points towards the inputs used within the derivation. This can be source code, but it can also be a pre-build binary. Usually depending on what the source is, a special series of steps is done to ensure its correctness in a Nix environment.
@@ Line 34: / Line 53: @@
 </syntaxhighlight>
-=== out ===
+==== out ====
 Unlike <code>src</code>, this is not an attribute you set but rather an environment variable which points to the finalized location of the derivation's contents. The actual directory of <code>$out</code> is an implementation detail abstracted away by Nix and the stdenv builder. Anything placed within <code>$out</code> will then be part of the final derivation. This follows an FHS-inspired like structure, where <code>$out/bin</code> contains binaries, <code>$out/lib</code> contains shared objects, <code>$out/include</code> contains headers, and so forth. These paths will become part of the derivation and are the resulting entries within the <code>/nix/store</code>.<blockquote>This attribute must point to either a file or directory, even if they are empty! Failure to create this path will result in the builder failing the entire build process.</blockquote>
@@ Line 49: / Line 69: @@
 </syntaxhighlight>
-=== meta ===
+==== meta ====
 Unlike the previous two, this attribute has no significant relevance to building and largely contains a loose set of attributes useful with the context of Nixpkgs. Therefore, if you're writing a derivation that is not intended for Nixpkgs, this entire attribute set can be safely omitted.