Building from Source¶

This guide provides detailed instructions for building Rodrigolab's Flow Cytometry Analyzer from source code.

Prerequisites¶

Required for All Platforms¶

Rust (latest stable version)

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Node.js (v20 or later) and npm
Download from nodejs.org

Or use a version manager:

# Using nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Verify installation:

node --version  # Should be v20 or later
npm --version

Git
Usually pre-installed on macOS and Linux
Windows: Download from git-scm.com

Platform-Specific Requirements¶

macOS¶

Xcode Command Line Tools
```
xcode-select --install
```
Verify installation
```
xcode-select -p
```

Windows¶

Microsoft Visual C++ Build Tools
Download from Visual Studio Build Tools
Install "Desktop development with C++" workload
Windows SDK
Included with Visual Studio Build Tools

Linux (Ubuntu/Debian)¶

Install system dependencies:

sudo apt-get update
sudo apt-get install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  patchelf \
  libgtk-3-dev

Getting the Source Code¶

# Clone the repository
git clone https://github.com/luksgrin/flow-cytometry-analyzer.git
cd flow-cytometry-analyzer

Development Build¶

For development and testing:

# Install dependencies
npm install

# Run in development mode
npm run tauri dev

This will: - Start the Vite development server - Launch the Tauri application - Enable hot-reload for frontend changes

Production Build¶

Build for Current Platform¶

# Install dependencies
npm install

# Build frontend
npm run build

# Build application
cd src-tauri
cargo tauri build

The built application will be in src-tauri/target/release/bundle/.

Build for Specific Platforms¶

macOS ARM64 (Apple Silicon)¶

npm install
npm run build

# Add target if not already added
rustup target add aarch64-apple-darwin

# Build
cd src-tauri
cargo tauri build --target aarch64-apple-darwin --bundles app,dmg

Output: src-tauri/target/aarch64-apple-darwin/release/bundle/

macOS Intel¶

npm install
npm run build

# Add target if not already added
rustup target add x86_64-apple-darwin

# Build
cd src-tauri
cargo tauri build --target x86_64-apple-darwin --bundles app,dmg

Output: src-tauri/target/x86_64-apple-darwin/release/bundle/

Windows¶

npm install
npm run build

# Add target if not already added
rustup target add x86_64-pc-windows-msvc

# Build
cd src-tauri
cargo tauri build --target x86_64-pc-windows-msvc --bundles msi

Output: src-tauri/target/x86_64-pc-windows-msvc/release/bundle/msi/

Linux (Ubuntu/Debian)¶

# Install system dependencies (see Prerequisites section)
sudo apt-get update
sudo apt-get install -y [dependencies listed above]

# Install Node.js and Rust dependencies
npm install
npm run build

# Add target if not already added
rustup target add x86_64-unknown-linux-gnu

# Build DEB package
cd src-tauri
cargo tauri build --target x86_64-unknown-linux-gnu --bundles deb

# Or build AppImage
cargo tauri build --target x86_64-unknown-linux-gnu --bundles appimage

Output: src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/deb/ or bundle/appimage/

Cross-Compilation¶

Building for Different Platforms¶

Cross-compilation requires additional setup:

Building Windows from Linux/macOS¶

Install MinGW toolchain
Add target: rustup target add x86_64-pc-windows-gnu
Configure Cargo for cross-compilation

Building Linux from macOS/Windows¶

Requires Docker or a Linux VM. Recommended: Use GitHub Actions (see below).

Using GitHub Actions¶

The easiest way to build for all platforms is using GitHub Actions:

Push your code to GitHub
The workflow (.github/workflows/build-simple.yml) will automatically build for all platforms
Download artifacts from the Actions tab

Creating a Release¶

To create a release with all platform builds:

# Tag your release
git tag v1.0.0
git push origin v1.0.0

This triggers the release workflow which: - Builds for all platforms - Creates a GitHub Release - Attaches all platform artifacts

Build Output Locations¶

After building, find your artifacts:

macOS:
App: src-tauri/target/<target>/release/bundle/macos/Rodrigolab's Flow Cytometry Analyzer.app
DMG: src-tauri/target/<target>/release/bundle/dmg/

Note: When running a locally built macOS app, you may encounter a "damaged and cannot be opened" error due to macOS Gatekeeper. To fix this, run:

xattr -cr "src-tauri/target/<target>/release/bundle/macos/Rodrigolab's Flow Cytometry Analyzer.app"

Or right-click the app and select "Open" (then click "Open" in the security dialog). See the Installation Guide for more details. - Windows: - MSI: src-tauri/target/x86_64-pc-windows-msvc/release/bundle/msi/ - Linux: - DEB: src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/deb/ - AppImage: src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/appimage/

Troubleshooting Build Issues¶

Common Issues¶

"Tauri CLI not found"
```
cargo install tauri-cli --locked
```
"Target not found"
```
rustup target add <target-triple>
```
"Icon files missing"
Ensure all icon files exist in src-tauri/icons/
Check tauri.conf.json has correct icon paths
Linux: Missing dependencies
Install all system dependencies listed in Prerequisites
Use apt-cache search <package> to find package names on your distribution
Windows: Linker errors
Ensure Visual C++ Build Tools are installed
Restart terminal after installation
macOS: Code signing warnings
These are normal for local builds
For distribution, set up code signing in tauri.conf.json
macOS: "App is damaged and cannot be opened"
This is macOS Gatekeeper blocking the unsigned app
Remove quarantine attribute: xattr -cr "/path/to/app.app"
Or right-click the app and select "Open"
See Troubleshooting Guide for detailed instructions

Getting Help¶

Check the Troubleshooting Guide
Open an issue on GitHub
Review Tauri documentation

Development Tips¶

Use cargo tauri dev for faster iteration
Check src-tauri/target/debug/ for debug builds
Use RUST_LOG=debug cargo tauri build for verbose output
Clean build: cargo clean then rebuild