cwrap

package module
v0.0.0-...-5577cdf Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2023 License: BSD-2-Clause Imports: 18 Imported by: 0

README

Cwrap: Wraps C libraries in Go

Cwrap is a Go wrapper generator for C libraries.

Features

  • No Cgo types exposed out of the wrapper package, and uses as less allocation/copy as possible.
  • C name prefix mapped to Go packages, and a wrapper package can import another wrapper package.
  • Follows Go naming conventions.
  • C union.
  • Use Go language features when possible:
    • string and bool.
    • Multiple return values.
    • Slice, slice of slice and slice of string.
    • struct with methods.
    • Go closures as callbacks.
  • Stay out of the way when you need to do it manually for specified declarations.

Usage

Cwrap itself is a Go package rather than an executable program. Just fill a cwrap.Package struct literal and call it's Wrap method to generate your wrapper package under $GOPATH. Here is a simple example:

Say you want to generate a wrapper package for SDL2, and its header is at

/usr/local/include/SDL2/SDL2.h

So the cwrap.Package literal looks like:

var sdl = &Package{
	PacName: "sdl",
	PacPath: "go-sdl",
	From: Header{
		Dir:           "/usr/local/include/",
		File:          "SDL2/SDL.h",
		OtherCode:     "#define _SDL_main_h",
		NamePattern:   `\ASDL(.*)`,
		Excluded:      []string{},
		CgoDirectives: []string{"pkg-config: sdl2"},
		BoolTypes:     []string{"SDL_bool"},
	},
	Included: []*Package{},
}

Then just call

err := sdl.Wrap()

Examples

In the examples directory, there are C libraries that I have successfully applied Cwrap, including:

  • Cairo
  • GSL (GNU Scientific Library)
  • MuPDF
  • PLplot
  • SDL2 (Simple DirectMedia Layer)

You are very welcome to submit examples you think useful to others.

Applications

Issue Report

Cwrap may not cover every possible case and fails to come up with a corrresonding Go type or convertion, then the generated code may not be able to compile. When this happens, do the following steps:

  1. Comment out the failed function wrappers till it compiles.
  2. Add the C names of these failed functions to the excluded list (Package.From.Excluded).
  3. Submit the generator example to me. I cannot guarantee anything but I will try to fix critical issues.

TODO

  • Go idiomatic error handling (return error for each function/method).
  • Godoc documentation.
  • Alignment and padding of generated Go struct fields may need more careful checking (It just works fine for now, and I won't spend time on this until a real bug is found).

Limitations

  • C variadic functions (...) are not supported.

Acknowledgement

Cwrap uses gccxml (http://gccxml.github.io) to parse C headers to an XML file. Thanks very much for their excellent work.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	NumConv = &convImpl{conv, conv}
	PtrConv = &convImpl{convPtr, convPtr}
	ValConv = &convImpl{convValue, convValue}
)
View Source 
var (
	GOPATHs   = filepath.SplitList(os.Getenv("GOPATH"))
	OutputDir = func() string {
		if len(GOPATHs) > 0 {
			return GOPATHs[0] + "/src/"
		}
		return "."
	}()
)
View Source 
var (
	MachineSize = int(unsafe.Sizeof(uintptr(0)))
)

Functions

func IsEnum 

func IsEnum(v interface{}) bool

func IsFunc 

func IsFunc(v interface{}) bool

func IsVoid 

func IsVoid(v interface{}) bool

func Wrap 

func Wrap(err error) error

func Wrapf 

func Wrapf(err error, format string, v ...interface{}) error

Types

type Argument 

type Argument struct {
	// contains filtered or unexported fields
}

func NewArgument 

func NewArgument(goName, cgoName string, typ Type) *Argument

func (*Argument) CgoName 

func (a *Argument) CgoName() string

func (*Argument) CgoTypeName 

func (a *Argument) CgoTypeName() string

func (*Argument) GoName 

func (a *Argument) GoName() string

func (*Argument) GoTypeName 

func (a *Argument) GoTypeName() string

func (*Argument) IsOut 

func (a *Argument) IsOut() bool

func (*Argument) IsPtr 

func (a *Argument) IsPtr() bool

func (*Argument) ToCgo 

func (a *Argument) ToCgo(w io.Writer, assign string)

func (*Argument) ToGo 

func (a *Argument) ToGo(w io.Writer, assign string)

func (*Argument) Type 

func (a *Argument) Type() Type

type Arguments 

type Arguments []*Argument

func (Arguments) ToParams 

func (as Arguments) ToParams() Params

type Array 

type Array struct {
	// contains filtered or unexported fields
}

func (*Array) CgoName 

func (a *Array) CgoName() string

func (*Array) GoName 

func (a *Array) GoName() string

func (*Array) Size 

func (a *Array) Size() int

func (*Array) ToCgo 

func (a *Array) ToCgo(w io.Writer, assign, g, c string)

func (*Array) ToGo 

func (a *Array) ToGo(w io.Writer, assign, g, c string)

func (*Array) WriteSpec 

func (a *Array) WriteSpec(w io.Writer)

type Bool 

type Bool struct {
	// contains filtered or unexported fields
}

func (*Bool) CgoName 

func (t *Bool) CgoName() string

func (*Bool) GoName 

func (t *Bool) GoName() string

func (*Bool) SetGoName 

func (t *Bool) SetGoName(n string)

func (*Bool) ToCgo 

func (n *Bool) ToCgo(w io.Writer, assign, g, c string)

func (*Bool) ToGo 

func (n *Bool) ToGo(w io.Writer, assign, g, c string)

type CNamer 

type CNamer interface {
	Id() string
	CName() string
	File() string
}

type CallbackFunc 

type CallbackFunc struct {
	CallbackIndex int

	CType *gccxml.FunctionType
	// contains filtered or unexported fields
}

func (*CallbackFunc) CgoName 

func (f *CallbackFunc) CgoName() string

func (CallbackFunc) Declare 

func (f CallbackFunc) Declare(w io.Writer)

func (CallbackFunc) GoName 

func (t CallbackFunc) GoName() string

func (*CallbackFunc) ToCgo 

func (f *CallbackFunc) ToCgo(w io.Writer, assign, g, c string)

func (*CallbackFunc) ToGo 

func (f *CallbackFunc) ToGo(w io.Writer, assign, g, c string)

func (*CallbackFunc) WriteSpec 

func (f *CallbackFunc) WriteSpec(w io.Writer)

type CallbackReturnPtr 

type CallbackReturnPtr struct {
	*ReturnPtr
}

func (CallbackReturnPtr) ToCgo 

func (s CallbackReturnPtr) ToCgo(w io.Writer, assign, g, c string)

type CgoNamer 

type CgoNamer interface {
	CgoName() string
}

type Conv 

type Conv interface {
	ToCgo(w io.Writer, assign, g, c, ctype string)
	ToGo(w io.Writer, assign, g, c, gtype string)
}

type ConvFunc 

type ConvFunc func(io.Writer, string, string, string, string)

type Decl 

type Decl interface {
	CNamer
	GoNamer
	GoNameSetter
	SpecWriter
}

type Enum 

type Enum struct {
	Values []EnumValue
	Methods
	// contains filtered or unexported fields
}

func (Enum) CName 

func (e Enum) CName() string

func (*Enum) CgoName 

func (t *Enum) CgoName() string

func (Enum) File 

func (e Enum) File() string

func (*Enum) GoName 

func (e *Enum) GoName() string

func (Enum) Id 

func (e Enum) Id() string

func (*Enum) SetGoName 

func (t *Enum) SetGoName(n string)

func (*Enum) Size 

func (t *Enum) Size() int

func (*Enum) ToCgo 

func (t *Enum) ToCgo(w io.Writer, assign, g, c string)

func (*Enum) ToGo 

func (t *Enum) ToGo(w io.Writer, assign, g, c string)

func (*Enum) WriteMethods 

func (e *Enum) WriteMethods(w io.Writer)

func (*Enum) WriteSpec 

func (e *Enum) WriteSpec(w io.Writer)

type EnumValue 

type EnumValue struct {
	// contains filtered or unexported fields
}

func (EnumValue) CName 

func (e EnumValue) CName() string

func (EnumValue) File 

func (e EnumValue) File() string

func (*EnumValue) GoName 

func (v *EnumValue) GoName() string

func (EnumValue) Id 

func (e EnumValue) Id() string

type EqualType 

type EqualType interface {
	Type
	Size() int
	SpecWriter
}

type Error 

type Error struct {
	// contains filtered or unexported fields
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Format 

func (e *Error) Format(f fmt.State, verb rune)

Format implements fmt.Formatter

func (*Error) FormatError 

func (e *Error) FormatError(p xerrors.Printer) error

FormatError implements xerrors.Formatter

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap implements xerrors.Wrapper

type FuncType 

type FuncType struct {
	// contains filtered or unexported fields
}

func (*FuncType) CgoName 

func (t *FuncType) CgoName() string

func (*FuncType) GoName 

func (t *FuncType) GoName() string

func (*FuncType) SetGoName 

func (t *FuncType) SetGoName(n string)

func (*FuncType) Size 

func (t *FuncType) Size() int

func (*FuncType) ToCgo 

func (t *FuncType) ToCgo(w io.Writer, assign, g, c string)

func (*FuncType) ToGo 

func (t *FuncType) ToGo(w io.Writer, assign, g, c string)

func (*FuncType) WriteSpec 

func (t *FuncType) WriteSpec(w io.Writer)

type Function 

type Function struct {
	// contains filtered or unexported fields
}

func (Function) CName 

func (e Function) CName() string

func (*Function) CgoName 

func (f *Function) CgoName() string

func (*Function) ConvertToMethod 

func (f *Function) ConvertToMethod() (*Method, bool)

func (Function) File 

func (e Function) File() string

func (*Function) GoName 

func (f *Function) GoName() string

func (Function) Id 

func (e Function) Id() string

func (*Function) SetGoName 

func (f *Function) SetGoName(n string)

func (*Function) ToCgo 

func (f *Function) ToCgo(w io.Writer, assign, g, c string)

func (*Function) ToGo 

func (f *Function) ToGo(w io.Writer, assign, g, c string)

func (*Function) WriteSpec 

func (f *Function) WriteSpec(w io.Writer)

type GoNameSetter 

type GoNameSetter interface {
	SetGoName(string)
}

type GoNamer 

type GoNamer interface {
	GoName() string
}
type Header struct {
	Dir         string
	File        string
	NamePattern string
	OtherCode   string
	// Not define it in the package, but may still searchable as included types
	// because it may be manually defined.
	Excluded      []string
	CgoDirectives []string
	BoolTypes     []string
	GccXmlArgs    []string
}

func (Header) FullPath 

func (h Header) FullPath() string

func (Header) Write 

func (h Header) Write(w io.Writer)

type Method 

type Method struct {
	*Function
	Receiver ReceiverArg
}

func (Method) CName 

func (e Method) CName() string

func (Method) CgoName 

func (f Method) CgoName() string

func (*Method) Declare 

func (m *Method) Declare(w io.Writer)

func (Method) File 

func (e Method) File() string

func (Method) Id 

func (e Method) Id() string

func (Method) ToCgo 

func (f Method) ToCgo(w io.Writer, assign, g, c string)

func (Method) ToGo 

func (f Method) ToGo(w io.Writer, assign, g, c string)

type Methods 

type Methods []*Method

func (*Methods) AddMethod 

func (ms *Methods) AddMethod(method *Method)

func (*Methods) Has 

func (ms *Methods) Has(methodName string) bool

func (*Methods) OptimizeNames 

func (ms *Methods) OptimizeNames(typeName string)

func (*Methods) WriteMethods 

func (ms *Methods) WriteMethods(w io.Writer)

type MethodsWriter 

type MethodsWriter interface {
	WriteMethods(w io.Writer)
}

type NameOptimizer 

type NameOptimizer interface {
	OptimizeNames()
}

type Num 

type Num struct {
	// contains filtered or unexported fields
}

func NewNum 

func NewNum(goName, cgoName string, size int) *Num

func (*Num) CgoName 

func (t *Num) CgoName() string

func (*Num) GoName 

func (t *Num) GoName() string

func (*Num) SetGoName 

func (t *Num) SetGoName(n string)

func (*Num) Size 

func (t *Num) Size() int

func (*Num) ToCgo 

func (t *Num) ToCgo(w io.Writer, assign, g, c string)

func (*Num) ToGo 

func (t *Num) ToGo(w io.Writer, assign, g, c string)

func (*Num) WriteSpec 

func (t *Num) WriteSpec(w io.Writer)

type Package 

type Package struct {
	// Required
	PacName string
	PacPath string
	From    Header

	// Optional
	Included []*Package
	GoFile   string
	CFile    string
	HFile    string
	TypeRule map[string]string
	ArgRule  map[string]string

	// intermediate
	Functions   []*Function
	Callbacks   []CallbackFunc
	TypeDeclMap TypeDeclMap
	Variables   []*Variable

	Statistics
	*gcc.XmlDoc
	// contains filtered or unexported fields
}

func (*Package) GenConst 

func (pac *Package) GenConst(file string) error

func (*Package) Load 

func (pac *Package) Load() (err error)

func (*Package) NewTypedef 

func (pac *Package) NewTypedef(t *gcc.Typedef) *Typedef

func (*Package) Prepare 

func (pac *Package) Prepare() error

func (*Package) TransformOriginalFunc 

func (pac *Package) TransformOriginalFunc(
	oriFunc *gcc.Function,
	f CallbackFunc,
	info *gcc.CallbackInfo,
) (*Function, *Function)

func (*Package) UpperName 

func (pac *Package) UpperName(cName string) string

upper camel name

func (*Package) Wrap 

func (pac *Package) Wrap() error

type Param 

type Param interface {
	GoName() string
	CgoName() string
	GoTypeName() string
	CgoTypeName() string
	ToCgo(w io.Writer, assign string)
	ToGo(w io.Writer, assign string)
	IsOut() bool
}

type Params 

type Params []Param

func (Params) Filter 

func (ps Params) Filter(filter func(i int, a Param) (Param, bool)) (as Params)

func (Params) In 

func (ps Params) In() Params

func (Params) Out 

func (ps Params) Out() Params

type Ptr 

type Ptr struct {
	// contains filtered or unexported fields
}

func (*Ptr) CgoName 

func (t *Ptr) CgoName() string

func (*Ptr) GoName 

func (t *Ptr) GoName() string

func (*Ptr) Size 

func (t *Ptr) Size() int

func (*Ptr) ToCgo 

func (t *Ptr) ToCgo(w io.Writer, assign, g, c string)

func (*Ptr) ToGo 

func (t *Ptr) ToGo(w io.Writer, assign, g, c string)

func (*Ptr) WriteSpec 

func (t *Ptr) WriteSpec(w io.Writer)

type ReceiverArg 

type ReceiverArg struct {
	*Argument
	EqualType ReceiverType
}

func (ReceiverArg) CgoName 

func (a ReceiverArg) CgoName() string

func (ReceiverArg) CgoTypeName 

func (a ReceiverArg) CgoTypeName() string

func (ReceiverArg) GoName 

func (a ReceiverArg) GoName() string

func (ReceiverArg) GoTypeName 

func (a ReceiverArg) GoTypeName() string

func (ReceiverArg) ToCgo 

func (a ReceiverArg) ToCgo(w io.Writer, assign string)

func (ReceiverArg) ToGo 

func (a ReceiverArg) ToGo(w io.Writer, assign string)

func (ReceiverArg) Type 

func (a ReceiverArg) Type() Type

type ReceiverType 

type ReceiverType interface {
	EqualType
	AddMethod(m *Method)
	MethodsWriter
}

type Return 

type Return struct {
	// contains filtered or unexported fields
}

func (*Return) CgoName 

func (a *Return) CgoName() string

func (*Return) CgoTypeName 

func (a *Return) CgoTypeName() string

func (*Return) GoName 

func (a *Return) GoName() string

func (*Return) GoTypeName 

func (a *Return) GoTypeName() string

func (*Return) IsOut 

func (r *Return) IsOut() bool

func (*Return) ToCgo 

func (a *Return) ToCgo(w io.Writer, assign string)

func (*Return) ToGo 

func (a *Return) ToGo(w io.Writer, assign string)

func (*Return) Type 

func (a *Return) Type() Type

type ReturnPtr 

type ReturnPtr struct {
	// contains filtered or unexported fields
}

func (*ReturnPtr) CgoName 

func (r *ReturnPtr) CgoName() string

func (*ReturnPtr) GoName 

func (r *ReturnPtr) GoName() string

func (*ReturnPtr) ToCgo 

func (r *ReturnPtr) ToCgo(w io.Writer, assign, g, c string)

func (*ReturnPtr) ToGo 

func (r *ReturnPtr) ToGo(w io.Writer, assign, g, c string)

func (*ReturnPtr) WriteSpec 

func (r *ReturnPtr) WriteSpec(w io.Writer)

type SSet 

type SSet struct {
	// contains filtered or unexported fields
}

func NewSSet 

func NewSSet() SSet

func (*SSet) Add 

func (m *SSet) Add(ss ...string)

func (*SSet) Del 

func (m *SSet) Del(s string)

func (*SSet) Has 

func (m *SSet) Has(s string) bool

func (*SSet) IsNil 

func (m *SSet) IsNil() bool

func (*SSet) Len 

func (m *SSet) Len() int

type Slice 

type Slice struct {
	// contains filtered or unexported fields
}

func (*Slice) CgoName 

func (s *Slice) CgoName() string

func (*Slice) GoName 

func (s *Slice) GoName() string

func (*Slice) ToCgo 

func (s *Slice) ToCgo(w io.Writer, assign, g, c string)

func (*Slice) ToGo 

func (s *Slice) ToGo(w io.Writer, assign, g, c string)

func (*Slice) WriteSpec 

func (s *Slice) WriteSpec(w io.Writer)

type SliceSlice 

type SliceSlice struct {
	Slice
}

func (*SliceSlice) ToCgo 

func (s *SliceSlice) ToCgo(w io.Writer, assign, g, c string)

type SpecWriter 

type SpecWriter interface {
	WriteSpec(w io.Writer)
}

type Statistics 

type Statistics struct {
	DefCount int
}

func (Statistics) Print 

func (s Statistics) Print()

type String 

type String struct {
	// contains filtered or unexported fields
}

func (*String) CgoName 

func (t *String) CgoName() string

func (*String) GoName 

func (t *String) GoName() string

func (*String) SetGoName 

func (t *String) SetGoName(n string)

func (*String) ToCgo 

func (s *String) ToCgo(w io.Writer, assign, g, c string)

func (*String) ToGo 

func (s *String) ToGo(w io.Writer, assign, g, c string)

type Struct 

type Struct struct {
	Fields []StructField
	Methods
	// contains filtered or unexported fields
}

func (Struct) CName 

func (e Struct) CName() string

func (*Struct) CgoName 

func (t *Struct) CgoName() string

func (Struct) File 

func (e Struct) File() string

func (*Struct) GoName 

func (t *Struct) GoName() string

func (Struct) Id 

func (e Struct) Id() string

func (*Struct) OptimizeFieldNames 

func (s *Struct) OptimizeFieldNames(methods Methods)

func (*Struct) OptimizeNames 

func (s *Struct) OptimizeNames()

func (*Struct) SetGoName 

func (t *Struct) SetGoName(n string)

func (*Struct) Size 

func (t *Struct) Size() int

func (*Struct) ToCgo 

func (t *Struct) ToCgo(w io.Writer, assign, g, c string)

func (*Struct) ToGo 

func (t *Struct) ToGo(w io.Writer, assign, g, c string)

func (*Struct) WriteSpec 

func (s *Struct) WriteSpec(w io.Writer)

type StructField 

type StructField struct {
	EqualType
	// contains filtered or unexported fields
}

func (*StructField) Declare 

func (f *StructField) Declare(w io.Writer)

type Type 

type Type interface {
	GoNamer
	CgoNamer
	TypeConv
}

type TypeConv 

type TypeConv interface {
	ToCgo(w io.Writer, assign, g, c string)
	ToGo(w io.Writer, assign, g, c string)
}

type TypeDecl 

type TypeDecl interface {
	ReceiverType
	CNamer
	GoNameSetter
}

type TypeDeclMap 

type TypeDeclMap map[string]TypeDecl

func (TypeDeclMap) Delete 

func (m TypeDeclMap) Delete(id string)

func (TypeDeclMap) Each 

func (m TypeDeclMap) Each(visit func(d TypeDecl))

func (TypeDeclMap) ToSlice 

func (m TypeDeclMap) ToSlice() TypeDecls

type TypeDecls 

type TypeDecls []TypeDecl

func (TypeDecls) Len 

func (s TypeDecls) Len() int

func (TypeDecls) Less 

func (s TypeDecls) Less(i, j int) bool

func (TypeDecls) Swap 

func (s TypeDecls) Swap(i, j int)

type Typedef 

type Typedef struct {
	Literal SpecWriter
	Methods
	// contains filtered or unexported fields
}

func NewSimpleTypeDef 

func NewSimpleTypeDef(cName, goName string, size int) *Typedef

func (Typedef) CName 

func (e Typedef) CName() string

func (*Typedef) CgoName 

func (t *Typedef) CgoName() string

func (Typedef) File 

func (e Typedef) File() string

func (*Typedef) GoName 

func (d *Typedef) GoName() string

func (Typedef) Id 

func (e Typedef) Id() string

func (*Typedef) OptimizeNames 

func (d *Typedef) OptimizeNames()

func (*Typedef) Root 

func (d *Typedef) Root() EqualType

func (*Typedef) SetGoName 

func (t *Typedef) SetGoName(n string)

func (*Typedef) Size 

func (t *Typedef) Size() int

func (*Typedef) ToCgo 

func (t *Typedef) ToCgo(w io.Writer, assign, g, c string)

func (*Typedef) ToGo 

func (t *Typedef) ToGo(w io.Writer, assign, g, c string)

func (*Typedef) WriteMethods 

func (d *Typedef) WriteMethods(w io.Writer)

func (*Typedef) WriteSpec 

func (d *Typedef) WriteSpec(w io.Writer)

type Union 

type Union struct {
	Fields []UnionField
	Methods
	// contains filtered or unexported fields
}

func (Union) CName 

func (e Union) CName() string

func (*Union) CgoName 

func (t *Union) CgoName() string

func (Union) File 

func (e Union) File() string

func (*Union) GoName 

func (t *Union) GoName() string

func (Union) Id 

func (e Union) Id() string

func (*Union) OptimizeNames 

func (s *Union) OptimizeNames()

func (*Union) SetGoName 

func (t *Union) SetGoName(n string)

func (*Union) Size 

func (t *Union) Size() int

func (*Union) ToCgo 

func (t *Union) ToCgo(w io.Writer, assign, g, c string)

func (*Union) ToGo 

func (t *Union) ToGo(w io.Writer, assign, g, c string)

func (*Union) WriteMethods 

func (s *Union) WriteMethods(w io.Writer)

func (*Union) WriteSpec 

func (s *Union) WriteSpec(w io.Writer)

type UnionField 

type UnionField struct {
	EqualType
	// contains filtered or unexported fields
}

func (*UnionField) Declare 

func (f *UnionField) Declare(w io.Writer)

type Variable 

type Variable struct {
	// contains filtered or unexported fields
}

func (Variable) CName 

func (e Variable) CName() string

func (*Variable) CgoName 

func (v *Variable) CgoName() string

func (Variable) File 

func (e Variable) File() string

func (*Variable) GoName 

func (v *Variable) GoName() string

func (Variable) Id 

func (e Variable) Id() string

func (*Variable) SetGoName 

func (v *Variable) SetGoName(n string)

func (*Variable) WriteSpec 

func (v *Variable) WriteSpec(w io.Writer)

type Void 

type Void struct {
}

func (*Void) CgoName 

func (v *Void) CgoName() string

func (*Void) GoName 

func (v *Void) GoName() string

func (*Void) Size 

func (v *Void) Size() int

func (*Void) ToCgo 

func (v *Void) ToCgo(w io.Writer, assign, g, c string)

func (*Void) ToGo 

func (v *Void) ToGo(w io.Writer, assign, g, c string)

func (*Void) WriteSpec 

func (v *Void) WriteSpec(w io.Writer)

Source Files

View all Source files

Directories

Path Synopsis
examples
cairo
gmime
gsl
mupdf
netcdf
paho
plplot
sdl

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.