diff options
Diffstat (limited to 'third_party/bazel/rules_nixpkgs/README.md')
| -rw-r--r-- | third_party/bazel/rules_nixpkgs/README.md | 402 |
1 files changed, 0 insertions, 402 deletions
diff --git a/third_party/bazel/rules_nixpkgs/README.md b/third_party/bazel/rules_nixpkgs/README.md deleted file mode 100644 index 6e967babdfc8..000000000000 --- a/third_party/bazel/rules_nixpkgs/README.md +++ /dev/null @@ -1,402 +0,0 @@ -# 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", - }, - … -) -``` |