Generator config section

There goes the documentation 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"]

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 cgogen 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.

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 cgogen 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

And will be handled by CGo respectively.