Java, Maven, & Gradle: OS Setup & Project-Level Usage

Related Java Setup Guides

This Article: Core Java, Maven & Gradle Setup & Usage -

Specifics: Setting up a Spring Boot Server

Part 1: OS-Level Tool Installation (The Foundation)

For project setups, you'll need a Java Development Kit (JDK) installed on your system. Optionally, you might install Maven and/or Gradle globally, though for most project work, their respective project-level wrappers (mvnw, gradlew) are also used.

Installing a Java Development Kit (JDK)

The JDK is essential for compiling and running Java applications. It includes the Java Runtime Environment (JRE) and development tools like the Java compiler (javac).

# Install the latest LTS version (e.g., OpenJDK 21)
brew install openjdk@21

# For ARM-based Macs (M1/M2/M3), Homebrew installs to /opt/homebrew.
# For Intel-based Macs, it's /usr/local.
# To make this JDK the default, symlink it:
sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

# Set JAVA_HOME in your shell profile (e.g., ~/.zshrc)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
# Add Java to your PATH
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
java -version
echo $JAVA_HOME

Installing Build Tools (Maven & Gradle) - OS Level (Optional)

While project wrappers (mvnw, gradlew) are preferred for project work, you might want global installations for bootstrapping new projects or for tools that expect them.

brew install maven
mvn -v # Verify

OS Install vs. Project Wrappers

Global (OS-level) installations of Maven/Gradle are for convenience or bootstrapping. For actual project development and builds, always prefer using the project's Maven Wrapper (./mvnw) or Gradle Wrapper (./gradlew). This ensures everyone uses the same build tool version, leading to reproducible builds. The wrappers will download the correct version if needed.

Part 2: Project-Specific Java Versioning

Ensure different projects can use different Java versions without conflict.

Project-Specific JAVA_HOME (Manual/Scripted)

Example: Point to a JDK 21 installation.

# Example: Point to a JDK 21 installation
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
# Or directly: export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
java -version

IDE Project JDK Settings

File > Project Structure... > Project > SDK. Select project JDK.

IntelliJ IDEA Project SDK setting — IntelliJ IDEA: Project Structure > Project SDK

Note

IDE settings control development. CLI consistency benefits from scripted JAVA_HOME or tools like SDKMAN!.

Part 3: Maven - Project Versioning & Common Commands

Maven is a build tool that uses a Project Object Model (POM) file (pom.xml) to manage a project's build, reporting, and documentation. Use the Maven Wrapper (mvnw) to pin the Maven version per project.

Understanding the Maven Wrapper

The Maven Wrapper (mvnw for Unix-like systems, mvnw.cmd for Windows) ensures that a project uses a consistent version of Maven without requiring a global installation. It downloads the specified Maven version if it's not already available.

Why use it? Reproducible builds across different developer machines and CI/CD environments.

Adding or Updating the Wrapper

If your project (often from Spring Initializr) doesn't include it, or to update the version:

# In project root, using a globally installed mvn (if available)
mvn -N io.takari:maven:wrapper -Dmaven=3.9.6 # Specify desired Maven version

This creates/updates .mvn/wrapper/maven-wrapper.properties, which specifies the Maven version to use.

# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
# ... other properties

Core Maven Lifecycle & Commands (using ./mvnw)

Always use ./mvnw (or mvnw.cmd) instead of a global mvn for project tasks.

# Clean the project (removes target/build directory)
./mvnw clean

# Compile source code
./mvnw compile

# Run tests
./mvnw test

# Package the application (e.g., creates a JAR or WAR file in target/)
./mvnw package

# Install the package into your local Maven repository (~/.m2/repository)
# Makes this project available as a dependency for other local projects.
./mvnw install

# Run application (common for Spring Boot projects)
# This typically requires the spring-boot-maven-plugin
./mvnw spring-boot:run

# Build and run tests, then package (common full build)
./mvnw clean package

# Build without running tests
./mvnw clean package -DskipTests

Maven Wrapper & Java Version

The pom.xml defines Java compatibility for compilation:

&lt;!-- pom.xml --&gt;
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>\${java.version}</maven.compiler.source>
    <maven.compiler.target>\${java.version}</maven.compiler.target>
</properties>

Ensure the active JAVA_HOME (ideally set per-project) is compatible with these settings.

Part 4: Gradle - Project Versioning & Common Commands

Gradle is another popular build automation tool, known for its flexibility and performance, especially with Groovy or Kotlin for build scripts (build.gradle or build.gradle.kts). The Gradle Wrapper (gradlew) is essential.

Understanding the Gradle Wrapper

The Gradle Wrapper (gradlew for Unix-like systems, gradlew.bat for Windows) allows a project to build with a specific version of Gradle without requiring a global Gradle installation. It downloads the declared Gradle version if necessary.

Why use it? Ensures build consistency and reproducibility.

Adding or Configuring the Wrapper

Most projects initialized with Gradle (e.g., via Spring Initializr) include the wrapper. To add or change the Gradle version it uses (if you have a global gradle installed):

# In project root
gradle wrapper --gradle-version 8.7 # Specify desired Gradle version

The wrapper configuration, including the Gradle distribution URL, is in gradle/wrapper/gradle-wrapper.properties.

# gradle/wrapper/gradle-wrapper.properties
distributionUrl=https://services.gradle.org/distributions/gradle-8.7-bin.zip
# ... other properties

Core Gradle Tasks & Commands (using ./gradlew)

Always use ./gradlew (or gradlew.bat) for project tasks.

# Clean the project (removes build directory)
./gradlew clean

# Compile source code (usually part of other tasks like build)
./gradlew classes

# Run tests
./gradlew test

# Assemble the project (e.g., creates a JAR or WAR in build/libs)
./gradlew assemble

# Build the project (compiles, tests, assembles)
./gradlew build

# Build without running tests
./gradlew build -x test

# Run application (common for Spring Boot or other executable JARs)
# Requires application plugin and mainClassName configured in build.gradle
./gradlew run

# List all available tasks for the project
./gradlew tasks
./gradlew tasks --all # More detailed

Gradle Wrapper & Java Version

The build.gradle (Groovy) or build.gradle.kts (Kotlin) file defines Java compatibility:

// build.gradle (Groovy DSL)
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Ensure the active JAVA_HOME is compatible. Gradle also supports Java toolchains for more fine-grained control over the JDK/JRE used by Gradle tasks, independent of JAVA_HOME.

Part 5: Managing & Updating Dependencies

Dependencies are external libraries your project relies on. They are declared in pom.xml (Maven) or build.gradle(.kts) (Gradle).

Dependency Declaration & Update Commands

Check for Updates

Requires versions-maven-plugin in pom.xml.

./mvnw versions:display-dependency-updates

Apply Updates

# Update specific dependency
./mvnw versions:use-latest-versions -Dincludes=groupId:artifactId

# Or edit pom.xml manually, then:
./mvnw clean install

IDE Support

IntelliJ IDEA and VS Code (with Java extensions) often provide UI features to detect and update dependencies.

Related Java Setup Guides

This Article: Core Java, Maven & Gradle Setup & Usage -

Specifics: Setting up JavaFX

Specifics: Setting up a Spring Boot Server

Part 1: OS-Level Tool Installation (The Foundation)

Installing a Java Development Kit (JDK)

The JDK is essential for compiling and running Java applications. It includes the Java Runtime Environment (JRE) and development tools like the Java compiler (javac).

# Install the latest LTS version (e.g., OpenJDK 21)
brew install openjdk@21

# For ARM-based Macs (M1/M2/M3), Homebrew installs to /opt/homebrew.
# For Intel-based Macs, it's /usr/local.
# To make this JDK the default, symlink it:
sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

# Set JAVA_HOME in your shell profile (e.g., ~/.zshrc)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
# Add Java to your PATH
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
java -version
echo $JAVA_HOME

Installing Build Tools (Maven & Gradle) - OS Level (Optional)

While project wrappers (mvnw, gradlew) are preferred for project work, you might want global installations for bootstrapping new projects or for tools that expect them.

brew install maven
mvn -v # Verify

OS Install vs. Project Wrappers

Part 2: Project-Specific Java Versioning

Ensure different projects can use different Java versions without conflict.

Project-Specific JAVA_HOME (Manual/Scripted)

Example: Point to a JDK 21 installation.

# Example: Point to a JDK 21 installation
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
# Or directly: export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
java -version

IDE Project JDK Settings

File > Project Structure... > Project > SDK. Select project JDK.

Note

IDE settings control development. CLI consistency benefits from scripted JAVA_HOME or tools like SDKMAN!.

Part 3: Maven - Project Versioning & Common Commands

Understanding the Maven Wrapper

Why use it? Reproducible builds across different developer machines and CI/CD environments.

Adding or Updating the Wrapper

If your project (often from Spring Initializr) doesn't include it, or to update the version:

# In project root, using a globally installed mvn (if available)
mvn -N io.takari:maven:wrapper -Dmaven=3.9.6 # Specify desired Maven version

This creates/updates .mvn/wrapper/maven-wrapper.properties, which specifies the Maven version to use.

# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
# ... other properties

Core Maven Lifecycle & Commands (using ./mvnw)

Always use ./mvnw (or mvnw.cmd) instead of a global mvn for project tasks.

# Clean the project (removes target/build directory)
./mvnw clean

# Compile source code
./mvnw compile

# Run tests
./mvnw test

# Package the application (e.g., creates a JAR or WAR file in target/)
./mvnw package

# Install the package into your local Maven repository (~/.m2/repository)
# Makes this project available as a dependency for other local projects.
./mvnw install

# Run application (common for Spring Boot projects)
# This typically requires the spring-boot-maven-plugin
./mvnw spring-boot:run

# Build and run tests, then package (common full build)
./mvnw clean package

# Build without running tests
./mvnw clean package -DskipTests

Maven Wrapper & Java Version

The pom.xml defines Java compatibility for compilation:

&lt;!-- pom.xml --&gt;
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>\${java.version}</maven.compiler.source>
    <maven.compiler.target>\${java.version}</maven.compiler.target>
</properties>

Ensure the active JAVA_HOME (ideally set per-project) is compatible with these settings.

Part 4: Gradle - Project Versioning & Common Commands

Understanding the Gradle Wrapper

Why use it? Ensures build consistency and reproducibility.

Adding or Configuring the Wrapper

Most projects initialized with Gradle (e.g., via Spring Initializr) include the wrapper. To add or change the Gradle version it uses (if you have a global gradle installed):

# In project root
gradle wrapper --gradle-version 8.7 # Specify desired Gradle version

The wrapper configuration, including the Gradle distribution URL, is in gradle/wrapper/gradle-wrapper.properties.

# gradle/wrapper/gradle-wrapper.properties
distributionUrl=https://services.gradle.org/distributions/gradle-8.7-bin.zip
# ... other properties

Core Gradle Tasks & Commands (using ./gradlew)

Always use ./gradlew (or gradlew.bat) for project tasks.

# Clean the project (removes build directory)
./gradlew clean

# Compile source code (usually part of other tasks like build)
./gradlew classes

# Run tests
./gradlew test

# Assemble the project (e.g., creates a JAR or WAR in build/libs)
./gradlew assemble

# Build the project (compiles, tests, assembles)
./gradlew build

# Build without running tests
./gradlew build -x test

# Run application (common for Spring Boot or other executable JARs)
# Requires application plugin and mainClassName configured in build.gradle
./gradlew run

# List all available tasks for the project
./gradlew tasks
./gradlew tasks --all # More detailed

Gradle Wrapper & Java Version

The build.gradle (Groovy) or build.gradle.kts (Kotlin) file defines Java compatibility:

// build.gradle (Groovy DSL)
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Ensure the active JAVA_HOME is compatible. Gradle also supports Java toolchains for more fine-grained control over the JDK/JRE used by Gradle tasks, independent of JAVA_HOME.

Part 5: Managing & Updating Dependencies

Dependencies are external libraries your project relies on. They are declared in pom.xml (Maven) or build.gradle(.kts) (Gradle).

Dependency Declaration & Update Commands

Check for Updates

Requires versions-maven-plugin in pom.xml.

./mvnw versions:display-dependency-updates

Apply Updates

# Update specific dependency
./mvnw versions:use-latest-versions -Dincludes=groupId:artifactId

# Or edit pom.xml manually, then:
./mvnw clean install

IDE Support

IntelliJ IDEA and VS Code (with Java extensions) often provide UI features to detect and update dependencies.

Related Java Setup Guides

Part 1: OS-Level Tool Installation (The Foundation)

OS Install vs. Project Wrappers

Part 2: Project-Specific Java Versioning

Note

Part 3: Maven - Project Versioning & Common Commands

Part 4: Gradle - Project Versioning & Common Commands

Part 5: Managing & Updating Dependencies

IDE Support

Similar Content

Related Java Setup Guides

Part 1: OS-Level Tool Installation (The Foundation)

OS Install vs. Project Wrappers

Part 2: Project-Specific Java Versioning

Note

Part 3: Maven - Project Versioning & Common Commands

Part 4: Gradle - Project Versioning & Common Commands

Part 5: Managing & Updating Dependencies

IDE Support

Similar Content