nix-tutorial/README.md

# nix-tutorial

## What is nix?


Nix is a package manager, like `apt`,`yum`,`dnf`,`pip`, etc. It can be installed in any operating system, although there is a Linux distribution that uses it by default: NixOS.

When installed independently, it doesn't interfere with the system's package manager (e.g. `apt`), as it uses a separate directory for everything: `/nix`.

## Why nix?

It allows for creating *reproducible* environments. This means that once someone creates a development environment, its configuration can be shared with other developers on the team, and have it work exactly the same way!

This has multiple benefits:
* Not every developer needs to struggle with installing every package from their distribution's repositories one-by-one, take care of incompatible versions, missing packages, add third-party repositories (e.g PPAs for Ubuntu), etc
* Easy on-boarding: new contributors can start working right away!

## Why not...

* Docker/Podman:
  * It's not reproducible!
    * The versions for every package installed depends on what was available the day the image was built. Some distribution package managers support version pinning, but that might not always work as expected.
    * Nix references packages not only by version, but also by the hash of its contents, and one can also even reference the `nixpkgs` repository's snapshot at a specific point in time (it's a git repository == commit!). This also means that multiple versions of the same package can be installed at the same time.
  * Inconvenient for everyday use: A large image will take a few seconds to start; the user needs to mount every directory needed as volumes; UID, file permissions and ownership inconsistencies; the user's system's familiar shell configuration, aliases, and utilities, are not available inside the container, etc
* `pip`:
  * Is language-specific; nix can manage *everything*, so the way it is used across multiple projects would be more uniform and familiar, both for developers working in multiple projects and for groups
  * It isn't able to install system utilities, compilers, etc (which some pypi packages need during installation!)
* `chroot`/`lxc` containers
  * Harder to use for a development workflow
  * Similar problems with Docker/Podman


 ## Install

### `nix`

The [recommended way](https://nixos.org/download/#download-nix) is:

```fish
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon
```

If you encounter any issues during installation, for example if your Linux distribution uses SELinux, you can try the single-user installation:

```fish
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --no-daemon
```

or [Determinate nix](https://docs.determinate.systems/), a nix distribution (!= Linux distribution):

```fish
curl -fsSL https://install.determinate.systems/nix | sh -s -- install --determinate
```

### `devbox`
As using nix by its own can be daunting for new users, we can use [devbox](https://jetify-com.vercel.app/docs/devbox/) (think of it as a wrapper for nix, which can be used like python/pip but for any package we need!)

```fish
nix profile install nixpkgs#devbox
```

## Using `devbox`

To create a `devbox` configuration:

```fish
cd project
devbox init
```

To manage your project's build dependencies and tools:

```fish
devbox add gcc@4.9.4
devbox list
devbox rm gcc
devbox add gcc
```

You can search for packges on [nixhub](https://www.nixhub.io), or directly from the terminal:

```fish
devbox search numpy
devbox add python313Packages.numpy
```

Then, enter the environment with:

```fish
devbox shell
```

`devbox` also supports various programming languages. For example, [Python](https://jetify-com.vercel.app/docs/devbox/devbox_examples/languages/python/):
once you add it as a dependency, devbox will also manage and activate a Python virtual environment for you:

```fish
devbox add python@3.6.12
devbox add gcc git ipcalc
devbox shell
pip install numpy
pip install -r requirements.txt
```

### Bonus instructions

[devbox](https://jetify-com.vercel.app/docs/devbox/ide_configuration/direnv/) can also be used with [direnv](https://direnv.net/#basic-installation) (highly recommended!):

```fish
nix profile install nixpkgs#direnv
cd project
devbox generate direnv
```

Then, after you also configure [your shell](https://direnv.net/docs/hook.html), the environment is activated automatically when you enter a project:

```fish
cd project
make
```

You could also use `devbox` as a [general package manager](https://jetify-com.vercel.app/docs/devbox/devbox_global/), without needing to `devbox shell` in a project to keep software available:

```fish
devbox global add ripgrep vim git
devbox global list
```

The same is possible with a nix command (although `devbox` might still seem easier for beginners):

```fish
nix profile install nixpkgs#wget
```

You can search [nix packages](https://search.nixos.org/packages) to find the name of a package you want to install