GNU bug report logs - #39640
[PATCH] doc: Document packaging guidelines for Rust crates.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39640 in the body.
You can then email your comments to 39640 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Efraim Flashner <efraim <at> flashner.co.il>
To: guix-patches <at> gnu.org
Cc: Efraim Flashner <efraim <at> flashner.co.il>
Subject: [PATCH] doc: Document packaging guidelines for Rust crates.
Date: Mon, 17 Feb 2020 11:21:59 +0200

* doc/contributing.texi (Rust Crates): New section.
---
 doc/contributing.texi | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index c6586a2adf..2fb641f0c5 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -347,6 +347,7 @@ needed is to review and apply the patch.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
 * Java Packages::               Coffee break.
+* Rust Crates::                 Beware of oxidation.
 * Fonts::                       Fond of fonts.
 @end menu
 
@@ -665,6 +666,39 @@ are also prepended by @code{perl-}.  Such modules tend to have the word
 prefix.  For instance, @code{libwww-perl} becomes @code{perl-libwww}.
 
 
+@node Rust Crates
+@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 incompatable versions of a
+package to be used at any given time, so all packages should have a versioned
+suffix.  If a package has passed version 1.0.0 then just the major version
+number is sufficient (e.g.@: rust-clap-2), otherwise the version suffix should
+contain the major and minor version (e.g.@: rust-rand-0.6).
+
+Because of the difficulty in reusing rust packages as pre-compiled inputs for
+other packages the @xref{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.
+
+
 @node Java Packages
 @subsection Java Packages
 
-- 
2.25.0

Message #8 received at 39640 <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: Efraim Flashner <efraim <at> flashner.co.il>
Cc: 39640 <at> debbugs.gnu.org
Subject: Re: [bug#39640] [PATCH] doc: Document packaging guidelines for Rust
 crates.
Date: Mon, 17 Feb 2020 12:39:22 +0100

Hello,

Efraim Flashner <efraim <at> flashner.co.il> writes:

> * doc/contributing.texi (Rust Crates): New section.

Great! Thank you for this clarification.

> +To prevent namespace collisions we prefix all other rust packages with the

rust -> Rust

> +In the rust ecosystem it is common for multiple incompatable versions of a

Ditto.

Also incompatable -> incompatible ?

> +package to be used at any given time, so all packages should have a versioned
> +suffix.  If a package has passed version 1.0.0 then just the major version
> +number is sufficient (e.g.@: rust-clap-2), otherwise the version suffix should
> +contain the major and minor version (e.g.@: rust-rand-0.6).

Nitpick: should contain both the major...

But that's just me.

I would also use @code{rust-clap-2} and @code{rust-rand-0.6}

> +Because of the difficulty in reusing rust packages as pre-compiled inputs for

rust -> Rust

> +other packages the @xref{cargo-build-system} presents the @code{#:cargo-inputs}

@xref is misused here. It targets references at the beginning of
a sentence. I.e., it will generate

  ... other packages the See cargo-build-system presents...

I suggest the more verbose

  ... other packages the Cargo build system (@pxref{cargo-build-system}) presents...

> +and @code{cargo-development-inputs} keywords as build-system arguments.  It

build-system or build system?

> 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

rust -> Rust

Regards,

-- 
Nicolas Goaziou

Message #13 received at 39640-done <at> debbugs.gnu.org (full text, mbox):

From: Efraim Flashner <efraim <at> flashner.co.il>
To: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
Cc: 39640-done <at> debbugs.gnu.org
Subject: Re: [bug#39640] [PATCH] doc: Document packaging guidelines for Rust
 crates.
Date: Tue, 18 Feb 2020 09:51:30 +0200

[Message part 1 (text/plain, inline)]

On Mon, Feb 17, 2020 at 12:39:22PM +0100, Nicolas Goaziou wrote:
> Hello,
> 
> Efraim Flashner <efraim <at> flashner.co.il> writes:
> 
> > * doc/contributing.texi (Rust Crates): New section.
> 
> Great! Thank you for this clarification.
> 

I realized I had most of it in my head and that wasn't helping anyone

> > +To prevent namespace collisions we prefix all other rust packages with the
> 
> rust -> Rust
> 
> > +In the rust ecosystem it is common for multiple incompatable versions of a
> 
> Ditto.
> 
> Also incompatable -> incompatible ?
> 

spelling is hard :)

> > +package to be used at any given time, so all packages should have a versioned
> > +suffix.  If a package has passed version 1.0.0 then just the major version
> > +number is sufficient (e.g.@: rust-clap-2), otherwise the version suffix should
> > +contain the major and minor version (e.g.@: rust-rand-0.6).
> 
> Nitpick: should contain both the major...
> 
> But that's just me.
> 
> I would also use @code{rust-clap-2} and @code{rust-rand-0.6}

Both sound good.

> 
> > +Because of the difficulty in reusing rust packages as pre-compiled inputs for
> 
> rust -> Rust
> 
> > +other packages the @xref{cargo-build-system} presents the @code{#:cargo-inputs}
> 
> @xref is misused here. It targets references at the beginning of
> a sentence. I.e., it will generate
> 
>   ... other packages the See cargo-build-system presents...
> 
> I suggest the more verbose
> 
>   ... other packages the Cargo build system (@pxref{cargo-build-system}) presents...

pxref turned out to be a bit more complicated than I thought. I got it
referring to Build Systems but not to cargo-build-system inside it.
Since the references to gnu-build-system are similar I figured it was
about the same.

> 
> > +and @code{cargo-development-inputs} keywords as build-system arguments.  It
> 
> build-system or build system?
> 

I've always thought of it as build-system due to the keyword, but 'build
system' would be the correct one.

> > 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
> 
> rust -> Rust
> 
> Regards,
> 
> -- 
> Nicolas Goaziou

Thanks for the review!

-- 
Efraim Flashner   <efraim <at> flashner.co.il>   אפרים פלשנר
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.