Q4OS Application Install Howto

General recommendations for developers creating application installers for Q4OS

Overview

This guide provides comprehensive instructions and best practices for developers who want to create application installers for Q4OS. It covers the recommended installation methods, packaging standards, and deployment strategies that ensure compatibility with the Q4OS Trinity desktop environment.

Installation Methods

1. Debian Package Installation

The preferred method for installing applications on Q4OS is through Debian packages (.deb files). This ensures proper integration with the system package manager and dependency resolution.

Creating a .deb Package

# Basic package structure
your-application/
├── DEBIAN/
│   ├── control
│   ├── postinst
│   ├── prerm
│   └── postrm
├── usr/
│   ├── bin/
│   │   └── your-application
│   ├── share/
│   │   ├── applications/
│   │   │   └── your-application.desktop
│   │   ├── icons/
│   │   │   └── hicolor/
│   │   │       └── 48x48/apps/
│   │   │           └── your-application.png
│   │   └── doc/
│   │       └── your-application/
│   │           └── README
└── etc/
    └── your-application/
        └── config.conf

Control File Requirements

The DEBIAN/control file must include proper metadata:

Package: your-application
Version: 1.0.0
Section: utils
Priority: optional
Architecture: amd64
Depends: libc6 (>= 2.31), libqt5core5a (>= 5.15.0)
Maintainer: Your Name <your.email@example.com>
Description: Short description of your application
 Longer description that explains what your application does
 and its main features. This can span multiple lines.

2. AppImage Distribution

AppImage is a universal application format that works well on Q4OS. It provides a self-contained application that doesn't require system-level installation.

AppImage Best Practices

Include all required libraries within the AppImage
Test compatibility with Q4OS Trinity desktop
Provide a .desktop file for menu integration
Use AppImageLauncher for better user experience

3. Q4OS Software Centre Integration

For optimal user experience, consider integrating your application with the Q4OS Software Centre:

Desktop Integration

Menu Entry (.desktop file)

Create a proper .desktop file for Trinity desktop menu integration:

[Desktop Entry]
Version=1.0
Type=Application
Name=Your Application
Comment=Short description of your application
Exec=/usr/bin/your-application
Icon=your-application
Categories=Utility;
Terminal=false
StartupNotify=true
MimeType=application/x-your-format;

Icon Guidelines

Provide icons in standard sizes: 16x16, 22x22, 32x32, 48x48, 64x64, 128x128
Use PNG format for better compatibility
Follow the FreeDesktop icon naming specification
Consider the Waterleaf icon theme for consistency

Dependencies and Requirements

System Requirements

Target Debian Bookworm (12) as the base system
Ensure compatibility with Trinity Desktop Environment
Test on both 32-bit and 64-bit architectures if applicable
Consider ARM support for Raspberry Pi installations

Common Dependencies

Most Q4OS applications will depend on these core packages:

libc6 - Standard C library
libqt5core5a - Qt5 core libraries (for Qt applications)
libgtk-3-0 - GTK3 libraries (for GTK applications)
libtqt3-mt - Trinity Qt libraries (for Trinity-native apps)

Installation Scripts

Post-installation Script (postinst)

#!/bin/bash
set -e

# Update desktop database
if command -v update-desktop-database > /dev/null 2>&1; then
    update-desktop-database /usr/share/applications
fi

# Update icon cache
if command -v gtk-update-icon-cache > /dev/null 2>&1; then
    gtk-update-icon-cache /usr/share/icons/hicolor
fi

# Update MIME database
if command -v update-mime-database > /dev/null 2>&1; then
    update-mime-database /usr/share/mime
fi

exit 0

Pre-removal Script (prerm)

#!/bin/bash
set -e

# Stop any running services
if systemctl is-active --quiet your-application; then
    systemctl stop your-application
fi

exit 0

Testing and Quality Assurance

Testing Checklist

Test installation and removal processes
Verify menu integration in Trinity desktop
Check icon display in various contexts
Test application startup and basic functionality
Verify file associations work correctly
Test on clean Q4OS installation
Check compatibility with different Q4OS versions

Performance Considerations

Optimize for older hardware that Q4OS often runs on
Minimize memory usage and startup time
Consider resource constraints on single-board computers
Test performance on ARM devices if supporting them

Distribution and Maintenance

Version Management

Use semantic versioning (MAJOR.MINOR.PATCH)
Maintain changelog for each release
Provide upgrade paths for existing installations
Test upgrade procedures thoroughly

Support and Documentation

Provide clear installation instructions
Include troubleshooting information
Document any Q4OS-specific configuration
Maintain compatibility notes for different Q4OS versions

Security Best Practices

Package Signing

Sign your packages with GPG for verification
Provide public key for package verification
Use secure download channels (HTTPS)

Permissions and Security

Follow principle of least privilege
Avoid requiring root permissions unnecessarily
Store user data in appropriate directories
Respect system security policies

Community and Resources

Getting Help

Q4OS Community Forum for development questions
Trinity Desktop documentation for TDE-specific features
Debian packaging guidelines for technical details
Q4OS development mailing list for announcements

Contributing Back

Consider contributing applications to Q4OS repositories
Share packaging scripts and tools with community
Report bugs and suggest improvements
Help maintain compatibility with new Q4OS releases