Nixpkgs/Create and debug packages: Difference between revisions

(40 intermediate revisions by 25 users not shown)

Line 1:

This article describes how to work with the nix related repositories to add new packages, edit and debug existing packages. For details on the NixOS module system see [[NixOS:Modules]]. [[NixOS:extend_NixOS]] explains how to write, test and debug your own modules.

There is a chapter about hacking packages and modules in the NixOS manual: http://nixos.org/nixos/manual/index.html#ch-development

There is a chapter about hacking packages and modules in the NixOS manual: [http://nixos.org/nixos/manual/index.html#ch-development development]

Writing packages is covered in ~~http~~://nixos.org/nixpkgs/~~manual~~ and writing modules in http://nixos.org/nixos/manual

Writing packages is covered in [https://nixos.org/manual/nixpkgs/stable/#chap-quick-start quick start] and writing modules is covered in the [http://nixos.org/nixos/manual manual]

The nix repositories are hosted ~~here:~~ https://github.com/~~nixos~~

If you've read the manual and still don't know how to go about creating a package, read on.

The nix repositories are hosted at https://github.com/NixOS

== Basics ==

The code for nix packages is managed in the nixpkgs repository. NixOS services, and other system configuration options are managed in ~~the~~ nixos ~~sub-directory of the~~ nixpkgs ~~repository~~.

The code for nix packages is managed in the [https://github.com/NixOS/nixpkgs/tree/master/pkgs nixpkgs/pkgs] repository. NixOS services, and other system configuration options are managed in [https://github.com/NixOS/nixpkgs/tree/master/nixos nixpkgs/nixos].

The steps to take for your first change should look something like this:

# Fork the repo (e.g. click the fork button on https://github.com/nixos/nixpkgs).

# Clone your fork <code>git clone ~~git@~~github.com~~:YOUR-GITHUB-ACCOUNT-NAME~~/nixpkgs.git</code>

# Clone your fork <code><nowiki>git clone --depth 1 https://github.com/YOURNAME/nixpkgs.git</nowiki></code>

# Hack hack hack

# Push your changes to your fork

Line 21:

Line 23:

This is pretty much the standard way to use github, so if you have trouble using git or github any general guide on these should get you going, or just ask on the NixOS IRC channel. The rest of this guide deals with the "Hack hack hack" step :)

== Rough process for creating a package ==

There are different steps here depending on whether you're building from source or packaging an existing binary. There are some common steps too.

=== Package from source code ===

# Read the repo build instructions and CI scripts (for example, on GitHub, these are located in <code>.github/workflows</code>).

# Look in nixpkgs for a package with a similar build process to use as reference. For example, if you're packaging a project written in Go, find a package for an existing Go application. Each language has its own supporting Nix functions and a more or less standard way of dealing with things. For example, [https://nixos.org/manual/nixpkgs/stable/#sec-language-go Go] has <code>buildGoModule</code>. [https://nixos.org/manual/nixpkgs/stable/#rust Rust] has <code>buildRustPackage</code>. [https://nixos.org/manual/nixpkgs/stable/#python Python] has <code>buildPythonApplication</code>. [https://nixos.org/manual/nixpkgs/stable/#node.js Node.js] has <code>node2nix</code>, <code>yarn2nix</code>, etc. There are also specific functions for wrapping e.g. [https://nixos.org/manual/nixpkgs/stable/#sec-language-gnome GNOME] applications (<code>wrapGAppsHook</code>), or [https://nixos.org/manual/nixpkgs/stable/#sec-language-qt Qt] apps (<code>libsForQt5</code>, <code>wrapQtAppsHook</code>). Refer to the [https://nixos.org/manual/nixpkgs/stable/#chap-language-support language support chapter in the nixpkgs manual].

# If there isn't a specific builder for the language, use <code>stdenv.mkDerivation</code> directly, which has built-in support for GNU make (and other build systems, provided you add the necessary <code>nativeBuildInputs</code>).

# Figure out at least some dependencies from the project repo. See if they're available in nixpkgs (<code>nix search some-library</code> or <code>nix-locate --top-level lib/somelibrary.so</code>). If any dependency is missing you'll need to package that as well.

# Create your derivation in <code>default.nix</code> in some empty local directory.

# At the top of the derivation, temporarily add <code>with import <nixpkgs> {};</code>. For now, don't worry too much about declaring every dependency as a parameter, to save time.

# Build the package with <code>nix-build</code>. Iterate on tweaking the derivation and rebuilding until it succeeds.

# For large projects with long compile times, you can use <code>nix-shell</code> instead to [https://nixos.org/manual/nixpkgs/stable/#sec-building-stdenv-package-in-nix-shell run the individual phases].

# At this stage, you may encounter some build quirks of the project. Compile-time errors will hopefully explain what you're missing. For example [https://github.com/NixOS/nixpkgs/blob/643ce4bd0f057bc0b90f0faebeb83a3b14f01674/pkgs/tools/package-management/micromamba/default.nix#L6-L10 micromamba needs a specialized build of libsolv].

# Read on below for further steps.

=== Packages from binaries ===

# There's probably a package for it for some other distro. Use that package definition to figure out the dependencies. For example, if you have a deb package you can view its dependencies by running <code>dpkg -I <package.deb></code>. [https://aur.archlinux.org/packages/ Arch packages] can also be useful to look up for reference (view the package's PKGBUILD):

# Sometimes the definitions for other distros won't be enough by nix's standards. If that's the case, use <code>ldd</code> and/or <code>strace</code> to find the rest of the dependencies. If you're not familiar with <code>ldd</code>/<code>strace</code> see [https://unix.stackexchange.com/questions/120015/how-to-find-out-the-dynamic-libraries-executables-loads-when-run How to find out the dynamic libraries executables loads when run?]

# See how other nix binary packages deal with dependencies. For example [https://github.com/NixOS/nixpkgs/search?q=%22dpkg+-x%22 nix packages based on deb packages].

# If the application contains some helper executable or vendored dlopen'd library you will probably need to give the nix treatment to it as well. For example, [https://github.com/NixOS/nixpkgs/blob/42c154d332eb4eb17c74b587c1d4c2fcc3042ba1/pkgs/applications/editors/jetbrains/default.nix#L196-L200 JetBrains Rider vendors dotnet so it needs to be replaced with the dotnet nix package].

# Because there's no real build step here you'll have to rely more on testing the actual execution of the package.

=== Both source code packages and binary packages ===

# Once you have the package building successfully, test the output. Ensure the build completes using<code>nix-build</code>, then run <code>result/bin/<executableName></code>. Test as much functionality of the application as you can to ensure that it works as intended.

# Now that your package builds and runs, it's time to move it to nixpkgs. Read [https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md nixpkgs/CONTRIBUTING.md], make sure your package is up to the standards e.g. add a suitable [https://nixos.org/manual/nixpkgs/stable/#sec-standard-meta-attributes <code>meta</code> section].

# Git clone https://github.com/NixOS/nixpkgs, figure out the best category / directory for the application (within https://github.com/NixOS/nixpkgs/tree/master/pkgs/), create the directory for your application, and move your default.nix there.

# If you used <code>with import <nixpkgs> {};</code> to iterate more quickly, now is the time to replace that with the actual dependencies as an attribute set at the beginning of the file e.g. <code>{ lib, stdenv, fetchFromGitHub }:</code>

# Add the package to the top level declaration of packages. Most of the time this will be https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix .

# If this is your first package in nixpkgs, add yourself in https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix in a separate commit.

# Read on about the final steps of branching and sending your PR in https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md .

== How to install from the local repository ==

Line 38:

Line 75:

$ nix-env -f $NIXPKGS -qaP '*'

~~</syntaxhighlight>~~

~~'''example: install software from local repository'''~~

~~<syntaxhighlight lang="console">~~

~~$ nix-env -f $NIXPKGS -i python-urlgrabber~~

</syntaxhighlight>

'''example: update the system''' based on your local '''$NIXPKGS'''

$ nixos-rebuild ~~-I nixos=$NIXPKGS/nixos~~ -I nixpkgs=$NIXPKGS switch

$ nixos-rebuild -I nixpkgs=$NIXPKGS switch

</syntaxhighlight>

Line 75:

Line 107:

$ git fetch upstream

$ git checkout -b upstream-master upstream/master

$ git pull

Line 152:

Line 185:

mkdir -p /~~tmp~~/~~nix~~-~~shell-bc~~

$ mkdir -p ~/tmpdev/bc-build && cd ~/tmpdev/bc-build

cd /~~tmp~~/~~nix-shell~~-bc

$ nix-shell $NIXPKGS -A bc

nix-shell $~~NIXREPOS/nixpkgs~~ -A bc

~~export out=/tmp/foo/out~~

</syntaxhighlight>

~~now we have find out which phases are specified~~ for ~~this~~ package:

You can also drop in the build environment for a package not in nixpkgs.

typeset -f genericBuild | grep 'phases='

$ mkdir -p ~/tmpdev/bc-build && cd ~/tmpdev/bc-build

$ nix-shell -E "with import <nixpkgs> {}; callPackage /path/to/package.nix {}"

</syntaxhighlight>

You would have seen the dependencies downloading, but the ''bc-build'' directory remains empty. The build system would next invoke a builder with some arguments. You can obtain the exact name of the builder (usually '''bash''') and the arguments '''args''' of the builder (typically a shell script) by checking the corresponding value in:

$ nix derivation show $(nix-instantiate .)

</syntaxhighlight>

However, most of the time (for instance when using '''stdenv''' ) the [https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/default-builder.sh default builder] invokes first '''source $stdenv/setup''' to load the appropriate environment variables, and then '''genericBuild()'''. This is a shell function defined by [https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/setup.sh stdenv] that you can review like this...

$ typeset -f genericBuild | less

</syntaxhighlight>

which shows when custom variables '''$buildCommandPath''' or '''$buildCommand''' are defined, those are evaluated exclusively. Otherwise, if no custom '''$phases''' variable is set, the standard build phase order is used as shown here...

$ typeset -f genericBuild | grep 'phases='

phases="$prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase fixupPhase installCheckPhase $preDistPhases distPhase $postPhases";

</syntaxhighlight>

The phases can be defined either as a string to be eval'ed or as a shell function, [https://github.com/NixOS/nixpkgs/blob/~~5a0b79~~/pkgs/stdenv/generic/setup.sh#L818 this is how] Nix invokes it.

The phases can be defined either as a string to be eval'ed or as a shell function, [https://github.com/NixOS/nixpkgs/blob/5a0b79f955d6c2dc21239f1b0d956ef8dc89a57e/pkgs/stdenv/generic/setup.sh#L818 this is how] Nix invokes it.

So to observe a full build, you can do...

$ export out=~/tmpdev/bc-build/out

$ set -x # Optional: it prints all commands, can be practical to debug

$ set +e # Optional: do not quit the shell on simple errors, Ctrl-C,...

$ export NIX_ENFORCE_PURITY=0 # Optional: nix automatically skip absolute files not in /nix/, /tmp or NIX_BUILD_TOP. When building in a nix-shell this may be an issue as the source won't be in the above folders and you may get errors like Fatal error: blabla.h: No such file or directory. https://github.com/NixOS/nixpkgs/issues/204036

$ genericBuild

</syntaxhighlight>

To only run some specific phases, use runPhase:

# Syntax: runPhase *phase*

$ runPhase unpackPhase

</syntaxhighlight>

~~so when~~ developing you need to run these phases in ~~a row~~:

While developing your own package, you need to run these phases in order:

unpackPhase

Line 177:

Line 240:

installCheckPhase

distPhase

</syntaxhighlight>

Phases can be both bash functions, or environment of identical name (when they are overridden). <code>genericBuild</code> takes care of that distinction for you, invoking them appropriately. You can of course drop down to evaluating them yourself, for example to invoke an overridden phase (an environment variable) using '''eval''' instead:

eval "$checkPhase"

# etc..

</syntaxhighlight>

{{Note|you do not need to run $preConfigurePhase explicitly as it is run, when running configurePhase already.}}

list all functions which are declared in '''set''':

To list all functions which are declared in '''set''':

typeset -F

Line 231:

Line 301:

echo $unpackPhase

echo "$unpackPhase"

</syntaxhighlight>

Line 301:

Line 371:

Tip: A git repository can be used for snapshotting attempts at building the package. This also makes it easy to generate patches, should you need to.

== Adding custom libraries and dependencies to a package ==

If you are packaging a dependency, such as a library used by applications for them to compile their code, you might have found you'd like to test if the derivation file installs correctly and can be used by other software.

In order to do this, you'll need to make a simple program that references the library, make a derivation for this program, then add the dependency. For example:

Your program to test the library:

{

pkgs ? import <nixpkgs> {

overlays = [

(final: prev: {

my-library = prev.callPackage ./my-library.nix { };

})

];

},

}:

pkgs.callPackage (

{

stdenv,

hello,

pkg-config,

my-library,

}:

stdenv.mkDerivation {

pname = "something";

version = "1";

strictDeps = true;

# host/target agnostic programs

depsBuildBuild = [

hello

];

# compilers & linkers & dependecy finding programs

nativeBuildInputs = [

pkg-config

];

# libraries

buildInputs = [

my-library

];

}

) { }

</syntaxhighlight>

== nix channels ==

nix channels can be used in parallel with your new local repositories, see its [[install/remove software#nix-channels| nix-channel-documentation]]

== Testing Package Updates with nixpkgs-review ==

~~== Testing Package Updates with Nox ==~~

You can also use [https://github.com/Mic92/nixpkgs-review nixpkgs-review] to compile, review and merge packages and its dependencies. It claims to be faster than nox and provides a nix-shell where you can test the package.

~~If you are updating a package's version, you can use nox to~~ make sure ~~all packages that depend on the updated package still compile correctly.~~

First make sure it is available in your shell:

nix-shell -p nixpkgs-review

</syntaxhighlight>

~~First make sure it is~~ in ~~your environment~~:

You can run nixpkgs-review against uncommitted/staged changes in a cloned nixpkgs repository:

~~nix~~-~~env~~ -~~i nox~~

cd ~/git/nixpkgs

nixpkgs-review wip [--staged]

</syntaxhighlight>

~~You can run nox against uncommited changes~~ to a ~~nixpkgs repository~~:

It is also possible to review a specified commit:

cd ~/~~.nix-defexpr~~

cd ~/git/nixpkgs

~~nox~~-review ~~wip~~

nixpkgs-review rev HEAD

</syntaxhighlight>

If you have already ~~commited~~ your changes and created a pull request, you can use the pr command:

If you have already committed your changes and created a pull request, you can use the pr command:

cd ~/git/nixpkgs

nixpkgs-review pr 5341

</syntaxhighlight>

You can post the build result, approve/merge or read the comments of a pull request inside the provided nix-shell:

# inside the provided shell

nixpkgs-review post-result

nixpkgs-review approve

nixpkgs-review merge

nixpkgs-review comments

</syntaxhighlight>

If the pr provides a new package you can start it inside the nix-shell using its package name:

# inside the provided shell

packagename

</syntaxhighlight>

== Formatting Packages with nixfmt ==

It is "good practice" to format packages in a way that following changed will create as minimal diffs as possible. The formatter [https://github.com/NixOS/nixfmt nixfmt] can be used for that.

nix-shell -p nixfmt-rfc-style --run 'nixfmt path/to/default.nix'

</syntaxhighlight>

== Testing Packages with nixpkgs-hammering ==

You can test some "good practices" in a package with [https://github.com/jtojnar/nixpkgs-hammering nixpkgs-hammering]. But before applying the recommendations you should read the given [https://github.com/jtojnar/nixpkgs-hammering/tree/main/explanations explanations].

~~nox~~-~~review pr 5341~~

cd ~/git/nixpkgs

nix run -f https://github.com/jtojnar/nixpkgs-hammering/archive/master.tar.gz -c nixpkgs-hammer packagename # if you are using stable nix

nix run github:jtojnar/nixpkgs-hammering packagename # if you are using nix flake

</syntaxhighlight>

Line 329:

Line 479:

* [[Generic Algorithm on Doing Packaging]]

* [https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html Fundamentals of Stdenv] in Nix Pills

* [https://nixos.org/guides/nix-pills/developing-with-nix-shell.html Developing with nix-shell] in Nix Pills

[[Category:Development]]

@@ Line 1: / Line 1: @@
 This article describes how to work with the nix related repositories to add new packages, edit and debug existing packages. For details on the NixOS module system see [[NixOS:Modules]]. [[NixOS:extend_NixOS]] explains how to write, test and debug your own modules.
-There is a chapter about hacking packages and modules in the NixOS manual: http://nixos.org/nixos/manual/index.html#ch-development
+There is a chapter about hacking packages and modules in the NixOS manual: [http://nixos.org/nixos/manual/index.html#ch-development development]
-Writing packages is covered in http://nixos.org/nixpkgs/manual and writing modules in http://nixos.org/nixos/manual
+Writing packages is covered in [https://nixos.org/manual/nixpkgs/stable/#chap-quick-start quick start] and writing modules is covered in the [http://nixos.org/nixos/manual manual]
-The nix repositories are hosted here: https://github.com/nixos
+If you've read the manual and still don't know how to go about creating a package, read on.
+The nix repositories are hosted at https://github.com/NixOS
 == Basics ==
-The code for nix packages is managed in the nixpkgs repository. NixOS services, and other system configuration options are managed in the nixos sub-directory of the nixpkgs repository.
+The code for nix packages is managed in the [https://github.com/NixOS/nixpkgs/tree/master/pkgs nixpkgs/pkgs] repository. NixOS services, and other system configuration options are managed in [https://github.com/NixOS/nixpkgs/tree/master/nixos nixpkgs/nixos].
 The steps to take for your first change should look something like this:
 # Fork the repo (e.g. click the fork button on https://github.com/nixos/nixpkgs).
-# Clone your fork <code>git clone git@github.com:YOUR-GITHUB-ACCOUNT-NAME/nixpkgs.git</code>
+# Clone your fork <code><nowiki>git clone --depth 1 https://github.com/YOURNAME/nixpkgs.git</nowiki></code>
 # Hack hack hack
 # Push your changes to your fork
@@ Line 21: / Line 23: @@
 This is pretty much the standard way to use github, so if you have trouble using git or github any general guide on these should get you going, or just ask on the NixOS IRC channel. The rest of this guide deals with the "Hack hack hack" step :)
+== Rough process for creating a package ==
+There are different steps here depending on whether you're building from source or packaging an existing binary.  There are some common steps too.
+=== Package from source code ===
+# Read the repo build instructions and CI scripts (for example, on GitHub, these are located in <code>.github/workflows</code>).
+# Look in nixpkgs for a package with a similar build process to use as reference. For example, if you're packaging a project written in Go, find a package for an existing Go application. Each language has its own supporting Nix functions and a more or less standard way of dealing with things. For example, [https://nixos.org/manual/nixpkgs/stable/#sec-language-go Go] has <code>buildGoModule</code>. [https://nixos.org/manual/nixpkgs/stable/#rust Rust] has <code>buildRustPackage</code>. [https://nixos.org/manual/nixpkgs/stable/#python Python] has <code>buildPythonApplication</code>. [https://nixos.org/manual/nixpkgs/stable/#node.js Node.js] has <code>node2nix</code>, <code>yarn2nix</code>, etc. There are also specific functions for wrapping e.g. [https://nixos.org/manual/nixpkgs/stable/#sec-language-gnome GNOME] applications (<code>wrapGAppsHook</code>), or [https://nixos.org/manual/nixpkgs/stable/#sec-language-qt Qt] apps (<code>libsForQt5</code>, <code>wrapQtAppsHook</code>). Refer to the [https://nixos.org/manual/nixpkgs/stable/#chap-language-support language support chapter in the nixpkgs manual].
+# If there isn't a specific builder for the language, use <code>stdenv.mkDerivation</code> directly, which has built-in support for GNU make (and other build systems, provided you add the necessary <code>nativeBuildInputs</code>).
+# Figure out at least some dependencies from the project repo. See if they're available in nixpkgs (<code>nix search some-library</code> or <code>nix-locate --top-level lib/somelibrary.so</code>). If any dependency is missing you'll need to package that as well.
+# Create your derivation in <code>default.nix</code> in some empty local directory.
+# At the top of the derivation, temporarily add <code>with import <nixpkgs> {};</code>. For now, don't worry too much about declaring every dependency as a parameter<!-- TODO clarify. "parameter of the default build function"? -->, to save time.
+# Build the package with <code>nix-build</code>. Iterate on tweaking the derivation and rebuilding until it succeeds.
+# For large projects with long compile times, you can use <code>nix-shell</code> instead to [https://nixos.org/manual/nixpkgs/stable/#sec-building-stdenv-package-in-nix-shell run the individual phases].
+# At this stage, you may encounter some build quirks of the project. Compile-time errors will hopefully explain what you're missing. For example [https://github.com/NixOS/nixpkgs/blob/643ce4bd0f057bc0b90f0faebeb83a3b14f01674/pkgs/tools/package-management/micromamba/default.nix#L6-L10 micromamba needs a specialized build of libsolv].
+# Read on below for further steps.
+=== Packages from binaries ===
+# There's probably a package for it for some other distro. Use that package definition to figure out the dependencies. For example, if you have a deb package you can view its dependencies by running <code>dpkg -I <package.deb></code>. [https://aur.archlinux.org/packages/ Arch packages] can also be useful to look up for reference (view the package's PKGBUILD):
+# Sometimes the definitions for other distros won't be enough by nix's standards. If that's the case, use <code>ldd</code> and/or <code>strace</code> to find the rest of the dependencies. If you're not familiar with <code>ldd</code>/<code>strace</code> see [https://unix.stackexchange.com/questions/120015/how-to-find-out-the-dynamic-libraries-executables-loads-when-run How to find out the dynamic libraries executables loads when run?]
+# See how other nix binary packages deal with dependencies. For example [https://github.com/NixOS/nixpkgs/search?q=%22dpkg+-x%22 nix packages based on deb packages].
+# If the application contains some helper executable or vendored dlopen'd library you will probably need to give the nix treatment to it as well. For example, [https://github.com/NixOS/nixpkgs/blob/42c154d332eb4eb17c74b587c1d4c2fcc3042ba1/pkgs/applications/editors/jetbrains/default.nix#L196-L200 JetBrains Rider vendors dotnet so it needs to be replaced with the dotnet nix package].
+# Because there's no real build step here you'll have to rely more on testing the actual execution of the package.
+=== Both source code packages and binary packages ===
+# Once you have the package building successfully, test the output. Ensure the build completes using<code>nix-build</code>, then run <code>result/bin/&lt;executableName></code>. Test as much functionality of the application as you can to ensure that it works as intended.
+# Now that your package builds and runs, it's time to move it to nixpkgs. Read [https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md nixpkgs/CONTRIBUTING.md], make sure your package is up to the standards e.g. add a suitable [https://nixos.org/manual/nixpkgs/stable/#sec-standard-meta-attributes <code>meta</code> section].
+# Git clone https://github.com/NixOS/nixpkgs, figure out the best category / directory for the application (within https://github.com/NixOS/nixpkgs/tree/master/pkgs/), create the directory for your application, and move your default.nix there.
+# If you used <code>with import <nixpkgs> {};</code> to iterate more quickly, now is the time to replace that with the actual dependencies as an attribute set at the beginning of the file e.g. <code>{ lib, stdenv, fetchFromGitHub }:</code>
+# Add the package to the top level declaration of packages. Most of the time this will be https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix .
+# If this is your first package in nixpkgs, add yourself in https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix in a separate commit.
+# Read on about the final steps of branching and sending your PR in https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md .
 == How to install from the local repository ==
@@ Line 38: / Line 75: @@
 <syntaxhighlight lang="console">
 $ nix-env -f $NIXPKGS -qaP '*'
-</syntaxhighlight>
-'''example: install software from local repository'''
-<syntaxhighlight lang="console">
-$ nix-env -f $NIXPKGS -i python-urlgrabber
 </syntaxhighlight>
 '''example: update the system''' based on your local '''$NIXPKGS'''
 <syntaxhighlight lang="console">
-$ nixos-rebuild -I nixos=$NIXPKGS/nixos -I nixpkgs=$NIXPKGS switch
+$ nixos-rebuild -I nixpkgs=$NIXPKGS switch
 </syntaxhighlight>
@@ Line 75: / Line 107: @@
 <syntaxhighlight lang="console">
+$ git fetch upstream
 $ git checkout -b upstream-master upstream/master
 $ git pull
@@ Line 152: / Line 185: @@
 <syntaxhighlight lang="bash">
-mkdir -p /tmp/nix-shell-bc
+$ mkdir -p ~/tmpdev/bc-build  &&  cd ~/tmpdev/bc-build
-cd /tmp/nix-shell-bc
+$ nix-shell $NIXPKGS -A bc
-nix-shell $NIXREPOS/nixpkgs -A bc
-export out=/tmp/foo/out
 </syntaxhighlight>
-now we have find out which phases are specified for this package:
+You can also drop in the build environment for a package not in nixpkgs.
 <syntaxhighlight lang="bash">
-typeset -f genericBuild | grep 'phases='
+$ mkdir -p ~/tmpdev/bc-build  &&  cd ~/tmpdev/bc-build
+$ nix-shell -E "with import <nixpkgs> {}; callPackage /path/to/package.nix {}"
+</syntaxhighlight>
+You would have seen the dependencies downloading, but the ''bc-build'' directory remains empty. The build system would next invoke a builder with some arguments. You can obtain the exact name of the builder (usually '''bash''') and the arguments '''args''' of the builder (typically a shell script) by checking the corresponding value in:
+<syntaxhighlight lang="bash">
+$ nix derivation show $(nix-instantiate .)
+</syntaxhighlight>
+However, most of the time (for instance when using '''stdenv''' ) the [https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/default-builder.sh default builder] invokes first '''source $stdenv/setup''' to load the appropriate environment variables, and then '''genericBuild()'''. This is a shell function defined by [https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/setup.sh stdenv] that you can review like this...
+<syntaxhighlight lang="bash">
+$ typeset -f genericBuild | less
+</syntaxhighlight>
+which shows when custom variables '''$buildCommandPath''' or '''$buildCommand''' are defined, those are evaluated exclusively.  Otherwise, if no custom '''$phases''' variable is set, the standard build phase order is used as shown here...
+<syntaxhighlight lang="bash">
+$ typeset -f genericBuild | grep 'phases='
 phases="$prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase fixupPhase installCheckPhase $preDistPhases distPhase $postPhases";
 </syntaxhighlight>
-The phases can be defined either as a string to be eval'ed or as a shell function, [https://github.com/NixOS/nixpkgs/blob/5a0b79/pkgs/stdenv/generic/setup.sh#L818 this is how] Nix invokes it.
+The phases can be defined either as a string to be eval'ed or as a shell function, [https://github.com/NixOS/nixpkgs/blob/5a0b79f955d6c2dc21239f1b0d956ef8dc89a57e/pkgs/stdenv/generic/setup.sh#L818 this is how] Nix invokes it.
+So to observe a full build, you can do...
+<syntaxhighlight lang="bash">
+$ export out=~/tmpdev/bc-build/out
+$ set -x # Optional: it prints all commands, can be practical to debug
+$ set +e # Optional: do not quit the shell on simple errors, Ctrl-C,...
+$ export NIX_ENFORCE_PURITY=0 # Optional: nix automatically skip absolute files not in /nix/, /tmp or NIX_BUILD_TOP. When building in a nix-shell this may be an issue as the source won't be  in the above folders and you may get errors like Fatal error: blabla.h: No such file or directory. https://github.com/NixOS/nixpkgs/issues/204036
+$ genericBuild
+</syntaxhighlight>
+To only run some specific phases, use runPhase:
+<syntaxhighlight lang="bash">
+# Syntax: runPhase *phase*
+$ runPhase unpackPhase
+</syntaxhighlight>
-so when developing you need to run these phases in a row:
+While developing your own package, you need to run these phases in order:
 <syntaxhighlight lang="bash">
 unpackPhase
@@ Line 177: / Line 240: @@
 installCheckPhase
 distPhase
+</syntaxhighlight>
+Phases can be both bash functions, or environment of identical name (when they are overridden). <code>genericBuild</code> takes care of that distinction for you, invoking them appropriately. You can of course drop down to evaluating them yourself, for example to invoke an overridden phase (an environment variable) using '''eval''' instead:
+<syntaxhighlight lang="bash">
+eval "$checkPhase"
+# etc..
 </syntaxhighlight>
 {{Note|you do not need to run $preConfigurePhase explicitly as it is run, when running configurePhase already.}}
-list all functions which are declared in '''set''':
+To list all functions which are declared in '''set''':
 <syntaxhighlight lang="bash">
 typeset -F
@@ Line 231: / Line 301: @@
 <syntaxhighlight lang="bash">
-echo $unpackPhase
+echo "$unpackPhase"
 </syntaxhighlight>
@@ Line 301: / Line 371: @@
 Tip: A git repository can be used for snapshotting attempts at building the package. This also makes it easy to generate patches, should you need to.
+== Adding custom libraries and dependencies to a package ==
+If you are packaging a dependency, such as a library used by applications for them to compile their code, you might have found you'd like to test if the derivation file installs correctly and can be used by other software.
+In order to do this, you'll need to make a simple program that references the library, make a derivation for this program, then add the dependency. For example:
+Your program to test the library:
+<syntaxhighlight lang="nix">
+{
+  pkgs ? import <nixpkgs> {
+    overlays = [
+      (final: prev: {
+        my-library = prev.callPackage ./my-library.nix { };
+      })
+    ];
+  },
+}:
+pkgs.callPackage (
+  {
+    stdenv,
+    hello,
+    pkg-config,
+    my-library,
+  }:
+  stdenv.mkDerivation {
+    pname = "something";
+    version = "1";
+    strictDeps = true;
+    # host/target agnostic programs
+    depsBuildBuild = [
+      hello
+    ];
+    # compilers & linkers & dependecy finding programs
+    nativeBuildInputs = [
+      pkg-config
+    ];
+    # libraries
+    buildInputs = [
+      my-library
+    ];
+  }
+) { }
+</syntaxhighlight>
 == nix channels ==
 nix channels can be used in parallel with your new local repositories, see its [[install/remove software#nix-channels| nix-channel-documentation]]
+== Testing Package Updates with nixpkgs-review ==
-== Testing Package Updates with Nox ==
+You can also use [https://github.com/Mic92/nixpkgs-review nixpkgs-review] to compile, review and merge packages and its dependencies. It claims to be faster than nox and provides a nix-shell where you can test the package.
-If you are updating a package's version, you can use nox to make sure all packages that depend on the updated package still compile correctly.
+First make sure it is available in your shell:
+<syntaxhighlight lang="bash">
+nix-shell -p nixpkgs-review
+</syntaxhighlight>
-First make sure it is in your environment:
+You can run nixpkgs-review against uncommitted/staged changes in a cloned nixpkgs repository:
 <syntaxhighlight lang="bash">
-nix-env -i nox
+cd ~/git/nixpkgs
+nixpkgs-review wip [--staged]
 </syntaxhighlight>
-You can run nox against uncommited changes to a nixpkgs repository:
+It is also possible to review a specified commit:
 <syntaxhighlight lang="bash">
-cd ~/.nix-defexpr
+cd ~/git/nixpkgs
-nox-review wip
+nixpkgs-review rev HEAD
 </syntaxhighlight>
-If you have already commited your changes and created a pull request, you can use the pr command:
+If you have already committed your changes and created a pull request, you can use the pr command:
+<syntaxhighlight lang="bash">
+cd ~/git/nixpkgs
+nixpkgs-review pr 5341
+</syntaxhighlight>
+You can post the build result, approve/merge or read the comments of a pull request inside the provided nix-shell:
+<syntaxhighlight lang="bash">
+# inside the provided shell
+nixpkgs-review post-result
+nixpkgs-review approve
+nixpkgs-review merge
+nixpkgs-review comments
+</syntaxhighlight>
+If the pr provides a new package you can start it inside the nix-shell using its package name:
+<syntaxhighlight lang="bash">
+# inside the provided shell
+packagename
+</syntaxhighlight>
+== Formatting Packages with nixfmt ==
+It is "good practice" to format packages in a way that following changed will create as minimal diffs as possible. The formatter [https://github.com/NixOS/nixfmt nixfmt] can be used for that.
+<syntaxhighlight lang="bash">
+nix-shell -p nixfmt-rfc-style --run 'nixfmt path/to/default.nix'
+</syntaxhighlight>
+== Testing Packages with nixpkgs-hammering ==
+You can test some "good practices" in a package with [https://github.com/jtojnar/nixpkgs-hammering nixpkgs-hammering]. But before applying the recommendations you should read the given [https://github.com/jtojnar/nixpkgs-hammering/tree/main/explanations explanations].
 <syntaxhighlight lang="bash">
-nox-review pr 5341
+cd ~/git/nixpkgs
+nix run -f https://github.com/jtojnar/nixpkgs-hammering/archive/master.tar.gz -c nixpkgs-hammer packagename # if you are using stable nix
+nix run github:jtojnar/nixpkgs-hammering packagename # if you are using nix flake
 </syntaxhighlight>
@@ Line 329: / Line 479: @@
 * [[Generic Algorithm on Doing Packaging]]
+* [https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html Fundamentals of Stdenv] in Nix Pills
+* [https://nixos.org/guides/nix-pills/developing-with-nix-shell.html Developing with nix-shell] in Nix Pills
 [[Category:Development]]