Cross-Platform Development

Platform Support

Conversor de Unidades Remoto is designed to run seamlessly across all major platforms:

Windows

PowerShell, CMD, and Git Bash supported

macOS

Native Terminal and zsh shell

Linux

Bash and other Unix shells

Key Differences

Virtual Environment Activation

The most significant difference between platforms is how you activate the Python virtual environment.

macOS/Linux
Windows PowerShell
Windows CMD

Uses forward slashes and .sh activation script:

# Create virtual environment
python3 -m venv .venv

# Activate
source .venv/bin/activate

# Deactivate
deactivate

Uses backslashes and .ps1 activation script:

# Create virtual environment
py -m venv .venv

# Activate
.\.venv\Scripts\Activate.ps1

# Deactivate
deactivate

If you get an execution policy error, run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Uses backslashes and .bat activation script:

rem Create virtual environment
py -m venv .venv

rem Activate
.venv\Scripts\activate.bat

rem Deactivate
deactivate

Python Command

Different platforms use different commands to invoke Python:

Platform	Command	Alternative
macOS/Linux	`python3`	`python` (if aliased)
Windows	`py`	`python` (if in PATH)

Use python (without the version) inside an activated virtual environment on all platforms.

Path Separators

# Forward slashes
cd backend
python3 server.py
slice2py backend/Conversor.ice

PowerShell accepts both forward and backward slashes in most contexts, making it more flexible than CMD.

Environment Variables

Setting environment variables differs significantly across platforms.

Temporary Variables (Current Session)

macOS/Linux
Windows PowerShell
Windows CMD

# Set and run in one command
HOST=0.0.0.0 PORT=8080 DEBUG=true python backend/web_server.py

# Or export for the session
export HOST=0.0.0.0
export PORT=8080
export DEBUG=true
python backend/web_server.py

# Set variables
$env:HOST="0.0.0.0"
$env:PORT="8080"
$env:DEBUG="true"

# Run the server
python backend/web_server.py

rem Set variables
set HOST=0.0.0.0
set PORT=8080
set DEBUG=true

rem Run the server
python backend\web_server.py

Persistent Variables

macOS/Linux - .bashrc or .zshrc

Add to ~/.bashrc (or ~/.zshrc on macOS Catalina+):

export HOST=0.0.0.0
export PORT=8080
export DEBUG=true

Reload:

source ~/.bashrc  # or ~/.zshrc

Windows - System Environment Variables

Open System Properties
Click “Environment Variables”
Add user or system variables

Or via PowerShell (admin required for system-wide):

[System.Environment]::SetEnvironmentVariable('HOST', '0.0.0.0', 'User')

Automated Run Scripts

The project includes platform-specific automation scripts that handle differences automatically.

macOS/Linux
Windows

File: run.sh

#!/bin/bash
# Automated startup script for Unix systems

First time setup:

chmod +x run.sh

Run:

./run.sh

Features:

Color-coded output using ANSI escape codes
Background process management with PIDs
SIGINT/SIGTERM trap for cleanup
Interactive ngrok prompt

File: run.ps1

# Automated startup script for Windows

Run:

powershell -ExecutionPolicy Bypass -File run.ps1

Features:

Color-coded output using PowerShell colors
Process management with Start-Process
Process tracking with PIDs
Interactive ngrok prompt

Both scripts provide the same user experience with:

ICE server startup on port 10000
Flask server startup on port 5000
Optional ngrok tunnel for remote access

Port Checking Commands

Checking which processes are using specific ports:

macOS/Linux
Windows PowerShell
Windows CMD

Check port usage:

lsof -i :10000
lsof -i :5000

Kill process by port:

# Find PID
lsof -ti :10000

# Kill it
kill -9 $(lsof -ti :10000)

Kill process by name:

pkill -f server.py
pkill -f web_server.py

Check port usage:

netstat -ano | findstr :10000
netstat -ano | findstr :5000

Kill process by PID:

# Get PID from netstat output, then:
taskkill /PID <PID> /F

Kill process by name:

taskkill /IM python.exe /F

Check port usage:

netstat -ano | findstr :10000
netstat -ano | findstr :5000

Kill process by PID:

rem Get PID from netstat output, then:
taskkill /PID <PID> /F

File Paths in Code

When writing Python code, use os.path.join() or pathlib for cross-platform compatibility:

import os
from pathlib import Path

# Good - works on all platforms
path = os.path.join('backend', 'Conversor.ice')
path = Path('backend') / 'Conversor.ice'

# Bad - only works on Unix
path = 'backend/Conversor.ice'

# Bad - only works on Windows
path = 'backend\\Conversor.ice'

The project’s current structure uses relative paths that work on both platforms because Python handles path conversion automatically in most cases.

Development Workflow

Recommended workflow that works identically across platforms:

Activate virtual environment

source .venv/bin/activate

Start ICE server

# Same on all platforms
cd backend
python server.py

Start Flask server (new terminal)

# Same on all platforms (after activating venv)
cd backend
python web_server.py

Access the application

http://localhost:5000

Same URL on all platforms.

Testing Commands

Test ICE connectivity directly:

# Same on all platforms
python backend/client.py

Test API endpoints with curl:

macOS/Linux
Windows PowerShell

# Status check
curl http://localhost:5000/api/status

# Conversion test
curl -X POST http://localhost:5000/api/convert \
  -H "Content-Type: application/json" \
  -d '{"categoria":"temperatura","valor":32,"desde":"fahrenheit","hasta":"celsius"}'

# Status check
curl http://localhost:5000/api/status

# Conversion test
Invoke-RestMethod -Uri http://localhost:5000/api/convert `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"categoria":"temperatura","valor":32,"desde":"fahrenheit","hasta":"celsius"}'

Package Installation

Python Package Manager

# Works on all platforms (inside activated venv)
pip install -r requirements.txt
pip install Flask
pip install zeroc-ice

System Package Managers

macOS - Homebrew
Windows - winget
Windows - Chocolatey
Linux - apt (Debian/Ubuntu)

brew install [email protected]
brew install ngrok

winget install Python.Python.3.11
winget install ngrok.ngrok

choco install python311
choco install ngrok

sudo apt update
sudo apt install python3.11 python3.11-venv

Best Practices

Use Virtual Environments

Always develop inside a virtual environment to isolate dependencies across all platforms

Path Handling

Use pathlib or os.path in Python code for automatic path separator handling

Test on Target Platforms

If possible, test your changes on Windows, macOS, and Linux before committing

Document Platform-Specific Steps

When adding features, document any platform-specific setup or commands

Git Considerations

Line Endings

Configure Git to handle line endings correctly:

# Recommended .gitattributes
* text=auto
*.sh text eol=lf
*.ps1 text eol=crlf
*.py text eol=lf

Always use LF (\n) for Python files, even on Windows. Windows Python handles LF correctly.

Execute Permissions

Bash scripts need execute permissions on Unix systems:

chmod +x run.sh

Git tracks these permissions. Windows users don’t need to worry about this.

Common Pitfalls

Mixed path separators in strings

Problem: Hardcoded paths with / or \\ in strings.Solution: Use os.path.join() or Path:

from pathlib import Path
ice_file = Path("backend") / "Conversor.ice"

Assuming bash commands exist

Problem: Using Unix commands like lsof, kill, grep in automation scripts.Solution: Provide separate scripts for Windows (.ps1) and Unix (.sh), or use Python for automation.

Hardcoded localhost

Problem: Not all systems resolve localhost the same way.Solution: Make the host configurable via environment variables:

host = os.getenv('HOST', 'localhost')

Assuming Python 3 is 'python'

Problem: Some systems use python for Python 2, python3 for Python 3.Solution: Inside a venv, use python (no version). Outside venv, use python3 (Unix) or py (Windows).

Summary Table

Task	macOS/Linux	Windows PowerShell	Windows CMD
Create venv	`python3 -m venv .venv`	`py -m venv .venv`	`py -m venv .venv`
Activate venv	`source .venv/bin/activate`	`.\.venv\Scripts\Activate.ps1`	`.venv\Scripts\activate.bat`
Run server	`python3 server.py`	`python server.py`	`python server.py`
Check port	`lsof -i :10000`	`netstat -ano \| findstr :10000`	`netstat -ano \| findstr :10000`
Set env var	`export VAR=value`	`$env:VAR="value"`	`set VAR=value`
Run script	`./run.sh`	`powershell -ExecutionPolicy Bypass -File run.ps1`	N/A

Bookmark this page for quick reference when switching between development machines!

Architecture

Contributing

Platform Support

Windows

macOS

Linux

Key Differences

Virtual Environment Activation

Python Command

Path Separators

Environment Variables

Temporary Variables (Current Session)

Persistent Variables

Automated Run Scripts

Port Checking Commands

File Paths in Code

Development Workflow

Testing Commands

Package Installation

Python Package Manager

System Package Managers

Best Practices

Use Virtual Environments

Path Handling

Test on Target Platforms

Document Platform-Specific Steps

Git Considerations

Line Endings

Execute Permissions

Common Pitfalls

Summary Table

Build docs developers (and LLMs) love

Architecture

Contributing

​Platform Support

Windows

macOS

Linux

​Key Differences

​Virtual Environment Activation

​Python Command

​Path Separators

​Environment Variables

​Temporary Variables (Current Session)

​Persistent Variables

​Automated Run Scripts

​Port Checking Commands

​File Paths in Code

​Development Workflow

​Testing Commands

​Package Installation

​Python Package Manager

​System Package Managers

​Best Practices

Use Virtual Environments

Path Handling

Test on Target Platforms

Document Platform-Specific Steps

​Git Considerations

​Line Endings

​Execute Permissions

​Common Pitfalls

​Summary Table

Build docs developers (and LLMs) love

Platform Support

Key Differences

Virtual Environment Activation

Python Command

Path Separators

Environment Variables

Temporary Variables (Current Session)

Persistent Variables

Automated Run Scripts

Port Checking Commands

File Paths in Code

Development Workflow

Testing Commands

Package Installation

Python Package Manager

System Package Managers

Best Practices

Git Considerations

Line Endings

Execute Permissions

Common Pitfalls

Summary Table