macOS Packaging & Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• packaging/macos/README.md
• README.md
• CMakeLists.txt
• CMakePresets.json
• app/desktop/main.cpp

The macOS packaging and deployment process for SSA Consulta Rapida Cpp focuses on creating a self-contained application bundle (.app) distributed as a compressed ZIP artifact. This process ensures that the C++20 and Qt 6/QML-based application is correctly compiled, validated via smoke tests, and packaged with a writable runtime environment for end-users.

Sources: packaging/macos/README.md:1-3, README.md:1-5

Build Configuration and Prerequisites

The project utilizes CMake and Ninja for its build system. On macOS, dependencies such as Qt 6, SQLite3, and the C++20 compiler are typically managed through Homebrew. The build process relies on CMake presets to differentiate between development and release environments.

Required Environment

To build and package the application on macOS, the following tools must be installed:

• CMake 3.24+
• Ninja
• Qt 6.6+ (Components: Core, Gui, Qml, Quick, QuickControls2, Sql, Test)
• SQLite3

Sources: README.md:7-16, CMakeLists.txt:1-11

Build Presets

The project defines specific configurations in CMakePresets.json to standardize the build environment.

Preset Name	Build Type	Purpose
dev	Debug	Local development and testing with full debug symbols.
release	Release	Optimized build intended for packaging and distribution.

Sources: CMakePresets.json:4-23

Application Bundle Structure

The macOS build target is configured to produce a standard macOS Bundle. The CMakeLists.txt file defines specific properties to ensure the bundle is recognized correctly by the operating system.

The diagram shows how CMake properties define the identity of the macOS application package.
Sources: CMakeLists.txt:88-100

Deployment Workflow

The deployment workflow for macOS follows a strict sequence of artifact generation and validation before a release is considered ready for publishing.

Step-by-Step Pipeline

1. Configure Release Preset: Initialize the build system using the release preset.
2. Build Release Artifact: Compile the source code into the .app bundle.
3. Validation (Smoke Tests):
   • Launch the app bundle with a writable runtime.
   • Execute QML smoke tests against a fixture database to verify startup and basic UI flow.
4. Final Packaging: Create a ZIP archive from the validated .app bundle.

Sources: packaging/macos/README.md:5-12

Automated Smoke Testing and Screenshots

The application includes specialized command-line arguments to facilitate automated validation during the packaging phase.

Option	Function
--smoke-exit-ms <ms>	Automatically exits the application after a specified duration.
--screenshot <path>	Grabs a window capture of the startup state and saves it to a file.
--open-preferences	Used with screenshotting to verify the preferences UI during smoke tests.

Sources: app/desktop/main.cpp:39-44, app/desktop/main.cpp:63-95

Execution in Local Environment

For testing purposes on macOS before final packaging, the application can be executed directly from the build directory. It requires a path to a valid SQLite database.

./build/dev/ssa_consulta_rapida.app/Contents/MacOS/ssa_consulta_rapida \
  --db /path/to/ssas.db

Sources: README.md:46-49

Summary

The macOS packaging system provides a structured path from source code to a distributable ZIP artifact. By leveraging CMake's MACOSX_BUNDLE capabilities and integrating automated smoke testing via command-line flags, the project ensures that the "SSA Consulta Rapida" application meets functional requirements before deployment.