Learning Journey tutorial - making a derivation

[zmitchell]

Project description

This tutorial covers making a derivation that builds a Rust crate with no dependencies. It starts with runCommand and shows the difficulties that you run into using this simple builder, then ends with showing how mkDerivation takes care of these same issues for you. This should help users get a better understanding of what mkDerivation is useful for e.g. it should help users build a mental model of what is happening and what needs to happen in order to successfully build a package.

Steps

• Submit a PR for the outline of the tutorial
• Submit a PR for the draft of the tutorial

Considerations

In the meeting where we discussed this tutorial we came up with this rough flow:

• Make sure that we’re not using any dependencies
  • Create a brand new project with cargo new --bin example_project
  • No dependencies -> no internet required -> works in the sandbox

Create a default.nix with a

runCommand "myProject" { ... } ''
  cargo build
'';

Observe failure, explain it (source isn’t available)

runCommand "myProject" { ... } ''
  cd ${./.}
  cargo build
'';

Explain how ${} imports paths into the store. Fails with not writable.

runCommand "myProject" { ... } ''
  cp ${./.} .
  chmod +w . -R
  cargo build
'';

Fails: $out empty

runCommand "myProject" { ... } ''
  # copy the source
  cp ${./.} .
  chmod +w . -R

  # build
  cargo build

  # install
  mkdir -p $out/bin
  mv target/debug/myProject $out/bin
'';

Then show how mkDerivation makes this easier:

stdenv.mkDerivation {
  name = "myProject";
  src = ./.;
  buildPhase = ''
    cargo build
  '';
  installPhase = ''
    mkdir -p $out/bin
    mv target/debug/myProject $out/bin
  '';
};

[zmitchell]

@roberth assigned to you for feedback

[fricklerhandwerk]

Discussed in LJWG meeting today:

This is a strong mix of explanation and tutorial. Tutorials should try to teach a behavioral pattern, and here the target skill is creating a mkDerivation espression that gives you something useful. We all agree we need good explanation of the internal structure, but this would be a different piece altogether.

We may want to rename the tutorial to be specific to stdenv.mkDerivation.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-06-29-learning-journey-working-group-meeting-notes-15/29799/1

[proofconstruction]

In the description of #601, we have

Migrating a project with an already working build system to a Nix-based workflow can be difficult. Doing a very basic derivation with runCommand or mkDerivation is covered in #599, but this follows the happy path of not having no dependencies at all outside of the native Rust build tools. This is not the reality for most developers working with Nix.

If the purpose of this tutorial was to teach mkDerivation for zero-dependency projects, we already have that with the hello section in #650 (just not with Rust).

Using runCommand until it's easier to just use the mkDerivation features would be a great way to wrap up #602 and segue to #601, though.

[zmitchell]

Agreed, we can revisit this later if we want.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-10-learning-journey-meeting-notes-21/31556/1