[Libguestfs] [PATCH libnbd 2/4] rust: Add overview documentation

--- .gitignore | 1 + docs/libnbd.pod | 4 ++++ rust/Makefile.am | 13 +++++++++++ rust/libnbd-rust.pod | 53 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 71 insertions(+) diff --git a/.gitignore b/.gitignore index 36bf8b60f8..0b1cf7646a 100644 --- a/.gitignore +++ b/.gitignore @@ -180,6 +180,7 @@ Makefile.in /python/run-python-tests /run /rust/Cargo.lock +/rust/libnbd-rust.3 /rust/libnbd-sys/Cargo.lock /rust/libnbd-sys/libnbd_version /rust/libnbd-sys/src/generated.rs diff --git a/docs/libnbd.pod b/docs/libnbd.pod index f15ea6403d..2fc78212a5 100644 --- a/docs/libnbd.pod +++ b/docs/libnbd.pod @@ -51,6 +51,10 @@ Using the API from OCaml. Using the API from Go. +=item L<libnbd-rust(3)> + +Using the API from Rust. + =item L<nbdsh(1)> Using the NBD shell (nbdsh) for command line and Python scripting. diff --git a/rust/Makefile.am b/rust/Makefile.am index 75738a0c30..5c73512c87 100644 --- a/rust/Makefile.am +++ b/rust/Makefile.am @@ -84,6 +84,7 @@ source_files = \ EXTRA_DIST = \ $(source_files) \ + libnbd-rust.pod \ $(NULL) if HAVE_RUST @@ -102,6 +103,18 @@ target/debug/liblibnbd.rlib: $(source_files) target/doc/libnbd/index.html: $(source_files) $(abs_top_builddir)/run $(CARGO) doc +if HAVE_POD + +man_MANS = libnbd-rust.3 +CLEANFILES += $(man_MANS) + +libnbd-rust.3: libnbd-rust.pod $(top_builddir)/podwrapper.pl + $(PODWRAPPER) --section=3 --man $@ \ + --html $(top_builddir)/html/$@.html \ + $< + +endif HAVE_POD + TESTS_ENVIRONMENT = \ LIBNBD_DEBUG=1 \ $(MALLOC_CHECKS) \ diff --git a/rust/libnbd-rust.pod b/rust/libnbd-rust.pod new file mode 100644 index 0000000000..622f0b4ac5 --- /dev/null +++ b/rust/libnbd-rust.pod @@ -0,0 +1,53 @@ +=head1 NAME + +libnbd-rust - how to use libnbd from Rust + +=head1 SYNOPSIS + + let nbd = libnbd::Handle::new().unwrap(); + nbd.connect_uri("nbd://localhost").unwrap(); + let size = nbd.get_size().unwrap(); + println!("{size} bytes"); + +In C<Cargo.toml> add: + + [dependencies] + libnbd = VERSION | { path = "libnbd/rust" } + +=head1 DESCRIPTION + +This manual page documents how to use libnbd to access Network Block +Device (NBD) servers from the Rust programming language. + +The Rust bindings work very similarly to the C bindings so you should +start by reading L<libnbd(3)>. + +There is also a higher level asynchronous API using Tokio. + +If you build libnbd from source, the main documentation can be found +in F<libnbd/rust/target/doc/libnbd/index.html> + +For the ordinary interface, start by reading the documentation for +C<Handle>. For the higher level asynchronous API, start by reading +C<AsyncHandle>. + +C<libnbd-sys> is a very low level wrapper around the libnbd API which +should not be used directly. + +=head1 EXAMPLES + +This directory contains examples written in Rust: + +L<https://gitlab.com/nbdkit/libnbd/tree/master/rust/examples> + +=head1 SEE ALSO + +L<libnbd(3)>. + +=head1 AUTHORS + +Tage Johansson + +=head1 COPYRIGHT + +Copyright Tage Johansson -- 2.41.0