Faust Header Gen

Faust Header Gen

Read a Faust-generated C file and produce a matching extern "C" header. Eliminates the manual step of writing and maintaining a synth.h, which was historically a source of errors whenever the Faust class name (-cn) changed or new functions were added.

Requirements

• Python 3.8+

Instructions

Arguments are in $ARGUMENTS. Pass them directly to the generator:

python3 "$(dirname "$0")/gen_header.py" $ARGUMENTS

What the generated header contains

| Element | Detail | |---------|--------| | Include guard | #ifndef CLASSNAME_H / #define CLASSNAME_H (or custom via --guard) | | FAUSTFLOAT default | #ifndef FAUSTFLOAT / #define FAUSTFLOAT float guard so the header can be included without the generated C | | Dependency note | Comment stating faust/gui/CInterface.h must be included before this header (it defines UIGlue, MetaGlue, FAUSTFLOAT) | | extern "C" wrapping | Guarded by #ifdef __cplusplus so the header works for both C and C++ consumers | | Opaque forward declaration | typedef struct ClassName ClassName; — declares a named struct tag even though the generated C uses an anonymous struct typedef. This is the correct pattern for C++ consumers who hold only opaque pointers. | | Public function prototypes | All non-static functions whose names end with the class name, grouped into: Lifecycle, Metadata, Query, Initialisation, User Interface, DSP | | RESTRICT stripped | The generated C uses RESTRICT on parameter declarations. Headers omit it — restrict is an optimisation hint, not a type qualifier that affects linkage. | | void on zero-arg functions | newSynth() in the generated C becomes newSynth(void) in the header — correct C for "no arguments". |

Options

| Option | Default | Description | |--------|---------|-------------| | -o FILE | stdout | Write header to file instead of stdout | | --guard NAME | CLASSNAME_H | Override the include guard name | | --exports FILE | — | Also write a linker exports file (one _symbol per line, for .exp dylib builds) |

Exit codes

• 0 — header generated successfully
• 1 — input file not found, class name could not be detected, or no public functions found

Examples

# Write to stdout (inspect before committing)
python3 gen_header.py src/generated/synth.c

# Write to file
python3 gen_header.py src/generated/synth.c -o src/generated/synth.h

# Also generate a linker exports file
python3 gen_header.py src/generated/synth.c \
  -o src/generated/synth.h \
  --exports src/generated/synth_exports.exp

Notes

• When to run: after every faust-build that changes the class name (--cn) or adds/removes DSP outputs. If only internal DSP logic changes (filter coefficients, signal routing), the public API surface does not change and the header does not need regenerating.
• Anonymous struct quirk: The generated C uses typedef struct { ... } Synth; (anonymous struct). C++ forward declarations require typedef struct Synth Synth; (named struct tag). These are compatible at link time because consumers only hold Synth* pointers — they never dereference struct members through the header. This is the only divergence between the header and the generated C.
• MetaGlue* and UIGlue* in prototypes: The header uses these types in function signatures but does not include their definitions. Include faust/gui/CInterface.h before this header. This is intentional — it avoids pulling Faust headers into the project's own include tree.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gertsylvest
• Source: gertsylvest/meta-team
• License: MIT

Install and usage instructions live in the source repository linked above.