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
dependency-reduced-pom.xml	Generated by maven-shade-plugin	Auto-generated, do not edit

For normal development, use pom.xml only.

The Java 8 compatibility build explicitly pins maven-resources-plugin to 3.3.1, a Java 8-compatible release, so resource processing does not depend on the Maven lifecycle defaults installed on a CI runner. Keep this pin when updating build plugins; verify both Java 8 CI platforms before changing it.

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\ -Force

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

Note: Adjust Python version and path as needed. The runtime loads lib/* (flat), so copy the JAR directly into neqsim/lib/, not a java11/java8 subfolder.

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

Test isolation and diagnostics

Devtools routing tests create a temporary synthetic agent catalog and exercise the real discovery and cue parser. Public CI therefore verifies installed-agent and plugin discovery, aliases, absent catalogs, and malformed cues without requiring an optional enterprise installation. The workflow also runs the production guard and persistent-ledger regression suite.

The Java 21 fast-test matrix uses fail-fast: false, so a Windows failure does not cancel the Ubuntu tests or hide their diagnostics. Each job retains its Surefire reports as fast-test-reports-<platform>, including after failure when reports are available. The existing Java 8 dependency on the fast-test matrix is unchanged.

Slow-test shards

The Java 21 slow suite runs in eight parallel jobs, each with a 60-minute limit and JaCoCo disabled. CI sorts the Java source files containing @Tag("slow") and assigns them round-robin using the matrix job count. Every discovered class belongs to one shard; Maven’s slow group filter selects its slow tests. Adding a slow test can change the assignments, so use the selected-class list printed in each job’s log when investigating a failure.

The eight jobs split the previous four shards in half. In PR #4328, the four-shard run 38524415607 timed out one shard at about 60 minutes; all eight shards in run 38534959694 passed, with the longest taking about 27 minutes. These are observed job wall times, including runner variation, not a claim of reduced total CPU work. This gives the expensive separator, distillation and transient tests more time to finish without increasing the job timeout or removing numerical checks. Each job uploads its Surefire reports as slow-test-reports-<zero-based shard> even after failure, when reports are available. A runner terminated by the job timeout may not reach artifact upload; the selected-class list and test progress remain in its log.

Four small compatibility gates preserve the historical Assert slow tests (1/4) through (4/4) check names. Each requires all eight numerical shards to succeed; failure, cancellation, or unexpected skipping cannot pass. They skip only when change detection succeeds and no Java build is required, matching the existing path-filter behavior. Keep these contexts until repository administrators confirm that branch-protection rules have migrated to the new shard checks.

CI Configuration Files

Azure Pipelines: azure-pipelines.yml
GitHub Actions: .github/workflows/core-run-build-test-and-javadoc.yml