Development

AndroLog is a Java CLI built with Maven. It uses AndroSpecter for instrumentation support and Soot for bytecode analysis. The report interface is bundled as HTML, CSS, and JavaScript resources.

This wiki was checked against commit 68b3312, the 0.1 development code with capture support.

Build and validate

From the main repository root:

mvn test
node --test src/test/js/report-links.test.js src/test/js/report-graph.test.js
mvn package

mvn package runs Java tests as part of packaging; use it directly when you need both validation and the executable JAR. JavaScript tests are separate. Runtime JVM tests exercise tracing and emitted statement instrumentation; device tests are still useful for APK verification, signing, installation, and Android behavior.

Source map

All Java paths below are under src/main/java/com/jordansamhi/androlog/.

File or area	Responsibility
Main.java	CLI validation, mode selection, Soot setup, pipeline stages
CaptureWorkflow.java	Device selection, instrumentation, install, launch, capture, and report orchestration
CaptureProcesses.java	Managed subprocesses, output draining, timeouts, and shutdown cleanup
AdbLogCapture.java	Logcat reader and readiness/stop markers
ApkPreparator.java	Configuration, alignment, test signing, and replacement of the exported APK
LauncherActivities.java	Launcher filters and alias resolution from the manifest
instrumentation/StatementInstrumenter.java	Before-statement probes and shared statement eligibility
instrumentation/MethodCallInstrumenter.java	Original callsite capture and runtime hook insertion
runtime/CallTraceRuntime.java	Thread-local call correlation and deduplicated MC2 emission
SummaryBuilder.java	Baseline entities, method bodies, and callsites from the original APK
LogParser.java, SummaryLogBuilder.java	Record validation, coverage deduplication, minute buckets
CallGraph.java	Accepted call observations and graph aggregation
SummaryStatistics.java	Terminal output and JSON serialization
HtmlReportWriter.java	Build and embed report data
src/main/resources/report.html	Coverage explorer, layout, and styles
src/main/resources/report-links.js	Code reference navigation
src/main/resources/report-graph.js	Graph indexing, class selection, layout, and interaction

Browse the Java implementation and report resources.

Instrumentation order matters

When enabled, callsite capture runs before other probes mutate the original statements. Statement instrumentation snapshots original statement text and positions, then inserts probes before eligible units. Other coverage transforms follow, and call-tracing hooks are inserted around the captured original calls and at eligible method entries.

This order preserves the identities that reporting reconstructs from the uninstrumented APK. Keep baseline eligibility and instrumentation eligibility aligned. A change to probe placement can require reinstrumentation and fresh logs; it cannot be repaired by changing report rendering alone.

The current method-entry hook excludes constructors and class initializers. Constructor callsites still produce declared records. Do not treat the proposed distinction between known targets and observed entries as a feature already implemented in the current graph schema.

Runtime matching

CallTraceRuntime maintains pending calls per thread. Entry confirmation requires a matching subsignature, the same receiver for instance calls, and a direct caller stack. Return and caught-exception hooks clean up pending calls. The current pending-call limit is 256 entries per thread.

Each record contains a process trace UUID and a sequence number. Emission deduplicates declarations and actual-target pairs per callsite. This keeps the graph about distinct relationships, rather than invocation frequencies. Changes to this behavior should update the Dynamic Call Graph and JSON and Logs pages.

Capture uses separate Java processes

flowchart TD
    C[Capture coordinator] --> I[Instrumentation JVM]
    I --> A[Aligned and signed APK]
    A --> D[ADB install and launch]
    D --> L[Bounded runtime log]
    C --> R[Reporting JVM]
    L --> R
    O[Original APK] --> I
    O --> R
    R --> H[HTML and JSON]

Loading

Instrumentation and reporting run in fresh JVMs because Soot and supporting libraries maintain global state. Child processes inherit the classpath so an external signing configuration remains available. Probe, scope, tag, and thread options are forwarded consistently. The coordinator owns ADB/logcat processes and retains session diagnostics.

Contributing

Keep changes focused and explain the user-visible behavior in the commit or pull request. Add regression coverage when changing instrumentation, parsing, or graph semantics. Useful cases include branches, exceptions, constructor verification, recursion, interface dispatch, excluded callees, and concurrent execution.

Do not commit local SDK paths, signing overrides, APKs from private testing, or runtime logs containing application data. Use a small fixture when possible. The repository's LICENSE is GNU LGPL v2.1.

Maintain the wiki

The wiki has its own Git repository:

git clone git@github.com:JordanSamhi/AndroLog.wiki.git
cd AndroLog.wiki

Pages are Markdown files. Home.md is the entry page; _Sidebar.md and _Footer.md provide navigation. Images are stored in images/. Update the relevant guide when changing the CLI or runtime behavior, and check examples against --help and the implementation before publishing.

The main project and wiki have separate histories. Commit documentation changes under your own Git identity and push to the wiki's default branch. GitHub's wiki documentation describes the publication workflow.