Skip to contentSkip to conversation

initialize xenlight go module

PATCH Superseded Nick Rosbrook 2 participants 9 messages May 13, 2020

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover initialize xenlight go module

These patches setup an initial Go module for the xenlight package. The go code is tracked again, since the module is defined in xen.git as xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight. The final patch adds a README and LICENSE to tools/golang/xenlight so that the package will show up properly on pkg.go.dev and be available via the module proxy at proxy.golang.org.

Changes in v2:
- Use xenproject.org instead of xen.org in module path.
- Use go build instead of go install in xenlight Makefile.
- Use LGPL instead of GPL for xenlight LICENSE.
- Add entry for xenlight package in SUPPORT.md.
- Change some wording in the README for clarity.

Nick Rosbrook (3):
golang/xenlight: re-track generated go code golang/xenlight: init xenlight go module golang/xenlight: add necessary module/package documentation

 .gitignore                           |    3 -
 .hgignore                            |    2 -
 SUPPORT.md                           |    6 +
 tools/golang/xenlight/LICENSE        |  198 ++
 tools/golang/xenlight/Makefile       |    3 +-
 tools/golang/xenlight/README.md      |   17 +
 tools/golang/xenlight/go.mod         |    1 +
 tools/golang/xenlight/helpers.gen.go | 4728 ++++++++++++++++++++++++++
 tools/golang/xenlight/types.gen.go   | 1226 +++++++
 tools/golang/xenlight/xenlight.go    |    2 +
 10 files changed, 6179 insertions(+), 7 deletions(-)
 create mode 100644 tools/golang/xenlight/LICENSE
 create mode 100644 tools/golang/xenlight/README.md
 create mode 100644 tools/golang/xenlight/go.mod
 create mode 100644 tools/golang/xenlight/helpers.gen.go
 create mode 100644 tools/golang/xenlight/types.gen.go
Signature · 1 line
2.17.1
#2 lore raw

PATCH v2 2/3 golang/xenlight: init xenlight go module

Initialize the xenlight Go module using the xenbits git-http URL, xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight.

Also simplify the build Make target by using go build instead of go install, and do not set GOPATH here because it is now unnecessary.

---
Changes in v2:
- Use xenproject.org instead of xen.org in module path.
- Undo change to XEN_GOCODE_URL; just use go build.

---
 tools/golang/xenlight/Makefile | 2 +-
 tools/golang/xenlight/go.mod   | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 tools/golang/xenlight/go.mod
tools/golang/xenlight/Makefile +1 -1
index 753132306a..37ed1358c4 100644
@@ -33,7 +33,7 @@ $(XEN_GOPATH)/src/$(XEN_GOCODE_URL)/xenlight/: xenlight.go types.gen.go helpers.
 # so that it can find the actual library.
 .PHONY: build
 build: package
-	CGO_CFLAGS="$(CFLAGS_libxenlight) $(CFLAGS_libxentoollog)" CGO_LDFLAGS="$(LDLIBS_libxenlight) $(LDLIBS_libxentoollog) -L$(XEN_XENLIGHT) -L$(XEN_LIBXENTOOLLOG)" GOPATH=$(XEN_GOPATH) $(GO) install -x $(XEN_GOCODE_URL)/xenlight
+	CGO_CFLAGS="$(CFLAGS_libxenlight) $(CFLAGS_libxentoollog)" CGO_LDFLAGS="$(LDLIBS_libxenlight) $(LDLIBS_libxentoollog) -L$(XEN_XENLIGHT) -L$(XEN_LIBXENTOOLLOG)" $(GO) build -x
 
 .PHONY: install
 install: build
tools/golang/xenlight/go.mod new file +1 -0
new file mode 100644
index 0000000000..926474d929
@@ -0,0 +1 @@
+module xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight
Signature · 1 line
2.17.1
#1 lore raw

PATCH v2 1/3 golang/xenlight: re-track generated go code

In reply to Nick Rosbrook

Commit df669de074c395a3b2eeb975fddd3da4c148da13 un-tracked the generated Go code, but it was decided that we actually keep the generated code in-tree.

Undo the changes to ignore the generated code, and re-generate it.

---
 .gitignore                           |    3 -
 .hgignore                            |    2 -
 tools/golang/xenlight/Makefile       |    1 -
 tools/golang/xenlight/helpers.gen.go | 4728 ++++++++++++++++++++++++++
 tools/golang/xenlight/types.gen.go   | 1226 +++++++
 5 files changed, 5954 insertions(+), 6 deletions(-)
 create mode 100644 tools/golang/xenlight/helpers.gen.go
 create mode 100644 tools/golang/xenlight/types.gen.go
.gitignore +0 -3
index 9c8a31f896..bfa53723b3 100644
@@ -406,9 +406,6 @@ tools/xenstore/xenstore-watch
 tools/xl/_paths.h
 tools/xl/xl
 
-tools/golang/src
-tools/golang/*/*.gen.go
-
 docs/txt/misc/*.txt
 docs/txt/man/*.txt
 docs/figs/*.png
.hgignore +0 -2
index 2ec52982e1..2d41670632 100644
@@ -282,8 +282,6 @@
 ^tools/ocaml/test/xtl$
 ^tools/ocaml/test/send_debug_keys$
 ^tools/ocaml/test/list_domains$
-^tools/golang/src$
-^tools/golang/.*/.*\.gen\.go$
 ^tools/autom4te\.cache$
 ^tools/config\.h$
 ^tools/config\.log$
tools/golang/xenlight/Makefile +0 -1
index 144c133ced..753132306a 100644
@@ -49,7 +49,6 @@ install: build
 clean:
 	$(RM) -r $(XEN_GOPATH)$(GOXL_PKG_DIR)
 	$(RM) $(XEN_GOPATH)/pkg/*/$(XEN_GOCODE_URL)/xenlight.a
-	$(RM) *.gen.go
 
 .PHONY: distclean
 distclean: clean
tools/golang/xenlight/helpers.gen.go new file +4728 -0

2,976 lines not on this page · raw message

tools/golang/xenlight/types.gen.go new file +1226 -0

1,226 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.17.1

Part of the diff is not shown here. View the raw message.

#4 lore raw

PATCH v2 3/3 golang/xenlight: add necessary module/package documentation

In reply to Nick Rosbrook

Add a README and package comment giving a brief overview of the package. These also help pkg.go.dev generate better documentation.

Also, add a copy of the LGPL (the same license used by libxl) to tools/golang/xenlight. This is required for the package to be shown on pkg.go.dev and added to the default module proxy, proxy.golang.org.

Finally, add an entry for the xenlight package to SUPPORT.md.

---
Changes in v2:
- Use LGPL instead of GPL for license.
- Change some wording in README for clarity.
- Add entry to SUPPORT.md for xenlight package.

---
 SUPPORT.md                        |   6 +
 tools/golang/xenlight/LICENSE     | 198 ++++++++++++++++++++++++++++++
 tools/golang/xenlight/README.md   |  17 +++
 tools/golang/xenlight/xenlight.go |   2 +
 4 files changed, 223 insertions(+)
 create mode 100644 tools/golang/xenlight/LICENSE
 create mode 100644 tools/golang/xenlight/README.md
SUPPORT.md +6 -0
index 7270c9b021..e3a366fd56 100644
@@ -147,6 +147,12 @@ Output of information in machine-parseable JSON format
 
     Status: Supported
 
+### xenlight Go package
+
+Go (golang) bindings for libxl
+
+    Status: Experimental
+
 ## Toolstack/3rd party
 
 ### libvirt driver for xl
tools/golang/xenlight/LICENSE new file +198 -0

198 lines not on this page · raw message

tools/golang/xenlight/README.md new file +17 -0
new file mode 100644
index 0000000000..046f86ab3e
@@ -0,0 +1,17 @@
+# xenlight
+
+## About
+
+The xenlight package provides Go bindings to Xen's libxl C library via cgo. The package is currently in an unstable "experimental" state. This means the package is ready for initial use and evaluation, but is not yet fully functional. Namely, only a subset of libxl's API is implemented, and breaking changes may occur in future package versions.
+
+Much of the package is generated using the libxl IDL. Changes to the generated code can be made by modifying `tools/golang/xenlight/gengotypes.py` in the xen.git tree.
+
+## Getting Started
+
+```go
+import (
+        "xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight"
+)
+```
+
+The module is not yet tagged independently of xen.git; if you don’t specify the version, you’ll get the most recent development version, which is probably not what you want.  A better option would be to specify a Xen release tag; for instance: `go get xenbits.xenproject.org/git-http/xen.git/tools/golang/[email protected]`.
tools/golang/xenlight/xenlight.go +2 -0
index 6b4f492550..3eaa5a3d63 100644
@@ -14,6 +14,8 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; If not, see <http://www.gnu.org/licenses/>.
  */
+
+// Package xenlight provides bindings to Xen's libxl C library.
 package xenlight
 
 /*
Signature · 1 line
2.17.1
#3 lore raw

Re: [PATCH v2 2/3] golang/xenlight: init xenlight go module

In reply to Nick Rosbrook
Quoted 9 lines · Nick Rosbrook

Initialize the xenlight Go module using the xenbits git-http URL, xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight.

Also simplify the build Make target by using go build instead of go install, and do not set GOPATH here because it is now unnecessary.

Glad you caught the GOPATH thing. :-)

Quoted 2 lines
Reviewed-by on v2 3/3
#5 lore raw

Re: [PATCH v2 3/3] golang/xenlight: add necessary module/package documentation

In reply to Nick Rosbrook
Quoted 6 lines · Nick Rosbrook

Add a README and package comment giving a brief overview of the package. These also help pkg.go.dev generate better documentation.

One thing I forgot to mention about the README is the long lines — do you mind if I wrap those before checking it in?

Quoted 7 lines

Also, add a copy of the LGPL (the same license used by libxl) to tools/golang/xenlight. This is required for the package to be shown on pkg.go.dev and added to the default module proxy, proxy.golang.org.

Finally, add an entry for the xenlight package to SUPPORT.md.

#6 lore raw

Re: [PATCH v2 3/3] golang/xenlight: add necessary module/package documentation

Quoted 1 line

One thing I forgot to mention about the README is the long lines — do you mind if I wrap those before checking it in?

I don't mind at all.

Quoted 9 lines
Quoted 7 lines

Also, add a copy of the LGPL (the same license used by libxl) to tools/golang/xenlight. This is required for the package to be shown on pkg.go.dev and added to the default module proxy, proxy.golang.org.

Finally, add an entry for the xenlight package to SUPPORT.md.

Thanks!

-NR

#7 lore raw

Re: [PATCH v2 3/3] golang/xenlight: add necessary module/package documentation

In reply to Nick Rosbrook
Quoted 9 lines · Nick Rosbrook

Add a README and package comment giving a brief overview of the package. These also help pkg.go.dev generate better documentation.

Also, add a copy of the LGPL (the same license used by libxl) to tools/golang/xenlight. This is required for the package to be shown on pkg.go.dev and added to the default module proxy, proxy.golang.org.

OK, so didn’t notice this at first. It looks like you read the comments at the top of libxl.c, noticed the comment about “...the special exception on linking described in file LICENSE”, looked around for such a file, and found it in tools/ocaml, and copied that one?

I had a chat with Ian Jackson on IRC (copied below for the record), and think that comment is simply in error. We agreed that we should just copy https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt into the directory verbatim.

-George

12:49:40           gwd | Hmm... libxl is supposedly under the LGPL, but I can't   
                       | seem to find a copy of it in our source tree             
12:50:01           gwd | Oh, there's one in tools/libxc                           
12:54:44           gwd | Diziet: The comment at the top of libxl.c refers to      
                       | "...the special exception on linking described in file   
                       | LICENSE."  But there's no such file in tools/libxl       
12:55:22           gwd | The most plausible candidate for what it's talking about 
                       | is tools/ocaml/LICENSE                                   
12:59:43        Diziet | Weird                                                    
13:00:16        Diziet | That text is present in                                  
                       | c5c301ac774d8cb36ccbc775bb7f1d7005d78a71 "libxenlight:   
                       | initial libxenlight implementation under tools/libxl"    
13:00:39        Diziet | There is no file LICENSE other than                      
                       | xen/tools/figlet/LICENSE                                 
13:00:57        Diziet | Which is a copy of the Artistic License and not          
                       | relevant.                                                
13:01:18        Diziet | However,                                                 
13:01:43        Diziet | | Licensing Exceptions (the relaxed BSD-style license)   
13:01:47        Diziet | ^ in the top-level COPYING                               
13:02:30        Diziet | I don't think this is an "exception on linking" and it   
                       | doesn't state that it applies to libxl.                  
13:03:29        Diziet | The phrase "exception on linking" appears only in libxl  
                       | in thta commit                                           
13:04:05        Diziet | https://github.com/xapi-project/xen-api/blob/master/ocam 
                       | l/idl/datamodel.ml                                       
13:04:31        Diziet | https://github.com/xapi-project/xen-api/blob/master/LICE 
                       | NSE                                                      
13:04:40        Diziet | I think that is probably what was intended to be         
                       | referred to.                                             
13:05:24        Diziet | And indeed that text appears in tools/ocaml              
13:06:59        Diziet | This is an additional permission (borrowing GPLv3        
                       | terminology) which a downstream can drop.                
13:07:39        Diziet | Furthermore I don't think anyone's S-o-b for a libxl     
                       | commit can be taken to have meant to include that        
                       | exception.  So I conclude that no exception in fact      
                       | applies and the text referring to it should be deleted.  
13:07:53        Diziet | gwd: ^                                                   
13:13:29           --> | zhengc ([email protected]) has joined #xendevel     
13:17:55           <-- | zhengc ([email protected]) has quit (Ping timeout:   
                       | 258 seconds)                                             
13:28:11           gwd | Diziet: OK -- this came up actually in the context of    
                       | "[PATCH v2 3/3] golang/xenlight: add necessary           
                       | module/package documentation"                            
13:28:48           gwd | golang has this automatic package proxy / cataloging     
                       | system                                                   
13:29:24           gwd | To have it work the way he wants it, the golang/xenlight 
                       | directory needs something that their system can          
                       | recognize as a suitable license                          
13:30:20           gwd | v1 had the GPL, which was just wrong; it looks like he's 
                       | then followed the same path I did, looking at libxl.c,   
                       | trying to find this "exception" thing, and copying the   
                       | file f/ tools/ocaml                                      
13:30:58           gwd | I guess I should tell him to just copy                   
                       | https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt   
13:31:37        Diziet | y
#8 lore raw

Re: [PATCH v2 3/3] golang/xenlight: add necessary module/package documentation

Quoted 3 lines

OK, so didn’t notice this at first. It looks like you read the comments at the top of libxl.c, noticed the comment about “...the special exception on linking described in file LICENSE”, looked around for such a file, and found it in tools/ocaml, and copied that one?

I had a chat with Ian Jackson on IRC (copied below for the record), and think that comment is simply in error. We agreed that we should just copy https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt into the directory verbatim.

Yeah that's what I did. I'll send a corrected patch shortly.

Thanks,
-NR