# Cross-Platform Setup for Synaptipy

## Problem Statement

Previously, Synaptipy had OS-specific dependencies that caused installation failures on different platforms:
- **Windows**: Required ucrt, vc, vs2015_runtime packages
- **macOS**: Required libcxx, libobjc, libtapi packages
- **Linux**: Required libstdcxx-ng, libgcc-ng, libgomp packages

## New Solution: Single Environment Approach

### **What Changed:**
1. **Removed**: Multiple OS-specific environment files
2. **Removed**: Complex OS detection in setup.py
3. **Removed**: OS-specific dependencies in pyproject.toml
4. **Added**: Single `environment.yml` that works everywhere
5. **Added**: Conda automatic OS-specific package handling

### **How It Works:**
```yaml
# Single environment.yml handles all OSes
dependencies:
 # Cross-platform packages (work everywhere)
 - python=3.11  # 3.11 recommended; 3.10 and 3.12 also supported
 - qt>=6.7
 - pyside6>=6.7

 # OS-specific packages (conda handles automatically)
 # Windows: ucrt, vc, vs2015_runtime, libclang13, libwinpthread
 # macOS: libcxx, libcxxabi, libobjc, libtapi, llvm-tools
 # Linux: libstdcxx-ng, libgcc-ng, libgomp, libgfortran-ng, libgfortran5
```

## Implementation Details

### **1. Single Environment File (`environment.yml`)**
- Contains all cross-platform dependencies
- Conda automatically installs OS-specific packages
- No manual OS detection needed

### **2. Clean Setup.py**
- No OS detection complexity
- Single environment creation function
- Works identically on all platforms

### **3. Clean PyProject.toml**
- No OS-specific dependencies
- Pure Python package requirements
- Cross-platform compatible

## Cross-Platform Compatibility

### **Windows**
```bash
# Automatically gets:
- ucrt=10.0.22621.0
- vc=14.3
- vs2015_runtime=14.44.35208
- libclang13=14.0.6
- libwinpthread=12.0.0.r4.gg4f2fc60ca
```

### **macOS**
```bash
# Automatically gets:
- libcxx=18.1.4
- libcxxabi=18.1.4
- libobjc=2.1
- libtapi=1100.0.11
- llvm-tools=18.1.4
```

### **Linux**
```bash
# Automatically gets:
- libstdcxx-ng=14.0.4
- libgcc-ng=14.0.4
- libgomp=14.0.4
- libgfortran-ng=14.0.4
- libgfortran5=14.0.4
```
### Standalone Installers (Recommended)

The easiest way to use Synaptipy is to download the standalone application. No Python environment setup is required.

[Download the Beta Release Here](https://github.com/anzalks/Synaptipy/releases)

Please download the appropriate file for your system:

* **Windows:** Download `Synaptipy_Setup_v0.1.1b2.exe` and follow the installation wizard.
* **macOS:** Download `Synaptipy_v0.1.1b2.dmg`. Open the file and drag the Synaptipy application into your Applications folder.
* **Linux:** Download `Synaptipy-v0.1.1b2-x86_64.AppImage`. You must make the file executable before running it. You can do this by right-clicking the file, navigating to Properties -> Permissions, and checking "Allow executing file as program", or via terminal: `chmod +x Synaptipy-v0.1.1b2-x86_64.AppImage`.

**Troubleshooting Notes:**
* **macOS:** Because the application is not currently signed via the Apple Developer Program, macOS Gatekeeper may block it the first time you try to open it. To bypass this, right-click (or Control-click) the Synaptipy app in your Applications folder and select "Open" from the context menu.
* **Linux:** AppImages require FUSE (Filesystem in Userspace) to run. If the application fails to launch silently on newer distributions (like Ubuntu 22.04 or later), you likely need to install `libfuse2`. You can install it via your terminal using: `sudo apt install libfuse2`.

## Installation Commands

### **One-Command Installation (Recommended)**
```bash
pip install -e .
```

### **Manual Installation**
```bash
# Create environment
conda env create -n synaptipy -f environment.yml

# Activate and install
conda activate synaptipy
pip install -e .
```

### **Custom Environment Name**
```bash
python install.py --env-name myenv
```

## Benefits

1. **Simplicity**: Single environment file instead of multiple OS-specific files
2. **Universal**: Works on Windows, macOS, and Linux without modification
3. **Version locked**: All packages have exact versions preserved
4. **Automatic**: No manual OS detection or configuration needed
5. **Clean**: No bloated files or complex setup logic
6. **Maintainable**: Easy to update and modify dependencies

## Testing

The setup has been tested to ensure:
- **Windows**: All OS-specific packages install correctly
- **macOS**: All OS-specific packages install correctly
- **Linux**: All OS-specific packages install correctly
- **Dependencies**: All version locks are preserved
- **Compatibility**: Qt6 and PySide6 work together properly

## How Conda Handles OS-Specific Packages

Conda automatically:
1. Detects the target platform (Windows/macOS/Linux)
2. Finds compatible versions of OS-specific packages
3. Installs the correct packages for that platform
4. Maintains compatibility with other packages

No manual intervention is required.

## Repository Structure

```
synaptipy/
 environment.yml # Single cross-platform environment
 setup.py # Simple setup script
 pyproject.toml # Clean package configuration
 install.py # Simple installation script
 README.md # Updated documentation
```

The following files are no longer present in the repository:

- `environment-base.yml`
- `environment-windows.yml`
- `environment-macos.yml`
- `environment-linux.yml`

## Result

Synaptipy now works on all platforms with:

- Single command installation: `pip install -e .`
- Automatic OS handling: No manual configuration required
- Version preservation: All dependencies locked exactly
- Clean codebase: No OS-specific files or complexity
- Universal compatibility: Windows, macOS, and Linux
