Main Entry Points for Maven Core Development: CLI, Embedder, and DefaultMaven

The three primary entry points for Apache Maven core development are MavenCli for command-line launches, DefaultMaven for programmatic build execution, and MavenEmbedder for embedding Maven in Java applications.

When contributing to the apache/maven repository, understanding the main entry points for Maven core development is essential for debugging builds, writing integration tests, or extending functionality. These bootstrap classes translate user input into executable build sessions by wiring together the lifecycle executor, repository system, and plugin manager.

Command-Line Interface: MavenCli

The MavenCli class serves as the official command-line entry point for the Maven distribution. Located at compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java, this class implements the public static void main(String[] args) method that the mvn shell script invokes.

Parsing and Request Construction

MavenCli handles argument parsing, environment detection, and the construction of a MavenExecutionRequest. It populates the request with goals, profiles, properties, and base directory information derived from the command line. After building the request, MavenCli delegates to the core implementation to run the actual build.

Key Method Signature

The primary execution method within MavenCli is:

public int doMain(String[] args, String workingDirectory, File userSettingsFile, File globalSettingsFile)

This method returns an integer exit code where 0 indicates success and non-zero values signal build failures or configuration errors.

Core Execution Engine: DefaultMaven

DefaultMaven represents the heart of Maven's build execution. Found in impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java, this class implements the Maven interface and provides the execute(MavenExecutionRequest) method that ultimately runs the build lifecycle.

Wiring Components Together

DefaultMaven orchestrates the following core components:

• Lifecycle executor – manages phase-to-goal mapping and execution order
• Plugin manager – resolves and loads plugin dependencies
• Repository system – handles artifact resolution and deployment
• Session management – maintains thread-local MavenSession state

Unlike MavenCli, this class contains no main method and is designed purely for programmatic use within the JVM.

Embedding API: MavenEmbedder

The MavenEmbedder class at impl/maven-embedder/src/main/java/org/apache/maven/embedder/MavenEmbedder.java provides a simplified facade for embedding Maven inside other Java applications. It abstracts the low-level plumbing of MavenExecutionRequest construction and Plexus container initialization.

Convenience Methods

MavenEmbedder exposes higher-level methods such as:

public MavenExecutionResult execute(String pomFile, List<String> goals)
public MavenExecutionResult execute(MavenExecutionRequest request)

This wrapper is particularly useful for IDE integrations, continuous integration servers, and testing frameworks that need to invoke Maven builds without spawning external processes.

Execution Flow from Entry to Build

Understanding how these entry points interact clarifies the bootstrap process:

1. MavenCli.main() receives JVM control from the mvn launcher
2. MavenCli.doMain() parses arguments and creates a MavenExecutionRequest defined in api/maven-api-core/src/main/java/org/apache/maven/execution/MavenExecutionRequest.java
3. DefaultMaven.execute() accepts the request and initializes the MavenSession
4. Lifecycle execution proceeds through phases, producing a MavenExecutionResult returned back up the call stack

Summary

• MavenCli (compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java) – Parses command-line arguments and bootstraps the build; contains the main method.
• DefaultMaven (impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java) – Core implementation that executes the request and manages the lifecycle.
• MavenEmbedder (impl/maven-embedder/src/main/java/org/apache/maven/embedder/MavenEmbedder.java) – High-level API for embedding Maven in Java applications.
• Execution flow – MavenCli creates the request, DefaultMaven executes it, and MavenEmbedder provides a convenience wrapper around both.

Frequently Asked Questions

What is the difference between MavenCli and MavenEmbedder?

MavenCli is designed for command-line invocation and handles system console interactions, environment variable parsing, and process exit codes. MavenEmbedder provides a cleaner Java API for programmatic use, hiding container initialization complexity and offering simpler method signatures for embedded scenarios.

Where is the main method located in Maven core?

The public static void main(String[] args) method resides in org.apache.maven.cli.MavenCli within compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java. This is the canonical entry point triggered when running the mvn command.

How does DefaultMaven interact with the lifecycle executor?

DefaultMaven obtains the lifecycle executor component from the Plexus container and delegates phase execution to it. The lifecycle executor then maps phases to bound plugin goals and manages the sequential execution of the build stages.

Can Maven be embedded in standalone Java applications?

Yes, through MavenEmbedder, which handles classloader isolation, component lookup, and request construction. This allows developers to execute Maven builds from within servlet containers, IDEs, or test harnesses without requiring a local Maven installation on the system path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}