How apache/maven-mvnd works
Project type and purpose
• This is neither a web app nor a database-backed service, but a CLI build tool employing a client–server (daemon) architecture to accelerate Maven builds.
• The mvnd client (a GraalVM-native executable) spawns or connects to one or more long-lived JVM “daemon” processes that embed Maven and cache build state across invocations.
Top-level modules and their roles
• client: the native GraalVM-compiled CLI that parses arguments, locates or spawns daemons, and forwards build requests.
• daemon: the long-running JVM process that loads Maven core, manages build execution, caches plugin classloaders, and returns results.
• common: shared communication primitives (sockets, messages, registry records, compatibility checks) used by client and daemon.
• agent: an optional Java agent injected into the daemon’s JVM to support advanced features (interactivity, logging, event spy).
• build-plugin: a Maven plugin shipped with mvnd (e.g., for documentation) that runs inside the Maven lifecycle.
• logging: slf4j integration to route Maven and plugin logs through the daemon back to the client console.
• native: JNI and native-image configuration for the client binary (OS detection, native loader).
• dist: assembly of the packaged distribution (shell scripts, completion files, default configs).
• helper: pump helper code to stream process output.
• integration-tests: full end-to-end tests exercising client, daemon, and real Maven projects (not part of runtime).
How components interact (data flow)
a. The user invokes the mvnd CLI (client).
b. Client reads config files (.mvn/mvnd.properties, ~/.m2/mvnd.properties, etc.) and determines build parameters.
c. Client consults the daemon registry (a file or directory under mvnd.daemonStorage) to find an idle daemon.
d. If none is available, the client launches a new daemon process (forking a JVM with the agent, classpath including Maven core).
e. Client opens an IPC channel (socket, named pipe) to the daemon using common/DaemonConnector and sends the build request.
f. Daemon receives the request in Server → ClientDispatcher → DaemonMavenInvoker, initializes or reuses cached plugin realms and classloaders.
g. Daemon executes the standard Maven build lifecycle (using embedded Maven core) in parallel threads, writing cache entries and plugin artifacts to the cache directory (cache factories in daemon/cache modules).
h. Logging subsystem captures build output, multiplexes thread-status lines into a “non-rolling” console view, and forwards it back over the IPC channel.
i. Daemon returns build completion status and full Maven logs to the client.
j. Client prints final results to the user and exits. The daemon remains running for subsequent builds.
Architectural patterns and design principles
• Client–server separation: a thin native front end vs. a heavyweight background service.
• Caching and reuse: plugin classloaders, JIT-compiled code, and parsed POMs survive across builds.
• Modular layering: each Maven/daemon concern is in its own Maven module; clear boundaries between CLI, IPC, build logic, cache, logging, native code.
• Extension points: agent for interactivity, build-plugin for docs, logging via slf4j.
• Cross-platform native support: native-image resource configs for Linux, macOS, Windows in native/src/main/resources.
Detail level
• Every major Maven module only if it contributes to runtime behavior (skip integration-tests).
• Two-process model (client vs. daemon), the IPC channel, caching layer, and Maven execution pipeline.
• Configuration lookup order (local → user → system).
• Don’t overcomplicate: break the system into client, registry, daemon (with cache + plugin + logging), external services (filesystem, remote repos).