Message ID | 20200217092159.776-1-efraim@flashner.co.il |
---|---|
State | Accepted |
Headers | show |
Series | [bug#39640] doc: Document packaging guidelines for Rust crates. | expand |
Context | Check | Description |
---|---|---|
cbaines/comparison | success | View comparision |
cbaines/git branch | success | View Git branch |
cbaines/applying patch | success | View Laminar job |
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,
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!
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