1 files changed, 72 insertions, 28 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 6d3f1622f30..c801ba5950a 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1635,34 +1635,78 @@ dashes and prepend the prefix @code{java-}.  So the class
 @subsection Rust Crates
 
 @cindex rust
-Rust programs standing for themselves are named as any other package, using the
-lowercase upstream name.
-
-To prevent namespace collisions we prefix all other Rust packages with the
-@code{rust-} prefix.  The name should be changed to lowercase as appropriate and
-dashes should remain in place.
-
-In the rust ecosystem it is common for multiple incompatible versions of a
-package to be used at any given time, so all package definitions should have a
-versioned suffix.  The versioned suffix is the left-most non-zero digit (and
-any leading zeros, of course).  This follows the ``caret'' version scheme
-intended by Cargo.  Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
-
-Because of the difficulty in reusing rust packages as pre-compiled inputs for
-other packages the Cargo build system (@pxref{Build Systems,
-@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
-@code{cargo-development-inputs} keywords as build system arguments.  It would be
-helpful to think of these as similar to @code{propagated-inputs} and
-@code{native-inputs}.  Rust @code{dependencies} and @code{build-dependencies}
-should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
-@code{#:cargo-development-inputs}.  If a Rust package links to other libraries
-then the standard placement in @code{inputs} and the like should be used.
-
-Care should be taken to ensure the correct version of dependencies are used; to
-this end we try to refrain from skipping the tests or using @code{#:skip-build?}
-when possible.  Of course this is not always possible, as the package may be
-developed for a different Operating System, depend on features from the Nightly
-Rust compiler, or the test suite may have atrophied since it was released.
+Rust applications (binary crates) and libraries (library crates) are packaged
+separately.  We put our main efforts into applications and only package
+libraries as sources, utilizing automation with a manual focus on unbundling
+vendored dependencies.
+
+Rust applications are treated like any other package and named using the
+lowercase upstream name.  When using the Cargo build system (@pxref{Build
+Systems, @code{cargo-build-system}}), Rust applications should have the
+@code{#:install-source?} parameter set to @code{#f}, as this parameter only
+makes sense for libraries.  When the package source is a Cargo workspace,
+@code{#:cargo-install-paths} must be set to enable relevant support.
+
+Rust libraries are hidden from the user interface and managed in two modules:
+
+@table @code
+@item (gnu packages rust-crates)
+Source definitions imported from Rust packages' @file{Cargo.lock} via the
+@code{crate} importer (@pxref{Invoking guix import}).
+
+Imported definitions must be checked and have vendored dependencies unbundled
+before being contributed to Guix.
+
+@item (gnu packages rust-sources)
+More complex definitions that need to be full packages.  This includes Rust
+libraries requiring external inputs to unbundle and Cargo workspaces.
+
+These libraries should have the @code{#:skip-build?} parameter set to @code{#t}.
+For Cargo workspaces, @code{#:cargo-package-crates} must be set.
+
+Since they are added manually, they follow the usual naming convention for Guix
+packages (@pxref{Package Naming}), with a @code{rust-} prefix.
+
+In the Rust community it is common for multiple incompatible versions of a
+package to be used at any given time, so all libraries should have a versioned
+suffix.  The versioned suffix is the left-most non-zero digit (and any leading
+zeros, of course).  This follows the ``caret'' version scheme intended by Cargo.
+Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
+
+In practice we often package development snapshots of Rust libraries and can't
+simply identify them by version.  In this case, the complete version information
+can be turned into a version string via @code{git-version}, for example
+@code{rust-pipewire-0.8.0.fd3d8f7} and @code{rust-pubgrub-0.3.0.b70cf70}.
+@end table
+
+To avoid merge conflicts with changes from multiple branches, these two modules
+are maintained by the Rust team (@pxref{Teams}).
+
+Rust libraries are not referenced directly.  @code{(guix build-sytem cargo)}
+provides a @code{cargo-inputs} procedure to lookup input lists generated by the
+lockfile importer.
+
+@cindex cargo inputs
+@findex define-cargo-inputs
+@findex lookup-cargo-inputs
+@deffn {Procedure} cargo-inputs name [#:module '(gnu packages rust-crates)]
+Lookup Cargo inputs for @var{name} in @var{module}, return an empty list if
+unavailable.
+
+@var{name} must be consistent with the one used in lockfile importer invocation,
+usually matching the variable name of the package:
+
+@example
+$ guix import -i @file{gnu/packages/rust-crates.scm} crate -f @file{/path/to/Cargo.lock} @var{name}
+@end example
+
+@var{module} must export a public interface @code{lookup-cargo-inputs}, a
+template is available in the @file{etc/teams/rust} directory of Guix source
+tree.
+@end deffn
+
+@xref{Packaging Rust Crates,,, guix-cookbook, GNU Guix Cookbook}, for
+packaging workflow.
 
 
 @node Elm Packages