codegen/

directory
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT

README

codegen package scope convention

The code generator has two pipelines that are intentionally kept separate — this split is a non-negotiable of the architecture:

Pipeline Binds via Struct ABI Packages
frameworks purego / ObjC runtime Go struct passed by value through purego func vars → Go layout must match the C ABI byte-exactly frameworks/*, emit/*/frameworks
libraries cgo / C bridge shims the C bridge handles the ABI libraries/*, emit/*/libraries

Because the two pipelines bind differently, their type mappers, naming, and emitters diverge in behaviour, not just structure. Do not assume that a function existing on both sides is shareable — many same-named helpers (IsCoreFoundationOpaqueRef, normalise/Normalise, splitCSV/splitArgs, the block/fn-ptr parsers, the primitive tables) have different implementations and different outputs on purpose. Merging them would change generated code.

The SCOPE — convention

Every non-obvious package declares its scope in its package doc with a scannable SCOPE — line. Run grep -rn "SCOPE —" internal/codegen for the live map.

  • SHARED — pipeline-agnostic, used by both. Keep these free of either pipeline's mapper/metadata:
    • emit/structlayout — ABI/layout reasoning (size, alignment, byte-array tier)
    • emit/layouttest — the generated ABI layout regression test
    • emitmanifest — the parity manifest recorded by both generator styles
    • shared/fileasm — generated-file scaffolding
    • pipeline/structindex — struct-ownership index for both loaders
    • naming/core — only behaviour-identical naming helpers
  • FRAMEWORKS pipeline (purego/ObjC) — everything under frameworks/ and emit/*/frameworks. frameworks/typemap is pipeline-specific by design.
  • LIBRARIES pipeline (cgo/C) — everything under libraries/ and emit/*/libraries. libraries/typemap is pipeline-specific by design and additionally carries a CType() dimension the frameworks side has no use for.

Rule of thumb

Shared logic must be behaviour-identical across both pipelines; the moment a helper needs to differ, it belongs in the pipeline package, not in a shared one. A path segment (frameworks/, libraries/) or a SCOPE — line should make every package's allegiance obvious without reading its body.

Directories

Path Synopsis
emit
idiomatic/frameworks
Package idiomatic emits fluent Go wrapper types for ObjC frameworks.
 Package idiomatic emits fluent Go wrapper types for ObjC frameworks.
idiomatic/frameworks/render
Package render: name-based execution for the construct emitters that render an ad-hoc view by template name rather than through a typed Render* function.
 Package render: name-based execution for the construct emitters that render an ad-hoc view by template name rather than through a typed Render* function.
idiomatic/frameworks/view
Package view is the intermediate representation (IR) of a fully-resolved idiomatic framework package.
 Package view is the intermediate representation (IR) of a fully-resolved idiomatic framework package.
idiomatic/libraries
idiomatic/libraries/render
Package render executes the idiomatic CGo library templates.
 Package render executes the idiomatic CGo library templates.
idiomatic/libraries/view
Package view holds the pure-data IR structs for the idiomatic CGo library emitter (idiolib).
 Package view holds the pure-data IR structs for the idiomatic CGo library emitter (idiolib).
layouttest
Package layouttest generates the per-package ABI layout regression test both frameworks emitters (raw and idiomatic) write: a reflect-based check that every emitted value/byte-array struct reproduces the authoritative C ABI size clang reported.
 Package layouttest generates the per-package ABI layout regression test both frameworks emitters (raw and idiomatic) write: a reflect-based check that every emitted value/byte-array struct reproduces the authoritative C ABI size clang reported.
raw/frameworks
Package emit contains the per-construct emitters for the purego code generator.
 Package emit contains the per-construct emitters for the purego code generator.
raw/frameworks/render
Package render turns the raw purego emitter's resolved view (package view) into Go source through templates only.
 Package render turns the raw purego emitter's resolved view (package view) into Go source through templates only.
raw/frameworks/view
Package view holds the pure-data intermediate representation for the raw purego framework emitter.
 Package view holds the pure-data intermediate representation for the raw purego framework emitter.
raw/libraries
Package rawlib contains the per-construct emitters that convert [meta] structures into the raw CGo library Go source files and bridge files.
 Package rawlib contains the per-construct emitters that convert [meta] structures into the raw CGo library Go source files and bridge files.
raw/libraries/render
Package render executes the raw CGo library templates.
 Package render executes the raw CGo library templates.
raw/libraries/view
structlayout
Package structlayout holds the pure, pipeline-agnostic helpers for deciding whether a C struct can be surfaced as a plain Go value struct that reproduces the C ABI, and for width-correcting struct field Go types.
 Package structlayout holds the pure, pipeline-agnostic helpers for deciding whether a C struct can be surfaced as a plain Go value struct that reproduces the C ABI, and for width-correcting struct field Go types.
Package emitmanifest records, per generated construct, which metadata symbol a code emitter turned into Go source and under what Go name.
 Package emitmanifest records, per generated construct, which metadata symbol a code emitter turned into Go source and under what Go name.
frameworks
appledocs
Package appledocs applies the shared Apple-documentation sidecar schema (internal/appledocs) to the purego generator's metadata model (internal/codegen/frameworks/meta).
 Package appledocs applies the shared Apple-documentation sidecar schema (internal/appledocs) to the purego generator's metadata model (internal/codegen/frameworks/meta).
idioconf
Package idioconf loads the per-framework idiomatic.json sidecar — the declarative configuration surface of the idiomatic emitter.
 Package idioconf loads the per-framework idiomatic.json sidecar — the declarative configuration surface of the idiomatic emitter.
mainactor
Package mainactor applies the @MainActor isolation sidecar (internal/mainactor) to the purego generator's metadata model so the idiomatic emitter can wrap main-thread-bound calls in purego.Main.
 Package mainactor applies the @MainActor isolation sidecar (internal/mainactor) to the purego generator's metadata model so the idiomatic emitter can wrap main-thread-bound calls in purego.Main.
meta
Package meta defines the data model consumed by the purego code generator.
 Package meta defines the data model consumed by the purego code generator.
naming
overrides
Package overrides applies the shared declarative override schema (internal/overrides) to the purego generator's metadata model (internal/codegen/frameworks/meta).
 Package overrides applies the shared declarative override schema (internal/overrides) to the purego generator's metadata model (internal/codegen/frameworks/meta).
pipeline
typemap
Package typemap resolves ObjC qualType strings to Go type strings for the FRAMEWORKS pipeline (purego/ObjC) only.
 Package typemap resolves ObjC qualType strings to Go type strings for the FRAMEWORKS pipeline (purego/ObjC) only.
libraries
classify
naming
Package naming converts ObjC identifiers to idiomatic Go names.
 Package naming converts ObjC identifiers to idiomatic Go names.
pipeline
Package pipeline orchestrates the load and generate phases of the code-generation pipeline.
 Package pipeline orchestrates the load and generate phases of the code-generation pipeline.
typemap
Package typemap resolves ObjC qualType strings to their Go equivalents for the LIBRARIES pipeline (cgo/C) only.
 Package typemap resolves ObjC qualType strings to their Go equivalents for the LIBRARIES pipeline (cgo/C) only.
naming
core
Package core holds the naming helpers that are identical across the frameworks (purego) and libraries (cgo) pipelines, so both pipeline-specific naming packages re-export them from a single source instead of keeping divergent copies.
 Package core holds the naming helpers that are identical across the frameworks (purego) and libraries (cgo) pipelines, so both pipeline-specific naming packages re-export them from a single source instead of keeping divergent copies.
pipeline
structindex
Package structindex builds the struct-name → owning-framework registry shared by the frameworks (purego) and libraries (cgo) pipeline loaders.
 Package structindex builds the struct-name → owning-framework registry shared by the frameworks (purego) and libraries (cgo) pipeline loaders.
shared
fileasm
Package fileasm assembles a complete generated Go source file — the DO-NOT-EDIT header, the build constraint, the package clause, the import block, and the rendered body — through a single template.
 Package fileasm assembles a complete generated Go source file — the DO-NOT-EDIT header, the build constraint, the package clause, the import block, and the rendered body — through a single template.

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.