all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [bug#39640] [PATCH] doc: Document packaging guidelines for Rust crates.
@ 2020-02-17  9:21 Efraim Flashner
  2020-02-17 11:39 ` Nicolas Goaziou
  0 siblings, 1 reply; 3+ messages in thread
From: Efraim Flashner @ 2020-02-17  9:21 UTC (permalink / raw)
  To: 39640; +Cc: Efraim Flashner

* 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

^ permalink raw reply related	[flat|nested] 3+ messages in thread

* [bug#39640] [PATCH] doc: Document packaging guidelines for Rust crates.
  2020-02-17  9:21 [bug#39640] [PATCH] doc: Document packaging guidelines for Rust crates Efraim Flashner
@ 2020-02-17 11:39 ` Nicolas Goaziou
  2020-02-18  7:51   ` bug#39640: " Efraim Flashner
  0 siblings, 1 reply; 3+ messages in thread
From: Nicolas Goaziou @ 2020-02-17 11:39 UTC (permalink / raw)
  To: Efraim Flashner; +Cc: 39640

Hello,

Efraim Flashner <efraim@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

^ permalink raw reply	[flat|nested] 3+ messages in thread

* bug#39640: [PATCH] doc: Document packaging guidelines for Rust crates.
  2020-02-17 11:39 ` Nicolas Goaziou
@ 2020-02-18  7:51   ` Efraim Flashner
  0 siblings, 0 replies; 3+ messages in thread
From: Efraim Flashner @ 2020-02-18  7:51 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: 39640-done

[-- Attachment #1: Type: text/plain, Size: 2580 bytes --]

On Mon, Feb 17, 2020 at 12:39:22PM +0100, Nicolas Goaziou wrote:
> Hello,
> 
> Efraim Flashner <efraim@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@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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2020-02-18  7:53 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-17  9:21 [bug#39640] [PATCH] doc: Document packaging guidelines for Rust crates Efraim Flashner
2020-02-17 11:39 ` Nicolas Goaziou
2020-02-18  7:51   ` bug#39640: " Efraim Flashner

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.