feat: split capi/idiomatic output by API level with build tags

Teach capigen and idiomgen to split functions by API level. Functions
above the base level (35) go into separate files with
//go:build android_ndk{N} tags.

For API-36 functions (NdkMediaCodecInfo.h), the cgo preamble uses
#undef/__define __ANDROID_MIN_SDK_VERSION__ 36 and
__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ to make declarations visible
despite compiling with an API-35 target NDK.

This fixes CI: without -tags android_ndk36, the 40 API-36 media
functions are excluded. With the tag, they're included.

The solution is generic — any module can use api_levels in its overlay.

Author: xaionaro@dx.center

Makefile

@@ -41,10 +41,14 @@ capi:
 		spec="spec/generated/$$m.yaml"; \
 		[ -f "$$manifest" ] || continue; \
 		[ -f "$$spec" ] || continue; \
+		overlay="spec/overlays/$$m.yaml"; \
+		overlay_flag=""; \
+		[ -f "$$overlay" ] && overlay_flag="-overlay $$overlay"; \
 		echo "capigen $$m"; \
 		go run ./tools/cmd/capigen \
 			-spec "$$spec" \
 			-manifest "$$manifest" \
+			$$overlay_flag \
 			-out "capi/$$m/"; \
 	done
 

capi/media/media.go

@@ -260,3 +260,43 @@ api_levels:
   AMediaMuxer_addTrack: 21
   AMediaMuxer_start: 21
   AMediaMuxer_stop: 21
+  AMediaCodecInfo_getCanonicalName: 36
+  AMediaCodecInfo_getKind: 36
+  AMediaCodecInfo_isVendor: 36
+  AMediaCodecInfo_getMediaCodecInfoType: 36
+  AMediaCodecInfo_getMediaType: 36
+  AMediaCodecInfo_getMaxSupportedInstances: 36
+  AMediaCodecInfo_isFeatureSupported: 36
+  AMediaCodecInfo_isFeatureRequired: 36
+  AMediaCodecInfo_isFormatSupported: 36
+  AMediaCodecInfo_getAudioCapabilities: 36
+  AMediaCodecInfo_getVideoCapabilities: 36
+  AMediaCodecInfo_getEncoderCapabilities: 36
+  ACodecAudioCapabilities_getBitrateRange: 36
+  ACodecAudioCapabilities_getSupportedSampleRates: 36
+  ACodecAudioCapabilities_getSupportedSampleRateRanges: 36
+  ACodecAudioCapabilities_getMaxInputChannelCount: 36
+  ACodecAudioCapabilities_getMinInputChannelCount: 36
+  ACodecAudioCapabilities_getInputChannelCountRanges: 36
+  ACodecAudioCapabilities_isSampleRateSupported: 36
+  ACodecPerformancePoint_create: 36
+  ACodecPerformancePoint_destroy: 36
+  ACodecPerformancePoint_coversFormat: 36
+  ACodecPerformancePoint_covers: 36
+  ACodecPerformancePoint_equals: 36
+  ACodecVideoCapabilities_getBitrateRange: 36
+  ACodecVideoCapabilities_getSupportedWidths: 36
+  ACodecVideoCapabilities_getSupportedHeights: 36
+  ACodecVideoCapabilities_getWidthAlignment: 36
+  ACodecVideoCapabilities_getHeightAlignment: 36
+  ACodecVideoCapabilities_getSupportedFrameRates: 36
+  ACodecVideoCapabilities_getSupportedWidthsFor: 36
+  ACodecVideoCapabilities_getSupportedHeightsFor: 36
+  ACodecVideoCapabilities_getSupportedFrameRatesFor: 36
+  ACodecVideoCapabilities_getAchievableFrameRatesFor: 36
+  ACodecVideoCapabilities_getNextSupportedPerformancePoint: 36
+  ACodecVideoCapabilities_areSizeAndRateSupported: 36
+  ACodecVideoCapabilities_isSizeSupported: 36
+  ACodecEncoderCapabilities_getQualityRange: 36
+  ACodecEncoderCapabilities_getComplexityRange: 36
+  ACodecEncoderCapabilities_isBitrateModeSupported: 36

capi/media/media_api36.go

@@ -16,12 +16,13 @@ func main() {
 	var (
 		specPath     = flag.String("spec", "", "path to spec YAML file (required)")
 		manifestPath = flag.String("manifest", "", "path to capi manifest YAML (required)")
+		overlayPath  = flag.String("overlay", "", "path to overlay YAML (optional, for api_levels)")
 		outDir       = flag.String("out", "", "output directory for generated package (required)")
 	)
 	flag.Parse()
 
 	if *specPath == "" || *manifestPath == "" || *outDir == "" {
-		fmt.Fprintln(os.Stderr, "usage: capigen -spec <spec.yaml> -manifest <manifest.yaml> -out <dir>")
+		fmt.Fprintln(os.Stderr, "usage: capigen -spec <spec.yaml> -manifest <manifest.yaml> -out <dir> [-overlay <overlay.yaml>]")
 		os.Exit(1)
 	}
 
@@ -37,7 +38,16 @@ func main() {
 		os.Exit(1)
 	}
 
-	if err := capigen.GeneratePackage(spec, manifest, *outDir); err != nil {
+	var apiLevels map[string]int
+	if *overlayPath != "" {
+		apiLevels, err = readAPILevels(*overlayPath)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "read overlay: %v\n", err)
+			os.Exit(1)
+		}
+	}
+
+	if err := capigen.GeneratePackage(spec, manifest, *outDir, apiLevels); err != nil {
 		fmt.Fprintf(os.Stderr, "generate: %v\n", err)
 		os.Exit(1)
 	}
@@ -73,3 +83,20 @@ func readManifest(path string) (*capigen.Manifest, error) {
 
 	return &m, nil
 }
+
+// readAPILevels reads only the api_levels map from an overlay YAML file.
+func readAPILevels(path string) (map[string]int, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	var overlay struct {
+		APILevels map[string]int `yaml:"api_levels"`
+	}
+	if err := yaml.Unmarshal(data, &overlay); err != nil {
+		return nil, err
+	}
+
+	return overlay.APILevels, nil
+}

spec/overlays/media.yaml

@@ -86,13 +86,23 @@ type FlagGroup struct {
 	Flags []string `yaml:"flags"`
 }
 
+// BaseAPILevel is the default Android API level. Functions at or below this
+// level go into the main generated file; functions above it are emitted into
+// separate build-tagged files.
+const BaseAPILevel = 35
+
 // GeneratePackage generates a complete capi/ Go package from the spec
 // and manifest. It writes doc.go, types.go, const.go, cgo_helpers.go,
 // cgo_helpers.h, and {module}.go into outDir.
+//
+// apiLevels is an optional map from C function name to the minimum Android
+// API level required. Functions above BaseAPILevel are placed in separate
+// files with //go:build android_ndk{N} tags.
 func GeneratePackage(
 	spec *specmodel.Spec,
 	manifest *Manifest,
 	outDir string,
+	apiLevels ...map[string]int,
 ) error {
 	if err := os.MkdirAll(outDir, 0o755); err != nil {
 		return fmt.Errorf("creating output directory %s: %w", outDir, err)
@@ -132,14 +142,51 @@ func GeneratePackage(
 	// the same name, so the type gets a "_s" suffix.
 	typeRenameMap := computeTypeRenameMap(spec, structPrefixSet)
 
+	// Resolve API levels map.
+	var levels map[string]int
+	if len(apiLevels) > 0 && apiLevels[0] != nil {
+		levels = apiLevels[0]
+	}
+
+	// Split functions into base (no tag) and per-API-level groups.
+	baseFunctions := make(map[string]specmodel.FuncDef)
+	higherFunctions := make(map[int]map[string]specmodel.FuncDef) // api level -> functions
+	for name, fn := range spec.Functions {
+		level := levels[name]
+		if level > BaseAPILevel {
+			if higherFunctions[level] == nil {
+				higherFunctions[level] = make(map[string]specmodel.FuncDef)
+			}
+			higherFunctions[level][name] = fn
+		} else {
+			baseFunctions[name] = fn
+		}
+	}
+
+	// Build a base spec (without higher-API functions) for the main file.
+	baseSpec := *spec
+	baseSpec.Functions = baseFunctions
+
 	files := map[string]string{}
 	files["doc.go"] = generateDocGo(pkgName, manifest.Generator.PackageDescription)
 	files["types.go"] = generateTypesGo(pkgName, preamble, spec, callbackSet, structPrefixSet, typeRenameMap)
 	files["const.go"] = generateConstGo(pkgName, preamble, spec, enumTypedefSet)
 	files["cgo_helpers.go"] = generateCgoHelpersGo(pkgName, preamble, spec, callbackSet)
 	files["cgo_helpers.h"] = generateCgoHelpersH(pkgName, manifest, spec, structPrefixSet)
 	files["cgo_helpers.c"] = generateCgoHelpersC(pkgName, spec, structPrefixSet)
-	files[pkgName+".go"] = generateFunctionsGo(pkgName, preamble, spec, callbackSet, structPrefixSet, typeRenameMap)
+	files[pkgName+".go"] = generateFunctionsGo(pkgName, preamble, &baseSpec, callbackSet, structPrefixSet, typeRenameMap)
+
+	// Generate per-API-level function files with build tags.
+	apiLevelKeys := sortedIntKeys(higherFunctions)
+	for _, level := range apiLevelKeys {
+		funcs := higherFunctions[level]
+		levelSpec := *spec
+		levelSpec.Functions = funcs
+		fileName := fmt.Sprintf("%s_api%d.go", pkgName, level)
+		levelPreamble := buildAPILevelPreamble(manifest, level)
+		buildTag := fmt.Sprintf("//go:build android_ndk%d\n\n", level)
+		files[fileName] = buildTag + generateFunctionsGo(pkgName, levelPreamble, &levelSpec, callbackSet, structPrefixSet, typeRenameMap)
+	}
 
 	for name, content := range files {
 		path := filepath.Join(outDir, name)
@@ -181,6 +228,46 @@ func buildCGoPreamble(manifest *Manifest) string {
 	return sb.String()
 }
 
+// buildAPILevelPreamble constructs a CGo comment block for a higher API level.
+// It uses #undef + #define __ANDROID_MIN_SDK_VERSION__ before the includes
+// so the preprocessor exposes declarations guarded by __INTRODUCED_IN(N).
+// The #undef is necessary because the compiler's target triple (e.g.
+// android35-clang) pre-defines __ANDROID_MIN_SDK_VERSION__ to the base level.
+// __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ disables the strict availability
+// attribute that would otherwise cause Clang to reject the declarations even
+// when __BIONIC_AVAILABILITY_GUARD passes.
+func buildAPILevelPreamble(manifest *Manifest, apiLevel int) string {
+	var sb strings.Builder
+	sb.WriteString("/*\n")
+	for _, fg := range manifest.Generator.FlagGroups {
+		sb.WriteString("#cgo ")
+		sb.WriteString(fg.Name)
+		sb.WriteString(": ")
+		sb.WriteString(strings.Join(fg.Flags, " "))
+		sb.WriteString("\n")
+	}
+	sb.WriteString("#undef __ANDROID_MIN_SDK_VERSION__\n")
+	fmt.Fprintf(&sb, "#define __ANDROID_MIN_SDK_VERSION__ %d\n", apiLevel)
+	sb.WriteString("#define __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ 1\n")
+	for _, inc := range manifest.Generator.Includes {
+		fmt.Fprintf(&sb, "#include \"%s\"\n", inc)
+	}
+	sb.WriteString("#include <stdlib.h>\n")
+	sb.WriteString("#include \"cgo_helpers.h\"\n")
+	sb.WriteString("*/")
+	return sb.String()
+}
+
+// sortedIntKeys returns sorted keys from a map[int]V.
+func sortedIntKeys[V any](m map[int]V) []int {
+	keys := make([]int, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Ints(keys)
+	return keys
+}
+
 // buildEnumTypedefSet returns the set of type names that have matching enum groups.
 func buildEnumTypedefSet(spec *specmodel.Spec) map[string]bool {
 	set := make(map[string]bool)

tools/cmd/capigen/main.go

@@ -107,6 +107,86 @@ func TestGeneratePackage(t *testing.T) {
 	}
 }
 
+func TestGeneratePackageWithAPILevels(t *testing.T) {
+	spec := looperSpec()
+	// Add an API-36 function to the spec.
+	spec.Functions["ALooper_newFeature"] = specmodel.FuncDef{
+		CName: "ALooper_newFeature",
+		Params: []specmodel.Param{
+			{Name: "looper", Type: "*ALooper"},
+		},
+		Returns: "int32",
+	}
+	manifest := looperManifest()
+	apiLevels := map[string]int{
+		"ALooper_newFeature": 36,
+	}
+
+	outDir := t.TempDir()
+	err := GeneratePackage(spec, manifest, outDir, apiLevels)
+	require.NoError(t, err)
+
+	// Base file should exist and not contain the API-36 function.
+	basePath := filepath.Join(outDir, "looper.go")
+	baseContent, err := os.ReadFile(basePath)
+	require.NoError(t, err)
+	assert.NotContains(t, string(baseContent), "ALooper_newFeature",
+		"base file must not contain API-36 function")
+	assert.Contains(t, string(baseContent), "ALooper_forThread",
+		"base file must contain base-level functions")
+
+	// API-36 file should exist with build tag and the function.
+	api36Path := filepath.Join(outDir, "looper_api36.go")
+	api36Content, err := os.ReadFile(api36Path)
+	require.NoError(t, err)
+	api36Str := string(api36Content)
+	assert.Contains(t, api36Str, "//go:build android_ndk36",
+		"API-36 file must have build tag")
+	assert.Contains(t, api36Str, "ALooper_newFeature",
+		"API-36 file must contain the higher-API function")
+	assert.Contains(t, api36Str, "#undef __ANDROID_MIN_SDK_VERSION__",
+		"API-36 preamble must undef the SDK version")
+	assert.Contains(t, api36Str, "#define __ANDROID_MIN_SDK_VERSION__ 36",
+		"API-36 preamble must define SDK version 36")
+	assert.Contains(t, api36Str, "__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__",
+		"API-36 preamble must enable weak symbols")
+}
+
+func TestGeneratePackageWithoutAPILevels(t *testing.T) {
+	spec := looperSpec()
+	manifest := looperManifest()
+
+	outDir := t.TempDir()
+	// No API levels — should produce the same output as before.
+	err := GeneratePackage(spec, manifest, outDir)
+	require.NoError(t, err)
+
+	basePath := filepath.Join(outDir, "looper.go")
+	baseContent, err := os.ReadFile(basePath)
+	require.NoError(t, err)
+	assert.Contains(t, string(baseContent), "ALooper_forThread")
+	assert.Contains(t, string(baseContent), "ALooper_addFd")
+
+	// No API-level files should be generated.
+	entries, err := os.ReadDir(outDir)
+	require.NoError(t, err)
+	for _, e := range entries {
+		assert.NotContains(t, e.Name(), "_api",
+			"no API-level files should exist without API levels")
+	}
+}
+
+func TestBuildAPILevelPreamble(t *testing.T) {
+	manifest := looperManifest()
+	preamble := buildAPILevelPreamble(manifest, 36)
+
+	assert.Contains(t, preamble, "#undef __ANDROID_MIN_SDK_VERSION__")
+	assert.Contains(t, preamble, "#define __ANDROID_MIN_SDK_VERSION__ 36")
+	assert.Contains(t, preamble, "#define __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ 1")
+	assert.Contains(t, preamble, "#cgo LDFLAGS: -landroid")
+	assert.Contains(t, preamble, "#include \"android/looper.h\"")
+}
+
 func TestGenerateDocGo(t *testing.T) {
 	content := generateDocGo("looper", "Raw CGo bindings for Android looper")
 	assert.Contains(t, content, "package looper")