From 7b48877133acfefaa97def4b39a41994a3a55ab4 Mon Sep 17 00:00:00 2001 From: phaer Date: Mon, 24 Jun 2024 15:02:38 +0200 Subject: [PATCH 1/2] docs: reworked gettingstarted.md --- docs/src/gettingstarted.md | 192 +++++++++++++++++++++++++++---------- 1 file changed, 143 insertions(+), 49 deletions(-) diff --git a/docs/src/gettingstarted.md b/docs/src/gettingstarted.md index dee8c24b..8478ea9b 100644 --- a/docs/src/gettingstarted.md +++ b/docs/src/gettingstarted.md @@ -1,75 +1,169 @@ -To package a piece of software with dream2nix, you'd typically start with -a bare-bones dream2nix flake like this: +!!! info -```nix + We assume that you already got a flakes-enabled [nix](https://nixos.org/) installed and at least a basic understanding of nix and flakes here. + + If that's not the case, check out the official documentation site at [nix.dev](https://nix.dev/) first! + +In this tutorial, we are going to package [GNU hello](https://gnu.org/s/hello), a traditional example for build systems, in order to get started +with dream2nix and its [module system ](./modules.md). + +## Start a project + +We start by creating a new git repository with the following two files: + +- `flake.nix` declares our inputs, dream2nix and nixpkgs, as well as a single package `hello` as an output. + The package is declared by calling `dream2nix.lib.evalModules` with the definitions in `hello.nix`, nixpkgs + and a helper module to let dream2nix know about your directory layout. + +- `hello.nix` declares a dream2nix module that imports [mkDerivation](./reference/mkDerivation/index.md) and + uses that to build GNU hello. + +Check out the code below and its annotations to learn more! + +!!! note + + And do not hesitate to message us on [matrix: #dream2nix:nixos.org](https://matrix.to/#/#dream2nix:nixos.org) if you found + a mistake or if things are unclear! + +### `flake.nix` + +```nix title="flake.nix" { - description = "My flake a dream2nix package"; + description = "A flake for my dream2nix packages"; - inputs = { + inputs = { # (1) dream2nix.url = "github:nix-community/dream2nix"; nixpkgs.follows = "dream2nix/nixpkgs"; }; - outputs = inputs @ { + outputs = { self, dream2nix, nixpkgs, - ... - }: let - system = "x86_64-linux"; + }: + let + eachSystem = nixpkgs.lib.genAttrs [ # (2) + "aarch64-darwin" + "aarch64-linux" + "x86_64-darwin" + "x86_64-linux" + ]; in { - packages.${system}.default = dream2nix.lib.evalModules { - packageSets.nixpkgs = inputs.dream2nix.inputs.nixpkgs.legacyPackages.${system}; - modules = [ - ./default.nix - { - paths.projectRoot = ./.; - paths.projectRootFile = "flake.nix"; - paths.package = ./.; - } - ]; + packages = eachSystem (system: { + hello = dream2nix.lib.evalModules { # (3) + packageSets.nixpkgs = nixpkgs.legacyPackages.${system}; # (4) + modules = [ + ./hello.nix # (5) + { # (6) + paths.projectRoot = ./.; + paths.projectRootFile = "flake.nix"; + paths.package = ./.; + } + ]; + }; + default = self.packages.${system}.hello; # (7) + }); + }; +} +``` + +1. Import dream2nix and tell nix to use whatever version of nixpkgs dream2nix declares. You can use other versions, but this it what we run our automated tests with. +2. Define a helper function that allows us to reduce boilerplate and still support all of of the listed systems for our package. +3. Create our package, called `hello` here, by *evaluating* the given dream2nix [modules](./modules.md). +4. Pass the given instance of nixpkgs to build our package with as a *module argument*. +5. Include our package definition from `hello.nix`. See below for its contents! +6. Define relative paths to aid dream2nix to find lock files and so on during *evaluation time*. These settings should work for repos containing multiple python projects as simpler ones. +7. We declare `hello` to be the default package. This allows us to just call i.e. `nix build .#` instead of `nix build .#hello`. + +### `hello.nix` + +```nix title="hello.nix" +{ # (1) + dream2nix, + config, + lib, + ... +}: { + imports = [ + dream2nix.modules.dream2nix.mkDerivation # (2) + ]; + + # (3) + name = "hello"; + version = "2.12.1"; + + # (4) + # deps = {nixpkgs, ...}: { + # inherit + # (nixpkgs) + # stdenv + # ; + # }; + + # (5) + mkDerivation = { + src = builtins.fetchTarball { + url = "https://ftp.gnu.org/gnu/hello/hello-${config.version}.tar.gz"; + sha256 = "sha256-jZkUKv2SV28wsM18tCqNxoCZmLxdYH2Idh9RLibH2yA="; }; }; } ``` -And a `default.nix` that looks like this: +1. Define a function, taking our *module arguments* and returning a *module*. + Inputs include `dream2nix`, a reference to package itself in `config`, and the nixpkgs library in `lib`. +2. Import the [`mkDerivation`](./reference/mkDerivation/index.md) module. +3. Define `name` and `version` of the package. Unlike most other options, those are not namespaced and defined in dream2nix `core` module. +4. Define a function that returns **dep**endencie**s** as *module options* from the given *package sets*. + `hello` here needs a compiler already in the defaults of `mkDerivation`, we don't need `deps` here but include it for demonstration purposes. +5. Define *module options* to further customize your build. In this case we just set `mkDerivation.src` to fetch a source tarball as well. + But you could use other arguments from `pkgs.mkDerivation`, such as `buildInputs` or `buildPhase` here as well. -```nix -{ - config, - lib, - dream2nix, - ... -}: { - imports = [ - # dream2nix modules go here - ]; +## Build it - deps = {nixpkgs, ...}: { - # dependencies go here - }; +!!! warning - name = "my-package-name"; - version = "2.7.1"; + Be aware that nix will only "see" your files once + they have been added to git's index, i.e. via `git add`! - # Ecosystem-dependent package definition goes here -} + This is because nix copies flakes to `/nix/store` before evaluating + them, but only those which are tracked by git. This can lead to confusion + if nix errors hint at missing files while you are able to seem them + in your shell. + +With all that code added, building it should work like any other nix build: + +```shell-session +$ git init +$ git add flake.nix hello.nix +$ nix build .# # (1) +$ ./result/bin/hello +Hello, World! ``` -To find out which dream2nix modules to import, browse through the modules -on the left and the [examples](https://github.com/nix-community/dream2nix/tree/main/examples/packages). When getting started, the -`./packages/languages` collection will be most helpful. +1. `.#` is a shorter form of `.#packages.x86_64-linux.default` (on `x86_64-linux` systems). -Once you have imported a module, this module will make ecosystem-dependent -functions available to create your package definition, such as `mkDerivation` -or `buildPythonPackage`. +## Lock it -### Building +Some of our our modules such as [pip](./reference/pip/index.md) require a custom lock file +added to your repository in order to pin your dependencies and store metadata which we can't +acquire during *evaluation time*. -Now, `git add` your `flake.nix` and `default.nix`. Depending on the module -you selected, you will generate and commit a `lock.json` describing the -'pinned' dependencies of your project. The error message produced by -`nix build .` should tell you how to generate this lock file, likely -something like `nix run .#default.lock`. +We don't need one in the `hello` example above. If you add a dream2nix module that does, +you will receive an error during building, with the error message telling you the command +you need to run. Generally: +```shell-session +$ nix run .#default.lock +$ git add lock.json +``` + +## Going further + +Check out our guides, the reference documentation and [examples](https://github.com/nix-community/dream2nix/tree/main/examples/packages/languages) +to learn more about the various modules and options to learn more about language-specific helpers to package and distribute your software with dream2nix. + +Once you have imported a module, this module will make ecosystem-dependent functions, such as [`mkDerivation`](./reference/mkDerivation/index.md) or [`buildPythonPackage`](./reference/buildPythonPackage/index.md), available to your package modules. + +And don't forget to join our communities at [matrix: #dream2nix:nixos.org](https://matrix.to/#/#dream2nix:nixos.org) and [github: nix-community/dream2nix](https://github.com/nix-community/dream2nix) to ask questions and learn from each other. Feedback we receive +there helps us to improve code & documentation as we go. From 363a6996c3325b8a1bf0b01e9583ffb893b7c262 Mon Sep 17 00:00:00 2001 From: phaer Date: Thu, 4 Jul 2024 16:42:48 +0200 Subject: [PATCH 2/2] docs: mv gettingstarted to guides/getting-started --- docs/src/.pages | 2 +- docs/src/guides/.pages | 2 ++ .../{gettingstarted.md => guides/getting-started.md} | 12 ++++++------ 3 files changed, 9 insertions(+), 7 deletions(-) create mode 100644 docs/src/guides/.pages rename docs/src/{gettingstarted.md => guides/getting-started.md} (92%) diff --git a/docs/src/.pages b/docs/src/.pages index 717f945a..45106025 100644 --- a/docs/src/.pages +++ b/docs/src/.pages @@ -1,6 +1,6 @@ nav: - "Home": index.md - - "Getting Started": gettingstarted.md + - Guides: guides - Concepts: - "Modules": modules.md - "Overriding Dependencies": overrides.md diff --git a/docs/src/guides/.pages b/docs/src/guides/.pages new file mode 100644 index 00000000..86a7881a --- /dev/null +++ b/docs/src/guides/.pages @@ -0,0 +1,2 @@ +nav: + - getting-started.md diff --git a/docs/src/gettingstarted.md b/docs/src/guides/getting-started.md similarity index 92% rename from docs/src/gettingstarted.md rename to docs/src/guides/getting-started.md index 8478ea9b..b13accd3 100644 --- a/docs/src/gettingstarted.md +++ b/docs/src/guides/getting-started.md @@ -5,7 +5,7 @@ If that's not the case, check out the official documentation site at [nix.dev](https://nix.dev/) first! In this tutorial, we are going to package [GNU hello](https://gnu.org/s/hello), a traditional example for build systems, in order to get started -with dream2nix and its [module system ](./modules.md). +with dream2nix and its [module system ](../modules.md). ## Start a project @@ -15,7 +15,7 @@ We start by creating a new git repository with the following two files: The package is declared by calling `dream2nix.lib.evalModules` with the definitions in `hello.nix`, nixpkgs and a helper module to let dream2nix know about your directory layout. -- `hello.nix` declares a dream2nix module that imports [mkDerivation](./reference/mkDerivation/index.md) and +- `hello.nix` declares a dream2nix module that imports [mkDerivation](../reference/mkDerivation/index.md) and uses that to build GNU hello. Check out the code below and its annotations to learn more! @@ -69,7 +69,7 @@ Check out the code below and its annotations to learn more! 1. Import dream2nix and tell nix to use whatever version of nixpkgs dream2nix declares. You can use other versions, but this it what we run our automated tests with. 2. Define a helper function that allows us to reduce boilerplate and still support all of of the listed systems for our package. -3. Create our package, called `hello` here, by *evaluating* the given dream2nix [modules](./modules.md). +3. Create our package, called `hello` here, by *evaluating* the given dream2nix [modules](../modules.md). 4. Pass the given instance of nixpkgs to build our package with as a *module argument*. 5. Include our package definition from `hello.nix`. See below for its contents! 6. Define relative paths to aid dream2nix to find lock files and so on during *evaluation time*. These settings should work for repos containing multiple python projects as simpler ones. @@ -112,7 +112,7 @@ Check out the code below and its annotations to learn more! 1. Define a function, taking our *module arguments* and returning a *module*. Inputs include `dream2nix`, a reference to package itself in `config`, and the nixpkgs library in `lib`. -2. Import the [`mkDerivation`](./reference/mkDerivation/index.md) module. +2. Import the [`mkDerivation`](../reference/mkDerivation/index.md) module. 3. Define `name` and `version` of the package. Unlike most other options, those are not namespaced and defined in dream2nix `core` module. 4. Define a function that returns **dep**endencie**s** as *module options* from the given *package sets*. `hello` here needs a compiler already in the defaults of `mkDerivation`, we don't need `deps` here but include it for demonstration purposes. @@ -145,7 +145,7 @@ Hello, World! ## Lock it -Some of our our modules such as [pip](./reference/pip/index.md) require a custom lock file +Some of our our modules such as [pip](../reference/pip/index.md) require a custom lock file added to your repository in order to pin your dependencies and store metadata which we can't acquire during *evaluation time*. @@ -163,7 +163,7 @@ $ git add lock.json Check out our guides, the reference documentation and [examples](https://github.com/nix-community/dream2nix/tree/main/examples/packages/languages) to learn more about the various modules and options to learn more about language-specific helpers to package and distribute your software with dream2nix. -Once you have imported a module, this module will make ecosystem-dependent functions, such as [`mkDerivation`](./reference/mkDerivation/index.md) or [`buildPythonPackage`](./reference/buildPythonPackage/index.md), available to your package modules. +Once you have imported a module, this module will make ecosystem-dependent functions, such as [`mkDerivation`](../reference/mkDerivation/index.md) or [`buildPythonPackage`](../reference/buildPythonPackage/index.md), available to your package modules. And don't forget to join our communities at [matrix: #dream2nix:nixos.org](https://matrix.to/#/#dream2nix:nixos.org) and [github: nix-community/dream2nix](https://github.com/nix-community/dream2nix) to ask questions and learn from each other. Feedback we receive there helps us to improve code & documentation as we go.