openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
libvirt/docs/libvirt-go.rst

27 lines
1.2 KiB
ReStructuredText
Raw Normal View History

docs: introduce stubs for new libvirt Go packages 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. Reviewed-by: Andrea Bolognani <abologna@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-05-25 18:42:32 +08:00
================================================
Obsolete libvirt Go Language API (no Go modules)
================================================
docs: add pages to support Go module package resolution Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace. When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository. https://golang.org/cmd/go/#hdr-Remote_import_paths This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation. Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L] Reviewed-by: Jiri Denemark <jdenemar@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-12-16 18:06:50 +08:00
docs: introduce stubs for new libvirt Go packages 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. Reviewed-by: Andrea Bolognani <abologna@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-05-25 18:42:32 +08:00
The obsolete `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go``
provided `CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native
Libvirt API.
This package is replaced by the new `libvirt.org/go/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 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.
docs: add pages to support Go module package resolution Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace. When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository. https://golang.org/cmd/go/#hdr-Remote_import_paths This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation. Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L] Reviewed-by: Jiri Denemark <jdenemar@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-12-16 18:06:50 +08:00
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
docs: Point to pkg.go.dev instead of godoc.org The former is the new recommended frontend for browsing Go API documentation online. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-07 18:37:37 +08:00
`Go package documentation <https://pkg.go.dev/libvirt.org/libvirt-go>`__.