Build from Source Guide

Overview

This guide covers building Calcora from source for:

• 🖥️ Desktop Application: Standalone Windows executable
• 🔧 Development: Contributing to Calcora or testing new features
• 📦 Custom Packaging: Creating your own distributions
• 🐛 Debugging: Troubleshooting issues locally

System Requirements

Disk Space Requirements

• Source code: ~5 MB
• Dependencies: ~150 MB (including SymPy, NumPy, Flask)
• Build artifacts: ~200 MB (PyInstaller temporary files)
• Desktop executable: ~37 MB (final .exe)
• Total: ~400 MB free space recommended

1 Clone the Repository

Download the Calcora source code from GitHub.

# Clone with HTTPS
git clone https://github.com/Dumbo-programmer/Calcora.git
cd Calcora

# Or clone with SSH (if you have SSH keys configured)
git clone git@github.com:Dumbo-programmer/Calcora.git
cd Calcora

Verify Repository Contents

# List important files
ls -la

# Expected files and directories:
# - api_server.py         (Flask API server)
# - calcora_desktop.py    (Desktop app entry point)
# - build-desktop.ps1     (Desktop build script)
# - pyproject.toml        (Python project metadata)
# - requirements-api.txt  (API dependencies)
# - src/                  (Source code)
# - tests/                (Test suite)
# - site/                 (Web UI files)

2 Create Virtual Environment

Isolate dependencies from system Python installation.

Windows (PowerShell)

# Create virtual environment
python -m venv .venv

# Activate virtual environment
.\.venv\Scripts\Activate.ps1

# Verify activation (should show (.venv) in prompt)
python -c "import sys; print(sys.prefix)"

Linux / macOS (Bash/Zsh)

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Verify activation
which python  # Should show path inside .venv/

3 Install Dependencies

Install required Python packages for development and building.

Core Dependencies

# Install API server dependencies
pip install -r requirements-api.txt

# Verify installation
pip list | grep -E "flask|sympy|numpy|pydantic"

# Expected output:
# Flask            3.0.0+
# flask-cors       4.0.0+
# sympy            1.12+
# numpy            1.26+
# pydantic         2.7+

Development Dependencies

# Install testing and build tools
pip install pytest pytest-cov pyinstaller

# Optional: Install code quality tools
pip install black flake8 mypy pylint

4 Run Tests

Ensure everything is working correctly before building.

Basic Test Suite

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_integration_engine.py

Expected Test Results (v0.2.0)

Manual Testing

# Test the API server locally
python api_server.py

# In another terminal/browser:
# Navigate to http://localhost:5000
# Try computing: d/dx (x^2 + 3x + 1)

5 Build Desktop Application

Create a standalone Windows executable using PyInstaller.

Using the Build Script (Recommended)

# Run the desktop build script
.\build-desktop.ps1

# Build with clean (removes previous builds)
.\build-desktop.ps1 -Clean

# Build and test immediately
.\build-desktop.ps1 -Test

What the Build Script Does

1. Checks that virtual environment is activated
2. Installs PyInstaller if not present
3. Runs PyInstaller with the calcora-desktop.spec configuration
4. Bundles Python runtime, dependencies, and web UI files
5. Creates single-file executable in dist/Calcora.exe
6. Reports build size and success status

Build Output

============================================================
  Calcora Desktop Builder v0.3
============================================================

Checking for PyInstaller...
PyInstaller is installed

Building Calcora Desktop executable...
This may take 2-5 minutes...

[PyInstaller build output...]

Build successful!
Executable: dist\Calcora.exe
Size: 36.8 MB

To test the executable, run:
  .\dist\Calcora.exe

PyInstaller Configuration

Understanding the calcora-desktop.spec file.

Key Configuration Options

# calcora-desktop.spec (simplified)

a = Analysis(
    ['calcora_desktop.py'],           # Entry point script
    pathex=[],
    binaries=[],
    datas=[
        ('src/calcora/web', 'web'),    # Bundle web UI files
        ('site', 'web'),               # Alternative web files
    ],
    hiddenimports=[
        'calcora.engine_implementations.sympy_engine',
        'sympy.parsing.sympy_parser',
    ],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
)

pyz = PYZ(a.pure)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.datas,
    [],
    name='Calcora',                    # Executable name
    debug=False,                       # Disable debug mode
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,                          # Compress with UPX
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,                     # No console window
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='media/icon.ico',             # Application icon
)

Customizing the Build

Edit calcora-desktop.spec to customize:

• Icon: Change icon='media/icon.ico'
• Name: Change name='Calcora'
• Console: Set console=True to keep terminal window open for debugging
• Hidden imports: Add modules to hiddenimports=[] if missing at runtime
• Data files: Add additional files to datas=[]

Manual Build (without script)

# Build directly with PyInstaller
pyinstaller calcora-desktop.spec --clean --noconfirm

# Or create spec file from scratch
pyinstaller --onefile \
  --windowed \
  --icon=media/icon.ico \
  --name=Calcora \
  --add-data "src/calcora/web;web" \
  calcora_desktop.py

Troubleshooting Build Issues

hiddenimports=[
    'calcora.engine_implementations.sympy_engine',
    'your_missing_module_here',
]

# Edit calcora-desktop.spec: set console=True
# Then rebuild:
.\build-desktop.ps1 -Clean

.\.venv\Scripts\Activate.ps1  # Windows
source .venv/bin/activate      # Linux/Mac

# Check datas in calcora-desktop.spec
datas=[
    ('src/calcora/web', 'web'),
    ('site', 'web'),  # Ensure this path exists
]

# Add folder exclusion in Windows Security:
# Settings > Privacy & Security > Windows Security
# > Virus & threat protection > Manage settings
# > Exclusions > Add folder: B:\Development\Calcora\dist

Testing the Executable

# Test the built executable
cd dist
.\Calcora.exe

# Check if server starts properly:
# 1. Browser should open automatically to http://localhost:5000
# 2. UI should load without errors
# 3. Try a computation: d/dx (x^2)
# 4. Close browser or click "Shutdown" to exit gracefully

Creating Distribution Packages

Package your build for distribution to users.

Windows Installer (Optional)

# Use Inno Setup or NSIS to create installer
# Example Inno Setup script structure:

[Setup]
AppName=Calcora
AppVersion=0.3.0
DefaultDirName={pf}\Calcora
DefaultGroupName=Calcora
OutputBaseFilename=CalcoraSetup
Compression=lzma2
SolidCompression=yes

[Files]
Source: "dist\Calcora.exe"; DestDir: "{app}"

[Icons]
Name: "{group}\Calcora"; Filename: "{app}\Calcora.exe"

Portable ZIP Package

# Create portable package
mkdir Calcora-Portable
cp dist/Calcora.exe Calcora-Portable/
cp README.md Calcora-Portable/
cp LICENSE Calcora-Portable/

# Create ZIP archive
Compress-Archive -Path Calcora-Portable -DestinationPath Calcora-v0.3.0-Portable.zip

# Calculate checksum (for verification)
Get-FileHash Calcora-v0.3.0-Portable.zip -Algorithm SHA256

Using package-desktop.ps1

# Run the packaging script (if available)
.\package-desktop.ps1

# This creates:
# - ZIP archive with executable
# - SHA256 checksum file
# - Ready for GitHub release

Code Signing (Optional)

Sign your executable to remove Windows security warnings.

Obtaining a Certificate

1. Purchase from: Sectigo, DigiCert, GlobalSign, or SSL.com
2. Complete identity verification (business or individual)
3. Receive certificate file (.pfx or .p12)
4. Install on Windows Certificate Store

Signing the Executable

# Using signtool.exe (Windows SDK)
signtool sign /f certificate.pfx /p password /t http://timestamp.digicert.com dist\Calcora.exe

# Verify signature
signtool verify /pa dist\Calcora.exe

See the Code Signing Guide for detailed instructions.

Contributing to Calcora

Help improve Calcora by contributing code, documentation, or bug reports.

Development Workflow

1. Fork the repository on GitHub
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/Calcora.git
3. Create a branch: git checkout -b feature/your-feature-name
4. Make changes and write tests
5. Run tests: pytest
6. Commit: git commit -m "Add feature: your description"
7. Push: git push origin feature/your-feature-name
8. Create Pull Request on GitHub

Code Standards

# Format code with Black
black src/ tests/

# Check code quality
flake8 src/ tests/ --max-line-length=100

# Type checking
mypy src/

Writing Tests

# Create test file in tests/ directory
# Example: tests/test_new_feature.py

import pytest
from calcora.bootstrap import default_engine

def test_new_integration_rule():
    """Test new integration rule implementation"""
    engine = default_engine(load_entry_points=True)
    result = engine.run(
        operation='integrate',
        expression='sin(x)',
        variable='x'
    )
    assert result.output == '-cos(x)'
    assert result.success is True

Documentation

• Update README.md for user-facing changes
• Add docstrings to new functions/classes
• Update CHANGELOG.md with your changes
• Create/update docs in docs/ directory

Guidelines

• Follow existing code style and patterns
• Write clear commit messages
• Add tests for new features
• Update documentation for API changes
• Be respectful in discussions (see Code of Conduct)

Read the full Contributing Guide for more details.

Advanced Topics

# .github/workflows/build.yml
name: Build Desktop App

on:
  push:
    tags:
      - 'v*'

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: |
          python -m venv .venv
          .\.venv\Scripts\Activate.ps1
          pip install -r requirements-api.txt
          pip install pyinstaller
          .\build-desktop.ps1
      - uses: actions/upload-artifact@v3
        with:
          name: Calcora-Windows
          path: dist/Calcora.exe

# Enable debug mode in spec file
exe = EXE(
    ...,
    debug=True,  # Enable debug output
    console=True,  # Show console window
    ...
)

# Run with debug flags
pyinstaller --debug=all calcora-desktop.spec

Need Help?

Build and development support resources:

• GitHub Issues — Report build problems or bugs
• GitHub Discussions — Ask development questions
• Contributing Guide — Detailed contribution instructions
• Self-Hosting Guide — Deploy your build to production