mirror of
https://github.com/nmattia/niv.git
synced 2024-11-07 22:36:53 +03:00
Merge pull request #16 from nmattia/nm-use-cases
Add use cases to README
This commit is contained in:
Nicolas Mattia
GitHub
commit
72e7720454
162
README.md
162
README.md
@ -2,8 +2,8 @@
|
||||
|
||||
[](https://circleci.com/gh/nmattia/niv)
|
||||
|
||||
A tool for dealing with third-party packages in [Nix]. Read more about it in
|
||||
the [usage](#usage) section.
|
||||
Painless dependencies for [Nix] projects. Read more in the [use case
|
||||
section](#use-cases) section below.
|
||||
|
||||
## Install
|
||||
|
||||
@ -39,6 +39,152 @@ necessary for fetching and updating the packages.
|
||||
`nix/sources.nix` file that returns the sources as a Nix object.
|
||||
* [Show](#show): shows the packages' information.
|
||||
|
||||
The next two sections cover [common use cases](#use-cases) and [full command
|
||||
description](#commands).
|
||||
|
||||
### Use cases
|
||||
|
||||
This section covers common use cases:
|
||||
|
||||
* [Bootstrapping a Nix project](#bootstrapping-a-nix-project).
|
||||
* [Tracking a different a different nixpkgs branch](#tracking-a-nixpkgs-branch).
|
||||
* [Importing packages from GitHub](#importing-packages-from-github).
|
||||
* [Fetching packages from custom URLs](#using-custom-urls).
|
||||
|
||||
#### Bootstrapping a Nix project
|
||||
|
||||
There is an `init` command that is useful when starting a new Nix project or
|
||||
when porting an existing Nix project to the niv versioning:
|
||||
|
||||
``` shell
|
||||
$ niv init
|
||||
...
|
||||
$ tree
|
||||
.
|
||||
├── default.nix
|
||||
├── nix
|
||||
│ ├── default.nix
|
||||
│ ├── packages.nix
|
||||
│ ├── sources.json
|
||||
│ └── sources.nix
|
||||
└── shell.nix
|
||||
|
||||
1 directory, 6 files
|
||||
```
|
||||
|
||||
The file `nix/sources.json` is the file used by niv to store versions and is
|
||||
initialized with niv and nixpkgs:
|
||||
|
||||
``` json
|
||||
{
|
||||
"nixpkgs": {
|
||||
"url": "https://github.com/NixOS/nixpkgs-channels/archive/....tar.gz",
|
||||
"owner": "NixOS",
|
||||
"branch": "nixos-18.09",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "nixpkgs-channels",
|
||||
"sha256": "...",
|
||||
"description": "Nixpkgs/NixOS branches that track the Nixpkgs/NixOS channels",
|
||||
"rev": "..."
|
||||
},
|
||||
"niv": {
|
||||
"homepage": "https://github.com/nmattia/niv",
|
||||
"url": "https://github.com/nmattia/niv/archive/....tar.gz",
|
||||
"owner": "nmattia",
|
||||
"branch": "master",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "niv",
|
||||
"sha256": "...",
|
||||
"description": "Manager for third-party packages in Nix",
|
||||
"rev": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The content of this file can be used from Nix by importing `nix/sources.nix` as
|
||||
done in the generated `nix/default.nix` file:
|
||||
|
||||
``` nix
|
||||
{ sources ? import ./sources.nix }:
|
||||
with
|
||||
{ overlay = _: pkgs:
|
||||
{ inherit (import sources.niv {}) niv;
|
||||
packages = pkgs.callPackages ./packages.nix {};
|
||||
};
|
||||
};
|
||||
import sources.nixpkgs
|
||||
{ overlays = [ overlay ] ; config = {}; }
|
||||
```
|
||||
|
||||
The files `default.nix`, `shell.nix` and `nix/packages.nix` are placeholders
|
||||
for your project.
|
||||
|
||||
#### 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 this commit to track
|
||||
update to the latest commit:
|
||||
|
||||
``` shell
|
||||
$ niv update nixpkgs
|
||||
```
|
||||
|
||||
To change the branch being tracked run this command:
|
||||
|
||||
``` shell
|
||||
$ 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:
|
||||
|
||||
|
||||
``` shell
|
||||
$ niv add stedolan/jq
|
||||
```
|
||||
|
||||
The following data was added in `nix/sources.json` for `jq`:
|
||||
|
||||
``` json
|
||||
{
|
||||
"homepage": "http://stedolan.github.io/jq/",
|
||||
"url": "https://github.com/stedolan/jq/archive/....tar.gz",
|
||||
"owner": "stedolan",
|
||||
"branch": "master",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "jq",
|
||||
"sha256": "...",
|
||||
"description": "Command-line JSON processor",
|
||||
"rev": "..."
|
||||
}
|
||||
```
|
||||
|
||||
#### 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`:
|
||||
|
||||
``` shell
|
||||
$ 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](#add) and [update](#update)).
|
||||
|
||||
For updating the version of GHC used run this command:
|
||||
|
||||
``` shell
|
||||
$ niv update ghc -v 8.6.2
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```
|
||||
NIV - Version manager for Nix projects
|
||||
|
||||
@ -57,7 +203,7 @@ Available commands:
|
||||
|
||||
```
|
||||
|
||||
### Add
|
||||
#### Add
|
||||
|
||||
```
|
||||
Examples:
|
||||
@ -84,7 +230,7 @@ Available options:
|
||||
|
||||
```
|
||||
|
||||
### Update
|
||||
#### Update
|
||||
|
||||
```
|
||||
Examples:
|
||||
@ -110,7 +256,7 @@ Available options:
|
||||
|
||||
```
|
||||
|
||||
### Drop
|
||||
#### Drop
|
||||
|
||||
```
|
||||
Examples:
|
||||
@ -126,7 +272,7 @@ Available options:
|
||||
|
||||
```
|
||||
|
||||
### Init
|
||||
#### Init
|
||||
|
||||
```
|
||||
Usage: niv init
|
||||
@ -137,7 +283,7 @@ Available options:
|
||||
|
||||
```
|
||||
|
||||
### show
|
||||
#### show
|
||||
|
||||
```
|
||||
Usage: niv show
|
||||
@ -148,3 +294,5 @@ Available options:
|
||||
```
|
||||
|
||||
[Nix]: https://nixos.org/nix/
|
||||
[jq]: https://stedolan.github.io/jq/
|
||||
[GHC]: https://www.haskell.org/ghc/
|
||||
|
||||
162
README.tpl.md
162
README.tpl.md
@ -2,8 +2,8 @@
|
||||
|
||||
[](https://circleci.com/gh/nmattia/niv)
|
||||
|
||||
A tool for dealing with third-party packages in [Nix]. Read more about it in
|
||||
the [usage](#usage) section.
|
||||
Painless dependencies for [Nix] projects. Read more in the [use case
|
||||
section](#use-cases) section below.
|
||||
|
||||
## Install
|
||||
|
||||
@ -39,38 +39,186 @@ necessary for fetching and updating the packages.
|
||||
`nix/sources.nix` file that returns the sources as a Nix object.
|
||||
* [Show](#show): shows the packages' information.
|
||||
|
||||
The next two sections cover [common use cases](#use-cases) and [full command
|
||||
description](#commands).
|
||||
|
||||
### Use cases
|
||||
|
||||
This section covers common use cases:
|
||||
|
||||
* [Bootstrapping a Nix project](#bootstrapping-a-nix-project).
|
||||
* [Tracking a different a different nixpkgs branch](#tracking-a-nixpkgs-branch).
|
||||
* [Importing packages from GitHub](#importing-packages-from-github).
|
||||
* [Fetching packages from custom URLs](#using-custom-urls).
|
||||
|
||||
#### Bootstrapping a Nix project
|
||||
|
||||
There is an `init` command that is useful when starting a new Nix project or
|
||||
when porting an existing Nix project to the niv versioning:
|
||||
|
||||
``` shell
|
||||
$ niv init
|
||||
...
|
||||
$ tree
|
||||
.
|
||||
├── default.nix
|
||||
├── nix
|
||||
│ ├── default.nix
|
||||
│ ├── packages.nix
|
||||
│ ├── sources.json
|
||||
│ └── sources.nix
|
||||
└── shell.nix
|
||||
|
||||
1 directory, 6 files
|
||||
```
|
||||
|
||||
The file `nix/sources.json` is the file used by niv to store versions and is
|
||||
initialized with niv and nixpkgs:
|
||||
|
||||
``` json
|
||||
{
|
||||
"nixpkgs": {
|
||||
"url": "https://github.com/NixOS/nixpkgs-channels/archive/....tar.gz",
|
||||
"owner": "NixOS",
|
||||
"branch": "nixos-18.09",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "nixpkgs-channels",
|
||||
"sha256": "...",
|
||||
"description": "Nixpkgs/NixOS branches that track the Nixpkgs/NixOS channels",
|
||||
"rev": "..."
|
||||
},
|
||||
"niv": {
|
||||
"homepage": "https://github.com/nmattia/niv",
|
||||
"url": "https://github.com/nmattia/niv/archive/....tar.gz",
|
||||
"owner": "nmattia",
|
||||
"branch": "master",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "niv",
|
||||
"sha256": "...",
|
||||
"description": "Manager for third-party packages in Nix",
|
||||
"rev": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The content of this file can be used from Nix by importing `nix/sources.nix` as
|
||||
done in the generated `nix/default.nix` file:
|
||||
|
||||
``` nix
|
||||
{ sources ? import ./sources.nix }:
|
||||
with
|
||||
{ overlay = _: pkgs:
|
||||
{ inherit (import sources.niv {}) niv;
|
||||
packages = pkgs.callPackages ./packages.nix {};
|
||||
};
|
||||
};
|
||||
import sources.nixpkgs
|
||||
{ overlays = [ overlay ] ; config = {}; }
|
||||
```
|
||||
|
||||
The files `default.nix`, `shell.nix` and `nix/packages.nix` are placeholders
|
||||
for your project.
|
||||
|
||||
#### 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 this commit to track
|
||||
update to the latest commit:
|
||||
|
||||
``` shell
|
||||
$ niv update nixpkgs
|
||||
```
|
||||
|
||||
To change the branch being tracked run this command:
|
||||
|
||||
``` shell
|
||||
$ 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:
|
||||
|
||||
|
||||
``` shell
|
||||
$ niv add stedolan/jq
|
||||
```
|
||||
|
||||
The following data was added in `nix/sources.json` for `jq`:
|
||||
|
||||
``` json
|
||||
{
|
||||
"homepage": "http://stedolan.github.io/jq/",
|
||||
"url": "https://github.com/stedolan/jq/archive/....tar.gz",
|
||||
"owner": "stedolan",
|
||||
"branch": "master",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
|
||||
"repo": "jq",
|
||||
"sha256": "...",
|
||||
"description": "Command-line JSON processor",
|
||||
"rev": "..."
|
||||
}
|
||||
```
|
||||
|
||||
#### 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`:
|
||||
|
||||
``` shell
|
||||
$ 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](#add) and [update](#update)).
|
||||
|
||||
For updating the version of GHC used run this command:
|
||||
|
||||
``` shell
|
||||
$ niv update ghc -v 8.6.2
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```
|
||||
replace_niv_help
|
||||
```
|
||||
|
||||
### Add
|
||||
#### Add
|
||||
|
||||
```
|
||||
replace_niv_add_help
|
||||
```
|
||||
|
||||
### Update
|
||||
#### Update
|
||||
|
||||
```
|
||||
replace_niv_update_help
|
||||
```
|
||||
|
||||
### Drop
|
||||
#### Drop
|
||||
|
||||
```
|
||||
replace_niv_drop_help
|
||||
```
|
||||
|
||||
### Init
|
||||
#### Init
|
||||
|
||||
```
|
||||
replace_niv_init_help
|
||||
```
|
||||
|
||||
### show
|
||||
#### show
|
||||
|
||||
```
|
||||
replace_niv_show_help
|
||||
```
|
||||
|
||||
[Nix]: https://nixos.org/nix/
|
||||
[jq]: https://stedolan.github.io/jq/
|
||||
[GHC]: https://www.haskell.org/ghc/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user