Skip to content

Latest commit

 

History

History
132 lines (84 loc) · 6.7 KB

README.md.gup

File metadata and controls

132 lines (84 loc) · 6.7 KB
Raw

#!bash -eu set -o pipefail

vim: set syntax=markdown:

gup --always dest="$1" function include { echo >&2 "Including $1" gup -u "$1" echo 'bash' >> "$dest" cat "$1" >> "$dest" echo '' >> "$dest" }

echo '' > "$1"

set -x

cat >> "$dest" <<"EOF"

nix-wrangle is deprecated

nix-wrangle is featureful but somewhat complex to use and maintain. I've decided to use the more basic niv myself rather than maintaining nix-wrangle, I suggest others do the same.

Purpose:

Nix-wrangle aims to be a swiss-army knife for working with nix dependencies. It works best with dependencies that include their own nix derivations, although using it for fetching plain archives works too.

Goals:

  • Simple usage should be idiomatic and portable, with no specific references to nix-wrangle's API
  • Keeping sources updated (and seeing their current state) should be trivial
  • Support local development across multiple related repositories

Get it:

EOF include example/00-bootstrap cat >> "$dest" <<"EOF"

Basic functionality:

nix-wrangle maintains a set of sources, which are typically dependencies. The following example shows the basic setup:

EOF include example/01-setup cat >> "$dest" <<"EOF"

Note that the piep dependency is built (by using pkgs.callPackage on the nix path within the source), which gives you the actual derivation, not simply the source code. This is one important difference compared to niv.

Sources are typically used for project dependencies, but there are three special sources:

  • 'nix-wrangle': (added automatically) used for bootstrapping in 'default.nix'
  • 'self': used to override the toplevel derivation's 'src' attribute when building 'default.nix'. Automatically added by nix-wrangle init as a git-local source if there's a .git directory present.
  • 'pkgs': (optional) used to pin the exact version of 'nixpkgs'. Added automatically by nix-wrangle init if you pass --pkgs nixpkgs-unstable (or any other branch name from https://github.com/NixOS/nixpkgs-channels)

Features:

Nix-wrangle is purpose built to solve a range of specific use cases which come up when developing with nix:

Update from specification

e.g. when using a git-based dependency, you can specify a branch instead of a specific commit. When you update, that branch will be re-resolved:

EOF include example/02-update cat >> "$dest" <<"EOF"

You can also make use of templating, e.g. for a URL dependency you can use the URL 'http://example.com/libfoo/libfoo-<version>.tgz'. When updating, you can pass --version NEW_VERSION to update it.

'src' injection

When building, a self dependency (if present) will be used to provide the src for the toplevel derivation. This lets you use nix-wrangle's various source types (e.g git-local, which isn't available as a nixpkgs builtin) and automatic generation (e.g. sha256 digests).

nix-wrangle will also inject the relevant src into each of your dependencies. Let's say you import commit x of the piep dependency, with a nix expression in it. It would be impossible for commit x of piep to refer to commit x as its src attribute. The best it could do is to refer to the parent of commit x, although it may often just refer to the most recently released version. Both of these would be counter-productive - you'd be importing the derivation at x, but building source code from some other version out of your control. nix-wrangle automatically overrides the src of imported dependencies so that the version you import is also the source code you build.

Local overrides

When working on both a library and an application that uses it, it's common to want to try out working changes before publishing them. This is easy with local sources:

EOF include example/03-local-override cat >> "$dest" <<"EOF"

This uses the local version of a dependency for building, but kept separate from the "public" version of your dependency specificaion.

Splicing src to produce a self-contained derivation

nix-wrangle was built so that your base derivation (nix/default.nix) can be idiomatic - it doesn't need to reference nix-wrangle at all, and its dependencies are injected as arguments, just like regular derivations in nixpkgs. The one way in which they aren't idiomatic is the src attribute, since in nixpkgs this typically refers to a remote repository or tarball.

So there's also the splice command. This injects the current value of a fetched source (defaulting to public) into an existing nix file to create a self-contained derivation. This is perfect for promoting your in-tree derivation (with source provided by nix-wrangle) into a derivation suitable for inclusion in nixpkgs, where it includes its own src and all dependencies are provided by the caller.

EOF include example/04-splice cat >> "$dest" <<"EOF"

Source types

  • url: any archive URL. May contain <version> which is resolved on update.
  • git: takes a url and rev (which can be a branch, tag or commit). rev is resolved to a concrete commit on initial add, and on update.
  • github: takes an owner, repo and rev (as for git)
  • git-local: takes a path (can be relative) and an optional rev (can be a branch, tag or HEAD). rev is resolved at evaluation time. If rev is not provided, you'll get the working changes in the given workspace (but not any excluded or untracked files).
  • path: path (can be relative or absolute)

Hacking

There are two options for development:

From within 'nix-shell', use 'cabal v1-build'

Alternatively, from within 'nix-shell -p haskellPackages.cabal-install' you can use 'cabal new-build'. This bypasses the nix infrastructure entirely and fetches its own copy of dependencies, but may be convenient when adjusting packages or pinning dependencies to specific versions.

Similar tools

niv:

nix-wrangle was heavily inspired by niv (the command line tool was even based off the niv source code). The main differences are:

  • nix-wrangle dependencies are derivations, not just source code.
  • nix-wrangle attempts to let you write idiomatic nix without explicitly referencing any files or functions provided by nix-wrangle.
  • nix-wrangle has a number of extra features not provided by niv: splice, self injection and local overlays.
  • nix-wrangle is more featureful, but also more complex

nix-flakes:

nix-wrangle (like niv) is similar in spirit to nix flakes, but there's no actual implementation of flakes yet. My hope is that any standard solution would be able to support nix-wrangle style workflows.

EOF