Building from Source

Building from Source

Guide for building EncodeForge from source code.

Overview

Build EncodeForge for:

• Custom modifications
• Development and testing
• Custom distributions
• Platform-specific optimizations

Prerequisites

Required Software

Java Development:

• Java 17+ JDK
• Maven 3.8+
• Git

Python Development:

• Python 3.8+
• pip
• Virtual environment

Build Tools:

• Windows: WiX Toolset (for MSI)
• macOS: Xcode Command Line Tools
• Linux: Build essentials, fakeroot

Platform-Specific Requirements

Windows:

• Windows 10+
• Visual Studio Build Tools
• WiX Toolset 3.11+

macOS:

• macOS 10.15+
• Xcode Command Line Tools
• Developer ID (for signing)

Linux:

• Ubuntu 18.04+ or equivalent
• Build essential packages
• dpkg-buildpackage or rpmbuild

Setup Development Environment

Clone Repository

git clone https://github.com/yourusername/encodeforge.git
cd encodeforge

Setup Java Project

cd EncodeForge

# Install dependencies
mvn clean install

# Verify build
mvn test

Setup Python Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-core.txt
pip install -r requirements-ai.txt

Building

Development Build

Run from IDE:

• Import Maven project
• Run MainApp.java

Run from Command Line:

mvn javafx:run

Production Build

Package JAR:

mvn clean package

Output: target/encodeforge-0.3.1.jar

Run JAR:

java -jar target/encodeforge-0.3.1.jar

Platform-Specific Builds

Windows

Build EXE Installer

# Activate Windows profile
mvn clean package -P windows-exe

# Output: target/dist/windows/EncodeForge-0.3.1.exe

Build MSI Installer

# Activate MSI profile
mvn clean package -P windows-msi

# Output: target/dist/windows/EncodeForge-0.3.1.msi

Requirements:

• WiX Toolset installed
• PATH includes WiX bin directory

Using Build Script

# Windows
.\EncodeForge\build.bat

# Or specify installer type
.\EncodeForge\build.bat --exe
.\EncodeForge\build.bat --msi

macOS

Build DMG Package

Intel (x64):

mvn clean package -P mac-dmg-x64

Apple Silicon (ARM64):

mvn clean package -P mac-dmg-arm64

Output: target/dist/mac/EncodeForge-0.3.1.dmg

Using Build Script

# macOS
./EncodeForge/build.sh

# Specify architecture
./EncodeForge/build.sh --arm64
./EncodeForge/build.sh --x64

Code Signing (Optional)

# Sign app bundle
codesign --deep --force --verify --verbose --sign "Developer ID Application: Your Name" EncodeForge.app

# Notarize
xcrun altool --notarize-app --primary-bundle-id "com.encodeforge.app" --username "your@email.com" --password "app-specific-password" --file EncodeForge.dmg

Linux

Build DEB Package

# Build DEB package
mvn clean package -P linux-deb

# Output: target/dist/linux/encodeforge-0.3.1.deb

Install:

sudo dpkg -i target/dist/linux/encodeforge-0.3.1.deb

Build RPM Package

# Build RPM package
mvn clean package -P linux-rpm

# Output: target/dist/linux/encodeforge-0.3.1.rpm

Install:

sudo rpm -i target/dist/linux/encodeforge-0.3.1.rpm

Using Build Script

# Linux
./EncodeForge/build.sh

# Or use Docker
cd docker
./build-deb-docker.sh
./build-rpm-docker.sh

Docker Builds

DEB Package in Docker

cd docker
./build-deb-docker.sh

# Output: dist-deb/encodeforge_0.3.1-1_amd64.deb

RPM Package in Docker

cd docker
./build-rpm-docker.sh

# Output: dist-rpm/encodeforge-0.3.1-1.x86_64.rpm

Build Configuration

Maven Profiles

Configure in pom.xml:

Windows:

<profile>
    <id>windows-exe</id>
    <!-- Windows EXE configuration -->
</profile>

macOS:

<profile>
    <id>mac-dmg-x64</id>
    <!-- macOS DMG configuration -->
</profile>

Linux:

<profile>
    <id>linux-deb</id>
    <!-- Linux DEB configuration -->
</profile>

jpackage Configuration

Configure native installers:

<plugin>
    <groupId>org.panteleyev</groupId>
    <artifactId>jpackage-maven-plugin</artifactId>
    <configuration>
        <name>EncodeForge</name>
        <appVersion>${project.version}</appVersion>
        <vendor>EncodeForge</vendor>
        <!-- Platform-specific config -->
    </configuration>
</plugin>

Customization

Change Application Name

Edit pom.xml:

<name>Your App Name</name>

Edit MainApp.java:

private static final String APP_TITLE = "Your App Name";

Change Version

Edit pom.xml:

<version>1.0.0</version>

Custom Icons

Replace icon files:

• src/main/resources/icons/app-icon.png
• src/main/resources/icons/app-icon.ico

Update in pom.xml:

<icon>src/main/resources/icons/app-icon.png</icon>

Bundle Python Runtime

Option 1: Download on First Launch (Current)

• No changes needed
• Downloads FFmpeg and Python on first run

Option 2: Bundle with Application

• Modify build scripts
• Include Python runtime in package
• Larger installer size

Troubleshooting

Common Build Issues

Issue: "jpackage not found"

• Solution: Ensure Java 17+ JDK includes jpackage

Issue: "WiX not found" (Windows)

• Solution: Install WiX Toolset, add to PATH

Issue: "Command line too long" (Windows)

• Solution: Enable long path support in Windows

Issue: "Permission denied" (Linux)

• Solution: Use sudo for system installations

Issue: "Xcode not found" (macOS)

• Solution: Install Xcode Command Line Tools:

  xcode-select --install

Build Errors

FFmpeg detection fails:

• Ensure FFmpeg is installed
• Set FFMPEG_PATH environment variable

Python dependencies fail:

• Use virtual environment
• Install from requirements.txt

Maven build fails:

• Clear Maven cache: mvn clean
• Delete target/ directory
• Run: mvn clean install

Verifying Build

Test Installation

Windows:

# Install EXE
EncodeForge-0.3.1.exe

# Run from installed location
"C:\Program Files\EncodeForge\EncodeForge.exe"

macOS:

# Install DMG
open EncodeForge-0.3.1.dmg
# Drag to Applications

# Run
open /Applications/EncodeForge.app

Linux:

# Install DEB
sudo dpkg -i encodeforge-0.3.1.deb

# Run
encodeforge

Test Functionality

1. Launch application
2. Check FFmpeg detection
3. Test each mode (Encoder, Subtitle, Metadata)
4. Verify settings save/load
5. Check logs for errors

Distribution

Creating Release

Tag version:

git tag -a v0.3.1 -m "Release 0.3.1"
git push origin v0.3.1

Create release:

1. Go to GitHub Releases
2. Click "Draft new release"
3. Select tag
4. Upload installers
5. Add release notes
6. Publish

Release Checklist

• All tests pass
• Version updated
• Changelog updated
• Documentation updated
• Builds successful for all platforms
• Installers tested
• Release notes prepared
• GitHub release created

Advanced Topics

Incremental Builds

# Build only changed modules
mvn install -DskipTests

# Skip tests for faster builds
mvn package -DskipTests

Cross-Platform Builds

Linux-only:

• Build Linux packages

macOS-only:

• Build macOS DMG

Windows-only:

• Build Windows installers

Note: Cross-compilation not supported. Build on target platform.

Automated Builds

GitHub Actions:

# .github/workflows/build.yml
name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [windows-latest, macos-latest, ubuntu-latest]
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: mvn clean package

Resources

• jpackage Documentation
• Maven Documentation
• WiX Documentation

---

Ready to build? Follow the steps for your platform!