Skip to content

Installation Guide

GeckoCIRCUITS runs on Windows, Linux, and macOS. Follow the instructions for your operating system.

Prerequisites

Java 21

GeckoCIRCUITS requires Java 21 or later.

  1. Download Eclipse Temurin JDK 21
  2. Run the installer
  3. Verify installation: 
    java -version

sudo apt update
sudo apt install openjdk-21-jdk
java -version

sudo dnf install java-21-openjdk-devel
java -version

# Using Homebrew
brew install openjdk@21

# Add to PATH
echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

java -version

Expected Output

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

Installation Methods

  1. Go to Releases
  2. Download the latest GeckoCIRCUITS-x.x-<platform>.zip
  3. Extract to your desired location
  4. Run the launcher script

Method 2: Build from Source

# Clone repository
git clone https://github.com/tinix84/GeckoCIRCUITS.git
cd geckocircuits

# Build with Maven
mvn clean package assembly:single -DskipTests

# The JAR is created at:
# target/gecko-1.0-jar-with-dependencies.jar

Maven Installation

If you don't have Maven installed:

Download from maven.apache.org and add to PATH

sudo apt install maven  # Debian/Ubuntu
sudo dnf install maven  # Fedora

brew install maven

Method 3: Docker (REST API only)

The REST API server can be run as a Docker container (no GUI required):

# Quick start with docker-compose
docker-compose up -d

# Or pull and run manually
docker run -p 8080:8080 gecko-rest-api:latest

# Verify it's running
curl http://localhost:8080/api/v1/health

See the REST API documentation for full endpoint reference.

Running GeckoCIRCUITS

Using Launcher Scripts

scripts\run-gecko.bat

:: With HiDPI support (4K displays)
scripts\run-gecko.bat --hidpi

:: Open specific circuit
scripts\run-gecko.bat path\to\circuit.ipes

./scripts/run-gecko-linux.sh

# With HiDPI support
./scripts/run-gecko-linux.sh --hidpi

# Headless mode (for CI/servers)
./scripts/run-gecko-linux.sh --headless

./scripts/run-gecko-macos.sh

# With Retina support
./scripts/run-gecko-macos.sh --hidpi

./scripts/run-gecko-wsl.sh

# First time: run setup
./scripts/setup-wsl.sh

Direct Java Execution

java -Xmx3G \
     -Dpolyglot.js.nashorn-compat=true \
     -jar target/gecko-1.0-jar-with-dependencies.jar

JVM Options

  • -Xmx3G - Allocate 3GB memory (adjust based on your system)
  • -Dpolyglot.js.nashorn-compat=true - Enable JavaScript scripting
  • -Dsun.java2d.uiScale=2 - HiDPI scaling (add for 4K displays)

Verifying Installation

  1. Launch GeckoCIRCUITS
  2. Go to Help > About to verify version
  3. Open a sample circuit: File > Open > resources/tutorials/1xx_getting_started/101_first_simulation/ex_1.ipes
  4. Click Run (or press F5)
  5. If waveforms appear in the scope, installation is successful!

Troubleshooting

Common Issues

Problem Solution
"Java not found" Ensure Java 21 is installed and in PATH
Application won't start Check Java version: java -version
Blank window on Linux Install libxrender1 libxtst6
Slow on 4K display Add --hidpi flag or -Dsun.java2d.uiScale=2
Out of memory Increase -Xmx value (e.g., -Xmx4G)

WSL-Specific Issues

# Install X server support
sudo apt install x11-apps

# Set DISPLAY variable
export DISPLAY=:0

# Or for WSLg (Windows 11)
export DISPLAY=:0
export WAYLAND_DISPLAY=wayland-0

Next Steps