# CubeCactus - Build Instructions

## Prerequisites Installation

### Ubuntu/Debian
```bash
# Update package list
sudo apt update

# Install JDK 21
sudo apt install openjdk-21-jdk

# Install Maven
sudo apt install maven

# Verify installations
java -version    # Should show "21"
javac -version   # Should show "21"
mvn -version     # Should show "3.6" or higher
```

### macOS
```bash
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Java 21
brew install openjdk@21

# Install Maven
brew install maven

# Link Java
sudo ln -sfn /usr/local/opt/openjdk@21/libexec/openjdk.jdk \
    /Library/Java/JavaVirtualMachines/openjdk-21.jdk

# Verify
java -version
mvn -version
```

### Windows
```bash
# 1. Download and install JDK 21 from:
#    https://adoptium.net/

# 2. Download and install Maven from:
#    https://maven.apache.org/download.cgi

# 3. Add to PATH:
#    JAVA_HOME=C:\Program Files\Java\jdk-21
#    MAVEN_HOME=C:\Program Files\Apache\maven
#    PATH=%JAVA_HOME%\bin;%MAVEN_HOME%\bin

# 4. Verify in Command Prompt:
java -version
mvn -version
```

---

## Build Steps

### Step 1: Navigate to Source
```bash
cd cubecactus-source/
```

### Step 2: Build with Maven
```bash
# Full build with tests
mvn clean package

# Skip tests (faster)
mvn clean package -DskipTests

# Verbose output
mvn clean package -X
```

### Step 3: Verify Build
```bash
# Check if JAR was created
ls -lh target/cubecactus-1.0.0.jar

# Should show ~50MB file
```

---

## Build Output

Successful build creates:
```
target/
├── cubecactus-1.0.0.jar           # Executable JAR (with dependencies)
├── cubecactus-1.0.0.jar.original  # Without dependencies
├── classes/                        # Compiled .class files
├── generated-sources/              # Generated code
├── maven-archiver/                 # Build metadata
└── maven-status/                   # Build status
```

---

## Running the Application

### Method 1: Run JAR Directly
```bash
java -jar target/cubecactus-1.0.0.jar
```

### Method 2: Run with Maven
```bash
mvn spring-boot:run
```

### Method 3: Run with Custom Port
```bash
java -Dserver.port=9090 -jar target/cubecactus-1.0.0.jar
```

### Method 4: Run with Custom Configuration
```bash
java -jar target/cubecactus-1.0.0.jar \
  --server.port=8080 \
  --cube.node.id=node-1 \
  --cube.data.dir=/var/lib/cubecactus
```

---

## Verify Installation

```bash
# Wait a few seconds for startup, then:

# Check health
curl http://localhost:8080/api/v1/health

# Should return:
# {"status":"UP"}

# Test SQL API
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE test (id TEXT PRIMARY KEY, value TEXT)"}'
```

---

## Build Profiles

### Development Profile
```bash
mvn clean package -Pdev -DskipTests
```

### Production Profile
```bash
mvn clean package -Pprod
```

### Docker Profile
```bash
mvn clean package -Pdocker
```

---

## Advanced Build Options

### Parallel Build
```bash
# Use all CPU cores
mvn clean package -T 1C

# Use specific number of threads
mvn clean package -T 4
```

### Offline Build
```bash
# Use cached dependencies
mvn clean package -o
```

### Update Dependencies
```bash
# Force update from remote repositories
mvn clean package -U
```

### Skip Specific Tests
```bash
mvn clean package -Dtest=!GossipProtocolTest
```

---

## Troubleshooting Build Issues

### Issue: "Failed to execute goal"
```bash
# Solution: Clean and rebuild
rm -rf target/
mvn clean install -U
```

### Issue: "Cannot find symbol"
```bash
# Solution: Ensure Java 21
java -version  # Must show 21 or higher

# Verify Maven uses correct Java
mvn -version   # Check "Java version" line
```

### Issue: "Connection timed out"
```bash
# Solution: Configure Maven proxy (if behind firewall)
# Edit ~/.m2/settings.xml:
<proxies>
  <proxy>
    <host>proxy.example.com</host>
    <port>8080</port>
  </proxy>
</proxies>
```

### Issue: "Insufficient memory"
```bash
# Solution: Increase Maven memory
export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"
mvn clean package
```

---

## Clean Build

```bash
# Remove all build artifacts
mvn clean

# Deep clean (including cached dependencies)
rm -rf target/ ~/.m2/repository/com/cube/
mvn clean install
```

---

## IDE-Specific Build

### IntelliJ IDEA
```
1. Import project (pom.xml)
2. Build → Build Project (Ctrl+F9)
3. Run → Run 'CubeApplication' (Shift+F10)
```

### Eclipse
```
1. Import → Maven → Existing Maven Project
2. Project → Build Project
3. Run As → Java Application
```

### VS Code
```
1. Open folder in VS Code
2. Maven sidebar → Execute → clean package
3. Run → Start Debugging (F5)
```

---

## Continuous Integration

### GitHub Actions
```yaml
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v2
        with:
          java-version: '21'
      - run: mvn clean package
```

### Jenkins
```groovy
pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'mvn clean package'
      }
    }
  }
}
```

---

## Summary

✅ **Install:** JDK 21 + Maven 3.6+  
✅ **Build:** `mvn clean package`  
✅ **Run:** `java -jar target/cubecactus-1.0.0.jar`  
✅ **Test:** `curl http://localhost:8080/api/v1/health`  

**Build time:** ~2-5 minutes (first build downloads dependencies)  
**JAR size:** ~50 MB  
**Memory:** ~512 MB minimum  

🌵 **Happy Building!**