Update rules_nixpkgs docs

tweag · Dec 10, 2021 · b3d8024 · b3d8024
1 parent 0c4cee9
commit b3d8024
Show file tree

Hide file tree

Showing 3 changed files with 206 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,7 @@ Links:
 * [nixpkgs_package](#nixpkgs_package)
 * [nixpkgs_cc_configure](#nixpkgs_cc_configure)
 * [nixpkgs_cc_configure_deprecated](#nixpkgs_cc_configure_deprecated)
+* [nixpkgs_java_configure](#nixpkgs_java_configure)
 * [nixpkgs_python_configure](#nixpkgs_python_configure)
 * [nixpkgs_sh_posix_configure](#nixpkgs_sh_posix_configure)
 * [nixpkgs_go_configure](#nixpkgs_go_configure)
@@ -566,6 +567,209 @@ Options to forward to the nix command.
 </table>
 
 
+<a id="#nixpkgs_java_configure"></a>
+
+### nixpkgs_java_configure
+
+<pre>
+nixpkgs_java_configure(<a href="#nixpkgs_java_configure-name">name</a>, <a href="#nixpkgs_java_configure-attribute_path">attribute_path</a>, <a href="#nixpkgs_java_configure-java_home_path">java_home_path</a>, <a href="#nixpkgs_java_configure-repository">repository</a>, <a href="#nixpkgs_java_configure-repositories">repositories</a>, <a href="#nixpkgs_java_configure-nix_file">nix_file</a>,
+                       <a href="#nixpkgs_java_configure-nix_file_content">nix_file_content</a>, <a href="#nixpkgs_java_configure-nix_file_deps">nix_file_deps</a>, <a href="#nixpkgs_java_configure-nixopts">nixopts</a>, <a href="#nixpkgs_java_configure-fail_not_supported">fail_not_supported</a>, <a href="#nixpkgs_java_configure-quiet">quiet</a>)
+</pre>
+
+Define a Java runtime provided by nixpkgs.
+
+Creates a `nixpkgs_package` for a `java_runtime` instance.
+Bazel can use this instance to run JVM binaries and tests, refer to the
+[Bazel documentation](https://docs.bazel.build/versions/4.0.0/bazel-and-java.html#configuring-the-jdk) for details.
+
+#### Example
+
+Add the following to your `WORKSPACE` file to import a JDK from nixpkgs:
+```bzl
+load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_java_configure")
+nixpkgs_java_configure(
+    attribute_path = "jdk11.home",
+    repository = "@nixpkgs",
+)
+```
+
+Add the following configuration to `.bazelrc` to enable this Java runtime:
+```
+build --javabase=@nixpkgs_java_runtime//:runtime
+build --host_javabase=@nixpkgs_java_runtime//:runtime
+# Adjust this to match the Java version provided by this runtime.
+# See `bazel query 'kind(java_toolchain, @bazel_tools//tools/jdk:all)'` for available options.
+build --java_toolchain=@bazel_tools//tools/jdk:toolchain_java11
+build --host_java_toolchain=@bazel_tools//tools/jdk:toolchain_java11
+```
+
+
+#### Parameters
+
+<table class="params-table">
+<colgroup>
+<col class="col-param" />
+<col class="col-description" />
+</colgroup>
+<tbody>
+<tr id="nixpkgs_java_configure-name">
+<td><code>name</code></td>
+<td>
+
+optional.
+default is <code>"nixpkgs_java_runtime"</code>
+
+<p>
+
+The name-prefix for the created external repositories.
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-attribute_path">
+<td><code>attribute_path</code></td>
+<td>
+
+optional.
+default is <code>None</code>
+
+<p>
+
+string, The nixpkgs attribute path for `jdk.home`.
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-java_home_path">
+<td><code>java_home_path</code></td>
+<td>
+
+optional.
+default is <code>""</code>
+
+<p>
+
+optional, string, The path to `JAVA_HOME` within the package.
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-repository">
+<td><code>repository</code></td>
+<td>
+
+optional.
+default is <code>None</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-repository).
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-repositories">
+<td><code>repositories</code></td>
+<td>
+
+optional.
+default is <code>{}</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-repositories).
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-nix_file">
+<td><code>nix_file</code></td>
+<td>
+
+optional.
+default is <code>None</code>
+
+<p>
+
+optional, Label, Obtain the runtime from the Nix expression defined in this file. Specify only one of `nix_file` or `nix_file_content`.
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-nix_file_content">
+<td><code>nix_file_content</code></td>
+<td>
+
+optional.
+default is <code>""</code>
+
+<p>
+
+optional, string, Obtain the runtime from the given Nix expression. Specify only one of `nix_file` or `nix_file_content`.
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-nix_file_deps">
+<td><code>nix_file_deps</code></td>
+<td>
+
+optional.
+default is <code>None</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-nix_file_deps).
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-nixopts">
+<td><code>nixopts</code></td>
+<td>
+
+optional.
+default is <code>[]</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-nixopts).
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-fail_not_supported">
+<td><code>fail_not_supported</code></td>
+<td>
+
+optional.
+default is <code>True</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-fail_not_supported).
+
+</p>
+</td>
+</tr>
+<tr id="nixpkgs_java_configure-quiet">
+<td><code>quiet</code></td>
+<td>
+
+optional.
+default is <code>False</code>
+
+<p>
+
+See [`nixpkgs_package`](#nixpkgs_package-quiet).
+
+</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+
 <a id="#nixpkgs_package"></a>
 
 ### nixpkgs_package

diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -10,6 +10,7 @@ stardoc(
         "nixpkgs_package",
         "nixpkgs_cc_configure",
         "nixpkgs_cc_configure_deprecated",
+        "nixpkgs_java_configure",
         "nixpkgs_python_configure",
         "nixpkgs_sh_posix_configure",
     ],

diff --git a/docs/README.md.tpl b/docs/README.md.tpl
@@ -28,6 +28,7 @@ Links:
 * [nixpkgs_package](#nixpkgs_package)
 * [nixpkgs_cc_configure](#nixpkgs_cc_configure)
 * [nixpkgs_cc_configure_deprecated](#nixpkgs_cc_configure_deprecated)
+* [nixpkgs_java_configure](#nixpkgs_java_configure)
 * [nixpkgs_python_configure](#nixpkgs_python_configure)
 * [nixpkgs_sh_posix_configure](#nixpkgs_sh_posix_configure)
 * [nixpkgs_go_configure](#nixpkgs_go_configure)