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, 402 insertions, 0 deletions
diff --git a/third_party/bazel/rules_nixpkgs/README.md b/third_party/bazel/rules_nixpkgs/README.md new file mode 100644 index 0000000000..6e967babdf --- /dev/null +++ b/third_party/bazel/rules_nixpkgs/README.md @@ -0,0 +1,402 @@ +# 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", + }, + … +) +``` |