Skip to content

API Reference ​

This document provides detailed API reference for Maven SDK Go. For the bigger picture — how these packages interact and how a build request flows through the system — see the Architecture guide.

Package Map ​

Package Overview ​

Finder ​

The Finder package locates Maven executables, including system Maven and Maven Wrapper.

go
package finder

// FindMaven finds a locally-installed Maven executable (PATH / M2_HOME / MAVEN_HOME)
func FindMaven() (string, error)

// Check validates a directory contains a valid Maven installation
func Check(mavenHomeDirectory string) bool

// FindMavenWrapper finds Maven Wrapper (mvnw/mvnw.cmd) in a project directory
func FindMavenWrapper(projectDir string) (string, error)

// FindBestMaven finds the best Maven: prefers project Wrapper, falls back to system Maven
func FindBestMaven(projectDir string) (string, error)

// HasMavenWrapper checks if a project directory contains Maven Wrapper
func HasMavenWrapper(projectDir string) bool

var ErrNotFoundMaven error
var ErrNotFoundMavenWrapper error

Resolution order used by FindBestMaven — the project wrapper is preferred because it pins the exact Maven version the project expects:

Check is the predicate behind the M2_HOME branch above — it confirms a candidate directory really is a Maven home by probing for the binary via command.BuildExecutable, not just trusting the env var:

Command ​

The Command package provides comprehensive Maven command execution.

The builder pattern provides a fluent, composable API for constructing Maven commands:

go
package command

// Create a builder with common CI settings
output, err := NewCommandBuilder().
    WithExecutable("mvn").
    WithWorkingDirectory("/path/to/project").
    WithBatchMode().           // -B: non-interactive mode for CI
    WithNoTransferProgress().  // -ntp: cleaner CI logs
    WithProfiles("ci").        // -P ci
    WithSkipTests().           // -DskipTests
    WithUpdateSnapshots().     // -U
    Clean()                    // executes "mvn -B -ntp -P ci -DskipTests -U clean"

Builder Options:

MethodCLI FlagDescription
WithExecutable(path)—Set mvn executable path
WithWorkingDirectory(dir)—Set working directory
WithPomFile(path)-fSpecify POM file
WithSettingsFile(path)-sSpecify user settings.xml
WithGlobalSettings(path)-gsSpecify global settings.xml
WithToolchains(path)-tSpecify toolchains file
WithProfiles(...)-PActivate profiles
WithProperty(k, v)-Dk=vSet system property
WithProperties(map)-Dk=vSet multiple properties
WithProjects(...)-plBuild specific modules
WithAlsoMake()-amAlso build dependencies
WithAlsoMakeDependents()-amdAlso build dependents
WithOffline()-oOffline mode
WithBatchMode()-BNon-interactive mode
WithUpdateSnapshots()-UForce update snapshots
WithSkipTests()-DskipTestsSkip test execution
WithSkipTestsCompletely()-Dmaven.test.skip=trueSkip test compilation & execution
WithErrors()-eShow full error stack traces
WithDebug()-XDebug output
WithQuiet()-qQuiet mode
WithThreads(n)-T nParallel builds
WithNonRecursive()-NDon't recurse into submodules
WithResumeFrom(module)-rfResume build from module
WithFailAtEnd()-faeContinue on failure, fail at end
WithFailNever()-fnNever fail
WithFailFast()-ffFail fast (default)
WithNoTransferProgress()-ntpSuppress download progress
WithStrictChecksums()-CFail on checksum mismatch
WithLaxChecksums()-cWarn on checksum mismatch
WithShowVersion()-VShow version without stopping

Builder Convenience Methods: Clean(), Compile(), Test(), Package(), Install(), Deploy(), Verify()

Immutability: Convenience methods do NOT mutate the builder. Each call creates a copy with the additional goal, so the original builder remains reusable for subsequent calls.

Error Handling ​

Every failure surfaces as a typed *MavenError carrying the exit code, the full argv, and Maven's stderr — so callers can branch on the exit code instead of grepping strings.

go
// MavenError represents a failed Maven command execution
type MavenError struct {
    Command   string   // The full command (e.g. "mvn clean install")
    Args      []string // Command arguments
    Stderr    string   // Maven's stderr output (truncated to 500 chars)
    ExitCode  int      // Process exit code (if available)
    Inner     error    // The original error
}

// ExecForStdout returns *MavenError when the command fails, including stderr content
output, err := command.Clean("mvn")
if err != nil {
    var me *command.MavenError
    if errors.As(err, &me) {
        log.Printf("Maven stderr: %s", me.Stderr)
    }
}

Generic Execution ​

go
// Options holds command execution configuration
type Options struct {
    Executable       string
    Args             []string
    WorkingDirectory string
    Stdin            io.Reader
    Stdout           io.Writer
    Stderr           io.Writer
}

// Exec executes a Maven command with options
func Exec(options *Options) error

// ExecForStdout executes and returns stdout
func ExecForStdout(executable string, args ...string) (string, error)

// BuildExecutable constructs mvn path from MAVEN_HOME
func BuildExecutable(mavenHomeDirectory string) string

Exec is the low-level escape hatch beneath the builder — it wires an Options struct straight into *exec.Cmd, giving you full control over the process's stdio. ExecForStdout is the convenience wrapper that captures stdout for you:

Lifecycle Phases ​

Invoking a phase runs it and every earlier phase in the same lifecycle. The functions below are thin wrappers over mvn <phase>.

go
// Standard phases
func Clean(executable string) (string, error)          // mvn clean
func Compile(executable string) (string, error)         // mvn compile
func Test(executable string) (string, error)            // mvn test
func TestCompile(executable string) (string, error)     // mvn test-compile
func Package(executable string) (string, error)         // mvn package
func Verify(executable string) (string, error)          // mvn verify
func Deploy(executable string) (string, error)          // mvn deploy
func Site(executable string) (string, error)            // mvn site
func Validate(executable string) (string, error)        // mvn validate
func Install(executable string) (string, error)         // mvn clean install
func StandaloneInstall(executable string) (string, error) // mvn install (no clean)

// Extended phases
func Initialize(executable string) (string, error)           // mvn initialize
func GenerateSources(executable string) (string, error)      // mvn generate-sources
func ProcessResources(executable string) (string, error)     // mvn process-resources
func PreparePackage(executable string) (string, error)       // mvn prepare-package
func PreIntegrationTest(executable string) (string, error)   // mvn pre-integration-test
func IntegrationTest(executable string) (string, error)      // mvn integration-test
func PostIntegrationTest(executable string) (string, error)  // mvn post-integration-test
func PreClean(executable string) (string, error)             // mvn pre-clean
func PostClean(executable string) (string, error)            // mvn post-clean
func PreSite(executable string) (string, error)              // mvn pre-site
func PostSite(executable string) (string, error)             // mvn post-site
func SiteDeploy(executable string) (string, error)           // mvn site-deploy

Dependency Commands ​

go
func DependencyGet(executable, groupId, artifactId, version string) (string, error)  // mvn dependency:get
func DependencyTree(executable string) (string, error)                               // mvn dependency:tree
func DependencyResolve(executable string) (string, error)                            // mvn dependency:resolve
func DependencyAnalyze(executable string) (string, error)                            // mvn dependency:analyze
func DependencyList(executable string) (string, error)                               // mvn dependency:list
func DependencyPurgeLocalRepository(executable string) (string, error)               // mvn dependency:purge-local-repository
func DependencyCopy(executable, gid, aid, ver, outputDir string) (string, error)     // mvn dependency:copy
func DependencyCopyDependencies(executable, outputDir string) (string, error)        // mvn dependency:copy-dependencies
func DependencyUnpack(executable, gid, aid, ver, outputDir string) (string, error)   // mvn dependency:unpack
func DependencyBuildClasspath(executable string) (string, error)                     // mvn dependency:build-classpath

The dependency commands split into three intents — inspecting the resolved graph, mutating the local cache, and materializing artifacts to disk:

Help Commands ​

go
func Version(executable string) (string, error)                    // mvn -v
func GetLocalRepositoryDirectory(executable string) (string, error) // mvn help:evaluate
func EffectivePom(executable string) (string, error)               // mvn help:effective-pom
func EffectiveSettings(executable string) (string, error)           // mvn help:effective-settings
func ActiveProfiles(executable string) (string, error)              // mvn help:active-profiles
func DescribePlugin(executable, plugin string) (string, error)     // mvn help:describe

The help commands are read-only introspection — they ask Maven about its own state without building anything. Version is the only one that doesn't even spawn the full runtime (it's just -v):

Testing Plugins ​

go
// Surefire (unit tests)
func SurefireTest(executable string) (string, error)                        // mvn surefire:test
func SurefireTestSingleClass(executable, className string) (string, error)  // mvn surefire:test -Dtest=...
func SurefireTestMethod(executable, methodSpec string) (string, error)      // mvn surefire:test -Dtest=Class#method

// Failsafe (integration tests)
func FailsafeIntegrationTest(executable string) (string, error)  // mvn failsafe:integration-test
func FailsafeVerify(executable string) (string, error)           // mvn failsafe:verify

Surefire and Failsafe are paired but serve different lifecycle phases — Surefire runs in test, Failsafe spans integration-test → verify so an integration-test failure can still trigger cleanup before failing the build:

SurefireTestSingleClass / SurefireTestMethod narrow the run with -Dtest=Class / -Dtest=Class#method, letting you re-run a single failing test without paying for the whole suite.

Version Management ​

go
func VersionsSet(executable, newVersion string) (string, error)               // mvn versions:set
func VersionsCommit(executable string) (string, error)                        // mvn versions:commit
func VersionsRevert(executable string) (string, error)                        // mvn versions:revert
func VersionsDisplayDependencyUpdates(executable string) (string, error)      // mvn versions:display-dependency-updates
func VersionsDisplayPluginUpdates(executable string) (string, error)          // mvn versions:display-plugin-updates
func VersionsUseLatestReleases(executable string) (string, error)             // mvn versions:use-latest-releases
func VersionsUseNextReleases(executable string) (string, error)               // mvn versions:use-next-releases

versions:set writes the new version into pom.xml and leaves a pom.xml.versionsBackup file behind — nothing is permanent until you commit or revert:

Release ​

go
func ReleasePrepare(executable string) (string, error)                    // mvn release:prepare
func ReleasePrepareWithArgs(executable string, args ...string) (string, error)
func ReleasePerform(executable string) (string, error)                    // mvn release:perform
func ReleaseRollback(executable string) (string, error)                   // mvn release:rollback
func ReleaseClean(executable string) (string, error)                      // mvn release:clean

A release spans multiple Git commits and a checkout of the tagged revision — prepare and perform are deliberately separate so you can verify the tag before pushing artifacts:

Artifact Packaging & Publishing ​

go
func JarJar(executable string) (string, error)                // mvn jar:jar
func SourceJar(executable string) (string, error)             // mvn source:jar
func SourceJarNoFork(executable string) (string, error)       // mvn source:jar-no-fork
func JavadocJavadoc(executable string) (string, error)        // mvn javadoc:javadoc
func JavadocJar(executable string) (string, error)            // mvn javadoc:jar
func InstallJar(executable, jarPath, gid, aid, ver string) (string, error) // mvn install:install-file
func DeployDeploy(executable string) (string, error)          // mvn deploy:deploy
func DeployDeployFile(executable, file, gid, aid, ver, repoId, url string) (string, error) // mvn deploy:deploy-file
func GpgSign(executable string) (string, error)               // mvn gpg:sign

These commands produce and ship the auxiliary artifacts that surround a primary JAR — sources, javadoc, and a GPG signature — before install/deploy lands them in a repository:

Build Tools ​

go
func AssemblySingle(executable string) (string, error)        // mvn assembly:single
func ShadeShade(executable string) (string, error)            // mvn shade:shade
func ExecJava(executable string) (string, error)              // mvn exec:java
func ExecJavaWithMainClass(executable, mainClass string) (string, error)
func ExecExec(executable string) (string, error)              // mvn exec:exec
func EnforcerEnforce(executable string) (string, error)       // mvn enforcer:enforce
func ArchetypeCreate(executable, dir, gid, aid, ver string) (string, error) // mvn archetype:generate
func Wrapper(executable string) (string, error)               // mvn wrapper:wrapper

These tools fall into four jobs — packaging the output, running code, enforcing rules, and scaffolding:

POM Parser ​

The POM package parses Maven pom.xml files into typed Go structs. All three entry points funnel into the same XML decoder, so behaviour is identical whether you start from a path, a reader, or a byte slice.

See the Architecture guide for the full Project object model as a class diagram.

go
package pom

// Parse from various sources
func ParseFile(path string) (*Project, error)
func ParseReader(r io.Reader) (*Project, error)
func ParseBytes(data []byte) (*Project, error)

// Project methods
func (p *Project) GetGAV() (groupId, artifactId, version string)
func (p *Project) GetDependencies() []Dependency
func (p *Project) GetModules() []string
func (p *Project) GetPlugins() []Plugin
func (p *Project) GetProfiles() []Profile
func (p *Project) GetRepositories() []Repository
func (p *Project) GetProperties() map[string]string
func (p *Project) GetLicenses() []License
func (p *Project) GetDevelopers() []Developer
func (p *Project) GetScm() *Scm
func (p *Project) GetBuild() *Build
func (p *Project) GetPackaging() string  // defaults to "jar" if not specified
func (p *Project) IsMultiModule() bool
func (p *Project) HasParent() bool
func (p *Project) FindDependency(groupId, artifactId string) *Dependency
func (p *Project) FindPlugin(groupId, artifactId string) *Plugin

Key Types: Project, Parent, Dependency, Plugin, Profile, Repository, Build, Scm, License, Developer

GAV inheritance (and its limits) ​

GetGAV() falls back to the <parent> block within the same file when the project omits its own groupId/version. But ParseFile does not recursively load the parent POM from disk — it only reads the <parent> metadata declared in this pom.xml:

WARNING

ParseFile reads one pom.xml. It does not chase <parent><relativePath> or fetch the parent from a repository, so inherited dependencies, plugins, and properties from the parent are not materialized on the returned *Project. For the fully-merged model, run mvn help:effective-pom (see EffectivePom in Help Commands) and parse that.

The Dependency type ​

GetDependencies() and FindDependency() return this struct. Fields map one-to-one to the <dependency> element in pom.xml:

go
type Dependency struct {
    GroupId    string      // e.g. "org.springframework"
    ArtifactId string      // e.g. "spring-core"
    Version    string      // may be empty when managed by <dependencyManagement>
    Type       string      // packaging type; defaults to "jar" when empty
    Scope      string      // see the scope table below; defaults to "compile"
    Classifier string      // e.g. "sources", "javadoc", "linux-x86_64"
    Optional   bool        // <optional>true</optional> — not transitively inherited
    Exclusions *Exclusions // transitive dependencies to prune; nil when absent
}

Dependency scopes — the Scope field controls when a dependency is on the classpath and whether it is inherited transitively:

ScopeCompile classpathRuntime classpathTest classpathTransitiveTypical use
compile (default)✅✅✅✅Normal libraries
provided✅—✅—Servlet/JEE APIs supplied by the container
runtime—✅✅✅JDBC drivers, SLF4J bindings
test——✅—JUnit, Mockito
system✅—✅—Local jar via <systemPath> (discouraged)
import————BOMs in <dependencyManagement> only

WARNING

An empty Version is normal for a dependency whose version is pinned by a parent POM or a BOM import. Resolve the effective version by inspecting <dependencyManagement> rather than assuming the field is populated.

Exclusions prunes unwanted transitive dependencies:

go
type Exclusions struct {
    Exclusion []Exclusion
}

type Exclusion struct {
    GroupId    string // supports the "*" wildcard
    ArtifactId string // supports the "*" wildcard
}

Settings Parser ​

The Settings package parses Maven settings.xml files. FindMirrorOf returns the first <mirror> whose mirrorOf is either an exact id match or the catch-all *:

go
package settings

// Parse from various sources
func ParseFile(path string) (*Settings, error)
func ParseReader(r io.Reader) (*Settings, error)
func ParseBytes(data []byte) (*Settings, error)
func ParseDefault() (*Settings, error)   // Parse ~/.m2/settings.xml or ${M2_HOME}/conf/settings.xml

// Utility
func GetDefaultSettingsPath() string     // Returns ~/.m2/settings.xml path

// Settings methods
func (s *Settings) GetMirrors() []Mirror
func (s *Settings) GetServers() []Server
func (s *Settings) GetProxies() []Proxy
func (s *Settings) GetProfiles() []SettingsProfile
func (s *Settings) GetActiveProfileIds() []string
func (s *Settings) GetPluginGroups() []string
func (s *Settings) GetLocalRepository() string
func (s *Settings) IsOffline() bool
func (s *Settings) FindServer(id string) *Server
func (s *Settings) FindMirror(id string) *Mirror
func (s *Settings) FindMirrorOf(repositoryId string) *Mirror
func (s *Settings) FindActiveProxy() *Proxy
func (s *Settings) FindProfile(id string) *SettingsProfile

Key Types: Settings, Server, Mirror, Proxy, SettingsProfile, SettingsActivation

The mirrorOf field on a <mirror> accepts two forms — an exact repository id, or the * wildcard that matches every repository:

WARNING

This SDK matches mirrorOf by exact id or * only. Full Maven also understands external:*, comma lists (a,b), and !exclusions — those are not supported here. If you rely on them, pre-filter mirrors in your own code.

ParseDefault searches two locations in order — the user-level file always wins over the global one when both exist:

Local Repository ​

go
package local_repository

var DefaultLocalRepositoryDirectory string  // ~/.m2/repository/

func ParseLocalRepositoryDirectory(executable string) string
func BuildDirectory(groupId, artifactId, version string) string
func FindDirectory(repoDir, groupId, artifactId, version string) (string, error)
func FindJar(repoDir, groupId, artifactId, version string) (string, error)
func FindJarWithClassifier(repoDir, groupId, artifactId, version, classifier string) (string, error)

ParseLocalRepositoryDirectory runs mvn help:evaluate to ask Maven itself where the local repo is (honoring -s settings overrides), then FindJar maps a coordinate onto the disk path:

Installer ​

Install() auto-detects the platform and picks the cheapest viable strategy; InstallWithOptions exposes version pinning, custom mirrors, checksum control, and idempotency overrides. See the Architecture guide for the complete flow, mirror-fallback sequence, and per-OS environment handling.

go
package installer

// High-level entry points
func Install() (string, error)              // Auto-detect platform, idempotent
func InstallLinux() (string, error)         // apt/dnf/yum/apk/pacman/zypper or binary
func InstallMacOS() (string, error)         // Homebrew or binary
func InstallWindows() (string, error)       // zip + safe PATH/MAVEN_HOME setup

// Configurable entry point
func InstallWithOptions(opts InstallOptions) (string, error)
func DefaultInstallOptions() InstallOptions
func InstallMacOSWithOptions(opts InstallOptions) (string, error) // legacy alias

// Options
type InstallOptions struct {
    Version      string   // "" → DefaultMavenVersion
    Mirrors      []string // "" → DefaultMirrors (Apache + Aliyun + Tsinghua)
    HomeDir      string   // install target (default: OS-specific)
    SkipEnvSetup bool     // don't touch PATH / shell rc
    SkipChecksum bool     // skip SHA512 verification (not recommended)
    Force        bool     // reinstall even if a usable Maven exists
    MaxRetries   int      // per-mirror download retries (default 3)
}

const DefaultMavenVersion = "3.9.11"
var DefaultMirrors []string

InstallOptions fields steer three independent concerns — what to install, how to fetch it, and whether to touch the environment:

Mirror fallback & checksum verification ​

downloadFromMirrors walks the mirror list in order. Each mirror gets up to MaxRetries attempts with exponential backoff. A checksum mismatch is not retried on the same mirror — it discards the file and advances to the next mirror, because a mismatch usually means the mirror is serving a stale or corrupted copy. Only when every mirror is exhausted is an aggregated error returned.

Idempotency: is an existing Maven good enough? ​

Before downloading, findUsableMaven checks whether a usable Maven is already present. "Usable" means: found on disk and its version is >= the requested version. A broken-but-present mvn whose version can't be parsed is trusted as-is rather than forcing a reinstall — the user may intentionally keep it.

Usage Examples ​

CI/CD Build (Builder Pattern) ​

go
output, err := command.NewCommandBuilder().
    WithExecutable("mvn").
    WithWorkingDirectory("/workspace/project").
    WithBatchMode().
    WithNoTransferProgress().
    WithProfiles("ci").
    WithSkipTests().
    WithUpdateSnapshots().
    Clean()

Multi-Module Build ​

go
output, err := command.NewCommandBuilder().
    WithProjects("module-a", "module-b").
    WithAlsoMake().
    WithBatchMode().
    Install()

Run Single Test ​

go
maven, _ := finder.FindMaven()
output, err := command.SurefireTestSingleClass(maven, "com.example.UserServiceTest")

Parse POM File ​

go
project, err := pom.ParseFile("pom.xml")
if err != nil {
    log.Fatal(err)
}
groupId, artifactId, version := project.GetGAV()
fmt.Printf("Project: %s:%s:%s\n", groupId, artifactId, version)

for _, dep := range project.GetDependencies() {
    fmt.Printf("  %s:%s:%s (%s)\n", dep.GroupId, dep.ArtifactId, dep.Version, dep.Scope)
}

Parse settings.xml ​

go
settings, err := settings.ParseDefault()
if err != nil {
    log.Fatal(err)
}
for _, mirror := range settings.GetMirrors() {
    fmt.Printf("Mirror %s: %s -> %s\n", mirror.Id, mirror.MirrorOf, mirror.URL)
}

Find JAR with Classifier ​

go
maven, _ := finder.FindMaven()
repoDir := local_repository.ParseLocalRepositoryDirectory(maven)
sources, _ := local_repository.FindJarWithClassifier(repoDir, "org.springframework", "spring-core", "5.3.21", "sources")

Version Management ​

go
maven, _ := finder.FindMaven()
output, err := command.VersionsSet(maven, "2.0.0")
// Verify the change, then commit:
output, err = command.VersionsCommit(maven)
// Or revert if something is wrong:
// output, err = command.VersionsRevert(maven)

Maven Wrapper Detection ​

go
// Prefer project wrapper over system Maven
maven, err := finder.FindBestMaven("/path/to/project")
if err != nil {
    log.Fatal(err)
}
output, _ := command.Compile(maven)

Released under the MIT License.