diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 94 |
1 files changed, 69 insertions, 25 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 6d3f1622f3..0f04ef7870 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -83,7 +83,7 @@ version 0.1.0 or later; @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib}; @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi}; @item -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0 +@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.10.0 or later; @item @uref{https://git-scm.com, Git} (yes, both!); @item @uref{https://github.com/aconchillo/guile-json, Guile-JSON} @@ -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. +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. -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. +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. -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}. +Rust libraries are hidden from the user interface and managed in two modules: -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. +@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 -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. +@xref{Packaging Rust Crates,,, guix-cookbook, GNU Guix Cookbook}, for +packaging workflow. @node Elm Packages |