Skip to content

Latest commit

 

History

History
298 lines (215 loc) · 10.4 KB

README.md

File metadata and controls

298 lines (215 loc) · 10.4 KB

ZED IDE Setup for OBP-API Development

Complete ZED IDE integration for the Open Bank Project API

This folder contains everything needed to set up ZED IDE with full Scala language server support, automated build tasks, and streamlined development workflows for OBP-API.

🚀 Quick Setup (5 minutes)

Prerequisites

  • Java 17+ (OpenJDK recommended)
  • Maven 3.6+
  • ZED IDE (latest version)

Single Setup Script

cd OBP-API
./zed/setup-zed-ide.sh

This unified script automatically:

  • ✅ Installs missing dependencies (Coursier, Bloop)
  • ✅ Compiles the project and resolves dependencies
  • ✅ Generates dynamic Bloop configurations
  • ✅ Sets up Metals language server
  • ✅ Copies ZED configuration files to .zed/ folder
  • ✅ Configures build and run tasks
  • ✅ Sets up manual-only code formatting

📁 What's Included

zed/
├── README.md                   # This comprehensive guide
├── setup-zed-ide.sh           # Single unified setup script
├── generate-bloop-config.sh    # Dynamic Bloop config generator
├── settings.json               # ZED IDE settings template
├── tasks.json                  # Pre-configured build/run tasks
├── .metals-config.json         # Metals language server config
└── setup-zed.bat              # Windows setup script

⌨️ Essential Keyboard Shortcuts

Action Linux macOS/Windows Purpose
Command Palette Ctrl+Shift+P Cmd+Shift+P Access all tasks
Go to Definition F12 F12 Navigate to symbol definition
Find References Shift+F12 Shift+F12 Find all symbol usages
Quick Open File Ctrl+P Cmd+P Fast file navigation
Format Code Ctrl+Shift+I Cmd+Shift+I Auto-format Scala code
Symbol Search Ctrl+T Cmd+T Search symbols project-wide

🛠️ Available Development Tasks

Access via Command Palette (Ctrl+Shift+P on Linux, Cmd+Shift+P on macOS/Windows) → "task: spawn" (Linux) or "Tasks: Spawn" (macOS/Windows):

Core Development Tasks

Task Purpose Duration When to Use
Quick Build Dependencies Build only dependencies 1-3 min First step, after dependency changes
[1] Run OBP-API Server Start development server 3-5 min Daily development
🔨 Build OBP-API Full project build 2-5 min After code changes
Run Tests Execute test suite 5-15 min Before commits
[3] Compile Only Quick syntax check 30s-1 min During development

Utility Tasks

Task Purpose
[4] Clean Target Folders Remove build artifacts
🔄 Continuous Compile (Scala) Auto-recompile on changes
[2] Test API Root Endpoint Verify server status
🔧 Kill Server on Port 8080 Stop stuck processes
🔍 Check Dependencies Verify Maven dependencies

🏗️ Development Workflow

Daily Development

  1. Start Development Session

    • Linux: Ctrl+Shift+P → "task: spawn" → "Quick Build Dependencies"
    • macOS: Cmd+Shift+P → "Tasks: Spawn" → "Quick Build Dependencies"

  2. Start API Server

    • Use task "[1] Run OBP-API Server"
    • Server runs on: http://localhost:8080
    • Test endpoint: http://localhost:8080/obp/v5.1.0/root

  3. Code Development

    • Edit Scala files in obp-api/src/main/scala/
    • Use F12 for Go to Definition
    • Auto-completion with Ctrl+Space
    • Real-time error highlighting
    • Format code with Ctrl+Shift+I

  4. Testing & Validation

    • Quick compile: "[3] Compile Only" task
    • Run tests: "Run Tests" task
    • API testing: "[2] Test API Root Endpoint" task

🔧 Configuration Details

ZED IDE Settings (settings.json)

  • Format on Save: DISABLED (manual formatting only - use Ctrl+Shift+I)
  • Scala LSP: Optimized Metals configuration
  • Maven Integration: Proper MAVEN_OPTS for Java 17+
  • UI Preferences: One Dark theme, consistent layout
  • Inlay Hints: Enabled for better code understanding

Build Tasks (tasks.json)

All tasks include proper environment variables:

MAVEN_OPTS="-Xss128m --add-opens=java.base/java.util.jar=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED"

Metals LSP (.metals-config.json)

  • Build Tool: Maven
  • Bloop Integration: Dynamic configuration generation
  • Scala Version: 2.12.20
  • Java Target: Java 11 (compatible with Java 17)

🚨 Troubleshooting

Common Issues

Problem Symptom Solution
Language Server Not Working No go-to-definition, no autocomplete Restart ZED, wait for Metals initialization
Compilation Errors Red squiggly lines, build failures Check Problems panel, run "Clean Target Folders"
Server Won't Start Port 8080 busy Run "Kill Server on Port 8080" task
Out of Memory Build fails with heap space error Already configured in tasks
Missing Dependencies Import errors Run "Check Dependencies" task

Recovery Procedures

  1. Full Reset:

    ./zed/setup-zed-ide.sh  # Re-run complete setup

  2. Regenerate Bloop Configurations:

    ./zed/generate-bloop-config.sh  # Regenerate configs

  3. Clean Restart:

    • Clean build with "Clean Target Folders" task
    • Restart ZED IDE
    • Wait for Metals to reinitialize (2-3 minutes)

Platform-Specific Notes

Linux Users

  • Use "task: spawn" in command palette (not "Tasks: Spawn")
  • Ensure proper Java permissions for Maven

macOS/Windows Users

  • Use "Tasks: Spawn" in command palette
  • Windows users can also use setup-zed.bat

🌐 API Development

Project Structure

OBP-API/
├── obp-api/                    # Main API application
│   └── src/main/scala/         # Scala source code
│       └── code/api/           # API endpoint definitions
│           ├── v5_1_0/         # Latest API version
│           ├── v4_0_0/         # Previous versions
│           └── util/           # Utility functions
├── obp-commons/                # Shared utilities and models
│   └── src/main/scala/         # Common Scala code
└── .zed/                       # ZED IDE configuration (generated)

Adding New API Endpoints

  1. Navigate to obp-api/src/main/scala/code/api/v5_1_0/
  2. Find appropriate API trait (e.g., OBPAPI5_1_0.scala)
  3. Follow existing endpoint patterns
  4. Use F12 to navigate to helper functions
  5. Test with API test task

Testing Endpoints

# Root API information
curl http://localhost:8080/obp/v5.1.0/root

# Health check
curl http://localhost:8080/obp/v5.1.0/config

# Banks list (requires proper setup)
curl http://localhost:8080/obp/v5.1.0/banks

🎯 Pro Tips

Code Navigation

  • Quick file access: Ctrl+P then type filename
  • Symbol search: Ctrl+T then type function/class name
  • Project-wide text search: Ctrl+Shift+F

Efficiency Shortcuts

  • Ctrl+/ - Toggle line comment
  • Ctrl+D - Select next occurrence
  • Ctrl+Shift+L - Select all occurrences
  • F2 - Rename symbol
  • Alt+←/→ - Navigate back/forward

Performance Optimization

  • Close unused files to reduce memory usage
  • Use "Continuous Compile" for faster feedback
  • Limit test runs to specific modules during development

📚 Additional Resources

Documentation

Learning Resources

🆘 Getting Help

Diagnostic Commands

# Check Java version
java -version

# Check Maven
mvn -version

# Check Bloop status
bloop projects

# Test compilation
bloop compile obp-commons obp-api

# Check ZED configuration
ls -la .zed/

Common Error Messages

Error Cause Solution
"Java module system" errors Java 17+ module restrictions Already handled in MAVEN_OPTS
"Port 8080 already in use" Previous server still running Use "Kill Server" task
"Metals not responding" Language server crashed Restart ZED IDE
"Compilation failed" Dependency issues Run "Check Dependencies"

🎉 Getting Started Checklist

  • Install Java 17+, Maven 3.6+, ZED IDE
  • Clone OBP-API repository
  • Run ./zed/setup-zed-ide.sh (single setup script)
  • Open project in ZED IDE
  • Wait for Metals initialization (2-3 minutes)
  • Run "Quick Build Dependencies" task
  • Start server with "[1] Run OBP-API Server" task
  • Test API at http://localhost:8080/obp/v5.1.0/root
  • Try "Go to Definition" (F12) on Scala symbol
  • Format code manually with Ctrl+Shift+I (auto-format disabled)
  • Make a small code change and test compilation

Welcome to productive OBP-API development with ZED IDE! 🚀

This setup provides a complete, optimized development environment for the Open Bank Project API using ZED IDE with full Scala language server support.