Building NeqSim

Complete reference for building, testing, and packaging NeqSim.

Quick Commands

Windows (PowerShell)

# Full build with tests
.\mvnw.cmd clean install

# Tests only
.\mvnw.cmd test

# Package JAR (skip tests)
.\mvnw.cmd package -DskipTests

# Static analysis
.\mvnw.cmd checkstyle:check spotbugs:check pmd:check

Linux/Mac (Bash)

# Full build with tests
./mvnw clean install

# Tests only
./mvnw test

# Package JAR (skip tests)
./mvnw package -DskipTests

# Static analysis
./mvnw checkstyle:check spotbugs:check pmd:check

Maven Wrapper

NeqSim uses Maven Wrapper (mvnw/mvnw.cmd) for consistent builds across environments.

Advantages

✅ No need to install Maven separately
✅ Guaranteed Maven version (defined in .mvn/wrapper/maven-wrapper.properties)
✅ Works on any system with Java 8+ installed
✅ Same build behavior in CI and local development

Using the Wrapper

# Windows
.\mvnw.cmd <maven-command>

# Linux/Mac
./mvnw <maven-command>

The wrapper auto-downloads the correct Maven version on first run (~5 MB, one-time).

POM Files Explained

NeqSim has multiple POM files for different purposes:

File	Purpose	Usage
pom.xml	Main build file	Use this for all normal development
pomJava8.xml	Java 8 compatibility profile	CI testing for Java 8 compliance
pomJava21.xml	Java 21 testing profile	Internal experiments (not published)
dependency-reduced-pom.xml	Generated by maven-shade-plugin	Auto-generated, do not edit

For normal development, use pom.xml only.

Current Version

Check pom.xml for the current version:

<revision>3.5.0</revision>

Build Profiles & Options

Skip Tests

Save time during development by skipping tests:

./mvnw package -DskipTests

Include Slow Tests

By default, tests tagged with @Tag("slow") are excluded. To run all tests:

./mvnw test -DexcludedTestGroups=

Clean Build

Remove all generated files and rebuild from scratch:

./mvnw clean install

Offline Mode

Build without downloading dependencies (requires previous successful build):

./mvnw -o install

Testing

Run All Tests

./mvnw test

Run Single Test Class

./mvnw test -Dtest=SeparatorTest

Run Single Test Method

./mvnw test -Dtest=SeparatorTest#testTwoPhase

Run Tests by Package

./mvnw test -Dtest=neqsim.thermo.**

Test Output

Console: Test results printed to terminal
Reports: target/surefire-reports/ (HTML and XML)
Coverage: target/site/jacoco/ (if jacoco enabled)

Static Analysis

NeqSim uses three static analysis tools:

Checkstyle (Code Formatting)

./mvnw checkstyle:check

Configuration: .config/checkstyle_neqsim.xml

SpotBugs (Bug Detection)

./mvnw spotbugs:check

Detects common programming mistakes and potential bugs.

PMD (Code Quality)

./mvnw pmd:check

Detects code quality issues and bad practices.

Run All Checks

./mvnw checkstyle:check spotbugs:check pmd:check

Note: These checks are configured not to fail the build by default, but all contributions should address reported issues.

Packaging

Create JAR

./mvnw package

Output: target/neqsim-<version>.jar

Create JAR with Dependencies (Fat JAR)

./mvnw package -P shade

Output: target/neqsim-<version>-shaded.jar

Install to Local Maven Repository

./mvnw install

Installs to ~/.m2/repository/com/equinor/neqsim/neqsim/<version>/

IDE Integration

Visual Studio Code

Required Extensions

Settings

Add to .vscode/settings.json (already configured in project):

{
  "java.configuration.updateBuildConfiguration": "interactive",
  "[java]": {
    "editor.defaultFormatter": "redhat.java",
    "editor.formatOnSave": true,
    "editor.tabSize": 2
  },
  "java.format.settings.url": "https://raw.githubusercontent.com/google/styleguide/gh-pages/eclipse-java-google-style.xml",
  "java.checkstyle.configuration": "${workspaceFolder}/.config/checkstyle_neqsim.xml"
}

Eclipse

Import as Maven project: File → Import → Maven → Existing Maven Projects
Install Google style formatter:
- Download eclipse-java-google-style.xml
- Window → Preferences → Java → Code Style → Formatter → Import

See CONTRIBUTING.md for detailed IDE setup.

IntelliJ IDEA

Import as Maven project: File → Open (select pom.xml)
Install Google Java Format plugin
Configure checkstyle: Settings → Tools → Checkstyle → Add .config/checkstyle_neqsim.xml

Updating Python Package

After building, copy the JAR to the Python neqsim package:

# Windows
.\mvnw.cmd package -DskipTests
Copy-Item target\neqsim-3.5.0.jar $env:APPDATA\Python\Python312\site-packages\neqsim\lib\java11\ -Force

# Linux/Mac
./mvnw package -DskipTests
cp target/neqsim-3.5.0.jar ~/.local/lib/python3.12/site-packages/neqsim/lib/java11/

Note: Adjust Python version and path as needed.

Troubleshooting

Build Fails with “package does not exist”

Solution: Clean and recompile:

./mvnw clean compile

Tests Fail Intermittently

Possible causes:

Some tests are tagged @Tag("slow") and may have timing dependencies
Parallel test execution conflicts

Solution: Run tests sequentially:

./mvnw test -DexcludedTestGroups= -Dmaven.test.parallel=false

Maven Wrapper Fails to Download

Error: “Error downloading Maven distribution”

Solution: Check network/proxy settings, or manually download:

Check Maven version in .mvn/wrapper/maven-wrapper.properties
Download from https://maven.apache.org/download.cgi
Place in ~/.m2/wrapper/dists/

OutOfMemoryError During Build

Solution: Increase Maven memory:

export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=512m"
./mvnw clean install

JAR Not Updating in Python

Issue: Changes not reflected after rebuild

Solution: Force copy and restart Python/Jupyter:

.\mvnw.cmd package -DskipTests
Copy-Item target\neqsim-3.5.0.jar <path-to-python-neqsim> -Force
# Restart Jupyter kernel or Python interpreter

Checkstyle/SpotBugs Errors

Solution: Fix reported issues or temporarily skip:

./mvnw install -Dcheckstyle.skip -Dspotbugs.skip

Note: All contributions should address static analysis issues before merging.

Advanced Build Options

Generate JavaDoc

./mvnw javadoc:javadoc

Output: target/site/apidocs/index.html

Generate Test Coverage Report

./mvnw clean verify

Output: target/site/jacoco/index.html

Run Specific Build Phase

./mvnw compile        # Compile only
./mvnw test-compile   # Compile tests
./mvnw verify         # Run integration tests

Multi-Module Builds

Build specific modules only:

./mvnw package -pl :neqsim -am

Debugging Build Issues

Verbose output:

./mvnw -X clean install    # Debug mode
./mvnw -e clean install    # Show full error stack traces

Continuous Integration

NeqSim uses Azure Pipelines and GitHub Actions for CI/CD.

CI Checks

On every PR, CI runs:

Clean build: mvn clean install
All tests (including slow tests)
Static analysis: checkstyle, spotbugs, pmd
Test coverage measurement
Security vulnerability scanning

CI Configuration Files

Azure Pipelines: azure-pipelines.yml
GitHub Actions: .github/workflows/verify_build.yml