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:

# Single environment.yml handles all OSes
dependencies:
 # Cross-platform packages (work everywhere)
 - python>=3.10
 - 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

# 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

# Automatically gets:
- libcxx=18.1.4
- libcxxabi=18.1.4
- libobjc=2.1
- libtapi=1100.0.11
- llvm-tools=18.1.4

Linux

# 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

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)

pip install -e .

Manual Installation

# Create environment
conda env create -n synaptipy -f environment.yml

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

Custom Environment Name

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