Official NixOS Wiki

Development environment with nix-shell: Difference between revisions

← Older edit
DHCP (talk | contribs)
232 edits
VisualWikitext
m Fixed indentation in code block.
DHCP (talk | contribs)
232 edits
m style improvements
 
(9 intermediate revisions by 6 users not shown)
Line 3: Line 3:
If you already have a nix package definition of your project it's easy: Just use <code>nix-shell</code> instead of <code>nix-build</code> and you will end up in a bash shell that reproduce the build-environment of your package. You can also override[https://nixos.org/nixpkgs/manual/#sec-pkg-override] your package in a <code>shell.nix</code> file to add test and coverage dependencies, that are not necessary for the actual build of the package, but that you want for your development environment.
If you already have a nix package definition of your project it's easy: Just use <code>nix-shell</code> instead of <code>nix-build</code> and you will end up in a bash shell that reproduce the build-environment of your package. You can also override[https://nixos.org/nixpkgs/manual/#sec-pkg-override] your package in a <code>shell.nix</code> file to add test and coverage dependencies, that are not necessary for the actual build of the package, but that you want for your development environment.


But, if you don't (or you don't want to) have a package definition you can still use a nix-shell to provide a reproducible development environment. To do so, you have to create a <code>shell.nix</code> file at the root of your repository. For example, if you want to have Ruby 3.2 and not one provided by your system you can write:
But, if you don't (or you don't want to) have a package definition you can still use a nix-shell to provide a reproducible development environment. To do so, you have to create a <code>shell.nix</code> file at the root of your repository. For example, if you want to have rustc with libraries and hello you can write:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{ pkgs ? import <nixpkgs> {} }:
{
pkgs.mkShell {
  pkgs ? import <nixpkgs> { },
  # nativeBuildInputs is usually what you want -- tools you need to run
}:
  nativeBuildInputs = with pkgs.buildPackages; [ ruby_3_2 ];
pkgs.callPackage (
}
  {
    mkShell,
    hello,
    rustc,
    pkg-config,
    openssl,
  }:
  mkShell {
    strictDeps = true;
    # host/target agnostic programs
    depsBuildBuild = [
      hello
    ];
    # compilers & linkers & dependency finding programs
    nativeBuildInputs = [
      rustc
      pkg-config
    ];
    # libraries
    buildInputs = [
      openssl
    ];
  }
) { }
 
</syntaxhighlight>
</syntaxhighlight>


Then just run:
Then just run:
{{Commands|$ nix-shell}}
 
<syntaxhighlight lang="console">
$ nix-shell
</syntaxhighlight>


Or, to be more explicit:
Or, to be more explicit:
{{Commands|$ nix-shell shell.nix}}


Now you have ruby 3.2 available in your shell:
<syntaxhighlight lang="console">
<syntaxHighlight lang=bash>
$ nix-shell shell.nix
$ ruby --version
</syntaxhighlight>
ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]
 
</syntaxHighlight>
Now you have rustc available in your shell:
<syntaxhighlight lang="console">
$ rustc --version
rustc 1.80.1 (3f5fd8dd4 2024-08-06) (built from a source tarball)
</syntaxhighlight>


To be sure that the tools installed on your system will not interfere with the dependencies that you've defined in the shell you can use the <code>--pure</code> option.
To be sure that the tools installed on your system will not interfere with the dependencies that you've defined in the shell you can use the <code>--pure</code> option.


If you'd like to load a local nix expression into a shell you can do it by modifying the earlier example a little bit:
If you'd like to load a local nix expression into a shell you can do it by modifying the earlier example a little bit, see comments in the earlier example for where to put your package:
<syntaxHighlight lang=nix>
<syntaxhighlight lang="nix">
{ pkgs ? import <nixpkgs> {} }:
{
pkgs.mkShell {
  pkgs ? import <nixpkgs> {
  # buildInputs is for dependencies you'd need "at run time",
    overlays = [
   # were you to to use nix-build not nix-shell and build whatever you were working on
      (final: prev: {
   buildInputs = [
        my-package = prev.callPackage ./my-package.nix { };
    (import ./my-expression.nix { inherit pkgs; })
      })
   ];
    ];
}
  },
</syntaxHighlight>
}:
pkgs.callPackage (
  {
    mkShell,
    my-package
   }:
   mkShell {
    strictDeps = true;
    buildInputs = [
      my-package
    ];
   }
) { }
</syntaxhighlight>


If you want to see how to manually run the various phases of a given derivation from a nix-shell (useful to debug), see [[Nixpkgs/Create_and_debug_packages#Using_nix-shell_for_package_development]].  
If you want to see how to manually run the various phases of a given derivation from a nix-shell (useful to debug), see [[Nixpkgs/Create_and_debug_packages#Using_nix-shell_for_package_development]].  
Line 45: Line 88:
we replace <code>nix-shell</code> with <code>nix develop</code>
we replace <code>nix-shell</code> with <code>nix develop</code>


Example: Building Nix in a development shell, to get [[Incremental builds]] = faster recompiles
Example: Building Nix in a development shell, to get [[Incremental builds]] = faster recompiles. This is because Nix evaluations are cached.


<pre>
<syntaxhighlight lang="console">
git clone https://github.com/NixOS/nix --depth 1
$ git clone https://github.com/NixOS/nix --depth 1
cd nix
$ cd nix
nix develop
$ nix develop
</pre>
</syntaxhighlight>


Now what? Let's read the manual:
Now what? Let's read the manual:


<pre>
<syntaxhighlight lang="console">
less README.md
$ less README.md
less doc/manual/src/contributing/hacking.md
$ less doc/manual/src/contributing/hacking.md
</pre>
</syntaxhighlight>


The contributing guide for Nix says:
The contributing guide for Nix says:
Line 81: Line 124:
So, in our <code>nix develop</code> shell, we run
So, in our <code>nix develop</code> shell, we run


<pre>
<syntaxhighlight lang="console">
./bootstrap.sh
$ ./bootstrap.sh
./configure $configureFlags --prefix=$(pwd)/outputs/out
$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
make -j $NIX_BUILD_CORES
$ make -j $NIX_BUILD_CORES
</pre>
</syntaxhighlight>


This will compile Nix to <code>./outputs/out/bin/nix</code>
This will compile Nix to <code>./outputs/out/bin/nix</code>
Line 96: Line 139:
Let's assume you have a <code>default.nix</code> file
Let's assume you have a <code>default.nix</code> file


<syntaxHighlight lang=nix>
<syntaxhighlight lang="nix">
{ stdenv, python }:
{ stdenv, python }:
stdenv.mkDerivation {
stdenv.mkDerivation {
   buildInputs = [ python ];
   pname = "some-package";
  name = "some-package";
  strictDeps = true;
  nativeBuildInputs = [ python ];
   version = "0.0.1";
   version = "0.0.1";
   src = /home/yourname/path/to/project; # can be a local path, or fetchFromGitHub, fetchgit, ...
   src = /home/yourname/path/to/project; # can be a local path, or fetchFromGitHub, fetchgit, ...
}
}
</syntaxHighlight>
</syntaxhighlight>


Then you can start a development shell with
Then you can start a development shell with


<syntaxHighlight lang=bash>
<syntaxHighlight lang=console>
nix-shell -E 'with import <nixpkgs> { }; callPackage ./default.nix { }'
$ nix-shell -E 'with import <nixpkgs> { }; callPackage ./default.nix { }'
</syntaxHighlight>
</syntaxHighlight>


Line 121: Line 165:
# this is useful to make many small changes to a large project
# this is useful to make many small changes to a large project
# after each change, just run `buildPhase`
# after each change, just run `buildPhase`
#cd $HOME/path/to/project
# cd $HOME/path/to/project


configurePhase
configurePhase
Line 137: Line 181:
</syntaxHighlight>
</syntaxHighlight>
and <code>nativeBuildInputs</code> would be for the native platform, while <code>buildInputs</code> would be for the foreign platform. That's a much more practical distinction: any tool that's miscategorized one won't be able to run, and any library that's miscategorized one won't be able to link!
and <code>nativeBuildInputs</code> would be for the native platform, while <code>buildInputs</code> would be for the foreign platform. That's a much more practical distinction: any tool that's miscategorized one won't be able to run, and any library that's miscategorized one won't be able to link!
== direnv ==
One of the limitations of nix-shell is that you can't use a shell other than bash. Thankfully, there is Direnv [[https://direnv.net/]] with the support of Nix[[https://github.com/direnv/direnv/wiki/Nix]] to overcome this limitation. Also, Direnv provides some nice features like loading the environment automatically when you enter your project directory and show the loaded variables to you (explicit is always better;-)).
First, install Direnv:
<syntaxHighlight lang=bash>
nix-env -i direnv
</syntaxHighlight>
Now, you need to add one more file in the root of your repository named <code>.envrc</code> that contains only this:
<syntaxHighlight lang=bash>
use_nix
</syntaxHighlight>
Then depending on the shell you are using, you need to add a line in your configuration file. See the ''Setup'' section of the doc[https://direnv.net/]. For example, for Zsh put in your <code>~/.zshrc.local</code>:
<syntaxHighlight lang=bash>
eval "$(direnv hook zsh)"
</syntaxHighlight>
Then, still at the root of your repository, run:
<syntaxHighlight lang=bash>
$ direnv allow .
direnv: loading .envrc
direnv: using nix
[...]
+SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +_PATH +buildInputs +builder +checkPhase +cmakeFlags +configureFlags +doCheck +enableParallelBuilding +name +nativeBuildInputs +out +postCheck +preCheck +preConfigure +propagatedBuildInputs +propagatedNativeBuildInputs +shell +src +stdenv +system +testInputs +version ~PATH
</syntaxHighlight>
Bonus: you can see all the variables set by the nix-shell :)
Now you can leave your project and the environment will be unloaded:
<syntaxHighlight lang=bash>
$ cd ..
direnv: unloading
</syntaxHighlight>
No need to use <code>direnv allow</code> anymore, the next time you go to your project the environment will be loaded!
More explanation and configuration tweaks can be found in the Direnv wiki [https://github.com/direnv/direnv/wiki/Nix].


== Troubleshooting ==
== Troubleshooting ==


When compiling software which links against local files (e.g. when compiling with rust's cargo), you may encounter the following problem:
When compiling software which links against local files (e.g. when compiling with rust's cargo), you may encounter the following problem:
<syntaxHighlight lang=bash>
<syntaxHighlight lang=console>
= note: impure path `/[...]' used in link
= note: impure path `/[...]' used in link
</syntaxHighlight>
</syntaxHighlight>
Line 198: Line 202:
mkShell {
mkShell {
   ...
   ...
  strictDeps = true;
   buildInputs = [ gtk3 ];
   buildInputs = [ gtk3 ];
   shellHook = ''
   shellHook = ''
Line 209: Line 214:
=== Icons not working ===
=== Icons not working ===
Similar to the Gsettings issue, icons can be added with XDG_DATA_DIRS:
Similar to the Gsettings issue, icons can be added with XDG_DATA_DIRS:
<pre> XDG_DATA_DIRS=...:${hicolor-icon-theme}/share:${gnome3.adwaita-icon-theme}/share</pre>
<syntaxhighlight lang=bash>
XDG_DATA_DIRS=...:${hicolor-icon-theme}/share:${gnome3.adwaita-icon-theme}/share
</syntaxhighlight>
 
== See Also ==
* [[Direnv]]
* [[Command Shell#Using a different shell in nix-shell and nix develop]]
* [https://nixcademy.com/posts/cpp-with-nix-in-2023-part-1-shell/ C++ with Nix in 2023, Part 1: Developer Shells, Nixcademy]
 
[[Category:Development]]
[[Category:Development]]
[[Category:nix]]
[[Category:nix]]
Retrieved from "https://wiki.nixos.org/wiki/Development_environment_with_nix-shell"