Skip to content

BUILD_REQUIREMENTS.md

Latest commit

 

History

History
289 lines (188 loc) · 5.75 KB

BUILD_REQUIREMENTS.md

File metadata and controls

289 lines (188 loc) · 5.75 KB
Raw

Build Requirements

This document describes the system-level dependencies required for building MrRSS on different platforms.

Overview

MrRSS uses Wails v3 (alpha) framework which requires CGO (C bindings for Go):

  • Wails v3: For the desktop application framework with built-in system tray
  • SQLite: Pure Go implementation (modernc.org/sqlite), no C dependencies

Important: CGO Requirement

⚠️ CRITICAL: Wails v3 requires CGO to be enabled. You must set:

export CGO_ENABLED=1

Or when building:

CGO_ENABLED=1 wails3 build

Platform-Specific Requirements

Linux

Development Dependencies

sudo apt-get update
sudo apt-get install -y \
  gcc \
  pkg-config \
  libgtk-4-dev \
  libwebkitgtk-6.0-dev \
  libsoup-3.0-dev

Dependency Breakdown:

  • gcc: C compiler (required for CGO)
  • pkg-config: Build tool for finding libraries
  • libgtk-4-dev: GTK4 development headers (for Wails UI)
  • libwebkitgtk-6.0-dev: WebKitGTK 6.0 development headers (for Wails webview, required for current Wails v3)
  • libsoup-3.0-dev: HTTP library 3.0 (required for Wails v3)

Important: Current Wails v3 requires GTK4, WebKitGTK 6.0, and libsoup 3.0. Older WebKitGTK 4.x and GTK3 packages are not sufficient.

Note for Linux Mint: Also install libxapp-dev

Runtime Dependencies

End users running the compiled binary will need:

  • libgtk-4-1
  • libwebkitgtk-6.0-4
  • libsoup-3.0-0

Windows

Development Dependencies

Install via Chocolatey:

choco install mingw nsis -y

Dependency Breakdown:

  • mingw: MinGW-w64 GCC compiler (required for CGO)
  • nsis: Nullsoft Scriptable Install System (for creating installers)

Alternative: Manual Installation

If not using Chocolatey:

  1. Install MinGW-w64
  2. Install NSIS (optional, for installers)
  3. Add MinGW bin directory to PATH

Build Flags

To avoid opening a console at application startup:

go build -ldflags "-H=windowsgui"

Or with Wails:

wails3 build -ldflags "-H=windowsgui"

Runtime Dependencies

Windows binaries are statically linked and don't require additional runtime dependencies.

macOS

Development Dependencies

Install Xcode Command Line Tools (if not already installed):

xcode-select --install

Note: macOS has native support for systray through AppKit, so no additional libraries are needed.

Application Bundle

macOS requires an application bundle structure:

MrRSS.app/
  Contents/
    Info.plist
    MacOS/
      MrRSS
    Resources/
      MrRSS.icns

Wails automatically creates this structure during build.

Info.plist Settings

Add these keys for better macOS integration:

<!-- High resolution support -->
<key>NSHighResolutionCapable</key>
<string>True</string>

<!-- Hide from Dock (optional, for menu bar only apps) -->
<key>LSUIElement</key>
<string>1</string>

Runtime Dependencies

macOS binaries are self-contained and don't require additional runtime dependencies.

Building with Wails

Standard Build

# Development build with hot reload
wails3 dev

# Production build (recommended: use Task)
task build

# Or directly with wails3
wails3 build

# Platform-specific build with Task
task linux:build
task windows:build
task darwin:build

Build Configuration

Wails v3 uses build/config.yml for build configuration and Taskfile for platform-specific builds:

  • Frontend: Automatically built via frontend/package.json scripts
  • Backend: CGO-enabled Go build with platform-specific flags
  • Installers: Created via platform-specific scripts (NSIS, create-dmg.sh, create-appimage.sh)

Cross-Compilation

Note: Cross-compilation with CGO is complex. For best results:

  • Build Linux binaries on Linux
  • Build Windows binaries on Windows
  • Build macOS binaries on macOS

GitHub Actions handles this automatically using platform-specific runners.

GitHub Actions

Our CI/CD pipeline automatically installs all required dependencies:

Test Workflow

  • Installs Linux dependencies for backend tests
  • Sets CGO_ENABLED=1

Release Workflow

  • Platform-specific dependency installation
  • Cross-platform builds using native runners
  • Artifact creation (installers, AppImages, DMGs)

Troubleshooting

"CGO is disabled" Error

Solution: Enable CGO before building:

export CGO_ENABLED=1
wails3 build

Linux: "Package webkitgtk-6.0 was not found"

Solution: Install WebKitGTK 6.0 development headers:

sudo apt-get install libwebkitgtk-6.0-dev

Linux: "Package ayatana-appindicator3-0.1 was not found"

This error is from older versions. Wails v3 uses its own system tray implementation.

Linux: "Package libsoup-3.0 was not found"

Solution: Install libsoup3 development headers:

sudo apt-get install libsoup-3.0-dev

Windows: "gcc: command not found"

Solution: Install MinGW:

choco install mingw -y

Or download from mingw-w64.org and add to PATH.

macOS: Missing Xcode Command Line Tools

Solution: Install Xcode Command Line Tools:

xcode-select --install

Development Environment Setup

Quick Setup Scripts

Linux/macOS:

# Install Go dependencies
go mod download

# Install frontend dependencies
cd frontend
npm install
cd ..

# Run development server
wails3 dev

Windows (PowerShell):

# Install Go dependencies
go mod download

# Install frontend dependencies
cd frontend
npm install
cd ..

# Run development server
wails3 dev

Related Documentation