# Overview

This package contains a collection of Nix expressions created by
SHARCNET staff for various software packages.  You can use them to
install the associated packages into your Nix environment.

These directions assume you have loaded the Nix module (this enables
your Nix environment and makes the various Nix commands available)


```sh
module load nix
```

# Obtaining the latest expressions

If you don't yet have a copy of *~/nix-nixpkgs-sharcnet*, you will
need to clone a copy (use your SHARCNET credentials)

```sh
cd ~
git clone https://git.sharcnet.ca/nix/nixpkgs-sharcnet.git
```

If you already have a copy, you can update to the latest version

```sh
cd ~/nix-nixpkgs-sharcnet
git pull
```

# Using an expression

Once you have a copy of the expressions you can use `nix-env` to
install, update, or remove them from your environment.


## Installing an expression

To install (or update) a package pass the corresponding file (replace
*package.nix* in what follows) to `nix-env` using the `--file` option

```sh
nix-env --install --file package.nix
```

You can also copy or symlink the file into your *~/.nix-defexpr*
directory and then refer to it as a top-level attribute (replace
*package* with the base name of the copied file)

```sh
nix-env --install --attr package
```

## Removing

To remove a package you first need to figure out its name (generally,
but not necessarily, the same as the name of the Nix expression file)

```sh
nix-env --query
```

Then you (replace *package* with the package name)

```sh
nix-env --uninstall package
```

## Reverting

To undo the last install/update/remove command

```sh
nix-env --rollback
```

# Creating an expression

The best way to create a new package is to pillage existing package
expressions.  This includes the ones in [this
repository](https://git.sharcnet.ca/nix/nixpkgs-sharcnet) (click the
repository tab to see the files) and all the various [upstream
ones](https://git.sharcnet.ca/nix/nixpkgs-sharcnet/tree/master) (click
on a package and then following the Nix expression link).  The
[packaging manual](https://nixos.org/nixpkgs/manual/) details all the
various options you will see in these files.

## Building

A package can be build by running (replace *file.nix* with the name of
your file)


```sh
nix-build file.nix
```

If the build succeeds, the output will be symlinked into
the current directory as *result*.

## Debugging a build

A simulated build environment can be entered by running (replace
*file.nix* with the name of your file)

```sh
nix-shell --pure file.nix
```

which gives you a shell in the build environment described by the
epxression.  The default build and install locations need to be
overriden to somewhere you have write permission (this uses */tmp*)


```sh
NIX_BUILD_TOP=/tmp/nix-$USER

mkdir "$NIX_BUILD_TOP"
cd "$NIX_BUILD_TOP"
mkdir out
out=$PWD/out
prefix=$out
```

Then you can invoke the standard nix build phases and use the fact
that you are in a shell to diagnose whatever goes wrong (setting
`NIX_ENFORCE_PURITY` enables various checks along the way to ensure no
host bits get into the results as these would not be available in the
real sandboxed build)


```
export NIX_ENFORCE_PURITY=1

unpackPhase
cd "$sourceRoot"

configurePhase
buildPhase
installPhase
```