niv: Easy dependency management for Nix projects

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

Easy dependency management for Nix projects.


[Skip to Readme]

Properties

Versions 0.1.0, 0.1.0, 0.1.1, 0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 0.2.6, 0.2.7, 0.2.8, 0.2.9, 0.2.10, 0.2.11, 0.2.12, 0.2.13, 0.2.14, 0.2.15, 0.2.16, 0.2.17, 0.2.18, 0.2.19, 0.2.20, 0.2.21, 0.2.22
Change log None available
Dependencies aeson, aeson-pretty, base (<5), bytestring, directory, file-embed, filepath, github, hashable, mtl, niv, optparse-applicative, process, string-qq, tasty, tasty-hunit, text, unliftio, unordered-containers [details]
License MIT
Copyright (c) 2019 Nicolas Mattia
Author Nicolas Mattia <nicolas@nmattia.com>
Maintainer Nicolas Mattia <nicolas@nmattia.com>
Category Development
Home page https://github.com/deckgo/wai-lambda#readme
Bug tracker https://github.com/deckgo/wai-lambda/issues
Source repo head: git clone https://github.com/deckgo/wai-lambda
Uploaded by nmattia at 2019-06-18T08:23:00Z

Modules

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for niv-0.1.0

[back to package description]

niv

CircleCI Netlify Status

Painless dependencies for Nix projects. Read more in the Getting started section below.

Install

$ nix-env -iA niv -f https://github.com/nmattia/niv/tarball/master

Build

Inside the provided nix shell:

$ repl

Run the test suite with this command:

$ ./script/test

Usage

niv simplifies adding and updating dependencies in Nix projects. It uses a single file, nix/sources.json, where it stores the data necessary for fetching and updating the packages.

niv has two more utility functions:

The next two sections cover common use cases and full command description.

Getting started

This section covers common use cases:

Bootstrapping a Nix project

Use the init command when starting a new Nix project or when porting an existing Nix project to niv:

$ niv init
...
$ tree
.
└── nix
    ├── sources.json
    └── sources.nix

1 directory, 2 files

The file nix/sources.json is the file used by niv to store versions and is initialized with niv and nixpkgs:

{
    "nixpkgs": {
        "url": "https://github.com/NixOS/nixpkgs-channels/archive/109a28ab954a0ad129f7621d468f829981b8b96c.tar.gz",
        "owner": "NixOS",
        "branch": "nixos-18.09",
        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
        "repo": "nixpkgs-channels",
        "sha256": "12wnxla7ld4cgpdndaipdh3j4zdalifk287ihxhnmrzrghjahs3q",
        "description": "Nixpkgs/NixOS branches that track the Nixpkgs/NixOS channels",
        "rev": "109a28ab954a0ad129f7621d468f829981b8b96c"
    },
    "niv": {
        "homepage": "https://github.com/nmattia/niv",
        "url": "https://github.com/nmattia/niv/archive/72e77204544527279e8f1e2d982d29503482b8f4.tar.gz",
        "owner": "nmattia",
        "branch": "master",
        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
        "repo": "niv",
        "sha256": "1zjcyzxhq9iwxh58j5d7sx1vz5s3r1f6gpmnfgj2a3rxmclwvn3c",
        "description": "Easy dependency management for Nix projects",
        "rev": "72e77204544527279e8f1e2d982d29503482b8f4"
    }
}

To use those dependencies import the file nix/sources.nix, e.g.:

{ sources ? import ./sources.nix }:     # import the sources
with
  { overlay = _: pkgs:
      { niv = import sources.niv {};    # use the sources :)
      };
  };
import sources.nixpkgs                  # and use them again!
  { overlays = [ overlay ] ; config = {}; }

Tracking a nixpkgs branch

The init command sets the nix/sources.json file to track the latest commit present on nixpkgs 18.09 when the command was run. Run the following command to update it:

$ niv update nixpkgs

To change the branch being tracked run this command:

$ niv update nixpkgs -b nixos-19.03     # equivalent to --branch nixos-19.03

Importing packages from GitHub

The add command will infer information about the package being added, when possible. This works very well for GitHub repositories. Run this command to add jq to your project:

$ niv add stedolan/jq

The following data was added in nix/sources.json for jq:

{
  "homepage": "http://stedolan.github.io/jq/",
  "url": "https://github.com/stedolan/jq/archive/9fa2e51099c55af56e3e541dc4b399f11de74abe.tar.gz",
  "owner": "stedolan",
  "branch": "master",
  "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
  "repo": "jq",
  "sha256": "0819rvk8057qgcqvgn7fpldvly2pfdw9fxcjrlqa8gr59p8a1cic",
  "description": "Command-line JSON processor",
  "rev": "9fa2e51099c55af56e3e541dc4b399f11de74abe"
}

Using custom URLs

It is possible to use niv to fetch packages from custom URLs. Run this command to add the Haskell compiler GHC to your nix/sources.json:

$ niv add ghc   \
    -v 8.4.3    \
    -t 'https://downloads.haskell.org/~ghc/<version>/ghc-<version>-i386-deb8-linux.tar.xz'

The option -v sets the "version" attribute to 8.4.3. The option -t sets a template that can be reused by niv when fetching a new URL (see the documentation for add and update).

For updating the version of GHC used run this command:

$ niv update ghc -v 8.6.2

Commands

NIV - Version manager for Nix projects

Usage: niv COMMAND

Available options:
  -h,--help                Show this help text

Available commands:
  init                     Initialize a Nix project. Existing files won't be
                           modified.
  add                      Add dependency
  show                     
  update                   Update dependencies
  modify                   Modify dependency
  drop                     Drop dependency

Add

Examples:

  niv add stedolan/jq
  niv add NixOS/nixpkgs-channels -n nixpkgs -b nixos-18.09
  niv add my-package -v alpha-0.1 -t http://example.com/archive/<version>.zip

Usage: niv add [-n|--name NAME] PACKAGE ([-a|--attribute KEY=VAL] |
               [-b|--branch BRANCH] | [-o|--owner OWNER] | [-r|--repo REPO] |
               [-v|--version VERSION] | [-t|--template URL] | [-T|--type TYPE])
  Add dependency

Available options:
  -n,--name NAME           Set the package name to <NAME>
  -a,--attribute KEY=VAL   Set the package spec attribute <KEY> to <VAL>
  -b,--branch BRANCH       Equivalent to --attribute branch=<BRANCH>
  -o,--owner OWNER         Equivalent to --attribute owner=<OWNER>
  -r,--repo REPO           Equivalent to --attribute repo=<REPO>
  -v,--version VERSION     Equivalent to --attribute version=<VERSION>
  -t,--template URL        Used during 'update' when building URL. Occurrences
                           of <foo> are replaced with attribute 'foo'.
  -T,--type TYPE           The type of the URL target. The value can be either
                           'file' or 'tarball'. If not set, the value is
                           inferred from the suffix of the URL.
  -h,--help                Show this help text

Update

Examples:

  niv update
  niv update nixpkgs
  niv update my-package -v beta-0.2

Usage: niv update [PACKAGE] ([-a|--attribute KEY=VAL] | [-b|--branch BRANCH] |
                  [-o|--owner OWNER] | [-r|--repo REPO] | [-v|--version VERSION]
                  | [-t|--template URL] | [-T|--type TYPE])
  Update dependencies

Available options:
  -a,--attribute KEY=VAL   Set the package spec attribute <KEY> to <VAL>
  -b,--branch BRANCH       Equivalent to --attribute branch=<BRANCH>
  -o,--owner OWNER         Equivalent to --attribute owner=<OWNER>
  -r,--repo REPO           Equivalent to --attribute repo=<REPO>
  -v,--version VERSION     Equivalent to --attribute version=<VERSION>
  -t,--template URL        Used during 'update' when building URL. Occurrences
                           of <foo> are replaced with attribute 'foo'.
  -T,--type TYPE           The type of the URL target. The value can be either
                           'file' or 'tarball'. If not set, the value is
                           inferred from the suffix of the URL.
  -h,--help                Show this help text

Drop

Examples:

  niv drop jq
  niv drop my-package version

Usage: niv drop PACKAGE [ATTRIBUTE]
  Drop dependency

Available options:
  -h,--help                Show this help text

Init

Usage: niv init 
  Initialize a Nix project. Existing files won't be modified.

Available options:
  -h,--help                Show this help text

show

Usage: niv show 

Available options:
  -h,--help                Show this help text