nix-community/dream2nix
1
1
Fork 0
mirror of https://github.com/nix-community/dream2nix.git synced 2024-11-23 00:13:02 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1012 from phaer/guides

Browse Source 
Reworked Getting started guide
This commit is contained in:
Paul Haerle 2024-07-10 12:05:00 +02:00 committed by GitHub
commit 0c6b5c8ab7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 172 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/src/.pages
View File

@ -1,6 +1,6 @@
nav:
- "Home": index.md
- "Getting Started": gettingstarted.md
- Guides: guides
- Concepts:
- "Modules": modules.md
- "Overriding Dependencies": overrides.md

75
docs/src/gettingstarted.md
View File

@ -1,75 +0,0 @@
To package a piece of software with dream2nix, you'd typically start with
a bare-bones dream2nix flake like this:
```nix
{
description = "My flake a dream2nix package";
inputs = {
dream2nix.url = "github:nix-community/dream2nix";
nixpkgs.follows = "dream2nix/nixpkgs";
};
outputs = inputs @ {
self,
dream2nix,
nixpkgs,
...
}: let
system = "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 = ./.;
}
];
};
};
}
```
And a `default.nix` that looks like this:
```nix
{
config,
lib,
dream2nix,
...
}: {
imports = [
# dream2nix modules go here
];
deps = {nixpkgs, ...}: {
# dependencies go here
};
name = "my-package-name";
version = "2.7.1";
# Ecosystem-dependent package definition goes here
}
```
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.
Once you have imported a module, this module will make ecosystem-dependent
functions available to create your package definition, such as `mkDerivation`
or `buildPythonPackage`.
### Building
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`.

2
docs/src/guides/.pages Normal file
View File

@ -0,0 +1,2 @@
nav:
- getting-started.md

169
docs/src/guides/getting-started.md Normal file
View File

@ -0,0 +1,169 @@
!!! info
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 = "A flake for my dream2nix packages";
inputs = { # (1)
dream2nix.url = "github:nix-community/dream2nix";
nixpkgs.follows = "dream2nix/nixpkgs";
};
outputs = {
self,
dream2nix,
nixpkgs,
}:
let
eachSystem = nixpkgs.lib.genAttrs [ # (2)
"aarch64-darwin"
"aarch64-linux"
"x86_64-darwin"
"x86_64-linux"
];
in {
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=";
};
};
}
```
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.
## Build it
!!! warning
Be aware that nix will only "see" your files once
they have been added to git's index, i.e. via `git add`!
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!
```
1. `.#` is a shorter form of `.#packages.x86_64-linux.default` (on `x86_64-linux` systems).
## Lock it
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*.
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.