mvn-generate-sources

Run all lifecycle phases up to generate-sources

Run the next phase to generate resources
Clean and regenerate sources

mvn [options] generate-sources

-D<property>=<value>
    Sets a system property, commonly used to pass configuration parameters to plugins bound to the generate-sources phase, such as schema locations or generation options.

-P <profile_id>
    Activates a specified build profile. Profiles can contain specific plugin configurations for code generation, allowing different sets of sources to be generated based on the environment or build target.

-f <file>, --file <file>
    Specifies an alternative path to the pom.xml file. Useful when the project's build file is not in the default location.

-B, --batch-mode
    Runs in non-interactive (batch) mode. Useful for automated scripts or continuous integration environments where user input is not possible.

-U, --update-snapshots
    Forces a check for updated releases and snapshots from remote repositories. Ensures the latest versions of plugins or dependencies required for code generation are used.

-X, --debug
    Produces execution debug output. Invaluable for troubleshooting issues related to plugin configuration or execution during the generate-sources phase.

-q, --quiet
    Works quietly, showing minimal output. Useful for clean logs in automated builds when only errors are of interest.

-o, --offline
    Works offline, preventing Maven from connecting to remote repositories. Requires all necessary plugins and dependencies to be present in the local repository.

The command mvn generate-sources executes the generate-sources phase of the Maven build lifecycle. This phase is strategically positioned to create or prepare any necessary source files that will be consumed by subsequent phases, particularly the compile phase.

It's crucial for projects that rely on code generation. Common scenarios include:

• Schema compilation: Generating Java classes from XML schemas (e.g., JAXB) or Protocol Buffers definitions.
• Grammar compilation: Generating parsers and lexers from grammar definitions (e.g., ANTLR).
• API contract generation: Creating client or server stubs from OpenAPI/Swagger specifications.
• Annotation processing: Tools like Lombok or MapStruct often perform their code generation around this phase, though sometimes it's associated with process-sources or compile.

The generate-sources phase itself doesn't perform any direct action; it acts as a hook where Maven plugins are configured to execute their goals. These plugins add the newly generated source directories to the project's build path, ensuring that the compile phase can locate and compile them alongside the handwritten sources. Executing this command explicitly ensures that all code generation tasks are completed before any compilation attempts.

The generate-sources phase only performs actions if plugins are explicitly configured in the pom.xml to execute goals during this phase. Without such configurations, running mvn generate-sources will simply execute all preceding lifecycle phases without any visible source generation.

Care must be taken to ensure that generated sources are correctly added to the project's source directories (e.g., using build-helper-maven-plugin:add-source) so that the compile phase can find them. Misconfigurations can lead to compilation errors or missing classes.

The generate-sources phase is part of Maven's standard build lifecycle, which defines a sequence of phases to build a project. It typically occurs after process-resources and before process-sources and compile. This ordering ensures that all resources are processed, then any necessary sources are generated, before the primary source code is compiled.

The actual work of generating sources is performed by specific Maven plugins configured in the <build> section of the pom.xml. Examples include:

• jaxb-maven-plugin (for XML to Java generation)
• protobuf-maven-plugin (for Protocol Buffers)
• antlr4-maven-plugin (for ANTLR grammars)
• build-helper-maven-plugin (specifically its add-source goal, crucial for including generated directories into the classpath)

These plugins bind their goals to the generate-sources phase, instructing Maven to execute them at the appropriate time.

The concept of a defined build lifecycle, including the generate-sources phase, has been a cornerstone of Maven since its early versions (Maven 2.x onwards, formalizing practices from Maven 1.x). Its inclusion reflects the growing complexity of software projects and the increasing reliance on automated code generation from various descriptions (e.g., schemas, grammars, models). The stability and predictable ordering of phases like generate-sources ensure that generated code is consistently produced and integrated into the build process at the correct time, predating the actual compilation.

mvn compile, mvn package, mvn install, mvn clean, maven(1)