Linux AppImage / System Packaging
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Linux packaging for the SSA Consulta Rapida C++ project focuses on providing portable and system-native distribution methods for the application. The project is currently in the planning phase for Linux-specific artifacts, which will include target formats such as AppImage, tarball, or distribution-specific packages. This packaging effort is contingent upon the stability of the core logic and QML smoke tests within the Linux Continuous Integration (CI) environment.
Sources: packaging/linux/README.md:1-5, README.md:1-5
The application architecture supports Linux through a modular build system using CMake and Qt 6. It requires standard Linux libraries such as libsqlite3 and various Qt6 modules (Core, Gui, Qml, Quick). System-level integration involves handling command-line arguments for database paths and configuration directories, ensuring the application adheres to standard Linux filesystem hierarchies.
Sources: README.md:13-19, app/desktop/main.cpp:33-45
Build Requirements and Environment
To package the application for Linux, the build environment must satisfy several dependencies. The project utilizes CMake 3.24+ and the Ninja build generator.
System Dependencies
The following packages are required on a Debian-based system for building and subsequent packaging:
- Build Tools:
build-essential,cmake,ninja-build. - Database:
libsqlite3-dev. - Qt 6 Framework:
qt6-base-dev,qt6-declarative-dev,qml6-module-qtquick,qml6-module-qtquick-controls.
Sources: README.md:7-19
Build Configuration
The project uses CMakePresets.json to define standardized build configurations. Packaging typically utilizes the release preset to ensure optimizations are applied and debug symbols are handled appropriately.
The diagram shows how CMake presets transition from configuration to the final executable ready for packaging.
Sources: CMakePresets.json:15-28, CMakeLists.txt:100-103
Installation and Filesystem Integration
The CMakeLists.txt file defines the installation rules which serve as the foundation for creating an AppImage or a tarball.
| Target Type | Destination | Description |
|---|---|---|
| Runtime | bin | The primary executable ssa_consulta_rapida. |
| Bundle | . | The base directory for bundled resources. |
Sources: CMakeLists.txt:100-103
Application Paths
On Linux, the application manages its data and configuration through the AppPaths class. By default, it looks for configuration in a directory specified via the --config-dir argument, typically pointing to $HOME/.config/ssa-consulta-rapida-cpp.
Sources: README.md:41-43, src/platform/AppPaths.cpp:11-18
Execution and Argument Handling
The packaging must ensure that the application can be invoked with standard Linux command-line arguments. This is critical for portable formats like AppImage where the database path might be external to the image.
Command Line Options
The application entry point in main.cpp processes several options relevant to system execution:
| Option | Argument | Description |
|---|---|---|
--db | path | Explicit path to the SQLite database. |
--config-dir | path | Custom directory for preferences and logs. |
--project-root | path | Root directory used for calculating default paths. |
Sources: app/desktop/main.cpp:35-43, README.md:58-60
This flowchart illustrates the initialization sequence when the application is launched on a Linux system.
Sources: app/desktop/main.cpp:45-56
Packaging Workflow
The workflow for generating Linux artifacts follows the stabilization of core components. The process is integrated into the CMake build system.
- Preparation: Build the application using the
releasepreset:cmake --build --preset release. - Verification: Run the test suite via
ctest --preset releaseto ensure stability before bundling. - Deployment: Organize binaries and Qt dependencies. While
windeployqtis used for Windows, Linux packaging typically relies onlinuxdeployorlinuxdeployqt(not explicitly in source, but implied by AppImage target). - Artifact Generation: Create the target format (AppImage or tarball).
Sources: packaging/linux/README.md:1-5, README.md:37-40, CMakeLists.txt:105-131
Conclusion
Linux packaging for SSA Consulta Rapida C++ is designed to leverage the project's modular architecture and CMake-based build system. By requiring standard system libraries and providing flexible command-line configuration for database and path management, the application is prepared for distribution via portable formats like AppImage. The current focus remains on maintaining CI stability to ensure that these distribution artifacts are reliable across different Linux environments.