NixOS Wiki

Nixpkgs/Create and debug packages: Difference between revisions

← Older edit
VisualWikitext
imported>Hypnosis2839
→Packages from source code: Remove references to nix3 CLI, fix instructions for phase-by-phase builds, clean up tone, remove repetitive phrasing
Das-g (talk | contribs)
3 edits
m →Using nix-shell for package development: Improve grammar in note about preConfigurePhase
 
(10 intermediate revisions by 7 users not shown)
Line 37: Line 37:
# 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.
# 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.
# 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 [[Development environment with nix-shell|nix-shell]] with <code>nix-shell</code>. Inside the development shell, you can [https://ryantm.github.io/nixpkgs/stdenv/stdenv/#sec-building-stdenv-package-in-nix-shell run the individual phases].
# 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].
# 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.
# Read on below for further steps.
Line 51: Line 51:
=== Both source code packages and binary packages ===
=== Both source code packages and binary packages ===


# Once you have the package building successfully, it's time to start testing the output. Run <code>nix run -L</code>, this will give you a shell where the application executable should be in the PATH. If the executable is not in the PATH, you might need to override <code>installPhase</code>. Try to test as many functions of the application as you can. Most of the time only making sure that the application starts up will not be enough.
# 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].
# 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.
# 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>
# 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 .
# 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
# 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 .
# 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 ==
== How to install from the local repository ==
Line 198: Line 197:
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:
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">
<syntaxhighlight lang="bash">
$ nix show-derivation $(nix-instantiate .)
$ nix derivation show $(nix-instantiate .)
</syntaxhighlight>
</syntaxhighlight>


Line 217: Line 216:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
$ export out=~/tmpdev/bc-build/out
$ export out=~/tmpdev/bc-build/out
$ source $stdenv/setup
$ set -x # Optional: it prints all commands, can be practical to debug
$ 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,...
$ set +e # Optional: do not quit the shell on simple errors, Ctrl-C,...
Line 224: Line 222:
</syntaxhighlight>
</syntaxhighlight>


To only run some specific phases:
To only run some specific phases, use runPhase:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
$ phases="buildPhase checkPhase" genericBuild
# Syntax: runPhase *phase*
$ runPhase unpackPhase
</syntaxhighlight>
</syntaxhighlight>


Line 250: Line 249:
</syntaxhighlight>
</syntaxhighlight>


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


To list all functions which are declared in '''set''':
To list all functions which are declared in '''set''':
Line 372: 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.
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 ==
Line 418: Line 461:
</syntaxhighlight>
</syntaxhighlight>


== Formatting Packages with nixpkgs-fmt ==
== 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/nix-community/nixpkgs-fmt nixpkgs-fmt] can be used for that.
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">
<syntaxhighlight lang="bash">
nixpkgs-fmt path/to/default.nix
nix-shell -p nixfmt-rfc-style --run 'nixfmt path/to/default.nix'
</syntaxhighlight>
</syntaxhighlight>


Retrieved from "https://wiki.nixos.org/wiki/Nixpkgs/Create_and_debug_packages"