Building from Source

Prerequisites

Before building Obsidian Chess Studio, ensure you have the required tools installed for your platform.

All Platforms

Install Node.js

Download and install Node.js 18+ from nodejs.orgVerify installation:

node --version
npm --version

Install pnpm

Install the pnpm package manager:

npm install -g [email protected]

Verify installation:

pnpm --version

Install Rust

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify installation:

rustc --version
cargo --version

Platform-Specific Prerequisites

Windows
macOS
Linux

Required:

Microsoft C++ Build Tools - Install from Visual Studio
WebView2 - Usually pre-installed on Windows 10/11

Install Visual Studio Build Tools:

Download the Visual Studio Installer
Select “Desktop development with C++” workload
Install required components

Verify:

# Check if build tools are available
where cl.exe

Required:

Xcode Command Line Tools

Install:

xcode-select --install

Verify:

xcode-select -p
# Should output: /Library/Developer/CommandLineTools

For Apple Silicon Macs, Rust will automatically compile for ARM64. For universal binaries, additional configuration is needed.

Required packages (Debian/Ubuntu):

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

Fedora/RHEL:

sudo dnf install webkit2gtk4.1-devel \
  openssl-devel \
  curl \
  wget \
  file \
  libappindicator-gtk3-devel \
  librsvg2-devel

Arch Linux:

sudo pacman -Syu
sudo pacman -S --needed \
  webkit2gtk \
  base-devel \
  curl \
  wget \
  file \
  openssl \
  appmenu-gtk-module \
  gtk3 \
  libappindicator-gtk3 \
  librsvg

Clone Repository

Clone the repository and navigate to the project directory:

git clone [email protected]:luisrivasnoriega/Obsidian-Chess-Studio.git
cd Obsidian-Chess-Studio

Or using HTTPS:

git clone https://github.com/luisrivasnoriega/Obsidian-Chess-Studio.git
cd Obsidian-Chess-Studio

Install Dependencies

Install all frontend and backend dependencies:

pnpm install

This command:

Installs Node.js packages from package.json
Downloads Rust dependencies (first run only)
Sets up the development environment

First run may take several minutes as Cargo downloads and compiles Rust dependencies.

Development Mode

Run the application in development mode with hot reload:

pnpm dev

This command:

Starts Vite dev server on http://127.0.0.1:1420
Compiles Rust backend in debug mode
Launches the Tauri application
Watches for file changes and auto-reloads

# Full dev mode (frontend + backend)
pnpm dev

Development Server Details

Frontend: Runs on port 1420 with hot module replacement (HMR)
Backend: Compiles with opt-level = 0 for faster builds
Auto-reload: Changes to .tsx, .ts, .rs files trigger rebuild
Debug logging: Enabled by default in dev mode

Production Build

Build optimized production binaries:

All Platforms
Windows Specific
macOS Specific
Linux Specific

# Build with bundled installer (recommended)
pnpm tauri build

# Build without installer (binary only)
pnpm build
# or
pnpm tauri build --no-bundle

Build output locations:

Windows: src-tauri/target/release/obsidian-chess-studio.exe
macOS: src-tauri/target/release/bundle/dmg/
Linux: src-tauri/target/release/obsidian-chess-studio

Installers (with pnpm tauri build):

Windows: .exe, .msi in src-tauri/target/release/bundle/
macOS: .dmg, .app in src-tauri/target/release/bundle/
Linux: .AppImage, .deb, .rpm in src-tauri/target/release/bundle/

Build configurations:

# Standard build
pnpm tauri build

# Build for specific architecture
pnpm tauri build --target x86_64-pc-windows-msvc
pnpm tauri build --target aarch64-pc-windows-msvc

Output:

obsidian-chess-studio_x.x.x_x64_en-US.msi
obsidian-chess-studio_x.x.x_x64-setup.exe

Windows builds use thin LTO to prevent linker errors. Build time: ~5-15 minutes depending on hardware.

Build universal binary (Intel + Apple Silicon):

# Build for current architecture
pnpm tauri build

# Build universal binary
pnpm tauri build --target universal-apple-darwin

Output:

obsidian-chess-studio_x.x.x_aarch64.dmg (Apple Silicon)
obsidian-chess-studio_x.x.x_x64.dmg (Intel)
obsidian-chess-studio_x.x.x_universal.dmg (Universal)

Code signing is required for distribution. See Tauri docs for details.

Build for different formats:

# Build all formats (AppImage, deb, rpm)
pnpm tauri build

# Build specific format
pnpm tauri build --bundles appimage
pnpm tauri build --bundles deb
pnpm tauri build --bundles rpm

Output:

obsidian-chess-studio_x.x.x_amd64.AppImage
obsidian-chess-studio_x.x.x_amd64.deb
obsidian-chess-studio-x.x.x-1.x86_64.rpm

Install built package:

# AppImage
chmod +x obsidian-chess-studio_*.AppImage
./obsidian-chess-studio_*.AppImage

# Debian/Ubuntu
sudo dpkg -i obsidian-chess-studio_*.deb

# Fedora/RHEL
sudo rpm -i obsidian-chess-studio-*.rpm

Build Optimization

Production builds use aggressive optimizations defined in src-tauri/Cargo.toml:

[profile.release]
opt-level = 3          # Maximum optimization
lto = "thin"           # Thin Link-Time Optimization
codegen-units = 1      # Better optimization
strip = true           # Remove debug symbols
panic = "abort"        # Smaller binary

Expected build times:

Debug build: 2-5 minutes
Release build: 5-20 minutes
First build: Significantly longer due to dependency compilation

Docker Build

Build using Docker for a consistent environment:

Build Docker Image

docker build -t obsidian-chess-studio .

Run Container

docker run -d --name obsidian-chess-studio-app obsidian-chess-studio

Extract Binary

docker cp obsidian-chess-studio-app:/output/obsidian-chess-studio ./obsidian-chess-studio

Docker builds are primarily used for Linux targets. For Windows/macOS, native builds are recommended.

Troubleshooting

Common Issues

Windows: 'link.exe' failed with exit code 1120

Solution: This occurs with lto = "fat". The project uses lto = "thin" by default.If you modified Cargo.toml, ensure:

[profile.release]
lto = "thin"  # NOT "fat"

Linux: webkit2gtk not found

Solution: Install WebKit2GTK development files:

# Debian/Ubuntu
sudo apt install libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install webkit2gtk4.1-devel

macOS: 'xcode-select' error

Solution: Install Xcode Command Line Tools:

xcode-select --install

If already installed, reset the path:

sudo xcode-select --reset

pnpm install fails

Solution: Clear pnpm cache and retry:

pnpm store prune
pnpm install --force

Cargo build fails with 'linker not found'

Solution:

Windows: Install Visual Studio Build Tools
Linux: Install build-essential or base-devel
macOS: Install Xcode Command Line Tools

Performance Optimization

To speed up development builds:

# Use mold linker (Linux only, much faster)
cargo install mold
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"

# Enable parallel frontend builds
export VITE_BUILD_PARALLEL=true

Next Steps

Project Structure

Understand the codebase organization

Contributing

Learn how to contribute code

Testing

Run tests and add new ones

Architecture

Deep dive into the architecture

Getting Started

Contributing

Architecture

Prerequisites

All Platforms

Platform-Specific Prerequisites

Clone Repository

Install Dependencies

Development Mode

Development Server Details

Production Build

Build Optimization

Docker Build

Troubleshooting

Common Issues

Performance Optimization

Next Steps

Project Structure

Contributing

Testing

Architecture

Build docs developers (and LLMs) love

Getting Started

Contributing

Architecture

​Prerequisites

​All Platforms

​Platform-Specific Prerequisites

​Clone Repository

​Install Dependencies

​Development Mode

​Development Server Details

​Production Build

​Build Optimization

​Docker Build

​Troubleshooting

​Common Issues

​Performance Optimization

​Next Steps

Project Structure

Contributing

Testing

Architecture

Build docs developers (and LLMs) love

Prerequisites

All Platforms

Platform-Specific Prerequisites

Clone Repository

Install Dependencies

Development Mode

Development Server Details

Production Build

Build Optimization

Docker Build

Troubleshooting

Common Issues

Performance Optimization

Next Steps