gen

package module
v0.0.0-...-3255704 Latest Latest
Warning

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

 Go to latest Published: Mar 28, 2022 License: BSD-3-Clause Imports: 14 Imported by: 0

README

go-clang/gen

PkgGoDev GitHub Workflow Codecov branch

Generate native Go bindings for Clang's C API.

I found a bug/missing a feature in go-clang

Please go through the open issues in the tracker first. If you cannot find your request just open up a new issue.

Where are the bindings?

The Go bindings are placed in their own repositories to provide the correct bindings for the corresponding Clang version:

Install go-clang/gen to contribute to go-clang

CGO_LDFLAGS="-L`llvm-config --libdir`" \
  go get github.com/go-clang/bootstrap github.com/go-clang/gen

How to contribute?

You want to contribute to go-clang? GREAT! If you are here because of a bug you want to fix or a feature you want to add, you can just read on. Otherwise we have a list of open issues in the tracker. Just choose something you think you can work on and discuss your plans in the issue by commenting on it.

This repository, gen, holds the code to generate new bindings from headers of Clang's C API. These bindings are then bootstrapped using the bootstrap repository. The bootstrap repository holds all basic files, like the CI configuration and a Makefile, as well as some additional code to make the bindings more complete and powerful.

To ease the development process we have our own development environment based on Vagrant. The provided Vagrantfile executed in the root of the repository will setup an Ubuntu VM with our currently used Go version as well as Clang 3.4 and will set up everything that is needed to development and handle new versions of Clang.

Please note, only the major and minor version must be declared if a Clang version is needed in a command.

Generate bindings for the current Clang version (VM)

Make sure that the go-clang-gen command is up to date using make install in the repository's root directory. After that execute go-clang-gen which will generate bindings in your current directory.

Switch to a different Clang version (VM)

Replace 3.4 with the Clang version you want to switch to.

$GOPATH/src/github.com/go-clang/gen/scripts/switch-clang-version.sh 3.4

This command will install and configure everything that is needed to develop with the given Clang version. The command will however not generate new bindings for the version.

Do a PR

Every PR must be prepared using the following commands:

cd $GOPATH/src/github.com/go-clang/gen
scripts/switch-clang-version.sh 3.4
make install
make test
make lint

This will switch to the current Clang version for the go-clang-gen command, execute all tests and process the source code with the project's linters. Make sure that you do not introduce new linting problems.

Regenerate the bindings for the bootstrap repository

The bootstrap repository holds the base for all version repositories it must therefore be updated if something changes in the gen repository to regenerate all version repositories. This tedious task is automated by the following command.

$GOPATH/src/github.com/go-clang/gen/scripts/update-bootstrap.sh

Any changes must be manually verified and pushed via a feature branch.

Maintainer documentation

The following sections are specific to the maintaining process.

Please note, only the major and minor version must be declared if a Clang version is needed in a command.

Create a new Clang version (VM)

Every now and then a new Clang version emerges which needs to be generated using the go-clang-gen command. The new version has to be available using the VM's and CI's packages. Otherwise, we cannot correctly test and therefore support the version.

If a new version is available create a repository on GitHub named v<MAJOR>.<MINOR> and set the repository description to Go bindings for Clang's C API v<MAJOR>.<MINOR>. Disable all repository features, e.g. Issues and Wiki. Enable the repository on TravisCI before you push anything to the repository. Lastly, execute the following command inside the development VM.

$GOPATH/src/github.com/go-clang/gen/scripts/create-clang-version.sh 3.4

This will create a new repository v3.4 in the $GOPATH/src/github.com/go-clang directory and initialize it using the bootstrap repository. The command also generates, installs, configures and tests bindings for the given Clang version. The changes must then be manually verified, added, committed and pushed to the already set up remote "origin".

After the repository is online godoc.org needs to know about the new repository. This can be achieved by visiting https://godoc.org/github.com/go-clang/v<MAJOR>.<MINOR>/clang.

Update a branch with a new Clang version (VM)

Every now and then a new Clang subminor version is released. The given version can be supported if packages are available inside the VM and CI. The following command can then be executed inside the development VM.

$GOPATH/src/github.com/go-clang/gen/scripts/update-clang-version.sh 3.4

This will rebase the latest commits of the bootstrap repository onto the commits of the v3.4 repository. The command also generates, installs, configures and tests bindings for the given Clang version. The changes must then be manually verified, added, committed and pushed to the already set up remote "origin".

Update branches with a new go-clang/gen version (VM)

If the go-clang-gen command changes its generation output, all branches need to be updated which is basically just updating for a new Clang version.

License

This project, like all go-clang projects, is licensed under a BSD-3 license which can be found in the LICENSE file in go-clang's license repository

Documentation

Index

Constants

View Source 
const (
	GoByte      = "byte"
	GoInt8      = "int8"
	GoUInt8     = "uint8"
	GoInt16     = "int16"
	GoUInt16    = "uint16"
	GoInt32     = "int32"
	GoUInt32    = "uint32"
	GoInt64     = "int64"
	GoUInt64    = "uint64"
	GoFloat32   = "float32"
	GoFloat64   = "float64"
	GoBool      = "bool"
	GoInterface = "interface"
	GoPointer   = "unsafe.Pointer"
)

Defines all available Go types.

View Source 
const (
	CChar      = "char"
	CSChar     = "schar"
	CUChar     = "uchar"
	CShort     = "short"
	CUShort    = "ushort"
	CInt       = "int"
	CUInt      = "uint"
	CLongInt   = "long"
	CULongInt  = "ulong"
	CLongLong  = "longlong"
	CULongLong = "ulonglong"
	CFloat     = "float"
	CDouble    = "double"
)

Defines all available C types.

Variables

This section is empty.

Functions

func ArrayNameFromLength 

func ArrayNameFromLength(lengthCName string) string

ArrayNameFromLength returns the array name from lengthCName length naming.

func CleanDoxygenComment 

func CleanDoxygenComment(name, comment string) string

CleanDoxygenComment converts Clang Doxygen comment to Go comment.

func CommonReceiverName 

func CommonReceiverName(s string) string

CommonReceiverName returns the common function receiver name.

func GenerateFunctionString 

func GenerateFunctionString(af *ASTFunc) string

GenerateFunctionString generates function string.

func IsInteger 

func IsInteger(typ *Type) bool

IsInteger reports whether the typ is Go integer type.

func LowerFirstCharacter 

func LowerFirstCharacter(s string) string

LowerFirstCharacter converts first s character to lower.

func ReplaceGoKeywords 

func ReplaceGoKeywords(s string) string

ReplaceGoKeywords replaces s to Go keyword.

func TrimCommonFunctionName 

func TrimCommonFunctionName(name string, typ Type) string

TrimCommonFunctionName trims common function-name from name.

func TrimCommonFunctionNamePrefix 

func TrimCommonFunctionNamePrefix(name string) string

TrimCommonFunctionNamePrefix trims common function-name prefix from name.

func TrimLanguagePrefix 

func TrimLanguagePrefix(name string) string

TrimLanguagePrefix trims Language prefix from name.

func UpperFirstCharacter 

func UpperFirstCharacter(s string) string

UpperFirstCharacter converts first s character to upper.

Types

type API 

type API struct {
	// PrepareFunctionName returns a prepared function name for further processing.
	PrepareFunctionName func(g *Generation, f *Function) string

	// PrepareFunction prepares a function for further processing.
	PrepareFunction func(f *Function)

	// FilterFunction determines if a function is generateable.
	FilterFunction func(f *Function) bool

	// FilterFunctionParameter determines if a function parameter is generateable.
	FilterFunctionParameter func(p FunctionParameter) bool

	// FixFunctionName returns an unempty string if a function needs to receive a specific name.
	FixFunctionName func(f *Function) string

	// PrepareStructFields is called before adding struct field getters.
	PrepareStructFields func(s *Struct)

	// FilterStructFieldGetter determines if a getter should be generated for a field.
	FilterStructFieldGetter func(f *StructField) bool

	// ClangArguments holds the command line arguments for Clang.
	ClangArguments []string
}

API represents a Clang bindings generation.

func (*API) HandleDirectory 

func (a *API) HandleDirectory(dir string) ([]*HeaderFile, error)

HandleDirectory handles header files on dir and returns the *HeaderFile slice.

type ASTFunc 

type ASTFunc struct {
	*ast.FuncDecl
	// contains filtered or unexported fields
}

ASTFunc represents a AST Func.

func NewASTFunc 

func NewASTFunc(f *Function) *ASTFunc

NewASTFunc returns the new initialized ASTFunc.

func (*ASTFunc) AddAssignment 

func (af *ASTFunc) AddAssignment(variable string, e ast.Expr)

AddAssignment adds assignment to af.

func (*ASTFunc) AddCArrayFromGoSlice 

func (af *ASTFunc) AddCArrayFromGoSlice(name string, typ Type)

AddCArrayFromGoSlice adds C array from Go slice to af.

func (*ASTFunc) AddCToGoConversions 

func (af *ASTFunc) AddCToGoConversions()

AddCToGoConversions adds C to Go conversions to af.

func (*ASTFunc) AddCToGoSliceConversion 

func (af *ASTFunc) AddCToGoSliceConversion(name string, cname string, lengthOfSlice string)

AddCToGoSliceConversion adds C to Go slice conversion to af.

func (*ASTFunc) AddDefer 

func (af *ASTFunc) AddDefer(call *ast.CallExpr)

AddDefer adds deferred statement to af.

func (*ASTFunc) AddEmptyLine 

func (af *ASTFunc) AddEmptyLine()

AddEmptyLine adds empty line to af.

func (*ASTFunc) AddGoToCSliceConversion 

func (af *ASTFunc) AddGoToCSliceConversion(name string, typ Type)

AddGoToCSliceConversion adds Go to C slice conversion to af.

func (*ASTFunc) AddReturnItem 

func (af *ASTFunc) AddReturnItem(item ast.Expr)

AddReturnItem adds return item to af.

func (*ASTFunc) AddReturnType 

func (af *ASTFunc) AddReturnType(name string, typ Type)

AddReturnType adds return type to af.

func (*ASTFunc) AddStatement 

func (af *ASTFunc) AddStatement(stmt ast.Stmt)

AddStatement adds stmt ast.Stmt to af.

func (*ASTFunc) Generate 

func (af *ASTFunc) Generate()

Generate generates function.

func (*ASTFunc) GenerateParameters 

func (af *ASTFunc) GenerateParameters() []ast.Expr

GenerateParameters generates function parameters.

func (*ASTFunc) GenerateReceiver 

func (af *ASTFunc) GenerateReceiver()

GenerateReceiver generates function receiver.

func (*ASTFunc) GenerateReturn 

func (af *ASTFunc) GenerateReturn(call ast.Expr)

GenerateReturn generates return statement.

type Enum 

type Enum struct {
	IncludeFiles IncludeFiles

	Name           string
	CName          string
	CNameIsTypeDef bool
	Receiver       Receiver
	Comment        string
	UnderlyingType string

	Items []EnumItem

	Methods []interface{}
}

Enum represents a generation enum.

func HandleEnumCursor 

func HandleEnumCursor(cursor clang.Cursor, cname string, cnameIsTypeDef bool) *Enum

HandleEnumCursor handles enum clang.Cursor and roterns the new *Enum.

func (*Enum) AddEnumSpellingMethod 

func (e *Enum) AddEnumSpellingMethod() error

AddEnumSpellingMethod adds Enum spelling method to e.

func (*Enum) AddEnumStringMethods 

func (e *Enum) AddEnumStringMethods() error

AddEnumStringMethods adds Enum String methods to e.

func (*Enum) AddSpellingMethodAlias 

func (e *Enum) AddSpellingMethodAlias(name string) error

AddSpellingMethodAlias adds spelling method alias to e.

func (*Enum) ContainsMethod 

func (e *Enum) ContainsMethod(name string) bool

ContainsMethod reports whether the contains name to Enum.Methods.

func (*Enum) Generate 

func (e *Enum) Generate() error

Generate generates enum.

type EnumItem 

type EnumItem struct {
	Name    string
	CName   string
	Comment string
	Value   uint64
}

EnumItem represents a generation enum item.

type File 

type File struct {
	Name string

	IncludeFiles IncludeFiles

	Functions []interface{}
	Enums     []*Enum
	Structs   []*Struct
}

File represents a generation file.

func NewFile 

func NewFile(name string) *File

NewFile creates a new blank file.

func (*File) Generate 

func (f *File) Generate() error

Generate generates file.

type Function 

type Function struct {
	IncludeFiles IncludeFiles

	Name    string
	CName   string
	Comment string

	Parameters []FunctionParameter
	ReturnType Type
	Receiver   Receiver
	Member     *FunctionParameter
}

Function represents a generation function.

func HandleFunctionCursor 

func HandleFunctionCursor(cursor clang.Cursor) *Function

HandleFunctionCursor handles function cursor.

func NewFunction 

func NewFunction(name, cname, comment, member string, typ Type) *Function

NewFunction returns the initialized *Function.

func (*Function) Generate 

func (f *Function) Generate() string

Generate generates the function.

type FunctionParameter 

type FunctionParameter struct {
	Name  string
	CName string
	Type  Type
}

FunctionParameter represents a generation function parameter.

type Generation 

type Generation struct {
	Lookup
	// contains filtered or unexported fields
}

Generation represents a generation entrypoint.

func NewGeneration 

func NewGeneration(a *API) *Generation

NewGeneration returns the new *Generation from a.

func (*Generation) AddBasicMethods 

func (g *Generation) AddBasicMethods(f *Function, fname string, fnamePrefix string, rt Receiver) bool

AddBasicMethods adds basic methods.

func (*Generation) AddHeaderFiles 

func (g *Generation) AddHeaderFiles(headerFiles []*HeaderFile)

AddHeaderFiles adds headerFiles to g.

func (*Generation) AddMethod 

func (g *Generation) AddMethod(f *Function, fname string, fnamePrefix string, rt Receiver) bool

AddMethod adds method to g.

func (*Generation) Generate 

func (g *Generation) Generate() error

Generate Clang bindings generation.

func (*Generation) GenerateMethod 

func (g *Generation) GenerateMethod(receiverName string, m interface{}) string

GenerateMethod method generation.

func (*Generation) SetIsPointerComposition 

func (g *Generation) SetIsPointerComposition(typ *Type)

SetIsPointerComposition sets IsPointerComposition if given.

type HeaderFile 

type HeaderFile struct {
	Lookup

	Filename string
	Path     string

	Enums     []*Enum
	Functions []*Function
	Structs   []*Struct
	// contains filtered or unexported fields
}

HeaderFile represents a generation headerfile.

func NewHeaderFile 

func NewHeaderFile(a *API, name string, dir string) *HeaderFile

NewHeaderFile returns the new initialized HeaderFile.

func (*HeaderFile) FullPath 

func (h *HeaderFile) FullPath() string

FullPath returns the full path of h.

func (*HeaderFile) HandleFile 

func (h *HeaderFile) HandleFile(cursor clang.Cursor)

HandleFile handles header file.

func (*HeaderFile) Parse 

func (h *HeaderFile) Parse(clangArguments []string) error

Parse parses header file with clangArguments.

func (*HeaderFile) PrepareFile 

func (h *HeaderFile) PrepareFile() error

PrepareFile prepares header files name.

type IncludeFiles 

type IncludeFiles map[string]struct{}

IncludeFiles represents a generation include files.

func NewIncludeFiles 

func NewIncludeFiles() IncludeFiles

NewIncludeFiles returns the new include files map.

func (IncludeFiles) AddIncludeFile 

func (inf IncludeFiles) AddIncludeFile(includeFile string)

AddIncludeFile adds include file to inf.

type Lookup 

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

Lookup represents a in-memory lookup store.

func NewLookup 

func NewLookup() Lookup

NewLookup returns the initialized Lookup.

func (*Lookup) HasEnum 

func (l *Lookup) HasEnum(n string) (*Enum, bool)

HasEnum reports whether the n has Enum.

func (*Lookup) HasStruct 

func (l *Lookup) HasStruct(n string) (*Struct, bool)

HasStruct reports whether the n has Struct.

func (*Lookup) IsEnumOrStruct 

func (l *Lookup) IsEnumOrStruct(name string) bool

IsEnumOrStruct reports whether the name is Enum or Struct.

func (*Lookup) LookupNonTypedef 

func (l *Lookup) LookupNonTypedef(s string) (string, bool)

LookupNonTypedef lookups non typedef from Lookup.

func (*Lookup) RegisterEnum 

func (l *Lookup) RegisterEnum(e *Enum)

RegisterEnum registers e *Enum to Lookup.

func (*Lookup) RegisterStruct 

func (l *Lookup) RegisterStruct(s *Struct)

RegisterStruct registers s *Struct to Lookup.

func (*Lookup) RemoveStruct 

func (l *Lookup) RemoveStruct(s *Struct)

RemoveStruct removes s *Struct from Lookup.

type Receiver 

type Receiver struct {
	Name  string
	CName string
	Type  Type
}

Receiver represents a generation receiver.

TODO(go-clang): refactor https://github.com/go-clang/gen/issues/52

type Struct 

type Struct struct {
	IncludeFiles

	Name           string
	CName          string
	CNameIsTypeDef bool
	Receiver       Receiver
	Comment        string

	IsPointerComposition bool

	Fields  []*StructField
	Methods []interface{}
	// contains filtered or unexported fields
}

Struct represents a generation struct.

func HandleStructCursor 

func HandleStructCursor(cursor clang.Cursor, cname string, cnameIsTypeDef bool) *Struct

HandleStructCursor handles the struct cursor.

func (*Struct) AddFieldGetters 

func (s *Struct) AddFieldGetters() error

AddFieldGetters adds field getters to s.

func (*Struct) ContainsMethod 

func (s *Struct) ContainsMethod(name string) bool

ContainsMethod reports whether the contains name in Struct.

func (*Struct) Generate 

func (s *Struct) Generate() error

Generate generates the struct.

type StructField 

type StructField struct {
	CName   string
	Comment string
	Type    Type
}

StructField field of Struct.

type Type 

type Type struct {
	// CName C Type name
	CName string

	// CGoName Cgo Type name
	CGoName string

	// GoName Go Type name
	GoName string

	// LengthOfSlice length of slice
	LengthOfSlice string

	// ArraySize size of array
	ArraySize int64

	// PointerLevel level of pointer
	PointerLevel int

	// IsPrimitive whether the this Type is primitive
	IsPrimitive bool

	// IsArray whether the this Type is array
	IsArray bool

	// IsEnumLiteral whether the this Type is enum literal
	IsEnumLiteral bool

	// IsFunctionPointer whether the this Type is function pointer
	IsFunctionPointer bool

	// IsReturnArgument whether the this Type is return argument
	IsReturnArgument bool

	// IsSlice whether the this Type is slice
	IsSlice bool

	// IsPointerComposition whether the this Type is pointer composition
	IsPointerComposition bool
}

Type represents a generation type.

func TypeFromClangType 

func TypeFromClangType(cType clang.Type) (Type, error)

TypeFromClangType returns the Type from Clang type.

Source Files

View all Source files

Directories

Path Synopsis
_embed/clang
cmd
go-clang-gen command
go-clang-gen/runtime

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.