User Guide

Microsphere Build Maven Project User Guide

1. Project Overview

microsphere-build is a Maven build aggregation module (POM) used to manage and standardize the build process of Microsphere open-source projects. It provides unified plugin management, multi-environment profile support, resource filtering, and streamlined deployment workflows for publishing to central repositories, continuous integration (CI), code quality checks, and more.

---

2. Project Structure Summary

• pom.xml: The main POM file defining common properties, plugin configurations, profiles, and dependency management.
• src/main/java: Java source directory (usually empty as it's a parent project).
• src/main/resources: Resource configuration directory.
• src/test/...: Optional test resources or code.

---

3. Core Features and Capabilities

3.1 Unified Plugin Management (pluginManagement)

Maven plugins are centrally configured with consistent versions and default settings:

Plugin	Functionality
maven-compiler-plugin	Java compiler configuration
maven-source-plugin	Generate source JARs
maven-javadoc-plugin	Generate Javadoc documentation
jacoco-maven-plugin	Test coverage reports
maven-checkstyle-plugin	Code style enforcement
flatten-maven-plugin	Flatten POM for CI usage
git-commit-id-plugin	Inject Git commit metadata
sign-maven-plugin / maven-gpg-plugin	GPG signing
nexus-staging-maven-plugin	Publish to Sonatype Nexus

---

3.2 Multi-Environment Profile Configuration

List of Common Profiles

Profile ID	Description
release	Used during official release; includes signing, Javadoc, GPG, etc.
publish	For publishing to Maven Central
ci	Simplified signing for CI environments
test	Enables unit tests and Checkstyle checks
coverage	Generates JaCoCo coverage report
docs	Builds AsciiDoc or DocBook documentation
java8+, java9+, java11, java9-15, java16+	JDK compatibility adjustments

Example Command to Activate Profiles

mvn clean install -Ptest,coverage

---

3.3 Resource Filtering and Encoding Setup

• Supports ${} placeholder replacement in both src/main/java and src/main/resources.
• UTF-8 encoding is enforced to prevent character encoding issues.

---

3.4 Publishing Configuration

• Supports publishing to Nexus (OSSRH) with automatic staging repository closing and releasing.
• GPG signing is supported both locally and in CI environments.

Example Publish Command

mvn deploy -Prelease

Note: You must configure credentials in ~/.m2/settings.xml.

---

3.5 Code Quality Control

• Uses maven-checkstyle-plugin for static code analysis.
• Uses jacoco to generate test coverage reports.
• Uses maven-enforcer-plugin to control dependency version conflicts.

---

3.6 Documentation Building Support

• Supports building documentation in AsciiDoc and DocBook formats.
• Can generate HTML, PDF, and other output formats.

---

4. Quick Start

4.1 Local Development Build

mvn clean install

Runs compilation, packaging, and basic tests by default.

4.2 Run Tests and Generate Coverage Report

mvn clean test jacoco:report -Ptest,coverage

4.3 Deploy to Nexus (Requires Permissions)

mvn clean deploy -Prelease

Ensure your settings.xml contains the server configuration:

<servers>
    <server>
        <id>ossrh</id>
        <username>your-sonatype-username</username>
        <password>your-sonatype-password</password>
    </server>
</servers>

---

5. Frequently Asked Questions

Q1: How to skip Checkstyle checks?

mvn install -Ddisable.checks=true

Q2: How to view Git commit information?

After the build, a Git info file will be generated at:

target/classes/git.properties

Q3: How to build documentation?

mvn generate-resources -Pdocs

---

6. Extension Suggestions

• Add more profiles for different environments (e.g., dev, staging).
• Integrate with CI tools like GitHub Actions or GitLab CI for automated builds and deployments.
• Combine with SonarQube for comprehensive code analysis.

---

7. Contribution Guidelines

Contributions are welcome! Please refer to CONTRIBUTING.md for details.

---

8. License

This project is licensed under the Apache License 2.0.