Development Guide

Everything you need to build, test, and package Driftleaf locally.

Table of Contents

• Prerequisites
• Local Development
• Building Packages
• Platform-Specific Requirements
• Cross-Architecture Builds
• Troubleshooting

Prerequisites

Base Requirements

Important Notice

Installing build tools, package manager dependencies, or third-party packages can modify your system, add services, change package versions, and in some cases break software already installed on your machine. Only install packages you understand and trust, and use the commands in this guide at your own risk.

AetherAssembly and its contributors are not responsible for any system breakage, dependency conflicts, data loss, or other issues caused by following these instructions or installing packages from external sources.

Platform-Specific Build Tools

Arch Linux

sudo pacman -S --needed ruby gcc make fakeroot dpkg rpm-tools qemu-full virt-manager

Note: On Arch-based distros, you need both dpkg and rpm-tools to generate .deb and .rpm artifacts respectively, even though you're on an RPM-native system.

If you use CachyOS, follow their wiki on QEMU installation/setup.

If you use Arch Linux, follow their wiki on QEMU installation/setup.

Debian/Ubuntu

sudo apt-get install ruby build-essential dpkg-dev rpm qemu-system-arm

Fedora/RHEL/CentOS

sudo dnf install ruby gcc rpm-build dpkg qemu-system-ARM

openSUSE

sudo zypper install ruby patterns-devel-base-devel_basis rpm-build dpkg qemu-system-arm

Local Development

Initial Setup for Linux

# GitHub Packages auth (one-time setup)
echo "//npm.pkg.github.com/:_authToken=<your-token>" >> ~/.npmrc

# Install dependencies
npm install

# Launch in development mode
npm run dev

Initial Setup for Windows

1. Open your User Folder

1. Press Windows Key + R to open the Run dialog.
2. Type %userprofile% and press Enter. (This opens your user folder, like C:\Users\YourName).

2. Create the .npmrc file

1. Inside that folder, right-click and select New > Text Document.
2. Name the file exactly: .npmrc
3. Important: Windows might add .txt to the end. You need to make sure the final name is .npmrc, not .npmrc.txt. * If you can't see file extensions: In File Explorer, click View at the top, and check the box for File name extensions. Then rename the file to remove the .txt. * Alternatively, when saving, select "All Files" as the file type and name it .npmrc.

Windows .npmrc example: create a plain-text .npmrc file in your user profile with the line //npm.pkg.github.com/:_authToken=YOUR_TOKEN.

3. Add the content

1. Right-click the newly created .npmrc file and choose Open with > Notepad.
2. Paste the following line inside:

text //npm.pkg.github.com/:_authToken=YOUR_TOKEN

3. Replace YOUR_TOKEN with your actual GitHub Personal Access Token (PAT). (Make sure the token has the read:packages scope enabled, as the image notes).
4. Save the file and close Notepad.

In-Depth aether-packages installation notes are available in the repo and on the wiki.

4. Verify and use

1. Open a new PowerShell or CMD window.
2. Run npm install again. It should now use the token in that file to authenticate with GitHub Packages.

⚠️ Note: Never commit this .npmrc file to a public Git repository, as it contains your secret token!

Common Commands

Debugging Search Performance

export DEBUG_SEARCH=1
npm run dev

Search the terminal running npm run dev for [search] timing logs. See Performance for details.

Building Packages

Standard Builds

# All Linux formats (x86_64 only)
npm run package:linux

# Single format
npm run package:appimage           # Portable AppImage
npm run package:linux              # AppImage + deb + rpm
npm run package:macos              # DMG + ZIP
npm run package:windows            # Installer + portable .exe

# Beta variants
npm run package:linux:beta         # Beta builds for Linux
npm run package:linux:arm64:beta   # Beta ARM64 builds

Output Locations

Artifacts are generated in release/ and named with the same version as proper releases unless changed.

If you test locally while the released version of Driftleaf is installed, either change the version before building or uninstall the released copy first. Otherwise, a local build may overwrite or replace the installed application and its system integrations.

release/
├── Driftleaf-<version>.AppImage
├── driftleaf_<version>_amd64.deb
├── driftleaf-<version>-1.x86_64.rpm
└── Driftleaf Setup <version>.exe

Platform-Specific Requirements

Runtime Dependencies (Declared in Package Metadata)

These are automatically added to your package's dependency list but good to know for testing:

AppImage Exception: Most dependencies are bundled inside the AppImage. However, FUSE3 may be required at runtime on some distributions (sudo apt install libfuse2 for legacy support).

Cross-Architecture Builds

ARM64 Builds from x86_64

Building ARM64 packages without native hardware requires QEMU emulation:

# Enable QEMU binfmt support (one-time per host)
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Build ARM64 packages
npm run package:linux:arm64

Important Notes

Alternative: OBS/Copr Hosting

For ongoing ARM64 builds without local hardware, we use remote build systems:

• OBS (openSUSE Build Service):
• Copr (Fedora):

These handle multi-architecture builds automatically. See PACKAGING.md for spec file details.

Troubleshooting

Common Issues

"Command 'dpkg' not found" (on non-Debian systems)

# Arch/Fedora/openSUSE
sudo <package-manager> install dpkg

"Command 'fpm' not found"

Don't worry—electron-builder bundles its own fpm. Make sure Ruby is installed on your host system.

"Permission denied" on AppImage

chmod +x dist/Driftleaf-*.AppImage
./release/Driftleaf-*.AppImage

QEMU errors during ARM64 build

Make sure binfmt support is active:

# Check if QEMU is registered
cat /proc/sys/fs/binfmt_misc/qemu-aarch64

# Re-register if missing
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Deb/RPM build fails on directory ownership

If you see "directories not owned by package" errors, check your %files section includes %dir declarations for parent directories. See the OBS build logs for details.

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

See CONTRIBUTING.md for full guidelines.

Resources

• Electron Builder Docs
• Electron Docs
• React Docs
• Vite Docs
• TypeScript Handbook