Since we removed gtk doc, we might as well replace it with a manual page explaining the basics of how to run gjs. --- .gitignore | 2 ++ docs/guestfs-recipes.pod | 1 + erlang/examples/guestfs-erlang.pod | 1 + gobject/Makefile.am | 19 +++++++++++ gobject/guestfs-gobject.pod | 64 ++++++++++++++++++++++++++++++++++++++ golang/examples/guestfs-golang.pod | 1 + java/examples/guestfs-java.pod | 1 + lib/guestfs.pod | 5 ++- lua/examples/guestfs-lua.pod | 1 + ocaml/examples/guestfs-ocaml.pod | 1 + perl/examples/guestfs-perl.pod | 1 + python/examples/guestfs-python.pod | 1 + ruby/examples/guestfs-ruby.pod | 1 + 13 files changed, 98 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore index 7ccc928bb..774043501 100644 --- a/.gitignore +++ b/.gitignore @@ -283,6 +283,8 @@ Makefile.in /gobject/bindtests.js /gobject/Guestfs-1.0.gir /gobject/Guestfs-1.0.typelib +/gobject/guestfs-gobject.3 +/gobject/stamp-guestfs-gobject.pod /golang/bindtests.go /golang/examples/guestfs-golang.3 /golang/examples/stamp-guestfs-golang.pod diff --git a/docs/guestfs-recipes.pod b/docs/guestfs-recipes.pod index 7d772b8f2..11eb96ad7 100644 --- a/docs/guestfs-recipes.pod +++ b/docs/guestfs-recipes.pod @@ -722,6 +722,7 @@ L<guestfs(3)>, L<guestfish(1)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/erlang/examples/guestfs-erlang.pod b/erlang/examples/guestfs-erlang.pod index 89cbda15b..2f03b8281 100644 --- a/erlang/examples/guestfs-erlang.pod +++ b/erlang/examples/guestfs-erlang.pod @@ -96,6 +96,7 @@ C<Arg> is the name of the unknown argument. L<guestfs(3)>, L<guestfs-examples(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/gobject/Makefile.am b/gobject/Makefile.am index 677d7a3d2..ddedd5b51 100644 --- a/gobject/Makefile.am +++ b/gobject/Makefile.am @@ -31,6 +31,7 @@ EXTRA_DIST = \ TODO.txt \ .gitignore \ bindtests-retvalues.js \ + guestfs-gobject.pod \ tests-misc.js \ run-tests \ run-tests-retvalues \ @@ -88,6 +89,8 @@ gir_DATA = $(INTROSPECTION_GIRS) typelibdir = $(libdir)/girepository-1.0 typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib) +# Tests. + TESTS = \ run-tests \ run-tests-retvalues @@ -103,3 +106,19 @@ $(TESTS): $(typelib_DATA) CLEANFILES += $(gir_DATA) $(typelib_DATA) endif HAVE_INTROSPECTION + +# Documentation. + +man_MANS = guestfs-gobject.3 +noinst_DATA = $(top_builddir)/website/guestfs-gobject.3.html + +guestfs-gobject.3 $(top_builddir)/website/guestfs-gobject.3.html: stamp-guestfs-gobject.pod + +stamp-guestfs-gobject.pod: guestfs-gobject.pod + $(PODWRAPPER) \ + --section 3 \ + --man guestfs-gobject.3 \ + --html $(top_builddir)/website/guestfs-gobject.3.html \ + --license examples \ + $< + touch $@ diff --git a/gobject/guestfs-gobject.pod b/gobject/guestfs-gobject.pod new file mode 100644 index 000000000..c0c6839fb --- /dev/null +++ b/gobject/guestfs-gobject.pod @@ -0,0 +1,64 @@ +=head1 NAME + +guestfs-gobject - How to use libguestfs with the GObject bindings + +=head1 SYNOPSIS + +From Javascript using gjs: + + const Guestfs = imports.gi.Guestfs; + var g = new Guestfs.Session(); + g.add_drive('disk.img', null); + g.launch(); + g.close(); + +=head1 DESCRIPTION + +This manual page documents how to call libguestfs using GObject +bindings, especially from Javascript. + +Note that the GObject bindings have problems handling 64 bit values. +You should not use the GObject bindings if there are native bindings +for your language. For example, to use libguestfs from Python you are +strongly advised to use the Python native bindings instead (see +L<guestfs-python(3)>). + +This page just documents the differences from the C API and gives some +examples. If you are not familiar with using libguestfs, you also +need to read L<guestfs(3)>. + +=head1 JAVASCRIPT + +Using gjs, you can write a C<.js> file containing: + + const Guestfs = imports.gi.Guestfs; + var g = new Guestfs.Session(); + g.add_drive('disk.img', null); + g.launch(); + g.close(); + +and then run it using: + + gjs program.js + +=head1 SEE ALSO + +L<guestfs(3)>, +L<guestfs-examples(3)>, +L<guestfs-erlang(3)>, +L<guestfs-golang(3)>, +L<guestfs-java(3)>, +L<guestfs-lua(3)>, +L<guestfs-perl(3)>, +L<guestfs-python(3)>, +L<guestfs-recipes(1)>, +L<guestfs-ruby(3)>, +L<http://libguestfs.org/>. + +=head1 AUTHORS + +Richard W.M. Jones (C<rjones at redhat dot com>) + +=head1 COPYRIGHT + +Copyright (C) 2012-2017 Red Hat Inc. diff --git a/golang/examples/guestfs-golang.pod b/golang/examples/guestfs-golang.pod index c2de45ece..7b9c80ab4 100644 --- a/golang/examples/guestfs-golang.pod +++ b/golang/examples/guestfs-golang.pod @@ -78,6 +78,7 @@ UUIDs are not returned in structures. L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, L<guestfs-ocaml(3)>, diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod index bcff3889f..2d5627f62 100644 --- a/java/examples/guestfs-java.pod +++ b/java/examples/guestfs-java.pod @@ -161,6 +161,7 @@ on the class path, as well as the path of your program. For example: L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-lua(3)>, L<guestfs-ocaml(3)>, diff --git a/lib/guestfs.pod b/lib/guestfs.pod index f2a54a1fd..b87210e65 100644 --- a/lib/guestfs.pod +++ b/lib/guestfs.pod @@ -1141,7 +1141,9 @@ See L<guestfs-erlang(3)>. =item B<GObject> Experimental GObject bindings (with GObject Introspection support) are -available. See the C<gobject> directory in the source. +available. + +See L<guestfs-gobject(3)>. =item B<Go> @@ -3393,6 +3395,7 @@ L<guestfs-examples(3)>. Language bindings: L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/lua/examples/guestfs-lua.pod b/lua/examples/guestfs-lua.pod index 36ea297ba..09de8d4a8 100644 --- a/lua/examples/guestfs-lua.pod +++ b/lua/examples/guestfs-lua.pod @@ -138,6 +138,7 @@ returned when you registered the callback: L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-ocaml(3)>, diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod index 523a60466..2fa3d53c1 100644 --- a/ocaml/examples/guestfs-ocaml.pod +++ b/ocaml/examples/guestfs-ocaml.pod @@ -82,6 +82,7 @@ function that you called. L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/perl/examples/guestfs-perl.pod b/perl/examples/guestfs-perl.pod index 1042f6948..6a9cb0ab5 100644 --- a/perl/examples/guestfs-perl.pod +++ b/perl/examples/guestfs-perl.pod @@ -41,6 +41,7 @@ L<Sys::Guestfs(3)>, L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod index 0891827f6..8d4c2e51a 100644 --- a/python/examples/guestfs-python.pod +++ b/python/examples/guestfs-python.pod @@ -65,6 +65,7 @@ You can use it like this: L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, diff --git a/ruby/examples/guestfs-ruby.pod b/ruby/examples/guestfs-ruby.pod index 5e4e1879a..bd8bb3108 100644 --- a/ruby/examples/guestfs-ruby.pod +++ b/ruby/examples/guestfs-ruby.pod @@ -36,6 +36,7 @@ string). L<guestfs(3)>, L<guestfs-examples(3)>, L<guestfs-erlang(3)>, +L<guestfs-gobject(3)>, L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>, -- 2.13.2 _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://www.redhat.com/mailman/listinfo/libguestfs