Installing Grapa

Grapa is available as platform-specific packages with a universal installer that automatically detects your platform and downloads the appropriate package.

Note: Documentation and downloads are available on GitHub.

🚀 Universal Installer (Recommended)

Grapa 0.1.56+ provides a universal installer that automatically detects your platform and downloads the correct package:

Smart platform detection - automatically identifies your system
Automatic dependency installation - installs system dependencies on Linux/macOS
Ubuntu version detection - provides version-specific installation instructions
Optimized packages - each platform gets only what it needs
Under 100MB - all packages stay well under GitHub's file size limit
Complete development kit - includes sample code, CMake build system, and all libraries
Self-contained - no external dependencies required

Quick Installation

# Download and run the universal installer
curl -O https://github.com/grapa-dev/grapa/releases/download/v0.1.56/install-grapa-0.1.56.py
python3 install-grapa-0.1.56.py

Installation with Automatic Dependencies

# Install Grapa and automatically install system dependencies (Linux/macOS)
python3 install-grapa-0.1.56.py --install-dependencies

The installer will: 1. Detect your platform (macOS, Linux, Windows, AWS) 2. Install system dependencies (Linux/macOS only, with --install-dependencies) 3. Download the appropriate package for your system 4. Install Grapa to /usr/local/ (or ~/.local/grapa/ on some systems) 5. Set up the environment for immediate use 6. Provide platform-specific instructions for Python extension installation

Manual Installation (Alternative)

If you prefer to download and install manually, you can download the specific package for your platform:

macOS (ARM64 - Apple Silicon)

Download and install:

# Download the macOS ARM64 package
curl -L -o grapa-0.1.56-mac-arm64.zip https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-mac-arm64.zip

# Extract the package
unzip grapa-0.1.56-mac-arm64.zip
cd grapa-0.1.56

# Run the installer
python3 install-grapa-0.1.56.py

# Verify installation
grapa --version

Test basic functionality:

grapa -c "2+2"
grapa -c "'Hello World'.echo()"

Uninstall:

# The installer provides uninstall instructions
# Or manually remove:
sudo rm -f /usr/local/bin/grapa
sudo rm -f /usr/local/lib/libgrapa_static.a
sudo rm -f /usr/local/lib/libgrapa.so

Linux (AMD64)

Download and install:

# Download the Linux AMD64 package
wget https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-linux-amd64.zip

# Extract and install
unzip grapa-0.1.56-linux-amd64.zip
cd grapa-0.1.56
sudo python3 install-grapa-0.1.56.py

# Verify installation
grapa --version

Linux (ARM64)

Download and install:

# Download the Linux ARM64 package
wget https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-linux-arm64.zip

# Extract and install
unzip grapa-0.1.56-linux-arm64.zip
cd grapa-0.1.56
sudo python3 install-grapa-0.1.56.py

# Verify installation
grapa --version

Test basic functionality:

grapa -c "2+2"
grapa -c "'Hello World'.echo()"

Uninstall:

# Remove from system directories
sudo rm -f /usr/local/bin/grapa
sudo rm -f /usr/local/lib/libgrapa_static.a
sudo rm -f /usr/local/lib/libgrapa.so

AWS (AMD64)

Download and install:

# Download the AWS AMD64 package
wget https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-aws-amd64.zip

# Extract and install
unzip grapa-0.1.56-aws-amd64.zip
cd grapa-0.1.56
sudo python3 install-grapa-0.1.56.py

# Verify installation
grapa --version

AWS (ARM64)

Download and install:

# Download the AWS ARM64 package
wget https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-aws-arm64.zip

# Extract and install
unzip grapa-0.1.56-aws-arm64.zip
cd grapa-0.1.56
sudo python3 install-grapa-0.1.56.py

# Verify installation
grapa --version

Test basic functionality:

grapa -c "2+2"
grapa -c "'Hello World'.echo()"

Uninstall:

# Remove from system directories
sudo rm -f /usr/local/bin/grapa
sudo rm -f /usr/local/lib/libgrapa_static.a
sudo rm -f /usr/local/lib/libgrapa.so

Windows (AMD64)

Download and install:

Automated Installation (Recommended)

Download the Windows package:

# Download the Windows AMD64 release
Invoke-WebRequest -Uri "https://github.com/grapa-dev/grapa/releases/download/v0.1.56/grapa-0.1.56-win-amd64.zip" -OutFile "grapa-0.1.56-win-amd64.zip"

Extract the package:

Expand-Archive -Path "grapa-0.1.56-win-amd64.zip" -DestinationPath "grapa-0.1.56" -Force

Run the installer (run PowerShell as Administrator):

cd grapa-0.1.56
python install-grapa-0.1.56.py

Verify installation:
```
grapa --version
```

Test basic functionality:

grapa -c "2+2"
grapa -c "'Hello World'.echo()"

Installation Location: After installation, Grapa will be available at: - Executable: C:\Program Files\Grapa\bin\grapa.exe - Static Library: C:\Program Files\Grapa\lib\grapa_static.lib - Shared Library: C:\Program Files\Grapa\lib\grapa.dll (if available) - PATH: Automatically added to system PATH for command-line access

Uninstall:

# Run PowerShell as Administrator
python install-grapa-0.1.56.py --uninstall

🛠️ Building and Running the Example

The universal development kit includes a complete C++ example demonstrating how to embed Grapa in your applications.

Build the Example Application

After extracting the universal package, you can build and run the included example:

# Navigate to the extracted directory
cd grapa-0.1.56

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build the project
cmake --build .

# Run the example
./grapa_example  # On Unix/macOS
grapa_example.exe  # On Windows

What the Example Demonstrates

The included main.cpp shows how to: - Initialize the Grapa runtime - Execute Grapa code from C++ - Handle errors and return values - Clean up resources properly

Development Workflow

The universal development kit supports the standard CMake workflow:

# Standard CMake build process
mkdir build && cd build
cmake ..
cmake --build .

This works consistently across all platforms (Windows, macOS, Linux) with the same commands.

Verify Installation

After installation, verify that Grapa is working correctly:

grapa --version

You should see output similar to:

Grapa version 0.1.56

Test Basic Functionality

Try running a simple Grapa command:

grapa -c "2+2"
grapa -c "'Hello World'.echo()"

You should see:

4
Hello World

🐍 Python Extension Installation

GrapaPy provides Python integration with Grapa's powerful data processing capabilities. Installation requirements vary by platform:

Platform-Specific Dependencies

GrapaPy requires system-level dependencies that must be installed before running pip install grapapy. The Python package includes built-in dependency checking and will provide detailed error messages if dependencies are missing.

Linux

Required Dependencies: - OpenSSL development libraries (libssl-dev, libcrypto-dev) - X11 development libraries (libx11-dev, libxext-dev) - Build tools (build-essential, g++ with C++17 support) - Python development headers (python3-dev)

Installation Commands:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential python3-dev libssl-dev libx11-dev libxext-dev

# CentOS/RHEL/Amazon Linux
sudo yum groupinstall 'Development Tools'
sudo yum install python3-devel openssl-devel libX11-devel libXext-devel

# Fedora
sudo dnf groupinstall 'Development Tools'
sudo dnf install python3-devel openssl-devel libX11-devel libXext-devel

Automatic Installation: ❌ No - pip install grapapy cannot install system packages. You must install dependencies manually or use the universal installer.

macOS

Required Dependencies: - Xcode Command Line Tools (includes compilers and build tools)

Installation Command:

xcode-select --install

Automatic Installation: ❌ No - pip install grapapy cannot install Xcode tools. You must install manually.

Windows

Required Dependencies: - Visual Studio 2022 or Build Tools for Visual Studio 2022 (version 17.x) - Windows 10/11 SDK (usually included with Visual Studio 2022) - Python 3.6+

Installation Steps: 1. Download and install Visual Studio 2022 or Build Tools for Visual Studio 2022 2. During installation, ensure "Desktop development with C++" workload is selected 3. This automatically includes the Windows SDK

Automatic Installation: ❌ No - pip install grapapy cannot install Visual Studio. You must install manually.

Important: Run pip install grapapy from the "x64 Native Tools Command Prompt for VS 2022" to ensure the build environment is properly configured.

Installation Methods

Method 1: From PyPI (Recommended)

Step 1: Install System Dependencies Install the platform-specific dependencies listed above before proceeding.

Step 2: Install GrapaPy

# Linux/macOS
pip3 install grapapy

# Windows (run from "x64 Native Tools Command Prompt for VS 2022")
pip install grapapy

What happens during installation: - GrapaPy checks for required system dependencies - If dependencies are missing, installation fails with detailed error messages - If dependencies are present, GrapaPy compiles and installs successfully

Method 2: Build from Source

# Build Grapa with Python extension support
python3 build.py --python

# On Windows, use:
python build.py --python

Alternative: Universal Installer for Dependencies

The Grapa universal installer can automatically install system dependencies for the CLI, which are the same dependencies needed for GrapaPy:

Automatic Dependency Installation (Linux/macOS)

# Install Grapa CLI with automatic dependency installation
python3 install-grapa-0.1.56.py --install-dependencies

# Then install GrapaPy (dependencies already installed)
pip3 install grapapy

What the universal installer installs: - Linux: All required development packages (OpenSSL, X11, build tools, etc.) - macOS: Xcode Command Line Tools - Windows: ❌ Not supported - requires manual Visual Studio installation

Manual Dependency Installation

If you prefer to install dependencies manually, use the commands listed in the platform-specific sections above.

🛠️ Building from Source

Grapa 0.1.56 includes support for building Python extensions from source:

Build with Python Extension

# Build Grapa with Python extension support
python3 build.py --python

# On Windows, use:
python build.py --python

Install Python Extension

After building, install the Python extension:

Windows:

# Upgrade pip first
pip install --upgrade pip

# Install GrapaPy from PyPI
pip install grapapy

Non-Windows:

# Upgrade pip first
pip3 install --upgrade pip

# Install GrapaPy from PyPI
pip3 install grapapy

Verify Python Integration

import grapapy
g = grapapy.grapa()
result = g.eval('2 + 2')
print(f'Grapa result: {result}')

Available Packages

The platform-specific release provides optimized packages for each platform:

install-grapa-0.1.56.py - Universal Installer (4 KB)
Automatically detects your platform
Downloads the appropriate package
Installs Grapa with proper setup

Platform-Specific Packages: - grapa-0.1.56-mac-arm64.zip - macOS ARM64 (11.0 MB) - grapa-0.1.56-linux-amd64.zip - Linux AMD64 (14.7 MB) - grapa-0.1.56-linux-arm64.zip - Linux ARM64 (15.4 MB) - grapa-0.1.56-win-amd64.zip - Windows AMD64 (42.7 MB) - grapa-0.1.56-aws-amd64.zip - AWS AMD64 (13.4 MB) - grapa-0.1.56-aws-arm64.zip - AWS ARM64 (13.7 MB)

Each package includes: - Platform-specific Grapa executable - Universal installer (install-grapa-0.1.56.py) - Sample C++ application (main.cpp) - Complete CMake build system - Platform libraries and headers - Self-contained with no external dependencies

Troubleshooting

"grapa: command not found"

Verify installation completed successfully:

# Check if grapa is installed
which grapa

# Check if it's executable
ls -la $(which grapa)

Check if PATH is set correctly:
```
echo $PATH | grep "/usr/local/bin"
```
Try restarting your terminal after installation.

Permission Denied

Ensure you have appropriate permissions:

# Linux/macOS
sudo chmod +x /usr/local/bin/grapa

Check file permissions:
```
# Linux/macOS
ls -la $(which grapa)
```

Windows-Specific Issues

Installation Script Issues

If the install-grapa-0.1.56.py script fails:

Check Python installation:

python --version
# Should show Python 3.6 or higher

Verify the script exists:
```
Test-Path "install-grapa-0.1.56.py"
```

Run the script with verbose output:

python install-grapa-0.1.56.py --verbose

Python Installation Issues

If you encounter Python-related errors:

Check Python installation:
```
python --version
```
Install Python if needed:
Download from python.org
Make sure to check "Add Python to PATH" during installation

PATH Issues

If Grapa is installed but not found in PATH:

Check if Grapa is in the installation directory:

Test-Path "C:\Program Files\Grapa\bin\grapa.exe"

Add Grapa to PATH manually:

$env:PATH += ";C:\Program Files\Grapa\bin"

Restart PowerShell to ensure PATH changes take effect.

Getting Help

If you encounter issues not covered here:

Check the Troubleshooting Guide
Search existing issues on GitHub
Create a new issue with details about your platform and error messages

Next Steps

After successful installation:

Read the Getting Started Guide for your first Grapa program
Explore the CLI Quick Start for command-line usage
Check out Examples for sample code and use cases