Low-level derivations: Difference between revisions

Line 1:

Writing '''low-level derivations''' without the convenience of the [[~~Standard~~ environment]] requires understanding the core fundamentals of how [[Nix]] works. While writing derivations in this manner is not common, they can be useful when no utility present in the standard environment matches the required use case, as well as being an essential learning tool for understanding why <code>stdenv.mkDerivation</code> is needed in most cases.

Writing '''low-level derivations''' without the convenience of the [[standard environment]] requires understanding the core fundamentals of how [[Nix]] works. While writing derivations in this manner is not common, they can be useful when no utility present in the standard environment matches the required use case, as well as being an essential learning tool for understanding why <code>stdenv.mkDerivation</code> is needed in most cases.

In the section below, we'll start by writing a simple derivation that creates a script which displays the message ''"Hello, world"'' when run. While developing the Nix file, we'll be encountering the same challenges that led the Nix community to develop more ergonomic tooling. Each obstacle we hit - from missing system dependencies to path management - illustrates a core principle of Nix's purely functional build model. By the end, you'll understand both what makes Nix powerful and why most derivations use abstraction layers.

Line 134:

}}

As mentioned above, building derivations this way can be unwieldy. But working through this example should shed some light onto why the community has built the [[standard environment]], providing utility functions to build derivations for the most common use cases.

As mentioned above, building derivations this way can be unwieldy. But working through this example should shed some light onto why the community has built the standard environment, providing utility functions to build derivations for the most common use cases.

=== Standard environment ===

For practicality purposes, let's compare this to the standard environment way of doing this. Using <code>stdenv.mkDerivation</code> gives us access to the common Linux utilities pre-included for us, so we don't have to do the package importing ourselves:

{{File|example.nix|nix|highlight=11|

{ pkgs ? import <nixpkgs> {} }:

pkgs.stdenv.mkDerivation {

name = "hello-world";

buildCommand = ''

echo '#!/bin/bash' > $out

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

chmod +x $out

'';

}

}}

=== Nixpkgs utilities ===

Even further up the chain of abstractions, [[Nixpkgs]] contains many pre-built utilities for us that handle some of the configuration involved in the standard environment as well. In our case, we can use the <code>writeShellScript</code>:

{{File|example.nix|nix|highlight=11|

{ pkgs ? import <nixpkgs> {} }:

pkgs.writeShellScript "hello-world" ''

echo "Hello, World!"

''

}}

@@ Line 1: / Line 1: @@
 {{wip|date=9 June 2025}}
-Writing '''low-level derivations''' without the convenience of the [[Standard environment]] requires understanding the core fundamentals of how [[Nix]] works. While writing derivations in this manner is not common, they can be useful when no utility present in the standard environment matches the required use case, as well as being an essential learning tool for understanding why <code>stdenv.mkDerivation</code> is needed in most cases.
+Writing '''low-level derivations''' without the convenience of the [[standard environment]] requires understanding the core fundamentals of how [[Nix]] works. While writing derivations in this manner is not common, they can be useful when no utility present in the standard environment matches the required use case, as well as being an essential learning tool for understanding why <code>stdenv.mkDerivation</code> is needed in most cases.
 In the section below, we'll start by writing a simple derivation that creates a script which displays the message ''"Hello, world"'' when run. While developing the Nix file, we'll be encountering the same challenges that led the Nix community to develop more ergonomic tooling. Each obstacle we hit - from missing system dependencies to path management - illustrates a core principle of Nix's purely functional build model. By the end, you'll understand both what makes Nix powerful and why most derivations use abstraction layers.
@@ Line 134: / Line 134: @@
 }}
-As mentioned above, building derivations this way can be unwieldy. But working through this example should shed some light onto why the community has built the [[standard environment]], providing utility functions to build derivations for the most common use cases.
+As mentioned above, building derivations this way can be unwieldy. But working through this example should shed some light onto why the community has built the standard environment, providing utility functions to build derivations for the most common use cases.
+=== Standard environment ===
+For practicality purposes, let's compare this to the standard environment way of doing this. Using <code>stdenv.mkDerivation</code> gives us access to the common Linux utilities pre-included for us, so we don't have to do the package importing ourselves:
+{{File|example.nix|nix|highlight=11|
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.stdenv.mkDerivation {
+  name = "hello-world";
+  buildCommand = ''
+    echo '#!/bin/bash' > $out
+    echo 'echo "Hello, World!"' >> $out
+    chmod +x $out
+  '';
+}
+}}
+=== Nixpkgs utilities ===
+Even further up the chain of abstractions, [[Nixpkgs]] contains many pre-built utilities for us that handle some of the configuration involved in the standard environment as well. In our case, we can use the <code>writeShellScript</code>:
+{{File|example.nix|nix|highlight=11|
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.writeShellScript "hello-world" ''
+  echo "Hello, World!"
+''
+}}