From nobody Fri May 3 20:38:59 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1623073259; cv=none; d=zohomail.com; s=zohoarc; b=MqCwrciWTE69t5plVqr/HubO64ZCyDTSQm+TWqaIh+GYMb9nSwHMCa73t2dD9OJdD6UIo+d+4CFRJB8IW2WSl0o23PS64VjMIc7kZp+9x1gUv51TLmhJSXbT+e9A832yyt3fPu0RCkmPB72G4x0GE6JP+jPdTXvaNP2SOqdIDhI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1623073259; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=6h7+fZlR9C0mYVqOPGmIbw8Ckmf1whNTzsA/QAHAtvc=; b=b2a3OShmoQmkI5OudBDepJM7PXfauEfNFKrwi9RVUhJKuPVWqQd7qOAu9aQJfCPQnyi1xTtc/hEzaLKN7ba6mMcgwCeDnwXTRkaDE1uFYIa672UaMeodTitlPbmJDMh7fGxHe0OymLT2nehpyHWFtVWgtyLAtXfqhAMGVZEWB3Q= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1623073259589276.5368579577191; Mon, 7 Jun 2021 06:40:59 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-18-5_Pig2ZmPPSSLXfRNrpAsg-1; Mon, 07 Jun 2021 09:40:56 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D235D1020C3C; Mon, 7 Jun 2021 13:40:51 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 989C760862; Mon, 7 Jun 2021 13:40:48 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 879434BB40; Mon, 7 Jun 2021 13:40:45 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 157Dcecf001437 for ; Mon, 7 Jun 2021 09:38:40 -0400 Received: by smtp.corp.redhat.com (Postfix) id 1653C5D764; Mon, 7 Jun 2021 13:38:40 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-114-203.ams2.redhat.com [10.36.114.203]) by smtp.corp.redhat.com (Postfix) with ESMTP id 13B625D6D3; Mon, 7 Jun 2021 13:38:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1623073258; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=6h7+fZlR9C0mYVqOPGmIbw8Ckmf1whNTzsA/QAHAtvc=; b=WLvenaVjzTJuYR390z7whkoVFiygwOm4JJBTTQ+TsOT0AuqeyuTzefyceh3ZlIVEHV/Ct6 Yw8h9Z1azt/ZZMWcQqN0jOqyOLxPiZuit3uPg8IpI5aionoIOTvAR/ZJVwXUFzbm9ggNrP w7VA5Xs5vo38vW/VskAfZG7HHkNGkuI= X-MC-Unique: 5_Pig2ZmPPSSLXfRNrpAsg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH v3] docs: introduce stubs for new libvirt Go packages Date: Mon, 7 Jun 2021 14:38:34 +0100 Message-Id: <20210607133834.177009-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: Andrea Bolognani X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) 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=C3=A9 --- docs/go/libvirt.rst | 19 +++++++++++++++ docs/go/libvirtxml.rst | 16 +++++++++++++ docs/go/meson.build | 53 +++++++++++++++++++++++++++++++++++++++++ docs/libvirt-go-xml.rst | 24 ++++++++++++++----- docs/libvirt-go.rst | 23 ++++++++++++++---- docs/meson.build | 1 + 6 files changed, 125 insertions(+), 11 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..6a1344ad3e --- /dev/null +++ b/docs/go/libvirt.rst @@ -0,0 +1,19 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Go Language API (with Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The `Go `__ package ``libvirt.org/go/libvirt`` provid= es +`CGo `__ binding from the OS native Libvirt A= PI. + +This package replaces the obsolete `libvirt.org/libvirt-go +<../libvirt-go.html>`__ package in order to switch to using `semver +`__ and `Go modules `__. +Aside from the changed import path and versioning scheme, the API is fully +compatible with the legacy 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 `__. diff --git a/docs/go/libvirtxml.rst b/docs/go/libvirtxml.rst new file mode 100644 index 0000000000..5407d609f2 --- /dev/null +++ b/docs/go/libvirtxml.rst @@ -0,0 +1,16 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Go XML parsing API (with Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The `Go `__ package ``libvirt.org/go/libvirtxml`` pro= vides +annotated Go struct definitions for parsing (and formatting) XML documents= used +with libvirt APIs. + +This package replaces the obsolete `libvirt.org/libvirt-go-xml +<../libvirt-go-xml.html>`__ package in order to switch to using `semver +`__ and `Go modules `__. +Aside from the changed import path and versioning scheme, the API is fully +compatible with the original package. + +For details of Go specific behaviour consult the +`Go package documentation `_= _. 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 =3D [ + 'libvirt', + 'libvirtxml', +] + +html_xslt_gen_xslt =3D subsite_xsl +html_xslt_gen_install_dir =3D docs_html_dir / 'go' +html_xslt_gen =3D [] + +foreach name : docs_go_files + rst_file =3D '@0@.rst'.format(name) + + html_xslt_gen +=3D { + '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 =3D data['name'] + '.html' + + html_file =3D 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 +=3D html_file + install_web_files +=3D html_file.full_path() + ':' + html_xslt_gen_insta= ll_dir +endforeach + +html_xslt_gen =3D [] + +# --- end of XSLT processing --- diff --git a/docs/libvirt-go-xml.rst b/docs/libvirt-go-xml.rst index 995fdd2b07..43ebf50765 100644 --- a/docs/libvirt-go-xml.rst +++ b/docs/libvirt-go-xml.rst @@ -1,10 +1,22 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D -Libvirt Go XML parsing API -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +Obsolete libvirt Go XML parsing API (no Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =20 -The `Go `__ package ``libvirt.org/libvirt-go-xml`` pr= ovides -annotated Go struct definitions for parsing (and formatting) XML documents= used -with libvirt APIs. +This obsolete `Go `__ package ``libvirt.org/libvirt-g= o-xml`` +provided annotated Go struct definitions for parsing (and formatting) XML +documents used with libvirt APIs. + +This package is replaced by the new `libvirt.org/go/libvirtxml +`__ package in order to switch to using `semver +`__ and `Go modules `__. +Aside from the changed import path and versioning scheme, the new package = API +is fully compatible with this legacy package. + +Software currently using this package will keep working, but no further +development will take place. libvirt XML scheme elements/attributes introd= uced +after 7.4.0 will never be available. Authors are strongly recommended to s= witch +imports to point to the new package, to prepare for future Go toolchains +which will mandate Go module support and semver. =20 For details of Go specific behaviour consult the `Go package documentation `= __. diff --git a/docs/libvirt-go.rst b/docs/libvirt-go.rst index f2d3f80fb2..7dd78b5f6e 100644 --- a/docs/libvirt-go.rst +++ b/docs/libvirt-go.rst @@ -1,9 +1,22 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -Libvirt Go Language API -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Obsolete libvirt Go Language API (no Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The `Go `__ package ``libvirt.org/libvirt-go`` provid= es -`CGo `__ binding from the OS native Libvirt A= PI. +This obsolete `Go `__ package ``libvirt.org/libvirt-g= o`` +provided `CGo `__ binding from the OS native +Libvirt API. + +This package is replaced by the new `libvirt.org/go/libvirt `__ +package in order to switch to using `semver `__ and +`Go modules `__. Aside from the changed +import path and versioning scheme, the new package API is fully compatible +with this legacy package. + +Software currently using this package will keep working, but no further +development will take place. libvirt APIs/constants introduced after +7.4.0 will never be available. Authors are strongly recommended to switch +imports to point to the new package, to prepare for future Go toolchains +which will mandate Go module support and semver. =20 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 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 =3D [] # --- end of XSLT processing --- =20 subdir('fonts') +subdir('go') subdir('html') subdir('internals') subdir('js') --=20 2.31.1