How manabu-gt/debugoverlay-android works
Project type and purpose
• This is a multi‐module Android library project (built with Gradle) that produces:
• debugoverlay (core AAR) – a runtime overlay service and UI modules
• debugoverlay-no-op (no-operation stub for release/test)
• debugoverlay-ext-timber and debugoverlay-ext-netstats (optional extension modules)
• sample (Android application demonstrating usage)
• Purpose: allow Android developers to plug in performance/debug overlays (CPU, memory, FPS, logcat, network, Timber logs, or custom) into their apps via a uniform API.
File structure
• Root: settings.gradle includes five subprojects: debugoverlay, debugoverlay-no-op, debugoverlay-ext-timber, debugoverlay-ext-netstats, sample
• Each library subproject follows the standard Android Gradle module layout:
• build.gradle + gradle.properties + proguard-rules (where applicable)
• src/main/java/com/ms_square/... – core classes (OverlayModule, DataModule, ViewModule, service, modules)
• src/main/res + src/main/AndroidManifest.xml
• src/test for unit tests
• The sample app consumes the AARs (via local modules/libs) and shows how to compose modules with DebugOverlay.Builder
• Key build files: top‐level build.gradle orchestrates plugin versions; each subproject’s build.gradle exports an AAR.
README for additional insights
• Architecture is plugin-based: each OverlayModule bundles a DataModule and a ViewModule
• A Builder API configures which modules to install, positioning, styling, and whether to use the system window layer
• Extensions (Timber, NetStats) are separate modules that implement the same OverlayModule interface
• No‐op variant implements the same interfaces but does nothing, to avoid method count in production
Main components
a. Core components:
• DebugOverlay.Builder (configuration entrypoint)
• OverlayService (for system‐layer window management)
• OverlayModule (abstract interface)
– DataModule (collects metrics, notifies observers)
– ViewModule (creates/updates Android View)
• Android WindowManager/System Alert Window (overlay host)
b. Extension modules (subprojects):
• debugoverlay-ext-timber → TimberModule → TimberDataModule + TimberViewModule
• debugoverlay-ext-netstats → NetStatsModule → NetStatsDataModule + NetStatsView
c. No-op library: stub implementations of OverlayModule, DataModule, ViewModule
d. Sample app: depends on core & optional modules, invokes Builder, embeds OverlayService
Relationships and interactions
• Sample App/API Consumer calls DebugOverlay.Builder → selects modules → calls install()
• Builder instantiates OverlayService (or uses in-process windows)
• For each OverlayModule:
• DataModule.start() reads OS sources (/proc, Choreographer callbacks, Logcat streams, Network stats)
• DataModule pushes updates via observer callbacks
• ViewModule receives updates and updates Android View contents (TextView or custom layouts)
• OverlayService attaches these Views to WindowManager as system alert windows (or in‐app overlays)
• No-op modules are swapped in during release/test builds by Gradle’s debugCompile/releaseCompile configuration
Architectural patterns and design principles
• Plugin/Modular architecture: core library defines interfaces; modules conform to those
• Separation of concerns: data gathering (DataModule) vs. UI rendering (ViewModule)
• Builder pattern: central configuration API for assembling modules, styles, permissions
• Multi-project Gradle setup: isolates core, no-op, extensions, sample
Technologies, frameworks, libraries
• Android SDK (WindowManager, Service, Choreographer, BroadcastReceiver)
• Gradle (multi-module build, AARs)
• Java (interfaces, observer pattern)
• Optional: Timber logging library for TimberModule