# What Is the Primary Function of the apache-maven Directory?

> Discover the primary function of the apache-maven directory. Learn how it assembles the complete Apache Maven release into downloadable archives for easy distribution.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: internals
- Published: 2026-07-07

---

**The `apache-maven` directory serves as Maven’s distribution packaging module, responsible for assembling the complete Apache Maven release into downloadable ZIP and TAR.GZ archives.**

Within the `apache/maven` repository, the `apache-maven` directory functions as the dedicated distribution module. It aggregates all compiled artifacts, configuration files, and launch scripts into the portable archives that users download from the official Maven website. This module leverages the **`maven-assembly-plugin`** to standardize the layout and contents of every official Maven release.

## Core Responsibility: Packaging the Maven Distribution

The primary purpose of the `apache-maven` module is to produce the **distribution archives**—both source and binary—that constitute the official Apache Maven release. According to the source code in `apache/maven`, this module declares all required Maven components—including the CLI, embedder, core, and resolver—in [`apache-maven/pom.xml`](https://github.com/apache/maven/blob/main/apache-maven/pom.xml) and bundles them into standardized formats.

When the build executes, the `maven-assembly-plugin` processes descriptors located under `src/assembly/` to generate archives containing:

- The `bin/` directory with platform-specific launch scripts
- The `conf/` directory with default [`settings.xml`](https://github.com/apache/maven/blob/main/settings.xml) and [`toolchains.xml`](https://github.com/apache/maven/blob/main/toolchains.xml)
- The `lib/` directory containing core Maven libraries
- The `boot/` directory with the Plexus Classworlds launcher
- Native libraries such as JLine for enhanced console interaction

## Key Configuration Files Inside the apache-maven Directory

The assembly process is governed by several critical files that define exactly what gets packaged and how it is structured.

### Module Declaration and Dependencies (apache-maven/pom.xml)

The [`apache-maven/pom.xml`](https://github.com/apache/maven/blob/main/apache-maven/pom.xml) declares the module as the distribution aggregator. It lists all Maven components that must be bundled and configures build plugins including the compiler, Surefire for testing, and crucially, the **`maven-assembly-plugin`**.

### Assembly Descriptors (src/assembly/)

The assembly descriptors determine the physical layout of the distribution:

- **[`src/assembly/bin.xml`](https://github.com/apache/maven/blob/main/src/assembly/bin.xml)**: Defines the ZIP and TAR.GZ formats for the final binary distribution
- **[`src/assembly/dir.xml`](https://github.com/apache/maven/blob/main/src/assembly/dir.xml)**: Used by the `create-distribution-in-dir` profile to output an uncompressed directory layout instead of archives
- **[`src/assembly/component.xml`](https://github.com/apache/maven/blob/main/src/assembly/component.xml)**: Specifies which individual Maven components, license files, and native binaries belong in each distribution subdirectory

### Launch Scripts and Default Configuration

Raw templates for the distribution’s runtime files reside under `src/assembly/maven/`:

- **`src/assembly/maven/bin/`**: Contains platform-specific launch scripts (`mvn`, `mvnDebug`, `mvn.cmd`) that become executable files in the final `bin/` directory
- **`src/assembly/maven/conf/`**: Houses the default [`settings.xml`](https://github.com/apache/maven/blob/main/settings.xml) and [`toolchains.xml`](https://github.com/apache/maven/blob/main/toolchains.xml) configuration files shipped with every Maven installation

## Building the Maven Distribution Locally

Developers can generate the distribution archives locally using specific Maven commands targeting this module.

### Build Standard Archives

To generate the ZIP and TAR.GZ files in the `apache-maven/target/` directory:

```bash
mvn -pl apache-maven -am package

```

The `-pl apache-maven` selector restricts the build to this module, while `-am` (also-make) ensures all required dependencies are built first. The `package` phase triggers the `maven-assembly-plugin` configured in [`apache-maven/pom.xml`](https://github.com/apache/maven/blob/main/apache-maven/pom.xml).

### Create an Uncompressed Distribution Directory

For development or testing purposes, you can unpack the assembly directly into a custom location without creating archive files:

```bash
mvn -pl apache-maven -am -DdistributionTargetDir=/tmp/maven-dist package \
    -Pcreate-distribution-in-dir

```

This command activates the **`create-distribution-in-dir`** profile, which uses the [`dir.xml`](https://github.com/apache/maven/blob/main/dir.xml) assembly descriptor to write the distribution layout directly to the specified path.

### Verify the Generated Archive Structure

After building, inspect the contents of the generated TAR.GZ to confirm the standard directory layout:

```bash
tar -tzf apache-maven/target/apache-maven-*.tar.gz | head

```

This output reveals the top-level folders (`bin/`, `conf/`, `lib/`, `boot/`) and documentation files that match the official Maven release structure.

## Summary

- The `apache-maven` directory is the **distribution module** within the `apache/maven` repository, responsible for packaging the complete Maven application
- It uses the **`maven-assembly-plugin`** with descriptors in `src/assembly/` (notably [`bin.xml`](https://github.com/apache/maven/blob/main/bin.xml) and [`component.xml`](https://github.com/apache/maven/blob/main/component.xml)) to define archive contents and layout
- The module aggregates core components including the CLI, embedder, resolver, and libraries into the `bin/`, `conf/`, `lib/`, and `boot/` directories
- Developers can build distributable archives locally using `mvn -pl apache-maven -am package` or create uncompressed directories using the `create-distribution-in-dir` profile

## Frequently Asked Questions

### What archive formats does the apache-maven directory produce?

The `apache-maven` module produces both **ZIP** and **TAR.GZ** archives as defined in the [`src/assembly/bin.xml`](https://github.com/apache/maven/blob/main/src/assembly/bin.xml) descriptor. These archives contain identical content but use different compression formats to support various operating systems and user preferences.

### How does the maven-assembly-plugin function in this module?

The `maven-assembly-plugin` executes during the package phase of the `apache-maven` module build. It reads XML descriptors from `src/assembly/` to determine which project artifacts, dependencies, and external files (like launch scripts and licenses) to include, then packages them into the final distributable archives or unpacked directories.

### Can I customize which components are included in my Maven distribution?

Yes. By modifying the [`src/assembly/component.xml`](https://github.com/apache/maven/blob/main/src/assembly/component.xml) descriptor or the dependency list in [`apache-maven/pom.xml`](https://github.com/apache/maven/blob/main/apache-maven/pom.xml), you can exclude specific Maven components or include additional libraries. When building locally, these changes will propagate into your custom distribution archive generated via `mvn package` in the `apache-maven` module.

### Where does the apache-maven directory store the launch script templates?

The launch script templates—such as `mvn`, `mvnDebug`, and Windows variants—are stored in `apache-maven/src/assembly/maven/bin/`. During the assembly process, the `maven-assembly-plugin` copies these files into the `bin/` directory of the final distribution, preserving their executable permissions.