From 8afee9820300a2f1de44d5e184609306d7195f18 Mon Sep 17 00:00:00 2001 From: fricklerhandwerk Date: Fri, 27 Oct 2023 05:26:59 +0200 Subject: [PATCH] dissolve the Learning Journey section This does not yet follow #701, because the change to get there would be too big. The goal is to keep the table of contents meaningful at all times and the diff of each pull request manageable. The packaging tutorial is quite important, so it's not wrong to have it visible on the front page until we have enough material for a packaging section. The sharing dependencies article should really be a very brief guide, but because that would be quite a big change, it's only moved to the Guides section for now. --- _redirects | 2 ++ source/guides/recipes/direnv.md | 2 +- source/guides/recipes/index.md | 3 +- .../recipes}/sharing-dependencies.md | 3 +- source/tutorials/index.md | 2 +- source/tutorials/learning-journey/index.md | 12 -------- source/tutorials/learning-journey/template.md | 29 ------------------- .../packaging-existing-software.md | 20 +++++++++---- 8 files changed, 23 insertions(+), 50 deletions(-) rename source/{tutorials/learning-journey => guides/recipes}/sharing-dependencies.md (99%) delete mode 100644 source/tutorials/learning-journey/index.md delete mode 100644 source/tutorials/learning-journey/template.md rename source/tutorials/{learning-journey => }/packaging-existing-software.md (96%) diff --git a/_redirects b/_redirects index 7689caf8a..a836e380f 100644 --- a/_redirects +++ b/_redirects @@ -22,3 +22,5 @@ /recipes/faq /guides/faq 301 /recipes/python-environment /guides/recipes/python-environment 301 /recipes/direnv /guides/recipes/direnv 301 +/tutorials/learning-journey/sharing-dependencies /guides/recipes/sharing-dependencies 301 +/tutorials/learning-journey/packaging-existing-software /tutorials/packaging-existing-software 301 diff --git a/source/guides/recipes/direnv.md b/source/guides/recipes/direnv.md index 5e282ac8a..69b3e1cc5 100644 --- a/source/guides/recipes/direnv.md +++ b/source/guides/recipes/direnv.md @@ -1,4 +1,4 @@ -(automatic-direnv)= +(direnv)= # Automatic environment activation with `direnv` Instead of manually activating the environment for each project, you can reload a [declarative shell](declarative-reproducible-envs) every time you enter the project's directory or change the `shell.nix` inside it. diff --git a/source/guides/recipes/index.md b/source/guides/recipes/index.md index d18ef4a8a..33b9b0de7 100644 --- a/source/guides/recipes/index.md +++ b/source/guides/recipes/index.md @@ -4,6 +4,7 @@ ```{toctree} :maxdepth: 1 -Automatic environments <./direnv.md> +sharing-dependencies.md +Automatic environments Python development environment <./python-environment.md> ``` diff --git a/source/tutorials/learning-journey/sharing-dependencies.md b/source/guides/recipes/sharing-dependencies.md similarity index 99% rename from source/tutorials/learning-journey/sharing-dependencies.md rename to source/guides/recipes/sharing-dependencies.md index 03d46ad96..0e53f7a0d 100644 --- a/source/tutorials/learning-journey/sharing-dependencies.md +++ b/source/guides/recipes/sharing-dependencies.md @@ -1,4 +1,5 @@ -# Sharing dependencies between `default.nix` and `shell.nix` +(sharing-dependencies)= +# Dependencies in the development shell diff --git a/source/tutorials/index.md b/source/tutorials/index.md index 45dca52bf..90ed2749d 100644 --- a/source/tutorials/index.md +++ b/source/tutorials/index.md @@ -9,7 +9,7 @@ These sections contains series of lessons to get started. first-steps/index.md nix-language.md -learning-journey/index.md +Packaging existing software nixos/index.md cross-compilation.md ``` diff --git a/source/tutorials/learning-journey/index.md b/source/tutorials/learning-journey/index.md deleted file mode 100644 index c3959f942..000000000 --- a/source/tutorials/learning-journey/index.md +++ /dev/null @@ -1,12 +0,0 @@ -(learning-journey)= -# Learning Journey - -This collection of tutorials guides you through your first steps with Nix. -This series is a work in progress and will have some overlap with existing tutorials. -The intention is to unify these tutorials over time. - -```{toctree} -:maxdepth: 1 -sharing-dependencies.md -packaging-existing-software.md -``` diff --git a/source/tutorials/learning-journey/template.md b/source/tutorials/learning-journey/template.md deleted file mode 100644 index 70e5efe0a..000000000 --- a/source/tutorials/learning-journey/template.md +++ /dev/null @@ -1,29 +0,0 @@ -# TITLE - - - -## Overview - -### What will you learn? - - - -### How long will it take? - - - -### What will you need? - - - -## CONTENT HEADING - -## CONTENT HEADING - -## CONTENT HEADING - -## Where to next? - - - - diff --git a/source/tutorials/learning-journey/packaging-existing-software.md b/source/tutorials/packaging-existing-software.md similarity index 96% rename from source/tutorials/learning-journey/packaging-existing-software.md rename to source/tutorials/packaging-existing-software.md index 3f8c15f6c..e732a6d93 100644 --- a/source/tutorials/learning-journey/packaging-existing-software.md +++ b/source/tutorials/packaging-existing-software.md @@ -5,17 +5,14 @@ myst: "keywords": "Nix, packaging" --- - (packaging-existing-software)= - - # Packaging Existing Software With Nix One of Nix's primary use-cases is in addressing common difficulties encountered while packaging software, like managing dependencies. In the long term, Nix helps tremendously in alleviating that stress, but when *first* packaging existing software with Nix, it's common to encounter missing dependencies preventing builds from succeeding. -In this tutorial, you'll create your first Nix derivations to package C/C++ software, taking advantage of the [`nixpkgs stdenv`](https://nixos.org/manual/nixpkgs/stable/#chap-stdenv) which automates much of the work of building self-contained C/C++ packages. +In this tutorial, you'll create your first Nix derivations to package C/C++ software, taking advantage of the [Nixpkgs Standard Environment](https://nixos.org/manual/nixpkgs/stable/#part-stdenv) (`stdenv`) which automates much of the work of building self-contained C/C++ packages. The tutorial begins by considering `hello`, an implementation of "hello world" which only requires dependencies provided by `stdenv`. @@ -118,7 +115,7 @@ in This allows you to use `nix-build -A hello` to realize the derivation in `hello.nix`, similar to the current convention used in `nixpkgs`. :::{note} -`callPackage` automatically passes attributes from `nixpkgs` to the given function, if they match attributes required by that function's argument attrset. +[`callPackage`] automatically passes attributes from `pkgs` to the given function, if they match attributes required by that function's argument attrset. In this case, `callPackage` will supply `lib`, and `stdenv` to the function defined in `hello.nix`. ::: @@ -517,3 +514,16 @@ default.nix hello.nix icat.nix result ``` `result/bin/icat` is the executable built previously. Success! + +## References + +- [Nixpkgs Manual - Standard Environment](https://nixos.org/manual/nixpkgs/unstable/#part-stdenv) +- [Nix Pills - `callPackage` Design Pattern][`callPackage`] + +[`callPackage`]: https://nixos.org/guides/nix-pills/callpackage-design-pattern.html + +## Next steps + +- [](sharing-dependencies) +- [](direnv) +- [](python-dev-environment)