# rules_nixpkgs
[](https://circleci.com/gh/tweag/rules_nixpkgs)
Rules for importing Nixpkgs packages into Bazel.
## Rules
* [nixpkgs_git_repository](#nixpkgs_git_repository)
* [nixpkgs_package](#nixpkgs_package)
## Setup
Add the following to your `WORKSPACE` file, and select a `$COMMIT` accordingly.
```bzl
http_archive(
name = "io_tweag_rules_nixpkgs",
strip_prefix = "rules_nixpkgs-$COMMIT",
urls = ["https://github.com/tweag/rules_nixpkgs/archive/$COMMIT.tar.gz"],
)
load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_git_repository", "nixpkgs_package")
```
## Example
```bzl
nixpkgs_git_repository(
name = "nixpkgs",
revision = "17.09", # Any tag or commit hash
sha256 = "" # optional sha to verify package integrity!
)
nixpkgs_package(
name = "hello",
repositories = { "nixpkgs": "@nixpkgs//:default.nix" }
)
```
## Rules
### nixpkgs_git_repository
Name a specific revision of Nixpkgs on GitHub or a local checkout.
```bzl
nixpkgs_git_repository(name, revision, sha256)
```
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>
<p><code>Name; required</code></p>
<p>A unique name for this repository.</p>
</td>
</tr>
<tr>
<td><code>revision</code></td>
<td>
<p><code>String; required</code></p>
<p>Git commit hash or tag identifying the version of Nixpkgs
to use.</p>
</td>
</tr>
<tr>
<td><code>remote</code></td>
<td>
<p><code>String; optional</code></p>
<p>The URI of the remote Git repository. This must be a HTTP
URL. There is currently no support for authentication.
Defaults to <a href="https://github.com/NixOS/nixpkgs">
upstream nixpkgs.</a></p>
</td>
</tr>
<tr>
<td><code>sha256</code></td>
<td>
<p><code>String; optional</code></p>
<p>The SHA256 used to verify the integrity of the repository.</p>
</td>
</tr>
</tbody>
</table>
### nixpkgs_local_repository
Create an external repository representing the content of Nixpkgs,
based on a Nix expression stored locally or provided inline. One of
`nix_file` or `nix_file_content` must be provided.
```bzl
nixpkgs_local_repository(name, nix_file, nix_file_deps, nix_file_content)
```
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>
<p><code>Name; required</code></p>
<p>A unique name for this repository.</p>
</td>
</tr>
<tr>
<td><code>nix_file</code></td>
<td>
<p><code>String; optional</code></p>
<p>A file containing an expression for a Nix derivation.</p>
</td>
</tr>
<tr>
<td><code>nix_file_deps</code></td>
<td>
<p><code>List of labels; optional</code></p>
<p>Dependencies of `nix_file` if any.</p>
</td>
</tr>
<tr>
<td><code>nix_file_content</code></td>
<td>
<p><code>String; optional</code></p>
<p>An expression for a Nix derivation.</p>
</td>
</tr>
</tbody>
</table>
### nixpkgs_package
Make the content of a Nixpkgs package available in the Bazel workspace.
```bzl
nixpkgs_package(
name, attribute_path, nix_file, nix_file_deps, nix_file_content,
repository, repositories, build_file, build_file_content, nixopts,
fail_not_supported,
)
```
If `repositories` is not specified, you must provide a
nixpkgs clone in `nix_file` or `nix_file_content`.
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>
<p><code>Name; required</code></p>
<p>A unique name for this target</p>
</td>
</tr>
<tr>
<td><code>attribute_path</code></td>
<td>
<p><code>String; optional</code></p>
<p>Select an attribute from the top-level Nix expression being
evaluated. The attribute path is a sequence of attribute
names separated by dots.</p>
</td>
</tr>
<tr>
<td><code>nix_file</code></td>
<td>
<p><code>String; optional</code></p>
<p>A file containing an expression for a Nix derivation.</p>
</td>
</tr>
<tr>
<td><code>nix_file_deps</code></td>
<td>
<p><code>List of labels; optional</code></p>
<p>Dependencies of `nix_file` if any.</p>
</td>
</tr>
<tr>
<td><code>nix_file_content</code></td>
<td>
<p><code>String; optional</code></p>
<p>An expression for a Nix derivation.</p>
</td>
</tr>
<tr>
<td><code>repository</code></td>
<td>
<p><code>Label; optional</code></p>
<p>A repository label identifying which Nixpkgs to use.
Equivalent to `repositories = { "nixpkgs": ...}`</p>
</td>
</tr>
<tr>
<td><code>repositories</code></td>
<td>
<p><code>String-keyed label dict; optional</code></p>
<p>A dictionary mapping `NIX_PATH` entries to repository labels.</p>
<p>Setting it to
<pre><code>repositories = { "myrepo" : "//:myrepo" }</code></pre>
for example would replace all instances
of <code><myrepo></code> in the called nix code by the
path to the target <code>"//:myrepo"</code>. See the
<a href="https://nixos.org/nix/manual/#env-NIX_PATH">relevant
section in the nix manual</a> for more information.</p>
<p>Specify one of `path` or `repositories`.</p>
</td>
</tr>
<tr>
<td><code>build_file</code></td>
<td>
<p><code>Label; optional</code></p>
<p>The file to use as the BUILD file for this repository.
Its contents are copied copied into the file
<code>BUILD</code> in root of the nix output folder.
The Label does not need to be named BUILD, but can be.
</p>
<p>For common use cases we provide filegroups that expose
certain files as targets:
<dl>
<dt><code>:bin</code></dt>
<dd>Everything in the <code>bin/</code> directory.</dd>
<dt><code>:lib</code></dt>
<dd>All <code>.so</code> and <code>.a</code> files
that can be found in subdirectories of
<code>lib/</code>.</dd>
<dt><code>:include</code></dt>
<dd>All <code>.h</code> files
that can be found in subdirectories of
<code>bin/</code>.</dd>
</dl>
</p>
<p>If you need different files from the nix package,
you can reference them like this: <pre><code>package(default_visibility = [ "//visibility:public" ])
filegroup(
name = "our-docs",
srcs = glob(["share/doc/ourpackage/**/*"]),
)</code></pre>
See the bazel documentation of
<a href="https://docs.bazel.build/versions/master/be/general.html#filegroup">filegroup</a>
and
<a href="https://docs.bazel.build/versions/master/be/functions.html#glob">glob</a>.
</p>
</td>
</tr>
<tr>
<td><code>build_file_content</code></td>
<td>
<p><code>String; optional</code></p>
<p>Like <code>build_file</code>, but a string of the contents
instead of a file name.</p>
</td>
</tr>
<tr>
<td><code>nixopts</code></td>
<td>
<p><code>String list; optional</code></p>
<p>Extra flags to pass when calling Nix.</p>
</td>
</tr>
<tr>
<td><code>fail_not_supported</code></td>
<td>
<p><code>Boolean; optional; default = True</code></p>
<p>
If set to <code>True</code> (default) this rule will fail on
platforms which do not support Nix (e.g. Windows). If set to
<code>False</code> calling this rule will succeed but no output
will be generated.
</p>
</td>
</tr>
</tbody>
</table>
### nixpkgs_cc_configure
Tells Bazel to use compilers and linkers from Nixpkgs for the CC
toolchain. By default, Bazel autodetects a toolchain on the current
`PATH`. Overriding this autodetection makes builds more hermetic and
is considered a best practice.
Example:
```bzl
nixpkgs_cc_configure(repository = "@nixpkgs//:default.nix")
```
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>nix_file</code></td>
<td>
<p><code>String; optional</code></p>
<p>An expression for a Nix environment derivation. The
environment should expose all the commands that make up
a CC toolchain (`cc`, `ld` etc). Exposes all commands in
`stdenv.cc` and `binutils` by default.</p>
</td>
</tr>
<tr>
<td><code>nix_file_deps</code></td>
<td>
<p><code>List of labels; optional</code></p>
<p>Dependencies of `nix_file` if any.</p>
</td>
</tr>
<tr>
<td><code>nix_file_content</code></td>
<td>
<p><code>String; optional</code></p>
<p>An expression for a Nix environment derivation.</p>
</td>
</tr>
<tr>
<td><code>repository</code></td>
<td>
<p><code>Label; optional</code></p>
<p>A repository label identifying which Nixpkgs to use.
Equivalent to `repositories = { "nixpkgs": ...}`</p>
</td>
</tr>
<tr>
<td><code>repositories</code></td>
<td>
<p><code>String-keyed label dict; optional</code></p>
<p>A dictionary mapping `NIX_PATH` entries to repository labels.</p>
<p>Setting it to
<pre><code>repositories = { "myrepo" : "//:myrepo" }</code></pre>
for example would replace all instances
of <code><myrepo></code> in the called nix code by the
path to the target <code>"//:myrepo"</code>. See the
<a href="https://nixos.org/nix/manual/#env-NIX_PATH">relevant
section in the nix manual</a> for more information.</p>
<p>Specify one of `path` or `repositories`.</p>
</td>
</tr>
</tbody>
</table>
## Migration
### `path` Attribute
`path` was an attribute from the early days of `rules_nixpkgs`, and
its ability to reference arbitrary paths a danger to build hermeticity.
Replace it with either `nixpkgs_git_repository` if you need
a specific version of `nixpkgs`. If you absolutely *must* depend on a
local folder, use bazel’s
[`local_repository` workspace rule](https://docs.bazel.build/versions/master/be/workspace.html#local_repository).
Both approaches work well with the `repositories` attribute of `nixpkgs_package`.
```bzl
local_repository(
name = "local-nixpkgs",
path = "/path/to/nixpkgs",
)
nixpkgs_package(
name = "somepackage",
repositories = {
"nixpkgs": "@local-nixpkgs//:default.nix",
},
…
)
```
