crate_universe: Improved documentation (#1305)
* crate_universe: updated documentation
* crate_universe: added dependencies API to docs
* Regenerate documentation
* Update crate_universe/docs.bzl
Co-authored-by: Daniel Wagner-Hall <dawagner@gmail.com>
* Regenerate documentation
Co-authored-by: Daniel Wagner-Hall <dawagner@gmail.com>
diff --git a/crate_universe/BUILD.bazel b/crate_universe/BUILD.bazel
index 523e325..ae5baa8 100644
--- a/crate_universe/BUILD.bazel
+++ b/crate_universe/BUILD.bazel
@@ -9,6 +9,7 @@
"Cargo.lock",
"Cargo.Bazel.lock",
"defs.bzl",
+ "docs.bzl",
],
visibility = ["//visibility:public"],
)
diff --git a/crate_universe/defs.bzl b/crate_universe/defs.bzl
index 80c1d06..095e264 100644
--- a/crate_universe/defs.bzl
+++ b/crate_universe/defs.bzl
@@ -1,171 +1,5 @@
-"""# Crate Universe
+"""Crate Universe rules"""
-Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
-
-## Experimental
-
-`crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
-
-## Setup
-
-After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
-
-```python
-load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
-
-crate_universe_dependencies()
-```
-
-Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
-flags such as [`bootstrap = True`](#crate_universe_dependencies-bootstrap) on the `crate_universe_dependencies`
-call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
-
-## Rules
-
-- [crates_repository](#crates_repository)
-- [crates_vendor](#crates_vendor)
-
-## Utility Macros
-
-- [crate_universe_dependencies](#crate_universe_dependencies)
-- [crate.annotation](#crateannotation)
-- [crate.spec](#cratespec)
-- [crate.workspace_member](#crateworkspace_member)
-- [render_config](#render_config)
-- [splicing_config](#splicing_config)
-
-## Workflows
-
-The [`crates_repository`](#crates_repository) rule (the primary repository rule of `cargo-bazel`) supports a number of different ways users
-can express and organize their dependencies. The most common are listed below though there are more to be found in
-the [./examples/crate_universe](https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe) directory.
-
-### Cargo Workspaces
-
-One of the simpler ways to wire up dependencies would be to first structure your project into a [Cargo workspace][cw].
-The `crates_repository` rule can ingest a root `Cargo.toml` file and generate dependencies from there.
-
-```python
-load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
-
-crates_repository(
- name = "crate_index",
- lockfile = "//:Cargo.Bazel.lock",
- manifests = ["//:Cargo.toml"],
-)
-
-load("@crate_index//:defs.bzl", "crate_repositories")
-
-crate_repositories()
-```
-
-The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
-Notably, the `all_crate_deps` and `aliases` macros commonly allow the `Cargo.toml` files to be the single source of
-truth for dependencies. Since these macros come from the generated repository, the dependencies and alias definitions
-they return will automatically update BUILD targets.
-
-```python
-load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
-load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
-
-rust_library(
- name = "lib",
- aliases = aliases(),
- deps = all_crate_deps(
- normal = True,
- ),
- proc_macro_deps = all_crate_deps(
- proc_macro = True,
- ),
-)
-
-rust_test(
- name = "unit_test",
- crate = ":lib",
- aliases = aliases(
- normal_dev = True,
- proc_macro_dev = True,
- ),
- deps = all_crate_deps(
- normal_dev = True,
- ),
- proc_macro_deps = all_crate_deps(
- proc_macro_dev = True,
- ),
-)
-```
-
-### Direct Packages
-
-In cases where Rust targets have heavy interractions with other Bazel targests ([Cc][cc], [Proto][proto], etc.),
-maintaining `Cargo.toml` files may have deminishing returns as things like [rust-analyzer][ra] begin to be confused
-about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
-to have a "Cargo free" setup. `crates_repository` supports this through the `packages` attribute.
-
-```python
-load("@cargo_bazel//:defs.bzl", "crate", "crates_repository", "render_config")
-
-crates_repository(
- name = "crate_index",
- lockfile = "//:Cargo.Bazel.lock",
- packages = {
- "async-trait": crate.spec(
- version = "0.1.51",
- ),
- "mockall": crate.spec(
- version = "0.10.2",
- ),
- "tokio": crate.spec(
- version = "1.12.0",
- ),
- },
- # Setting the default package name to `""` forces the use of the macros defined in this repository
- # to always use the root package when looking for dependencies or aliases. This should be considered
- # optional as the repository also exposes alises for easy access to all dependencies.
- render_config = render_config(
- default_package_name = ""
- ),
-)
-
-load("@crate_index//:defs.bzl", "crate_repositories")
-
-crate_repositories()
-```
-
-Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.
-
-```python
-load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
-
-rust_library(
- name = "lib",
- deps = [
- "@crate_index//:tokio",
- ],
- proc_macro_deps = [
- "@crate_index//:async-trait",
- ],
-)
-
-rust_test(
- name = "unit_test",
- crate = ":lib",
- deps = [
- "@crate_index//:mockall",
- ],
-)
-```
-
-[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
-[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
-[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
-[ra]: https://rust-analyzer.github.io/
-"""
-
-load(
- "//crate_universe:repositories.bzl",
- _crate_universe_dependencies = "crate_universe_dependencies",
-)
load(
"//crate_universe/private:crate.bzl",
_crate = "crate",
@@ -192,7 +26,6 @@
crates_vendor = _crates_vendor
# Utility Macros
-crate_universe_dependencies = _crate_universe_dependencies
crate = _crate
render_config = _render_config
splicing_config = _splicing_config
diff --git a/crate_universe/docs.bzl b/crate_universe/docs.bzl
new file mode 100644
index 0000000..11ab921
--- /dev/null
+++ b/crate_universe/docs.bzl
@@ -0,0 +1,213 @@
+"""# Crate Universe
+
+Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
+
+## Experimental
+
+`crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
+
+## Setup
+
+After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
+
+```python
+load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
+
+crate_universe_dependencies()
+```
+
+Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
+flags such as [`bootstrap = True`](#crate_universe_dependencies-bootstrap) on the `crate_universe_dependencies`
+call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
+
+## Rules
+
+- [crates_repository](#crates_repository)
+- [crates_vendor](#crates_vendor)
+
+## Utility Macros
+
+- [crate_universe_dependencies](#crate_universe_dependencies)
+- [crate.annotation](#crateannotation)
+- [crate.spec](#cratespec)
+- [crate.workspace_member](#crateworkspace_member)
+- [render_config](#render_config)
+- [splicing_config](#splicing_config)
+
+## Workflows
+
+The [`crates_repository`](#crates_repository) rule (the primary repository rule of `rules_rust`'s cargo support) supports a number of different
+ways users can express and organize their dependencies. The most common are listed below though there are more to be found in
+the [./examples/crate_universe](https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe) directory.
+
+### Cargo Workspaces
+
+One of the simpler ways to wire up dependencies would be to first structure your project into a [Cargo workspace][cw].
+The `crates_repository` rule can ingest a root `Cargo.toml` file and generate dependencies from there.
+
+```python
+load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
+
+crates_repository(
+ name = "crate_index",
+ lockfile = "//:Cargo.Bazel.lock",
+ manifests = ["//:Cargo.toml"],
+)
+
+load("@crate_index//:defs.bzl", "crate_repositories")
+
+crate_repositories()
+```
+
+The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
+Notably, the `all_crate_deps` and `aliases` macros (see [Dependencies API](#dependencies-api)) commonly allow the
+`Cargo.toml` files to be the single source of truth for dependencies. Since these macros come from the generated
+repository, the dependencies and alias definitions they return will automatically update BUILD targets.
+
+```python
+load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
+load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
+
+rust_library(
+ name = "lib",
+ aliases = aliases(),
+ deps = all_crate_deps(
+ normal = True,
+ ),
+ proc_macro_deps = all_crate_deps(
+ proc_macro = True,
+ ),
+)
+
+rust_test(
+ name = "unit_test",
+ crate = ":lib",
+ aliases = aliases(
+ normal_dev = True,
+ proc_macro_dev = True,
+ ),
+ deps = all_crate_deps(
+ normal_dev = True,
+ ),
+ proc_macro_deps = all_crate_deps(
+ proc_macro_dev = True,
+ ),
+)
+```
+
+### Direct Packages
+
+In cases where Rust targets have heavy interractions with other Bazel targests ([Cc][cc], [Proto][proto], etc.),
+maintaining `Cargo.toml` files may have deminishing returns as things like [rust-analyzer][ra] begin to be confused
+about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
+to have a "Cargo free" setup. `crates_repository` supports this through the `packages` attribute.
+
+```python
+load("@cargo_bazel//:defs.bzl", "crate", "crates_repository", "render_config")
+
+crates_repository(
+ name = "crate_index",
+ lockfile = "//:Cargo.Bazel.lock",
+ packages = {
+ "async-trait": crate.spec(
+ version = "0.1.51",
+ ),
+ "mockall": crate.spec(
+ version = "0.10.2",
+ ),
+ "tokio": crate.spec(
+ version = "1.12.0",
+ ),
+ },
+ # Setting the default package name to `""` forces the use of the macros defined in this repository
+ # to always use the root package when looking for dependencies or aliases. This should be considered
+ # optional as the repository also exposes alises for easy access to all dependencies.
+ render_config = render_config(
+ default_package_name = ""
+ ),
+)
+
+load("@crate_index//:defs.bzl", "crate_repositories")
+
+crate_repositories()
+```
+
+Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.
+
+```python
+load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
+
+rust_library(
+ name = "lib",
+ deps = [
+ "@crate_index//:tokio",
+ ],
+ proc_macro_deps = [
+ "@crate_index//:async-trait",
+ ],
+)
+
+rust_test(
+ name = "unit_test",
+ crate = ":lib",
+ deps = [
+ "@crate_index//:mockall",
+ ],
+)
+```
+
+## Dependencies API
+
+After rendering dependencies, convenience macros may also be generated to provide
+convenient accessors to larger sections of the dependency graph.
+
+- [aliases](#aliases)
+- [crate_deps](#crate_deps)
+- [all_crate_deps](#all_crate_deps)
+- [crate_repositories](#crate_repositories)
+
+---
+
+---
+
+[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
+[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
+[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
+[ra]: https://rust-analyzer.github.io/
+"""
+
+load(
+ "//crate_universe:defs.bzl",
+ _crate = "crate",
+ _crates_repository = "crates_repository",
+ _crates_vendor = "crates_vendor",
+ _render_config = "render_config",
+ _splicing_config = "splicing_config",
+)
+load(
+ "//crate_universe:repositories.bzl",
+ _crate_universe_dependencies = "crate_universe_dependencies",
+)
+load(
+ "//crate_universe/3rdparty/crates:defs.bzl",
+ _aliases = "aliases",
+ _all_crate_deps = "all_crate_deps",
+ _crate_deps = "crate_deps",
+ _crate_repositories = "crate_repositories",
+)
+
+# Rules
+crates_repository = _crates_repository
+crates_vendor = _crates_vendor
+
+# Utility Macros
+crate_universe_dependencies = _crate_universe_dependencies
+crate = _crate
+render_config = _render_config
+splicing_config = _splicing_config
+
+# Dependencies API
+aliases = _aliases
+all_crate_deps = _all_crate_deps
+crate_deps = _crate_deps
+crate_repositories = _crate_repositories
diff --git a/crate_universe/private/crates_repository.bzl b/crate_universe/private/crates_repository.bzl
index 78eb24a..70f7045 100644
--- a/crate_universe/private/crates_repository.bzl
+++ b/crate_universe/private/crates_repository.bzl
@@ -151,7 +151,8 @@
Rust targets found in the dependency graph defined by the given manifests.
**NOTE**: The `lockfile` must be manually created. The rule unfortunately does not yet create
-it on its own.
+it on its own. When initially setting up this rule, an empty file should be created and then
+populated by repinning dependencies.
### Repinning / Updating Dependencies
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index ca77136..430d634 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -184,7 +184,7 @@
stardoc(
name = "crate_universe",
out = "crate_universe.md",
- input = "@rules_rust//crate_universe:defs.bzl",
+ input = "@rules_rust//crate_universe:docs.bzl",
deps = [":all_docs"],
)
diff --git a/docs/crate_universe.md b/docs/crate_universe.md
index 233bb28..cf5d14e 100644
--- a/docs/crate_universe.md
+++ b/docs/crate_universe.md
@@ -38,8 +38,8 @@
## Workflows
-The [`crates_repository`](#crates_repository) rule (the primary repository rule of `cargo-bazel`) supports a number of different ways users
-can express and organize their dependencies. The most common are listed below though there are more to be found in
+The [`crates_repository`](#crates_repository) rule (the primary repository rule of `rules_rust`'s cargo support) supports a number of different
+ways users can express and organize their dependencies. The most common are listed below though there are more to be found in
the [./examples/crate_universe](https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe) directory.
### Cargo Workspaces
@@ -62,9 +62,9 @@
```
The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
-Notably, the `all_crate_deps` and `aliases` macros commonly allow the `Cargo.toml` files to be the single source of
-truth for dependencies. Since these macros come from the generated repository, the dependencies and alias definitions
-they return will automatically update BUILD targets.
+Notably, the `all_crate_deps` and `aliases` macros (see [Dependencies API](#dependencies-api)) commonly allow the
+`Cargo.toml` files to be the single source of truth for dependencies. Since these macros come from the generated
+repository, the dependencies and alias definitions they return will automatically update BUILD targets.
```python
load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
@@ -158,6 +158,20 @@
)
```
+## Dependencies API
+
+After rendering dependencies, convenience macros may also be generated to provide
+convenient accessors to larger sections of the dependency graph.
+
+- [aliases](#aliases)
+- [crate_deps](#crate_deps)
+- [all_crate_deps](#all_crate_deps)
+- [crate_repositories](#crate_repositories)
+
+---
+
+---
+
[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
@@ -226,7 +240,8 @@
Rust targets found in the dependency graph defined by the given manifests.
**NOTE**: The `lockfile` must be manually created. The rule unfortunately does not yet create
-it on its own.
+it on its own. When initially setting up this rule, an empty file should be created and then
+populated by repinning dependencies.
### Repinning / Updating Dependencies
@@ -346,6 +361,71 @@
| <a id="crates_vendor-vendor_path"></a>vendor_path | The path to a directory to write files into. Absolute paths will be treated as relative to the workspace root | String | optional | "crates" |
+<a id="#aliases"></a>
+
+## aliases
+
+<pre>
+aliases(<a href="#aliases-normal">normal</a>, <a href="#aliases-normal_dev">normal_dev</a>, <a href="#aliases-proc_macro">proc_macro</a>, <a href="#aliases-proc_macro_dev">proc_macro_dev</a>, <a href="#aliases-build">build</a>, <a href="#aliases-build_proc_macro">build_proc_macro</a>, <a href="#aliases-package_name">package_name</a>)
+</pre>
+
+Produces a map of Crate alias names to their original label
+
+If no dependency kinds are specified, `normal` and `proc_macro` are used by default.
+Setting any one flag will otherwise determine the contents of the returned dict.
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="aliases-normal"></a>normal | If True, normal dependencies are included in the output list. | <code>False</code> |
+| <a id="aliases-normal_dev"></a>normal_dev | If True, normla dev dependencies will be included in the output list.. | <code>False</code> |
+| <a id="aliases-proc_macro"></a>proc_macro | If True, proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="aliases-proc_macro_dev"></a>proc_macro_dev | If True, dev proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="aliases-build"></a>build | If True, build dependencies are included in the output list. | <code>False</code> |
+| <a id="aliases-build_proc_macro"></a>build_proc_macro | If True, build proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="aliases-package_name"></a>package_name | The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code> when unset. | <code>None</code> |
+
+**RETURNS**
+
+dict: The aliases of all associated packages
+
+
+<a id="#all_crate_deps"></a>
+
+## all_crate_deps
+
+<pre>
+all_crate_deps(<a href="#all_crate_deps-normal">normal</a>, <a href="#all_crate_deps-normal_dev">normal_dev</a>, <a href="#all_crate_deps-proc_macro">proc_macro</a>, <a href="#all_crate_deps-proc_macro_dev">proc_macro_dev</a>, <a href="#all_crate_deps-build">build</a>, <a href="#all_crate_deps-build_proc_macro">build_proc_macro</a>,
+ <a href="#all_crate_deps-package_name">package_name</a>)
+</pre>
+
+Finds the fully qualified label of all requested direct crate dependencies for the package where this macro is called.
+
+If no parameters are set, all normal dependencies are returned. Setting any one flag will
+otherwise impact the contents of the returned list.
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="all_crate_deps-normal"></a>normal | If True, normal dependencies are included in the output list. | <code>False</code> |
+| <a id="all_crate_deps-normal_dev"></a>normal_dev | If True, normla dev dependencies will be included in the output list.. | <code>False</code> |
+| <a id="all_crate_deps-proc_macro"></a>proc_macro | If True, proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="all_crate_deps-proc_macro_dev"></a>proc_macro_dev | If True, dev proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="all_crate_deps-build"></a>build | If True, build dependencies are included in the output list. | <code>False</code> |
+| <a id="all_crate_deps-build_proc_macro"></a>build_proc_macro | If True, build proc_macro dependencies are included in the output list. | <code>False</code> |
+| <a id="all_crate_deps-package_name"></a>package_name | The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code> when unset. | <code>None</code> |
+
+**RETURNS**
+
+list: A list of labels to generated rust targets (str)
+
+
<a id="#crate.spec"></a>
## crate.spec
@@ -452,6 +532,41 @@
string: A json encoded string of all inputs
+<a id="#crate_deps"></a>
+
+## crate_deps
+
+<pre>
+crate_deps(<a href="#crate_deps-deps">deps</a>, <a href="#crate_deps-package_name">package_name</a>)
+</pre>
+
+Finds the fully qualified label of the requested crates for the package where this macro is called.
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="crate_deps-deps"></a>deps | The desired list of crate targets. | none |
+| <a id="crate_deps-package_name"></a>package_name | The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code>. | <code>None</code> |
+
+**RETURNS**
+
+list: A list of labels to generated rust targets (str)
+
+
+<a id="#crate_repositories"></a>
+
+## crate_repositories
+
+<pre>
+crate_repositories()
+</pre>
+
+A macro for defining repositories for all generated crates
+
+
+
<a id="#crate_universe_dependencies"></a>
## crate_universe_dependencies
