Development Setup

This guide will help you set up your development environment for contributing to MARSLib. The setup process takes about 10-15 minutes.

Prerequisites

Required Tools

Java 17 - Development JDK.
Gradle 8.5+ - Build system (included with project)
Git - Version control.
VS Code - Recommended IDE (with extensions)
Node.js 18+ - For website development.

Optional Tools

AdvantageScope - Telemetry visualization.
WPILib VS Code Extension - FRC development support.

Step 1: Fork and Clone

Fork the Repository

Go to github.com/MARSProgramming/MARSLib
Click the “Fork” button in the top-right.
Choose your GitHub account as the destination.

Clone Your Fork

# Clone your fork
git clone https://github.com/YOUR_USERNAME/MARSLib.git
cd MARSLib

# Add upstream repository
git remote add upstream https://github.com/MARSProgramming/MARSLib.git

Step 2: Install Java Dependencies

Using Gradle Wrapper (Recommended)

The project includes Gradle Wrapper, so you don’t need to install Gradle separately:

# On Windows
.\gradlew.bat build

# On macOS/Linux
./gradlew build

Verify Installation

# Run tests to verify setup
.\gradlew.bat test

# Run simulation to verify physics
.\gradlew simulateJava

Step 3: Set Up VS Code

Install Extensions

Install these VS Code extensions for best development:

Extension Pack for Java (Microsoft)
Gradle for Java (Microsoft)
WPILib (WPILib contributors)
Markdown All in One (for documentation)

Configure VS Code

Create .vscode/settings.json (if not present):

{
  "java.format.settings.url": "https://raw.githubusercontent.com/MARSProgramming/MARSLib/master/spotless.license",
  "java.configuration.updateBuildConfiguration": "automatic",
  "java.import.gradle.enabled": true,
  "files.associations": {
    "*.gradle": "groovy"
  }
}

Step 4: Set Up Website Development

Install Dependencies

cd website
npm install

Run Development Server

npm run dev

The website will be available at http://localhost:4321

Build for Production

npm run build

Step 5: Install Git Hooks (Optional)

Install git hooks to automatically format code before commits:

# On Windows
.\install-git-hooks.bat

# On macOS/Linux
chmod +x .githooks/pre-commit

This ensures your code follows MARSLib formatting standards automatically.

Step 6: Verify Everything Works

Build the Project

.\gradlew.bat build

Run Tests

.\gradlew.bat test

Run Simulation

.\gradlew.bat simulateJava

Test Website

cd website
npm run dev

Development Workflow

Create a Feature Branch

git checkout -b feature/your-feature-name

Make Changes

Edit code in src/main/java/
Add tests in src/test/java/
Update documentation if needed.

Test Your Changes

# Run all tests
.\gradlew.bat test

# Run specific test
.\gradlew.bat test --tests SwerveDriveTest

# Run simulation
.\gradlew.bat simulateJava

Commit Your Changes

git add .
git commit -m "Descriptive commit message"

Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Useful Gradle Commands

Building

# Build entire project
.\gradlew.bat build

# Build without tests
.\gradlew.bat build -x test

# Clean build artifacts
.\gradlew.bat clean

Testing

# Run all tests
.\gradlew.bat test

# Run with coverage
.\gradlew.bat test jacocoTestReport

# Run specific test class
.\gradlew.bat test --tests MARSTestHarness

# Run simulation tests
.\gradlew.bat simulateJava

Documentation

# Generate JavaDoc
.\gradlew.bat generateDocs

# View generated docs
# Open docs/javadoc/index.html

Deployment

# Deploy to robot
.\gradlew.bat deploy

# Build deployment JAR
.\gradlew.bat buildDeploymentJar

Troubleshooting

Java Version Issues

Ensure you’re using Java 17:

java -version
# Should show "17.x.x"

Gradle Build Fails

Try cleaning and rebuilding:

.\gradlew.bat clean build --refresh-dependencies

Tests Fail Locally

Make sure you’ve initialized HAL:

# Tests should call this automatically
HAL.initialize(500, 0);

Website Won’t Build

Clear node_modules and reinstall:

cd website
rm -rf node_modules package-lock.json
npm install

Next Steps

Read our Coding Standards to understand our patterns.
Learn about our Testing Philosophy .
Find a good first issue.
Join our GitHub Discussions.

Need Help?

📖 Check the main documentation
💬 Ask in GitHub Discussions
🐛 Report issues on GitHub Issues

Ready to code? Check out our Coding Standards to learn MARSLib patterns!