spec

Documentation

Overview

Package spec defines the intermediate representation for AIDL and Java source extraction. Specs are serialized as YAML, one file per Go package. Generators read specs to produce Go code, CLI commands, and documentation.

Index

• func GoPackageFromAIDL(aidlPackage string) string
• func ReadAllSpecs(rootDir string) (map[string]*PackageSpec, error)
• func SpecPath(rootDir string, goPackage string) string
• func WriteAllSpecs(rootDir string, specs map[string]*PackageSpec) error
• func WritePackageSpec(path string, s *PackageSpec) error
• type ConstantSpec
• type Direction
• type EnumSpec
• type EnumeratorSpec
• type FieldSpec
• type InterfaceSpec
• type JavaConstantGroup
• type JavaConstantValue
• type JavaWireField
• type MethodSpec
• type PackageSpec
  • func ReadPackageSpec(path string) (*PackageSpec, error)
• type ParamSpec
• type ParcelableSpec
• type ServiceMapping
• type TypeRef
• type UnionSpec

Functions

func GoPackageFromAIDL

func GoPackageFromAIDL(aidlPackage string) string

GoPackageFromAIDL converts a dot-separated AIDL package name to a slash-separated Go package path, matching the existing codegen convention.

func ReadAllSpecs

func ReadAllSpecs(
	rootDir string,
) (map[string]*PackageSpec, error)

ReadAllSpecs reads all spec.yaml files from the given root directory. Returns specs keyed by Go package path.

func SpecPath

func SpecPath(
	rootDir string,
	goPackage string,
) string

SpecPath returns the spec.yaml path for a Go package.

func WriteAllSpecs

func WriteAllSpecs(
	rootDir string,
	specs map[string]*PackageSpec,
) error

WriteAllSpecs writes all specs to the given root directory. Each spec is written to rootDir/<go_package>/spec.yaml.

func WritePackageSpec

func WritePackageSpec(
	path string,
	s *PackageSpec,
) error

WritePackageSpec writes a single YAML spec file. Creates parent directories as needed.

Types

type ConstantSpec

type ConstantSpec struct {
	Name  string `yaml:"name"`
	Type  string `yaml:"type"`
	Value string `yaml:"value"`
}

ConstantSpec describes an AIDL constant declaration within an interface or parcelable.

type Direction

type Direction string

Direction indicates parameter directionality in AIDL.

const (
	DirectionIn    Direction = "in"
	DirectionOut   Direction = "out"
	DirectionInOut Direction = "inout"
)

type EnumSpec

type EnumSpec struct {
	Name        string           `yaml:"name"`
	BackingType string           `yaml:"backing_type"`
	Values      []EnumeratorSpec `yaml:"values"`
	Annotations []string         `yaml:"annotations,omitempty"`
}

EnumSpec describes an AIDL enum.

type EnumeratorSpec

type EnumeratorSpec struct {
	Name  string `yaml:"name"`
	Value string `yaml:"value"`
}

EnumeratorSpec describes a single enum value.

type FieldSpec

type FieldSpec struct {
	Name         string   `yaml:"name"`
	Type         TypeRef  `yaml:"type"`
	DefaultValue string   `yaml:"default_value,omitempty"`
	Annotations  []string `yaml:"annotations,omitempty"`
}

FieldSpec describes a parcelable or union field.

type InterfaceSpec

type InterfaceSpec struct {
	Name       string `yaml:"name"`
	Descriptor string `yaml:"descriptor"`
	Oneway     bool   `yaml:"oneway,omitempty"`

	Methods     []MethodSpec   `yaml:"methods,omitempty"`
	Constants   []ConstantSpec `yaml:"constants,omitempty"`
	NestedTypes []string       `yaml:"nested_types,omitempty"`
	Annotations []string       `yaml:"annotations,omitempty"`

	// VersionCodes maps revision ID (e.g., "36.r4") to a map of
	// method name → transaction code offset (relative to FirstCallTransaction).
	// Used by the version-aware transport for multi-API-level support.
	VersionCodes map[string]map[string]int `yaml:"version_codes,omitempty"`
}

InterfaceSpec describes an AIDL interface with its methods, constants, and multi-version transaction code mappings.

type JavaConstantGroup

type JavaConstantGroup struct {
	// Name identifies this constant group (e.g., "LocationProvider").
	Name string `yaml:"name"`

	// GoType is the Go type name for the constants
	// (e.g., "LocationProvider").
	GoType string `yaml:"go_type"`

	Values []JavaConstantValue `yaml:"values"`
}

JavaConstantGroup describes a set of typed constants extracted from a Java source file (e.g., LocationProvider constants from LocationManager.java).

type JavaConstantValue

type JavaConstantValue struct {
	Name  string `yaml:"name"`
	Value string `yaml:"value"`
}

JavaConstantValue is a single constant within a group.

type JavaWireField

type JavaWireField struct {
	Name        string `yaml:"name"`
	WriteMethod string `yaml:"write_method"`
	Condition   string `yaml:"condition,omitempty"`
}

JavaWireField describes one field's serialization in the Java writeToParcel() method. Used to generate Go marshal/unmarshal code that matches the Java wire format.

type MethodSpec

type MethodSpec struct {
	Name string `yaml:"name"`

	// TransactionCodeOffset is the offset from binder.FirstCallTransaction.
	// The actual code is FirstCallTransaction + TransactionCodeOffset.
	TransactionCodeOffset int `yaml:"transaction_code_offset"`

	Oneway      bool        `yaml:"oneway,omitempty"`
	Params      []ParamSpec `yaml:"params,omitempty"`
	ReturnType  TypeRef     `yaml:"return_type,omitempty"`
	Annotations []string    `yaml:"annotations,omitempty"`
}

MethodSpec describes a single AIDL interface method.

type PackageSpec

type PackageSpec struct {
	// AIDLPackage is the dot-separated AIDL package name
	// (e.g., "android.app").
	AIDLPackage string `yaml:"package"`

	// GoPackage is the slash-separated Go package path relative to the
	// module root (e.g., "android/app").
	GoPackage string `yaml:"go_package"`

	Interfaces  []InterfaceSpec  `yaml:"interfaces,omitempty"`
	Parcelables []ParcelableSpec `yaml:"parcelables,omitempty"`
	Enums       []EnumSpec       `yaml:"enums,omitempty"`
	Unions      []UnionSpec      `yaml:"unions,omitempty"`

	// Services holds service name → AIDL descriptor mappings
	// extracted from Context.java + SystemServiceRegistry.java.
	// Typically only present in the servicemanager package spec.
	Services []ServiceMapping `yaml:"services,omitempty"`

	// JavaConstants holds typed constant groups extracted from Java sources.
	JavaConstants []JavaConstantGroup `yaml:"java_constants,omitempty"`
}

PackageSpec is the top-level spec for a single Go package. It contains all definitions extracted from AIDL and Java sources that belong to this package.

func ReadPackageSpec

func ReadPackageSpec(
	path string,
) (*PackageSpec, error)

ReadPackageSpec reads a single YAML spec file.

type ParamSpec

type ParamSpec struct {
	Name        string    `yaml:"name"`
	Type        TypeRef   `yaml:"type"`
	Direction   Direction `yaml:"direction,omitempty"`
	Annotations []string  `yaml:"annotations,omitempty"`
}

ParamSpec describes a method parameter.

type ParcelableSpec

type ParcelableSpec struct {
	Name string `yaml:"name"`

	Fields      []FieldSpec    `yaml:"fields,omitempty"`
	Constants   []ConstantSpec `yaml:"constants,omitempty"`
	NestedTypes []string       `yaml:"nested_types,omitempty"`
	Annotations []string       `yaml:"annotations,omitempty"`

	// JavaWireFormat describes the field serialization order and methods
	// as extracted from the Java writeToParcel() implementation.
	// Present only when java2spec has analyzed the corresponding Java class.
	JavaWireFormat []JavaWireField `yaml:"java_wire_format,omitempty"`
}

ParcelableSpec describes an AIDL parcelable (struct).

type ServiceMapping

type ServiceMapping struct {
	// ServiceName is the binder service name registered with ServiceManager
	// (e.g., "activity", "power", "clipboard").
	ServiceName string `yaml:"service_name"`

	// ConstantName is the Java constant name from android.content.Context
	// (e.g., "ACTIVITY_SERVICE", "POWER_SERVICE").
	ConstantName string `yaml:"constant_name"`

	// Descriptor is the fully qualified AIDL interface name
	// (e.g., "android.app.IActivityManager").
	Descriptor string `yaml:"descriptor"`
}

ServiceMapping connects an Android service name to its AIDL interface. Extracted from Context.java constants and SystemServiceRegistry.java registrations.

type TypeRef

type TypeRef struct {
	// Name is the type name. For primitives: "int32", "int64", "bool",
	// "float32", "float64", "String16", "String8", "byte", "char".
	// For AIDL types: fully qualified name (e.g., "android.app.ProcessMemoryState").
	// For arrays: the element type name (with IsArray=true).
	// For generics: the base type name (with TypeArgs set).
	Name string `yaml:"name"`

	// IsArray indicates T[] (variable-length array).
	IsArray bool `yaml:"is_array,omitempty"`

	// FixedSize is the array dimension for fixed-size arrays (e.g., "128"
	// for byte[128]). Empty for variable-length arrays.
	FixedSize string `yaml:"fixed_size,omitempty"`

	// IsNullable indicates the @nullable annotation.
	IsNullable bool `yaml:"is_nullable,omitempty"`

	// Annotations holds type-level annotation names beyond @nullable
	// (e.g., "utf8InCpp"). The @nullable annotation is NOT included
	// here — it is represented by IsNullable.
	Annotations []string `yaml:"annotations,omitempty"`

	// TypeArgs holds generic type arguments (e.g., List<T> → TypeArgs=[T]).
	TypeArgs []TypeRef `yaml:"type_args,omitempty"`
}

TypeRef describes a type reference in the spec. It captures both simple types (int32, bool, String16) and complex types (arrays, generics, nullable).

type UnionSpec

type UnionSpec struct {
	Name        string         `yaml:"name"`
	Fields      []FieldSpec    `yaml:"fields"`
	Constants   []ConstantSpec `yaml:"constants,omitempty"`
	NestedTypes []string       `yaml:"nested_types,omitempty"`
	Annotations []string       `yaml:"annotations,omitempty"`
}

UnionSpec describes an AIDL union (tagged variant type).