Introduction

Setting up a proper Java development environment is the first step to becoming a productive Java developer. This guide will walk you through installing Java, Maven, and other essential tools on macOS using Homebrew, a popular package manager that makes installation and management of development tools straightforward.

infoThis guide focuses on macOS installation using Homebrew. If you’re on Windows or Linux, the concepts are similar, but installation methods will differ.

What You’ll Install

By the end of this guide, you’ll have:

Installing Homebrew

Homebrew is a package manager for macOS that simplifies the installation of software and development tools.

Check if Homebrew is Already Installed

Open Terminal and run:

brew --version

If you see a version number, Homebrew is already installed and you can skip to the next section.

Install Homebrew

If Homebrew isn’t installed, run this command in Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions. You may need to enter your password.

Add Homebrew to Your PATH (Apple Silicon Only)

If you’re on an M1/M2/M3 Mac, you’ll need to add Homebrew to your PATH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Installation

brew --version

You should see output like: Homebrew 4.x.x

Installing Java (JDK)

The Java Development Kit (JDK) contains everything you need to develop Java applications, including the Java compiler (javac) and the Java Runtime Environment (JRE).

Understanding Java Versions

Java has several versions and distributions:

For most purposes, OpenJDK is the recommended choice.

View Available Java Versions

brew search openjdk

This shows all available Java versions.

Install Java 11 (Long-Term Support version)

brew install openjdk@11

info_outlineJava 11 is a Long-Term Support (LTS) release, making it a stable choice for learning and production use. Other LTS versions include Java 8, 17, and 21.

Add Java to Your PATH

After installation, you need to make the Java command accessible:

sudo ln -sfn /opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-11.jdk

For Intel Macs, use:

sudo ln -sfn /usr/local/opt/openjdk@11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-11.jdk

Set JAVA_HOME Environment Variable

Add this to your ~/.zshrc (or ~/.bash_profile if using bash):

echo 'export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify Java Installation

java -version

You should see output like:

openjdk version "11.0.x" 2023-xx-xx
OpenJDK Runtime Environment (build 11.0.x+x)
OpenJDK 64-Bit Server VM (build 11.0.x+x, mixed mode)

Also verify the compiler:

javac -version

Output: javac 11.0.x

Verify JAVA_HOME

echo $JAVA_HOME

Should output: /Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home

Installing Apache Maven

Maven is a build automation tool that manages project dependencies, compiles code, runs tests, and packages applications.

Install Maven with Homebrew

brew install maven

This installs the latest version of Maven.

Verify Maven Installation

mvn -version

You should see output like:

Apache Maven 3.9.x
Maven home: /opt/homebrew/Cellar/maven/3.9.x/libexec
Java version: 11.0.x, vendor: Homebrew
Java home: /opt/homebrew/Cellar/openjdk@11/11.0.x/libexec/openjdk.jdk/Contents/Home

infoNote that Maven shows which Java version it’s using. Make sure it matches the Java version you installed.

Understanding Your Setup

What is the JDK?

The Java Development Kit (JDK) includes:

What is Maven?

Apache Maven is a build automation tool that:

Maven uses a pom.xml file (Project Object Model) to configure projects, which you’ll learn about in a future lesson.

Environment Variables Explained

JAVA_HOME

Points to your JDK installation directory. Many Java tools and IDEs use this to find Java.

PATH

Contains directories where your system looks for executable commands. By adding Java and Maven to PATH, you can run java, javac, and mvn from any directory.

Optional: Install an IDE

While not strictly necessary (you can write Java in any text editor), an Integrated Development Environment (IDE) makes development much easier.

IntelliJ IDEA Community Edition (Recommended)

brew install --cask intellij-idea-ce

Eclipse

brew install --cask eclipse-java

Visual Studio Code (with Java extensions)

brew install --cask visual-studio-code

Troubleshooting

“command not found: java”

Solution: Java isn’t in your PATH. Verify:

echo $JAVA_HOME
echo $PATH

If JAVA_HOME is empty, re-add the export commands to your shell profile.

“JAVA_HOME is set to an invalid directory”

Solution: Verify your JDK location:

/usr/libexec/java_home -V

This lists all installed Java versions. Update JAVA_HOME to point to the correct one.

Multiple Java Versions

If you have multiple Java versions installed:

List all versions:

/usr/libexec/java_home -V

Set a specific version:

export JAVA_HOME=$(/usr/libexec/java_home -v 11)

Maven Can’t Find Java

Solution: Maven needs JAVA_HOME to be set. Verify with:

echo $JAVA_HOME
mvn -version

If Maven shows a different Java version, restart your terminal or source your profile:

source ~/.zshrc

Testing Your Setup

Let’s verify everything works by creating and running a simple Java program.

Create a Test Directory

mkdir ~/java-test
cd ~/java-test

Create a Simple Java File

Create a file named HelloWorld.java:

cat > HelloWorld.java << 'EOF'
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, Java World!");
    }
}
EOF

Compile the Program

javac HelloWorld.java

This creates a HelloWorld.class file.

Run the Program

java HelloWorld

Output: Hello, Java World!

Clean Up

cd ~
rm -rf ~/java-test

Maven Settings (Optional)

Custom Maven Repository Location

By default, Maven stores downloaded dependencies in ~/.m2/repository. To change this:

Create Maven Settings File

mkdir -p ~/.m2
nano ~/.m2/settings.xml

Add:

<settings>
  <localRepository>/path/to/your/repository</localRepository>
</settings>

Configure Maven Memory Settings

For large projects, you may need to increase Maven’s memory:

echo 'export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"' >> ~/.zshrc
source ~/.zshrc

Best Practices

Keep Your Tools Updated

Update Homebrew and packages:

brew update
brew upgrade

Update Maven dependencies in projects:

mvn versions:display-dependency-updates

Use Version Managers

For managing multiple Java versions, consider:

Backup Your Configuration

Keep your shell profile (~/.zshrc) and Maven settings (~/.m2/settings.xml) backed up or in version control.

Summary

You now have a complete Java development environment set up on your macOS machine!

Key takeaways:

What’s Next?

Now that your environment is ready, you can:

  1. Write your first Java Hello World program (covered in the next lecture)
  2. Learn Java basics: variables, data types, and control flow
  3. Create a Maven project with proper structure and dependencies
  4. Write unit tests to ensure your code works correctly

Quick Reference

# Check Java version
java -version
javac -version

# Check Maven version
mvn -version

# Check environment variables
echo $JAVA_HOME
echo $PATH

# Update Homebrew
brew update
brew upgrade

# List installed Java versions
/usr/libexec/java_home -V

infoBookmark this page! You’ll likely need to reference these commands when setting up new machines or helping teammates configure their environments.