Parser config section

A documentation page for the PARSER section of config manifest.

An example configuration piece:

PARSER: 
  IncludePaths: ["/usr/include"]
  SourcesPaths: ["vorbis/ogg/ogg.h", "vorbis/vorbis/codec.h"]

Most of these options are going directly as configuration parameters for cznic/cc.

IncludePaths

Specifies a list of paths where to search all the referenced include files while parsing C header files. This goes straight to cznic/cc and does not correlate nor with system environment nor the Go toolchain.

Example: IncludePaths: ["/usr/include"].

SourcesPaths

Specifies a list of C header files to parse. These are usually relative to the cgogen working directory (.) or absolute on the system of the developer who maintains the bindings.

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

SourcesPaths:
    - vorbis/ogg/ogg.h
    - vorbis/vorbis/codec.h

Another example, the order is significant.

  IncludePaths:
    - android
    # NOTE: Replace these paths if you want to re-generate.
    # NOTE: Can be processed only with -ccdefs cgogen option enabled.
    - /Users/xlab/Library/Android/sdk/ndk-bundle/toolchains/arm-linux-androideabi-4.9/prebuilt/darwin-x86_64/lib/gcc/arm-linux-androideabi/4.9.x/include
    - /Users/xlab/Library/Android/sdk/ndk-bundle/platforms/android-23/arch-arm/usr/include
    - /Users/xlab/Library/Android/sdk/ndk-bundle/platforms/android-23/arch-arm/usr/include/linux
    - /Users/xlab/Library/Android/sdk/ndk-bundle/platforms/android-23/arch-arm/usr/include/android

Arch

Override the target CPU architecture. Defaults to x86_64 but supported bases are:

• i386
• x86_48
• x86_64
• arm
• aarch64

Moreover, cgogen supports Arch aliases, check predefined.go for the full map. The arch you choose will mostly affect the memory model the cznic/cc sanity checker will use and will affect the set of system defines.

Example: Arch: arm would result into having two extra defines and the different memory model (pointer of size 4 bytes instead of 8 bytes).

#define __ARM_EABI__ 1
#define __arm__ 1

The generator does not need all that information for sure, because sizes can be determined dynamically at compile time like this:

const sizeOfEnvValue = unsafe.Sizeof([1]C.MDB_env{})
const sizeOfPtr = unsafe.Sizeof(&struct{}{})

{
	const m = 0x7fffffff
	ptr1 := (*(*[m / sizeOfPtr]*C.char)(unsafe.Pointer(ptr0)))[i0]
	// a valid static conversion that does not overflow! Sick.
}

Defines

Allows user to specify custom defines, override built-in ones and disable dubious macros.

Example:

  Defines:
    __STDC_HOSTED__: null
    VK_USE_PLATFORM_ANDROID_KHR: yes
    VK_NO_PROTOTYPES: 1
    __dafuq__: {}

In this example

1. After all predefines an #undef __STDC_HOSTED__ statement will be added because of null value;
2. A define statement will be added as #define VK_USE_PLATFORM_ANDROID_KHR "yes" because of yes string;
3. A define statement will be added as #define VK_NO_PROTOTYPES 1 because of 1 numeric value;
4. In the beginning the symbol will be defined as #define __dafuq__ i.e. with an empty substitution, that will force parser to ignore any other attempts to define it properly. Use this to disable wonky macros and GCC extensions.

..and CCDefs

There is a special flag of the cgogen executable -ccdefs that enables stealing of built-in defines from a hosted C-compiler, note that CC env variable must be set. So the built-in predefines will be replaced by that new set. Some of them may rely on built-in capabilities (that are simply absent) so be ready to disable these macros. Study parser.go for more details on the flow.