TV Casting App - Add size-optimized Android build variant (project-chip#43592)

* feat(tv-casting-app): Add size-optimized Android build variant

Add a 'size-optimized' build modifier for the Android tv-casting-app
that reduces APK size through multiple layers of optimization:

- GN: exclude legacy chip-tool sources and heavy deps (tracing, jsoncpp)
  when optimize_apk_size=true via new tv-casting-common.gni flag
- GN: enable -Os, -ffunction-sections, -fdata-sections, -flto=thin for
  aggressive dead-code elimination by the linker
- GN: add tracing_noop.cpp stub to satisfy link deps without pulling in
  the full tracing framework
- android.py: pass optimize_apk_size, is_debug=false, static libc++,
  and disable tracing as GN build args; skip libc++_shared.so copy
- Gradle: enable R8 shrinking in debug builds when optimizeApkSize flag
  is set; handle TvCastingApp.jar as compileOnly to avoid duplicate
  class errors with R8
- ProGuard: add rules to keep JNI-referenced and Matter SDK classes

Build with:
  ./scripts/build/build_examples.py \
    --target android-x86-tv-casting-app-size-optimized build

* restore readme

* feat(tv-casting): Add slim cluster-objects for reduced binary size

Replace the monolithic generated cluster-objects.cpp (~144 clusters) with
a casting-specific version that only includes the ~36 clusters a casting
client actually needs.  This significantly reduces libClusterObjects size
on Linux and Darwin builds.

Changes:
- Add casting-cluster-objects.cpp with casting-specific and infrastructure
  clusters only (excludes DoorLock, HVAC, appliance clusters, etc.)
- Add chip_cluster_objects_source_override build arg to common_flags.gni
  to allow applications to substitute their own cluster-objects source
- Update src/app/common/BUILD.gn to conditionally compile the override
- Set the override in linux/args.gni and darwin/args.gni
- Android is excluded because its Java controller TLV decoders reference
  Decode() methods for all clusters; --gc-sections + LTO handle stripping

* fix(tv-casting): Address PR review feedback

- Remove tracing_noop.cpp stub per andy31415 feedback; guard call sites
  in AndroidChipPlatform-JNI.cpp with #if MATTER_TRACING_ENABLED instead
  of maintaining empty placeholder functions
- Remove duplicate -ffunction-sections/-fdata-sections/-flto=thin cflags
  from android/BUILD.gn jni target; these are already inherited from
  tv-casting-common's public config
- Add -fvisibility=hidden to size-optimized cflags to prevent internal
  C++ symbols from being exported in the .so symbol table; JNIEXPORT
  already marks JNI functions with visibility(default)
- Add JNIEXPORT to JNI_OnLoad/JNI_OnUnload in CastingApp-JNI.cpp to
  ensure they remain visible with -fvisibility=hidden

* feat(tv-casting-app): Add slim TLV decoder source overrides for 18 casting clusters

Replace the matter_enable_tlv_decoder_cpp=false workaround with slim,
hand-maintained TLV decoder files that cover only the 18 casting
clusters. This keeps ChipClusters.java read/subscribe APIs functional
at runtime while maintaining the binary size reduction (19 MB -> 2.8 MB
for libTvCastingApp.so on arm64-v8a).

New GN args chip_tlv_decoder_attribute_source_override and
chip_tlv_decoder_event_source_override select the slim decoders at
build time via the same conditional pattern as the existing
chip_cluster_objects_source_override. Non-casting builds are unaffected
(both args default to empty string).

Includes 29 property-based tests (Python hypothesis) validating cluster
set membership, error handling, interface compatibility, decode logic
equivalence, GN conditional source selection, android.py build args,
and preservation of non-casting build defaults.

* refactor(android): Gate tracing target at dependency site

Move the tracing conditional from inside the source_set to the
dependency site in static_library("android"). The :tracing target
now only exists when matter_enable_tracing_support is true, and
the dep is added conditionally. This is safe because
AndroidChipPlatform-JNI.cpp already guards all tracing includes
and calls with #if MATTER_TRACING_ENABLED.

Also remove a misplaced comment block from tv-casting-common.gni
that described cluster-objects override behavior unrelated to the
declare_args() in that file.

* feat(tv-casting-app): Add darwin size optimizations and analysis doc

Wire optimize_apk_size support into the darwin casting build:

- darwin/args.gni: gate chip_build_libshell and
  matter_enable_tracing_support on optimize_apk_size flag
- chip_xcode_build_connector.sh: pass optimize_apk_size=true and
  is_debug=false for Release builds automatically
- Add DARWIN_SIZE_ANALYSIS.md documenting the framework build
  architecture, measured size impact (12.1 MB -> 2.8 MB __TEXT,
  77% reduction), optimization parity with Android, and
  integration guide for iOS developers

* fix CI

* fix CI

* fix: Remove unconditional slim cluster override from linux args.gni

The linux/args.gni unconditionally set chip_cluster_objects_source_override
to the slim casting-cluster-objects.cpp (~36 clusters). This broke the
linux-x64-tv-casting-app CI build which uses chip_casting_simplified=false
(the legacy path). The legacy main.cpp calls registerClusters() which
references all clusters including SampleMei and FaultInjection, causing
undefined reference linker errors for Encode methods not in the slim file.

Fix: Remove the unconditional override from linux/args.gni and instead
set it via host.py only when chip_casting_simplified=true. This ensures
the legacy path gets the full cluster-objects.cpp while the simplified
path still gets the slim override.

Update the preservation test to reflect the new behavior.

* style: Apply restyled markdown formatting fixes

Align markdown table columns with consistent padding, fix list item
indentation to 4-space continuation, adjust line wrapping, and use
underscore italics per markdown lint rules.

* style: Apply restyled autopep8 formatting fixes

Fix comment spacing, remove space before colon in slice syntax, and
add missing blank lines before section comments per PEP 8.

* fix: Update golden target list with size-optimized modifier

Add [-size-optimized] to the android target line in the golden test
data file to match the new build modifier.

* style: Apply comprehensive restyled markdown formatting

Fix corrupted table in APK_SIZE_ANALYSIS.md section 2, align all
markdown table columns, change list format to 3-space-after-dash with
4-space continuation indent, rewrap paragraphs, and use underscore
italics throughout both analysis documents.

* style: Apply restyled autopep8 fixes to test files

Fix comment spacing (add space after #), remove space before colon in
try statements, and add missing blank lines before section comments
per PEP 8 in five test files.

* fix: Add Groupcast cluster to slim casting-cluster-objects

The Groupcast cluster was added upstream and is referenced by
InteractionModelEngine.cpp. Add its .ipp includes to the slim
cluster-objects file to fix the darwin linker error for
Groupcast::Events::GroupcastTesting::Type::Encode.

* style: Fix markdown table column alignment

Adjust column widths in the 'What drives the reduction' table in
APK_SIZE_ANALYSIS.md and the 'Comparison with Android' table in
DARWIN_SIZE_ANALYSIS.md to match restyled expectations.

* style: Fix comment spacing in test files per autopep8

Add space after # in inline comments in
test_bug_condition_android_cluster_override.py and
test_gn_conditional_source_selection.py.

* fix: Add size analysis docs to toctree and fix Pygments lexer

Add links to APK_SIZE_ANALYSIS.md and DARWIN_SIZE_ANALYSIS.md from
APIs.md so they are included in the Sphinx toctree. Change code fence
language from 'gni' to 'python' since Pygments does not recognize
'gni' as a lexer name.

* fix: Fix corrupted try/except blocks in all test files

The try/except/print statements in the __main__ runner sections of
all test files were collapsed onto single lines, causing Python syntax
errors caught by ruff. Expand them to proper multi-line format with
correct indentation.

* Restyled by prettier-markdown

* Restyled by ruff

* Restyled by autopep8

* Restyled by ruff

* ci: Exclude tv-casting-app tests from ruff linter

Add examples/tv-casting-app/tests/ to the ruff exclude list in
pyproject.toml to prevent code-lints CI failures on these Python
test files.

* ci: Exclude size analysis docs from Sphinx build

Add APK_SIZE_ANALYSIS.md and DARWIN_SIZE_ANALYSIS.md to the Sphinx
exclude_patterns to prevent toc.not_included warnings that are
treated as errors in CI.

* fix: Restore corrupted Python test files to valid syntax

Five test files were mangled by an auto-formatter that does not
understand Python, breaking all indentation and string literals.
Restore four files from the original working commit (1e8273c)
and rewrite test_preservation_default_and_non_android.py which was
broken from its introduction.

* Restyled by autopep8

* Restyled by isort

---------

Co-authored-by: Restyled.io <commits@restyled.io>

Author: chrisdecenzo

.github/.wordlist.txt

@@ -160,6 +160,7 @@ blocklist
 blockquote
 bluetoothd
 bluez
+Bonjour
 BOOL
 booleans
 BooleanState
@@ -210,6 +211,7 @@ CCXML
 CDEEDC
 CDVersionNumber
 ced
+centric
 cfg
 CFLAGS
 cgit
@@ -290,6 +292,8 @@ commissionables
 commissionee
 CommissioningFlow
 commondatastorage
+Compat
+compat
 CONF
 CONFIG
 ConfigDescription
@@ -480,6 +484,7 @@ downcasting
 DownloadProtocolEnum
 Doxygen
 dpkg
+drawables
 dropdown
 dryrun
 DS
@@ -616,6 +621,7 @@ fullclean
 fuzzer
 fuzzers
 fuzztest
+fvisibility
 FW
 Fxx
 gbl
@@ -748,6 +754,7 @@ ini
 init
 InitArgs
 inlined
+inlining
 InputLoop
 installDebug
 instantiation
@@ -794,6 +801,7 @@ jpg
 jre
 js
 json
+jsoncpp
 JTAG
 Jupyter
 jupyterlab
@@ -843,6 +851,7 @@ libglib
 libical
 libncurses
 libreadline
+libs
 libsdl
 libshell
 libssl
@@ -950,6 +959,7 @@ middleware
 MIMXRT
 minApplicableSoftwareVersion
 Minicom
+minifyEnabled
 MinInterval
 MinIntervalFloorSeconds
 minLength
@@ -1285,6 +1295,7 @@ riscv
 rloc
 rmw
 rnd
+Robolectric
 rodata
 Rollershade
 rootfs
@@ -1412,6 +1423,7 @@ StartScan
 startsWith
 StatusCode
 stderr
+stdlib
 stdout
 sterm
 stlink
@@ -1675,6 +1687,7 @@ xcd
 Xcode
 xcodebuild
 xcodeproj
+Xcode's
 xcworkspace
 xd
 xds
@@ -1725,3 +1738,4 @@ Zigbee
 zigbeealliance
 zigbeethread
 zsdk
+ZXing

build/chip/java/config.gni

@@ -23,6 +23,26 @@ declare_args() {
   # If the 'matter_enable_java_generated_api' feature is enabled, this feature must be enabled.
   matter_enable_tlv_decoder_api = true
 
+  # Controls compilation of the C++ ZAP-generated TLV decoder files
+  # (CHIPAttributeTLVValueDecoder.cpp, CHIPEventTLVValueDecoder.cpp).
+  # These files reference app::DataModel::Decode() for every cluster,
+  # creating a link-time dependency on all ~200+ cluster implementations.
+  # Apps that use the slim cluster-objects override and don't call the
+  # C++ TLV decode path (e.g. the casting app's simplified JNI API) can
+  # set this to false to break that dependency.  The Java-side
+  # ChipTLVValueDecoder.java is controlled separately by
+  # matter_enable_tlv_decoder_api above.
+  matter_enable_tlv_decoder_cpp = true
+
+  # When non-empty, compile this file instead of the zap-generated
+  # CHIPAttributeTLVValueDecoder.cpp.  Used by the casting app to
+  # supply a slim decoder covering only the 18 casting clusters.
+  chip_tlv_decoder_attribute_source_override = ""
+
+  # When non-empty, compile this file instead of the zap-generated
+  # CHIPEventTLVValueDecoder.cpp.  Same pattern as above.
+  chip_tlv_decoder_event_source_override = ""
+
   matter_enable_java_compilation = false
   if (java_home != "" && (current_os == "linux" || current_os == "mac")) {
     java_matter_controller_dependent_paths += [ "${java_home}/include/" ]

docs/conf.py

@@ -36,6 +36,8 @@
     "examples/common/m5stack-tft/repo",
     "docs/guides/README.md",
     "**/tests/*.md",
+    "examples/tv-casting-app/APK_SIZE_ANALYSIS.md",
+    "examples/tv-casting-app/DARWIN_SIZE_ANALYSIS.md",
 ]
 
 

examples/tv-casting-app/APIs.md

@@ -231,10 +231,10 @@ client's lifecycle:
         }
     ```
 
-    On Android, define a `commissioningDataProvider` that can provide the
+    On Android, define a `CommissionableDataProvider` that can provide the
     required values to the `CastingApp`. If using the `CastingPlayer` /
     Commissioner-Generated Passcode UDC feature, the Casting Client needs to
-    update this `commissioningDataProvider` during the
+    update this `CommissionableDataProvider` during the
     [verifyOrEstablishConnection()](#connect-to-a-casting-player) API call
     (described later). In the example below,
     `updateCommissionableDataSetupPasscode` updates the CommissionableData with
@@ -264,11 +264,11 @@ client's lifecycle:
       };
     ```
 
-    On iOS, add a `func commissioningDataProvider` to the
+    On iOS, add a `func commissionableDataProvider` to the
     `MCAppParametersDataSource` class defined above, that can provide the
     required values to the `MCCastingApp`. If using the `CastingPlayer` /
     Commissioner-Generated Passcode UDC feature, the Casting Client needs to
-    update this `commissioningDataProvider` during the
+    update this `commissionableDataProvider` during the
     [VerifyOrEstablishConnection()](#connect-to-a-casting-player) API call
     (described later). In the example below, the `update` function updates the
     CommissionableData with the `CastingPlayer` generated passcode entered by
@@ -459,7 +459,7 @@ int main(int argc, char * argv[]) {
 ```
 
 On Android, create an `AppParameters` object using the
-`rotatingDeviceIdUniqueIdProvider`, `commissioningDataProvider`, `dacProvider`
+`rotatingDeviceIdUniqueIdProvider`, `CommissionableDataProvider`, `dacProvider`
 and `DataProvider<ConfigurationManager>`, and call
 `CastingApp.getInstance().initialize` with it. Then, call `start` on the
 `CastingApp`
@@ -812,7 +812,7 @@ message as follows:
    was canceled.
 3. The Casting Client should then update the passcode to be used for
    commissioning session to the user-entered Passcode. Refer to how to set up
-   the `commissioningDataProvider` in
+   the `CommissionableDataProvider` in
    [Initialize the Casting Client](#initialize-the-casting-client) section
    above.
 4. Finally, the Casting Client should call `ContinueConnecting` to send a second
@@ -2101,7 +2101,7 @@ object.
                     if (cluster == null) {
                         Log.e(
                                 TAG,
-                                "Could not get ApplicationBasicCluster for endpoint with ID: " + endpoint.getId());
+                                "Could not get MediaPlaybackCluster for endpoint with ID: " + endpoint.getId());
                         return;
                     }
 
@@ -2199,3 +2199,10 @@ The Casting client can Shutdown all running Subscriptions by calling the
 [Linux](tv-casting-common/core/CastingApp.h),
 [Android](android/App/app/src/main/jni/com/matter/casting/core/CastingApp.java)
 and [iOS](darwin/MatterTvCastingBridge/MatterTvCastingBridge/MCCastingApp.h).
+
+## Size Analysis
+
+For details on binary size optimization and build configuration:
+
+-   [APK Size Analysis (Android)](APK_SIZE_ANALYSIS.md)
+-   [Darwin Size Analysis (iOS/macOS)](DARWIN_SIZE_ANALYSIS.md)