docs/go/libvirt.rst | 18 ++++++++++++++ docs/go/libvirtxml.rst | 15 ++++++++++++ docs/go/meson.build | 53 +++++++++++++++++++++++++++++++++++++++++ docs/libvirt-go-xml.rst | 12 +++++++--- docs/libvirt-go.rst | 12 +++++++--- docs/meson.build | 1 + 6 files changed, 105 insertions(+), 6 deletions(-) create mode 100644 docs/go/libvirt.rst create mode 100644 docs/go/libvirtxml.rst create mode 100644 docs/go/meson.build
Currently we expose libvirt Go packages at
libvirt.org/libvirt-go
libvirt.org/libvirt-go-xml
These packages have not supported Go modules historically and when we
tried to introduce modules, we hit the problem that we're not using
semver for versioning.
The only way around this is to introduce new packages under a different
namespace, that will have the exact same code, but be tagged with a
different version numbering scheme.
This change proposes:
libvirt.org/go/libvirt
libvirt.org/go/libvirtxml
Note the hyphen is removed so that the import basename matches the
Go package name.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
docs/go/libvirt.rst | 18 ++++++++++++++
docs/go/libvirtxml.rst | 15 ++++++++++++
docs/go/meson.build | 53 +++++++++++++++++++++++++++++++++++++++++
docs/libvirt-go-xml.rst | 12 +++++++---
docs/libvirt-go.rst | 12 +++++++---
docs/meson.build | 1 +
6 files changed, 105 insertions(+), 6 deletions(-)
create mode 100644 docs/go/libvirt.rst
create mode 100644 docs/go/libvirtxml.rst
create mode 100644 docs/go/meson.build
diff --git a/docs/go/libvirt.rst b/docs/go/libvirt.rst
new file mode 100644
index 0000000000..df74660b5f
--- /dev/null
+++ b/docs/go/libvirt.rst
@@ -0,0 +1,18 @@
+=================================================
+Libvirt Go Language API (semver, with Go modules)
+=================================================
+
+The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirt`` provides
+`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API.
+
+This package replaces the original `libvirt-go <../libvirt-go.html>`__
+package in order to switch to using `semver <https://semver.org/>`__ and
+`Go modules <https://golang.org/ref/mod>`__. Aside from the changed
+import path, the API is fully compatible with the original package.
+
+In general the Go representation is a direct 1-1 mapping from native API
+concepts to Go, so the native API documentation should serve as a reference
+for most behaviour.
+
+For details of Go specific behaviour consult the
+`Go package documentation <https://pkg.go.dev/libvirt.org/go/libvirt>`__.
diff --git a/docs/go/libvirtxml.rst b/docs/go/libvirtxml.rst
new file mode 100644
index 0000000000..70b2aca594
--- /dev/null
+++ b/docs/go/libvirtxml.rst
@@ -0,0 +1,15 @@
+====================================================
+Libvirt Go XML parsing API (semver, with Go modules)
+====================================================
+
+The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirtxml`` provides
+annotated Go struct definitions for parsing (and formatting) XML documents used
+with libvirt APIs.
+
+This package replaces the original `libvirt-go-xml <../libvirt-go-xml.html>`__
+package in order to switch to using `semver <https://semver.org/>`__ and
+`Go modules <https://golang.org/ref/mod>`__. Aside from the changed
+import path, the API is fully compatible with the original package.
+
+For details of Go specific behaviour consult the
+`Go package documentation <https://pkg.go.dev/libvirt.org/go/libvirtxml>`__.
diff --git a/docs/go/meson.build b/docs/go/meson.build
new file mode 100644
index 0000000000..d2accd322b
--- /dev/null
+++ b/docs/go/meson.build
@@ -0,0 +1,53 @@
+docs_go_files = [
+ 'libvirt',
+ 'libvirtxml',
+]
+
+html_xslt_gen_xslt = subsite_xsl
+html_xslt_gen_install_dir = docs_html_dir / 'go'
+html_xslt_gen = []
+
+foreach name : docs_go_files
+ rst_file = '@0@.rst'.format(name)
+
+ html_xslt_gen += {
+ 'name': name,
+ 'file': docs_rst2html_gen.process(rst_file),
+ 'source': 'docs' / 'go' / rst_file,
+ }
+endforeach
+
+# keep the XSLT processing code block in sync with docs/meson.build
+
+# --- begin of XSLT processing ---
+
+foreach data : html_xslt_gen
+ html_filename = data['name'] + '.html'
+
+ html_file = custom_target(
+ html_filename,
+ input: data.get('file', data['name'] + '.html.in'),
+ output: html_filename,
+ command: [
+ xsltproc_prog,
+ '--stringparam', 'pagesrc', data.get('source', ''),
+ '--stringparam', 'builddir', meson.build_root(),
+ '--stringparam', 'timestamp', docs_timestamp,
+ '--nonet',
+ html_xslt_gen_xslt,
+ '@INPUT@',
+ ],
+ depends: data.get('depends', []),
+ depend_files: [ page_xsl ],
+ capture: true,
+ install: true,
+ install_dir: html_xslt_gen_install_dir,
+ )
+
+ install_web_deps += html_file
+ install_web_files += html_file.full_path() + ':' + html_xslt_gen_install_dir
+endforeach
+
+html_xslt_gen = []
+
+# --- end of XSLT processing ---
diff --git a/docs/libvirt-go-xml.rst b/docs/libvirt-go-xml.rst
index 995fdd2b07..11954043c9 100644
--- a/docs/libvirt-go-xml.rst
+++ b/docs/libvirt-go-xml.rst
@@ -1,10 +1,16 @@
-==========================
-Libvirt Go XML parsing API
-==========================
+==================================================
+Libvirt Go XML parsing API (calver, no Go modules)
+==================================================
The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go-xml`` provides
annotated Go struct definitions for parsing (and formatting) XML documents used
with libvirt APIs.
+This package is replaced by the new `libvirt <go/libvirtxml.html>`__
+package in order to switch to using `semver <https://semver.org/>`__ and
+`Go modules <https://golang.org/ref/mod>`__. Aside from the changed
+import path, the new package API is fully compatible with this original
+package.
+
For details of Go specific behaviour consult the
`Go package documentation <https://pkg.go.dev/libvirt.org/libvirt-go-xml>`__.
diff --git a/docs/libvirt-go.rst b/docs/libvirt-go.rst
index f2d3f80fb2..7fc1a430a9 100644
--- a/docs/libvirt-go.rst
+++ b/docs/libvirt-go.rst
@@ -1,10 +1,16 @@
-=======================
-Libvirt Go Language API
-=======================
+===============================================
+Libvirt Go Language API (calver, no Go modules)
+===============================================
The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` provides
`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API.
+This package is replaced by the new `libvirt <go/libvirt.html>`__
+package in order to switch to using `semver <https://semver.org/>`__ and
+`Go modules <https://golang.org/ref/mod>`__. Aside from the changed
+import path, the new package API is fully compatible with this original
+package.
+
In general the Go representation is a direct 1-1 mapping from native API
concepts to Go, so the native API documentation should serve as a reference
for most behaviour.
diff --git a/docs/meson.build b/docs/meson.build
index bee0d80d53..4497f7270f 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -297,6 +297,7 @@ html_xslt_gen = []
# --- end of XSLT processing ---
subdir('fonts')
+subdir('go')
subdir('html')
subdir('internals')
subdir('js')
--
2.31.1
On Fri, Jun 04, 2021 at 03:46:59PM +0100, Daniel P. Berrangé wrote: > +================================================= > +Libvirt Go Language API (semver, with Go modules) > +================================================= "with Go modules support", perhaps? > +The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirt`` provides > +`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API. > + > +This package replaces the original `libvirt-go <../libvirt-go.html>`__ I would go with the original canonical (though not enforced) import path here, so "libvirt.org/libvirt-go" instead of just "libvirt-go". > +package in order to switch to using `semver <https://semver.org/>`__ and > +`Go modules <https://golang.org/ref/mod>`__. Aside from the changed > +import path ... and the different versioning scheme, ... > the API is fully compatible with the original package. [...] > +=============================================== > +Libvirt Go Language API (calver, no Go modules) > +=============================================== I don't think "calver" is as immediately understood as "semver". I would keep things simple and just write "obsolete" here. > The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` provides > `CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API. > > +This package is replaced by the new `libvirt <go/libvirt.html>`__ > +package in order to switch to using `semver <https://semver.org/>`__ and > +`Go modules <https://golang.org/ref/mod>`__. Aside from the changed > +import path, the new package API is fully compatible with this original > +package. I would prefer to have much stronger wording here, along the lines of The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` has been replaced by the new `libvirt.org/go/libvirt <go/libvirt.html>` package and is now considered obsolete. Software using the old package will keep working, but no further development will happen on it; in particular, libvirt APIs introduced after 7.4.0 are never going to be available to users of the old package. If your application uses the old ``libvirt.org/libvirt-go`` package, we strongly encourage you to migrate to the new ``libvirt.org/go/libvirt`` package: as the new package is fully backwards compatible with the old one, this should be as easy as changing all occurrences of the import path. Since the technical part of the patch is solid, if you'd rather avoid respinning and would prefer me to propose these changes as follow-up adjustments, you can consider your version Reviewed-by: Andrea Bolognani <abologna@redhat.com> and push it without any further ado :) -- Andrea Bolognani / Red Hat / Virtualization
© 2016 - 2024 Red Hat, Inc.