Skip to content

Development Environment Setup

Jump to bottom
Marc Sanchis edited this page Jun 5, 2025 · 1 revision

Development Environment Setup

Complete guide for setting up a professional development environment for the Hyperloop UPV Control Station across all supported platforms.

📋 Overview

This guide provides comprehensive setup instructions for:

  • Cross-platform development (Windows, macOS, Linux)
  • Advanced development tools and configurations
  • IDE integration and recommended extensions
  • Testing and debugging setup
  • Performance optimization for development

🛠️ Core Requirements

Essential Tools

Tool Version Purpose Installation
Go 1.21+ Backend development golang.org
Node.js 18+ Frontend development nodejs.org
Git Latest Version control git-scm.com
Make Latest Build automation Platform package manager

Platform-Specific Dependencies

Windows

# Using Chocolatey (recommended)
choco install golang nodejs git make

# Manual installations
# - Go: Download from golang.org
# - Node.js: Download from nodejs.org
# - Git: Download from git-scm.com
# - Make: Install via chocolatey or use WSL

macOS

# Using Homebrew (recommended)
brew install go node git make libpcap

# Additional tools
brew install tmux tree

Linux (Ubuntu/Debian)

# Essential packages
sudo apt update
sudo apt install golang-go nodejs npm git make libpcap-dev

# Additional development tools
sudo apt install tmux tree curl wget

# For other distributions, use appropriate package manager

🔧 Development Tools Setup

Recommended IDEs and Editors

Visual Studio Code (Recommended)

Extensions for Go:

  • Go (official Go extension)
  • Go Test Explorer
  • REST Client (for API testing)

Extensions for React/TypeScript:

  • ES7+ React/Redux/React-Native snippets
  • TypeScript Hero
  • Auto Rename Tag
  • Bracket Pair Colorizer

General Extensions:

  • GitLens
  • Docker
  • YAML
  • Markdown All in One

GoLand (JetBrains)

Professional Go IDE with excellent debugging and refactoring tools.

Other Options

  • Vim/Neovim with Go and TypeScript plugins
  • Emacs with Go mode and TypeScript support
  • Sublime Text with appropriate packages

Git Configuration

# Global Git configuration
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Useful aliases
git config --global alias.st status
git config --global alias.br branch
git config --global alias.co checkout
git config --global alias.ci commit

# Line ending configuration (important for cross-platform)
git config --global core.autocrlf input  # macOS/Linux
git config --global core.autocrlf true   # Windows

📁 Project Setup

1. Clone and Initial Setup

# Clone the repository
git clone https://github.com/HyperloopUPV-H8/software.git
cd software

# Verify project structure
ls -la

2. Development Scripts Setup

The project includes cross-platform development scripts:

Unix/Linux/macOS

# Make scripts executable
chmod +x scripts/dev.sh scripts/dev-unified.sh

# Run setup
./scripts/dev.sh setup

# Verify installation
./scripts/dev.sh test

Windows PowerShell

# Enable script execution (one-time)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Run setup
.\scripts\dev.ps1 setup

# Verify installation
.\scripts\dev.ps1 test

Windows Command Prompt

REM Run setup
scripts\dev.cmd setup

REM Verify installation
scripts\dev.cmd test

3. Environment Variables

Create a .env file in the project root for local development:

# Development environment variables
DEVELOPMENT=true
BACKEND_PORT=8080
FRONTEND_CONTROL_PORT=5173
FRONTEND_ETHERNET_PORT=5174

# Go environment
GOOS=auto
GOARCH=auto
CGO_ENABLED=1

# Node environment
NODE_ENV=development

🏗️ Build System Understanding

Go Backend Build

# Manual build
cd backend
go mod download
go mod tidy

# Build for development
go build -o backend cmd/main.go cmd/config.go cmd/pid.go cmd/trace.go

# Build for production
go build -ldflags="-s -w" -o backend cmd/main.go cmd/config.go cmd/pid.go cmd/trace.go

Frontend Build Process

# 1. Build common-front first (required)
cd common-front
npm install
npm run build

# 2. Build individual frontends
cd ../ethernet-view
npm install
npm run build

cd ../control-station
npm install
npm run build

Cross-Platform Build Matrix

Platform Backend Frontend Package Manager
Windows GOOS=windows GOARCH=amd64 Standard npm build npm, chocolatey
macOS Intel GOOS=darwin GOARCH=amd64 Standard npm build npm, homebrew
macOS Apple Silicon GOOS=darwin GOARCH=arm64 Standard npm build npm, homebrew
Linux GOOS=linux GOARCH=amd64 Standard npm build npm, apt/yum

🧪 Testing Setup

Go Testing

# Run all backend tests
cd backend
go test -v ./...

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific test
go test -v ./pkg/boards/... -run TestBLCU

Frontend Testing

# Run frontend tests (where available)
cd ethernet-view
npm test

# Watch mode for development
npm test -- --watch

Integration Testing

# Test development scripts
./scripts/dev.sh test

# Test build process
./scripts/dev.sh build

🐛 Debugging Setup

Go Debugging

VS Code Setup

Add to .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Backend",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/backend/cmd",
            "cwd": "${workspaceFolder}/backend/cmd",
            "env": {
                "DEVELOPMENT": "true"
            }
        }
    ]
}

Delve Debugger

# Install delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug backend
cd backend/cmd
dlv debug

Frontend Debugging

Browser DevTools

  • Enable source maps in browser
  • Use React Developer Tools extension
  • Monitor WebSocket connections in Network tab

VS Code Setup

Add to .vscode/launch.json:

{
    "name": "Launch Chrome",
    "type": "chrome",
    "request": "launch",
    "url": "http://localhost:5173",
    "webRoot": "${workspaceFolder}/control-station/src"
}

⚡ Performance Optimization

Development Performance

Go Development

# Use air for hot reloading
go install github.com/cosmtrek/air@latest

# Create .air.toml in backend directory
air init
air

Frontend Development

  • Vite provides built-in hot module replacement
  • Use React Developer Tools Profiler
  • Monitor bundle size with npm run build -- --analyze

System Optimization

Memory and CPU

  • Allocate sufficient RAM (8GB+ recommended)
  • Use SSD for better I/O performance
  • Close unnecessary applications during development

Network

  • Use wired connection for better stability
  • Configure local DNS for faster resolution
  • Use local package mirrors when possible

🔧 Advanced Configuration

Docker Development (Optional)

# Dockerfile.dev
FROM golang:1.21-alpine AS backend
WORKDIR /app
COPY backend/ .
RUN go mod download
RUN go build -o backend cmd/main.go

FROM node:18-alpine AS frontend
WORKDIR /app
COPY common-front/ ./common-front/
COPY control-station/ ./control-station/
RUN cd common-front && npm install && npm run build
RUN cd control-station && npm install && npm run build

# Multi-stage build for development

WSL2 Setup (Windows)

# Install WSL2 with Ubuntu
wsl --install -d Ubuntu

# Setup development environment in WSL2
sudo apt update
sudo apt install golang-go nodejs npm git make libpcap-dev

# Clone and setup project
git clone https://github.com/HyperloopUPV-H8/software.git
cd software
chmod +x scripts/dev.sh
./scripts/dev.sh setup

📊 Development Workflow

Daily Development Flow

  1. Start Development Session

    # Pull latest changes
git pull origin develop

# Start all services
./scripts/dev.sh all

  2. Make Changes

    • Edit code with hot reloading enabled
    • Test changes in browser
    • Run relevant tests

  3. Commit Changes

    # Stage changes
git add .

# Commit with meaningful message
git commit -m "feat: add new BLCU troubleshooting guide"

# Push to feature branch
git push origin feature/blcu-improvements

  4. End Session

    • Stop all services (Ctrl+C)
    • Commit any remaining work
    • Clean up temporary files

Troubleshooting Development Issues

Common Problems

Port conflicts

# Check what's using ports
netstat -an | grep ':5173\|:5174\|:8080'

# Kill processes if needed
lsof -ti:8080 | xargs kill -9

Go module issues

# Clean module cache
go clean -modcache

# Re-download modules
go mod download
go mod tidy

Node.js issues

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Build failures

# Clean build artifacts
./scripts/dev.sh clean  # if available
make clean              # if using Makefile

# Rebuild from scratch
./scripts/dev.sh setup

🚀 Next Steps

For New Developers

  1. Contributing Guide - Learn contribution workflow
  2. Code Standards - Follow coding conventions
  3. System Architecture - Understand system design

For Advanced Development

  1. Backend Architecture - Deep dive into Go backend
  2. Frontend Architecture - React application structure
  3. Performance Optimization - Advanced optimization

For Team Leads

  1. Deployment Guide - Production deployment
  2. Testing Guide - Comprehensive testing strategies
  3. Maintenance Procedures - System maintenance

🎯 You're now ready for professional Hyperloop UPV development!

For questions or issues, check the Common Issues page or create a GitHub Issue.

Clone this wiki locally