Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:The troubleshooting and error handling system in SOFL is designed to assist both end-users and developers in identifying and resolving issues. It combines a comprehensive logging mechanism, user-friendly error dialogs, and specific checks for configuration, development, and packaging problems. This document outlines the key components of this system.
Logging System
The logging system is the primary tool for debugging application behavior. It is configured at startup to capture system information, application events, and errors, writing them to session-specific log files.
Sources: sofl/main.py:120-123, sofl/logging/setup.py, sofl/logging/session_file_handler.py
Initialization
Logging is one of the first systems initialized when the application starts. The setup_logging() function is called, which in turn calls log_system_info() to record details about the user's environment.
Sources: sofl/main.py:121, sofl/logging/setup.py:100
The diagram below shows the logging setup flow.
Log Files
Logs are managed by the SessionFileHandler, which creates a new log file for each application session. This prevents logs from growing indefinitely and makes it easier to isolate issues from a specific run.
- Location: Log files are stored in the directory specified by
shared.log_dir. - Rotation: The system keeps a maximum of 5 log files (
MAX_LOG_FILES). Older files are compressed into.xzformat, and the oldest ones are deleted to save space. - Debug Info: The content of all current log files is aggregated and displayed in the "Debug Info" section of the "About" dialog, providing a convenient way for users to copy and share diagnostic information.
Sources: sofl/logging/session_file_handler.py:27-56, sofl/main.py:280-291
| File/Parameter | Description | Source |
|---|---|---|
shared.log_dir | The directory where log files are stored. | sofl/logging/setup.py:98 |
sofl.log | The log file for the current session. | sofl/logging/session_file_handler.py:28 |
sofl.log.1.xz, ... | Compressed log files from previous sessions. | sofl/logging/session_file_handler.py:46 |
MAX_LOG_FILES | The maximum number of log files to retain (default: 5). | sofl/logging/session_file_handler.py:19 |
User-Facing Errors
SOFL uses several UI patterns to communicate errors and warnings to the user without crashing.
Friendly Errors
The FriendlyError class is used for non-critical errors, such as a failure to download a game cover from SteamGridDB. These errors are intended to be displayed in a dialog to the user with a clear title and subtitle, allowing the application to continue running.
Sources: sofl/errors/friendly_error.py, sofl/preferences.py:291-294
The diagram below shows the class structure and an example sequence of its use.
Toasts and Dialogs
For immediate, less intrusive feedback, Adw.Toast notifications are used. For example, the InstallDialog uses toasts to confirm actions or report minor issues, such as an invalid file path. For more critical validation failures, Adw.MessageDialog is used to ensure the user acknowledges the issue.
Sources: sofl/dialogs/install_dialog.py:202-205, sofl/details_dialog.py:202-207
Configuration Warnings
A common source of user error is incorrect configuration. The SOFLPreferences dialog has built-in validation for paths to game sources (e.g., Steam, Lutris).
If a configured directory for a game source cannot be found or is invalid, a UnresolvableLocationError is caught. In response, the UI displays a warning icon next to the invalid path, prompting the user to select a valid directory.
Sources: sofl/preferences.py:488-535
This flow is illustrated below:
Development and Packaging Troubleshooting
Specific tools and scripts are provided to help developers and packagers troubleshoot issues.
Development Script (dev.sh)
The ./scripts/dev.sh script is a helper for setting up a local development environment. It includes checks for required binaries and can automatically set up, build, and install the application.
- The
require_binfunction checks if essential tools likemesonandblueprint-compilerare installed. - The
smartcommand automatically checks if a build or install is needed by comparing file timestamps, preventing unnecessary rebuilds.
Sources: scripts/dev.sh:56-62, 80-104, 204-229
Packaging
The packaging/README.md file provides commands to diagnose issues with Flatpak, Debian, and Arch Linux packages.
| Package Type | Command | Description |
|---|---|---|
| Flatpak | flatpak-builder --show-manifest org.badkiko.sofl.yml | Checks the Flatpak manifest for errors. |
| Debian | dpkg-checkbuilddeps | Checks for missing build dependencies. |
| Debian | lintian sofl_VERSION.deb | Lints the built .deb package for common issues. |
| Arch Linux | namcap PKGBUILD | Analyzes the PKGBUILD for errors and missing dependencies. |
Sources: packaging/README.md:163-181
Conclusion
SOFL's troubleshooting framework is multi-layered, addressing issues from initial setup to runtime operation. The logging system provides deep insights for developers, while user-facing dialogs and warnings guide users to correct configuration errors. Finally, dedicated scripts and documentation assist with resolving packaging and development environment problems, creating a robust system for maintaining application stability.