Generator config section

A documentation page for the GENERATOR section of config manifest.

An example configuration piece:

GENERATOR: 
  PackageName: vorbis
  PackageDescription: "Package vorbis provides Go bindings for OggVorbis implementation by the Xiph.Org Foundation"
  PackageLicense: "THE AUTOGENERATED LICENSE. ALL THE RIGHTS ARE RESERVED BY ROBOTS."
  PkgConfigOpts: [ogg, vorbis]
  Includes: ["ogg/ogg.h", "vorbis/codec.h"]
  Options:
    SafeStrings: true

PackageName

Specifies the package name for the generated code. A directory with that name will be created in the -out prefix (. by default) provided for the c-for-go executable.

Examples: PackageName: vorbis, PackageName: pm, etc.

PackageDescription

Specifies the package description that will be written into doc.go and act as a short description in GoDoc.

Example: PackageDescription: "Package vorbis provides Go bindings for OggVorbis implementation by the Xiph.Org Foundation" or consider using YAML syntax for multiline and verbatim text blocks.

PackageLicense

Specify a license for the generated code. I prefer delegating all the rights to the robots.

Example: PackageLicense: "THE AUTOGENERATED LICENSE. ALL THE RIGHTS ARE RESERVED BY ROBOTS." or consider using YAML syntax for multiline and verbatim text blocks.

Options

This section allows to specify controversial options to be enabled within the generator. Currently available options:

SafeStrings

SafeStrings automatically NULL-terminates all strings passed to bindings API, prevents exposing strings to C which will easily lead to buffer overflows. This option doesn't affect []byte args.

PkgConfigOpts

An optional parameter that leverages pkg-config if the library you are binding have any .pc manifests. Firstly, the parser module will be configured by c-for-go main routine to use the specified include search paths, it does so by parsing *.pc files with github.com/xlab/pkgconfig/pkg. Secondly, the generator will write a CGo header that the Go toolchain respects, so at compiling and linking stages it will find all required include files and shared objects.

#cgo pkg-config: ogg vorbis

Example: PkgConfigOpts: [ogg, vorbis] or multiline:

PkgConfigOpts:
    - ogg
    - vorbis

Includes

The list of include files that generator must write in the resulting files so CGo will find all the symbols used.

#include "ogg/ogg.h"
#include "vorbis/codec.h"

Example: Includes: ["ogg/ogg.h", "vorbis/codec.h"] or multiline:

Includes:
   - ogg/ogg.h
   - vorbis/vorbis.h

These files are part of the distribution so the paths are relative. Consider SysIncludes if you're expecting the system to have these headers. Be aware that system headers and the generated bindings must be compatible, any missing declarations will fail the build.

SysIncludes

The same as Includes, but results in:

#include <ogg/ogg.h>
#include <vorbis/codec.h>

FlagGroups

This option allows to specify flag groups with build constraints for CGo, the group is represented as

type TraitFlagGroup struct {
	Name   string   `yaml:"name"`
	Traits []string `yaml:"traits"`
	Flags  []string `yaml:"flags"`
}

A common example would be specifying a platform-dependent LDFLAGS or CFLAGS group, the traits are specified as described in Build Constraints.

Example with no traits:

  FlagGroups:
    - {name: LDFLAGS, flags: [-landroid -llog]}

Would result in

#cgo LDFLAGS: -landroid -llog

Example with traits:

  FlagGroups:
    - {name: "CFLAGS", traits: ["linux"], flags: [-DMDB_USE_SYSV_SEM=1]}
    - {name: "LDFLAGS", traits: ["windows"], flags: [-lntdll]}

Results in

#cgo linux CFLAGS: -DMDB_USE_SYSV_SEM=1
#cgo windows LDFLAGS: -lntdll

The real world example:

  FlagGroups:
    - {name: "CFLAGS", flags: [
        "-I.",
        "-DVK_NO_PROTOTYPES",
        "-DVK_USE_PLATFORM_ANDROID_KHR",
    ]}
    - {name: "LDFLAGS", traits: ["android"], flags: [
      "-Wl,--no-warn-mismatch",
      "-lm_hard",
    ]}
    - {name: "CFLAGS", traits: ["android"], flags: [
        "-D__ARM_ARCH_7A__",
        "-D_NDK_MATH_NO_SOFTFP=1",
        "-mfpu=vfp",
        "-mfloat-abi=hard",
        "-march=armv7-a",
    ]}

Results in

#cgo CFLAGS: -I. -DVK_NO_PROTOTYPES -DVK_USE_PLATFORM_ANDROID_KHR
#cgo android LDFLAGS: -Wl,--no-warn-mismatch -lm_hard
#cgo android CFLAGS: -D__ARM_ARCH_7A__ -D_NDK_MATH_NO_SOFTFP=1 -mfpu=vfp -mfloat-abi=hard -march=armv7-a

And will be handled by CGo respectively.