11:42 p.m.
`cargo doc` will generate docs with long descriptions.
I did not add the settings of outputting these docs to `/website`.
This is because
- by publishing this crate to crates.io, users can see the docs in
`docs.rs` like `https://docs.rs/guestfs/<version>/guestfs/`. It is easy
to hold multiple documents corresponding to each version.
- the style of the documents generated by `cargo doc` is far different
from the documents which already exist.
---
generator/rust.ml | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/generator/rust.ml b/generator/rust.ml
index 1f5cefa62..3a07c3b53 100644
--- a/generator/rust.ml
+++ b/generator/rust.ml
@@ -52,6 +52,14 @@ let translate_bad_symbols s =
else
s
+(* output longdesc to the rust file *)
+let pr_longdesc name longdesc indent_depth =
+ let l = pod2text name longdesc in
+ List.iter (fun x ->
+ indent indent_depth;
+ pr "/// %s\n" x;
+ ) l
+
let generate_rust () =
generate_header ~copyrights CStyle LGPLv2plus;
@@ -398,6 +406,8 @@ extern \"C\" {
style = (ret, args, optargs) } as f) ->
let cname = snake2caml name in
pr " /// %s\n" shortdesc;
+ pr " ///\n";
+ pr_longdesc name longdesc 1;
pr " #[allow(non_snake_case)]\n";
pr " pub fn %s" name;
--
2.20.1 (Apple Git-117)
11:42 p.m.
New subject: [PATCH 2/2] Rust bindings: Make it able to publish this crate
I added
- data required to publish this crate to `crates.io`.
- README.md which contains the details of how to publish this crate.
---
rust/Cargo.toml.in | 5 ++++-
rust/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
2 files changed, 46 insertions(+), 1 deletion(-)
create mode 100644 rust/README.md
diff --git a/rust/Cargo.toml.in b/rust/Cargo.toml.in
index b61e3ec7f..d217a530e 100644
--- a/rust/Cargo.toml.in
+++ b/rust/Cargo.toml.in
@@ -17,7 +17,10 @@
[package]
name = "guestfs"
-version = "@VERSION@"
+version = "0.1.0-compat@VERSION@"
edition = "2018"
+authors = ["Hiroyuki Katsura <hiroyuki.katsura.0513(a)gmail.com>"]
+description = "libguestfs bindings for Rust"
+license-file = "../COPYING"
[dependencies]
diff --git a/rust/README.md b/rust/README.md
new file mode 100644
index 000000000..f7dd96d39
--- /dev/null
+++ b/rust/README.md
@@ -0,0 +1,42 @@
+# libguestfs bindings for Rust
+
+This package contains the libguestfs bindings for Rust. You can use this crate
+by using cargo. See [crates.io](https://https://crates.io/crates/guestfs)
+
+# For maintainer
+
+## How to test
+
+Tests are incorporated into the build system.
+
+You can test it manually by
+
+```
+$ ../run cargo test
+```
+
+## How to publish
+
+### 1. Fix version in Cargo.toml.in
+
+Regarding Versioning convention, see [Semantic
+Versioning](https://semver.org/).
+
+You must not break '-compat@VERSION@' to make sure that this binding is
+compatible with the installed libguestfs.
+
+Example
+```
+version = "0.1.0-compat@VERSION@"
+```
+
+### 2. Commit the change of the version
+
+### 3. Build libguestfs
+
+### 4. Publish
+
+```
+$ cargo publish
+```
+
--
2.20.1 (Apple Git-117)
2:36 p.m.
New subject: [PATCH 2/2] Rust bindings: Make it able to publish this crate
On Sun, Aug 11, 2019 at 01:42:22PM +0900, Hiroyuki Katsura wrote:
I added
- data required to publish this crate to `crates.io`.
- README.md which contains the details of how to publish this crate.
Pino had some comments for patch 1. However this patch looks OK to
me, and implements the version change that we discussed, so I have
pushed it now, thanks.
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW
11:01 a.m.
On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
`cargo doc` will generate docs with long descriptions.
This is a nice start, although most probably it will not look that good
though (since the plain text output may be misrendered as markdown).
I remember we talked about converting the POD texts to markdown, and
that there seems to be something we can use:
https://metacpan.org/release/Pod-Markdown
Did you try to use it? What were the results?
I did not add the settings of outputting these docs to `/website`.
This is because
- by publishing this crate to crates.io, users can see the docs in
`docs.rs` like `https://docs.rs/guestfs/<version>/guestfs/`. It is easy
to hold multiple documents corresponding to each version.
- the style of the documents generated by `cargo doc` is far different
from the documents which already exist.
While this certainly makes sense, note that we don't create in the
website online API docs, at most just basic intro pages for the various
programming languages for which we have (stable) bindings. For example
http://libguestfs.org/guestfs-ocaml.3.html
(IMHO we could publish API docs for the few bindings that have them,
but that is a separate discussion and for another day.)
I'd leave the paragraph above out from the commit message, since it is
mostly unrelated.
---
generator/rust.ml | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/generator/rust.ml b/generator/rust.ml
index 1f5cefa62..3a07c3b53 100644
--- a/generator/rust.ml
+++ b/generator/rust.ml
@@ -52,6 +52,14 @@ let translate_bad_symbols s =
else
s
+(* output longdesc to the rust file *)
+let pr_longdesc name longdesc indent_depth =
indent_depth seems always 1, so I'd say to hardcode this indentation
level for now (it can be always changed).
+ let l = pod2text name longdesc in
Better specify a width, so indent + comment + text does not overflow
the recommended line limit of 100 characters:
https://rust-lang.github.io/rustc-guide/conventions.html#line-length
+ List.iter (fun x ->
+ indent indent_depth;
+ pr "/// %s\n" x;
+ ) l
Without indent_depth, this can be nicely simplified as
List.iter (pr " /// %s\n") l
:-)
--
Pino Toscano
10:17 p.m.
2019/08/13 1:01、Pino Toscano <ptoscano(a)redhat.xn--com>-1e4f10b4csi:
On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
> `cargo doc` will generate docs with long descriptions.
This is a nice start, although most probably it will not look that good
though (since the plain text output may be misrendered as markdown).
I remember we talked about converting the POD texts to markdown, and
that there seems to be something we can use:
https://metacpan.org/release/Pod-Markdown
<https://metacpan.org/release/Pod-Markdown>
Did you try to use it? What were the results?
Yes. As I mentioned before, it looked pretty good except for some encode-errors.
However, at first, I just translate pod to text by the exisiting function because using
pod2markdown looks a little tricky.
> I did not add the settings of outputting these docs to `/website`.
> This is because
> - by publishing this crate to crates.io <http://crates.io/>;, users can see the
docs in
> `docs.rs <http://docs.rs/>` like
`https://docs.rs/guestfs/<version>/guestfs/`
<https://docs.rs/guestfs/%3Cversion%3E/guestfs/%60>;. It is easy
> to hold multiple documents corresponding to each version.
> - the style of the documents generated by `cargo doc` is far different
> from the documents which already exist.
While this certainly makes sense, note that we don't create in the
website online API docs, at most just basic intro pages for the various
programming languages for which we have (stable) bindings. For example
http://libguestfs.org/guestfs-ocaml.3.html
<http://libguestfs.org/guestfs-ocaml.3.html>
(IMHO we could publish API docs for the few bindings that have them,
but that is a separate discussion and for another day.)
I'd leave the paragraph above out from the commit message, since it is
mostly unrelated.
Hmm, It seems better to create an intro page for rust bindings.
I’ll create it.
> ---
> generator/rust.ml | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
> diff --git a/generator/rust.ml b/generator/rust.ml
> index 1f5cefa62..3a07c3b53 100644
> --- a/generator/rust.ml
> +++ b/generator/rust.ml
> @@ -52,6 +52,14 @@ let translate_bad_symbols s =
> else
> s
>
> +(* output longdesc to the rust file *)
> +let pr_longdesc name longdesc indent_depth =
indent_depth seems always 1, so I'd say to hardcode this indentation
level for now (it can be always changed).
OK.
> + let l = pod2text name longdesc in
Better specify a width, so indent + comment + text does not overflow
the recommended line limit of 100 characters:
https://rust-lang.github.io/rustc-guide/conventions.html#line-length
<https://rust-lang.github.io/rustc-guide/conventions.html#line-length>
Ah, It seems good.
Question:
There are some places where the length of the line in the generated code
is over 100 characters. Of course, I can try to make the length of each line under 100
characters. However, there is a nice tool: ‘rustfmt.’ I want to use this as a
‘post-process’
of generating bindings. Is it OK?(I should have ask you when I sent the first patch)
> + List.iter (fun x ->
> + indent indent_depth;
> + pr "/// %s\n" x;
> + ) l
Without indent_depth, this can be nicely simplified as
List.iter (pr " /// %s\n") l
Hmm, that’s true.
:-)
5:44 a.m.
On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> 2019/08/13 1:01、Pino Toscano <ptoscano(a)redhat.xn--com>-1e4f10b4csi:
>
> On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
>> `cargo doc` will generate docs with long descriptions.
>
> This is a nice start, although most probably it will not look that good
> though (since the plain text output may be misrendered as markdown).
>
> I remember we talked about converting the POD texts to markdown, and
> that there seems to be something we can use:
> https://metacpan.org/release/Pod-Markdown
<https://metacpan.org/release/Pod-Markdown>
> Did you try to use it? What were the results?
Yes. As I mentioned before, it looked pretty good except for some encode-errors.
However, at first, I just translate pod to text by the exisiting function because using
pod2markdown looks a little tricky.
Can you explain which errors did you get? I tried pod2markdown on a
couple of API longdesc's, and the result seemed OK.
Most probably we will need to write our own pod2markdown though, as
pod2markdown does not allow users to customize all the options that
the Pod::Markdown module has.
Question:
There are some places where the length of the line in the generated code
is over 100 characters. Of course, I can try to make the length of each line under 100
characters. However, there is a nice tool: ‘rustfmt.’ I want to use this as a
‘post-process’
of generating bindings. Is it OK?(I should have ask you when I sent the first patch)
Considering we are generating most of the rust code using the
generator, IMHO it is better to produce the code directly following
the style conventions. I just checked the difference between our
currently generated guestfs.rs and the "formatted" version of it, and
fixing guestfs.rs does not seem too difficult. It can be done in steps,
of course, no need to rush everything in a single fix.
--
Pino Toscano
8:02 a.m.
Can you explain which errors did you get? I tried pod2markdown on a
couple of API longdesc's, and the result seemed OK.
Most probably we will need to write our own pod2markdown though, as
pod2markdown does not allow users to customize all the options that
the Pod::Markdown module has.
Yes. Most of the results seemed OK. But, for example, translating
'docs/guestfs-internals.pod' dumps the following errors at the end of the
output file
```
# POD ERRORS
Hey! **The above document had some coding errors, which are explained
below:**
- Around line 17:
Non-ASCII character seen before =encoding in '┌───────────────────┐'.
Assuming UTF-8
```
I do not know whether there are such non-ascii characters in API longdescs,
and I have no idea to find
such characters easily. So, I am not able to say whether pod2markdown is
usable or not for now...
IMHO it is better to produce the code directly following
the style conventions.
OK. I'll send the formatting patch.
Regards,
Hiroyuki
2019年8月13日(火) 19:44 Pino Toscano <ptoscano(a)redhat.com>:
> On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> >
> > > 2019/08/13 1:01、Pino Toscano <ptoscano(a)redhat.xn--com>-1e4f10b4csi:
> > >
> > > On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
> > >> `cargo doc` will generate docs with long descriptions.
> > >
> > > This is a nice start, although most probably it will not look that good
> > > though (since the plain text output may be misrendered as markdown).
> > >
> > > I remember we talked about converting the POD texts to markdown, and
> > > that there seems to be something we can use:
> > > https://metacpan.org/release/Pod-Markdown <
> https://metacpan.org/release/Pod-Markdown>
> > > Did you try to use it? What were the results?
> >
> > Yes. As I mentioned before, it looked pretty good except for some
> encode-errors.
> > However, at first, I just translate pod to text by the exisiting
> function because using
> > pod2markdown looks a little tricky.
>
Can you explain which errors did you get? I tried pod2markdown on a
couple of API longdesc's, and the result seemed OK.
Most probably we will need to write our own pod2markdown though, as
pod2markdown does not allow users to customize all the options that
the Pod::Markdown module has.
>
> > Question:
> > There are some places where the length of the line in the generated code
> > is over 100 characters. Of course, I can try to make the length of each
> line under 100
> > characters. However, there is a nice tool: ‘rustfmt.’ I want to use this
> as a ‘post-process’
> > of generating bindings. Is it OK?(I should have ask you when I sent the
> first patch)
>
> Considering we are generating most of the rust code using the
> generator, IMHO it is better to produce the code directly following
> the style conventions. I just checked the difference between our
> currently generated guestfs.rs and the "formatted" version of it, and
> fixing guestfs.rs does not seem too difficult. It can be done in steps,
> of course, no need to rush everything in a single fix.
>
> --
> Pino Toscano
8:12 a.m.
On Tuesday, 13 August 2019 15:02:10 CEST Hiroyuki Katsura wrote:
> Can you explain which errors did you get? I tried pod2markdown
on a
> couple of API longdesc's, and the result seemed OK.
> Most probably we will need to write our own pod2markdown though, as
> pod2markdown does not allow users to customize all the options that
> the Pod::Markdown module has.
Yes. Most of the results seemed OK. But, for example, translating
'docs/guestfs-internals.pod' dumps the following errors at the end of the
output file
Oh no need to convert everything :-) The bits that matter at the moment
are the "longdesc" of APIs, writing them to guestfs.rs just like you
did with pod2text.
--
Pino Toscano
8:38 a.m.
Oh no need to convert everything :-) The bits that matter at the
moment
are the "longdesc" of APIs, writing them to guestfs.rs just like you
did with pod2text.
Ah, Yes I knew it. I just tested pod2markdown by the existing pod files.
Regards,
Hiroyuki
2019年8月13日(火) 22:12 Pino Toscano <ptoscano(a)redhat.com>:
> On Tuesday, 13 August 2019 15:02:10 CEST Hiroyuki Katsura wrote:
> > > Can you explain which errors did you get? I tried pod2markdown on a
> > > couple of API longdesc's, and the result seemed OK.
> > > Most probably we will need to write our own pod2markdown though, as
> > > pod2markdown does not allow users to customize all the options that
> > > the Pod::Markdown module has.
> >
> > Yes. Most of the results seemed OK. But, for example, translating
> > 'docs/guestfs-internals.pod' dumps the following errors at the end of
the
> > output file
>
Oh no need to convert everything :-) The bits that matter at the
moment
are the "longdesc" of APIs, writing them to guestfs.rs just like you
did with pod2text.
>
> --
> Pino Toscano
11:04 p.m.
`cargo doc` will generate docs with long descriptions.
I did not add the settings of outputting these docs to `/website`.
This is because
- by publishing this crate to crates.io, users can see the docs in
`docs.rs` like `https://docs.rs/guestfs/<version>/guestfs/`. It is easy
to hold multiple documents corresponding to each version.
- the style of the documents generated by `cargo doc` is far different
from the documents which already exist.
---
generator/rust.ml | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/generator/rust.ml b/generator/rust.ml
index 1f5cefa62..f62205185 100644
--- a/generator/rust.ml
+++ b/generator/rust.ml
@@ -52,6 +52,13 @@ let translate_bad_symbols s =
else
s
+(* output longdesc to the rust file *)
+let pr_longdesc name longdesc =
+ (* Lines should be at most 100 characters *)
+ (* And Each line begins with ' /// ' *)
+ let l = pod2text ~width:92 name longdesc in
+ List.iter (pr " /// %s\n") l
+
let generate_rust () =
generate_header ~copyrights CStyle LGPLv2plus;
@@ -398,6 +405,8 @@ extern \"C\" {
style = (ret, args, optargs) } as f) ->
let cname = snake2caml name in
pr " /// %s\n" shortdesc;
+ pr " ///\n";
+ pr_longdesc name longdesc;
pr " #[allow(non_snake_case)]\n";
pr " pub fn %s" name;
--
2.20.1 (Apple Git-117)
1852
days inactive
1854
days old
9 comments
4 participants
participants (4)
-
Hiroyuki Katsura -
Katsura Hiroyuki -
Pino Toscano -
Richard W.M. Jones