Skip to content

Installation Guide

This guide provides detailed instructions for setting up a complete V2X development environment. Follow these steps to install all necessary components for V2X development and documentation.

System Requirements

Minimum Requirements

  • Operating System: Windows 10, macOS 10.14+, or Ubuntu 18.04+
  • CPU: Intel i5 or AMD equivalent (2+ cores)
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 10GB available space
  • Network: Internet connection for package downloads
  • Operating System: Ubuntu 20.04+ or Windows 11
  • CPU: Intel i7 or AMD Ryzen 7 (4+ cores)
  • RAM: 32GB
  • Storage: 50GB SSD
  • Network: High-speed internet connection

Prerequisites

1. Python Installation

Windows

# Download Python from python.org or use winget
winget install Python.Python.3.11

# Verify installation
python --version
pip --version

macOS

# Using Homebrew
brew install python@3.11

# Verify installation
python3 --version
pip3 --version

Ubuntu/Debian

# Update package list
sudo apt update

# Install Python and pip
sudo apt install python3.11 python3.11-pip python3.11-venv

# Verify installation
python3.11 --version
pip3.11 --version

2. Git Installation

Windows

# Download from git-scm.com or use winget
winget install Git.Git

macOS

# Using Homebrew
brew install git

# Or download from git-scm.com

Ubuntu/Debian

sudo apt install git

3. Node.js (Optional, for advanced development)

Windows

winget install OpenJS.NodeJS

macOS

brew install node

Ubuntu/Debian

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Installation Steps

Step 1: Clone the Repository

# Clone the V2X documentation repository
git clone https://github.com/your-org/v2x-documentation.git
cd v2x-documentation

# Verify the repository structure
ls -la

Step 2: Create Virtual Environment

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Verify activation (should show venv path)
which python

Step 3: Install Python Dependencies

Create a requirements.txt file:

# Core MkDocs
mkdocs>=1.5.0
mkdocs-material>=9.0.0

# Extensions
pymdown-extensions>=10.0.0
mkdocs-minify-plugin>=0.7.0
mkdocs-git-revision-date-localized-plugin>=1.2.0

# Development tools
pytest>=7.0.0
black>=23.0.0
flake8>=6.0.0
pre-commit>=3.0.0

# V2X specific libraries
asyncio-mqtt>=0.13.0
paho-mqtt>=1.6.1
websockets>=11.0.0

Install the dependencies:

# Upgrade pip first
pip install --upgrade pip

# Install requirements
pip install -r requirements.txt

# Verify installation
pip list

Step 4: Install Additional Tools

Docker (Optional, for containerized development)

# Ubuntu/Debian
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER

# macOS
brew install --cask docker

# Windows
# Download Docker Desktop from docker.com

V2X Hardware Simulator (Optional)

# Install V2X simulation tools
pip install v2x-simulator

# Or build from source
git clone https://github.com/v2x-simulator/v2x-simulator.git
cd v2x-simulator
pip install -e .

Step 5: Configure Development Environment

Set up pre-commit hooks

# Install pre-commit
pip install pre-commit

# Set up hooks
pre-commit install

# Run on all files
pre-commit run --all-files

Configure Git

# Set up Git configuration
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Set up Git hooks
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Step 6: Verify Installation

# Test MkDocs installation
mkdocs --version

# Test V2X simulator (if installed)
python -c "import v2x_simulator; print('V2X Simulator installed successfully')"

# Start development server
mkdocs serve

Open your browser and navigate to http://127.0.0.1:8000 to verify the documentation site is working.

Configuration Files

MkDocs Configuration

The mkdocs.yml file is already configured with:

  • Material theme with dark/light mode
  • Navigation structure
  • Search functionality
  • Code highlighting
  • MathJax support
  • Git revision dates

Environment Variables

Create a .env file for local development:

# V2X Configuration
V2X_SIMULATION_MODE=true
V2X_LOG_LEVEL=INFO
V2X_DATA_DIR=./data

# Development settings
DEBUG=true
FLASK_ENV=development

IDE Configuration

VS Code Settings

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "files.associations": {
        "*.md": "markdown"
    }
}

PyCharm Configuration

  1. Open the project in PyCharm
  2. Go to File → Settings → Project → Python Interpreter
  3. Add the virtual environment interpreter
  4. Install required packages through PyCharm

Troubleshooting

Common Issues

Python Version Issues

# Check Python version
python --version

# If wrong version, use specific version
python3.11 --version
python3.11 -m venv venv

Permission Issues (Linux/macOS)

# Fix permission issues
sudo chown -R $USER:$USER venv/
chmod +x venv/bin/activate

Network Issues

# Use alternative package index
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# Or use conda
conda install mkdocs mkdocs-material

Port Already in Use

# Check what's using port 8000
lsof -i :8000

# Use different port
mkdocs serve -a localhost:8001

Verification Checklist

  • Python 3.8+ installed and accessible
  • Virtual environment created and activated
  • All dependencies installed successfully
  • MkDocs development server starts without errors
  • Documentation site accessible in browser
  • Git repository cloned and configured
  • Pre-commit hooks installed (optional)
  • V2X simulator working (optional)

Next Steps

After successful installation:

  1. Read the Quick Start Guide to create your first V2X application
  2. Explore V2X Technology Overview for technical details
  3. Check Implementation Guidelines for system design
  4. Review Best Practices for production deployment

Support

If you encounter issues during installation:

  1. Check the Troubleshooting section
  2. Review the Common Issues page
  3. Search existing issues in the repository
  4. Create a new issue with detailed error information

This installation guide provides a complete setup for V2X development. For specific platform instructions or advanced configurations, refer to the detailed documentation sections.