repository·main·Indexed 20 days ago
https://github.com/appimagecommunity/appimageupdateA tool for decentralized, efficient AppImage updates using delta updates. It utilizes information embedded in the AppImage's ISO 9660 descriptor to locate updates without a central repository. The project includes a GUI application, the appimageupdatetool CLI for describing and checking updates, and libappimageupdate for C++ integration via CMake. It also provides functionality to validate AppImage signatures using the SignatureValidator class.
The project consists of three main components:
AppImageUpdate: A GUI application used to update AppImages.appimagedetool: A command-line tool used to update AppImages (performs the same logic as the GUI).validate: A command-line tool used to validate the integrity of the signature built into an AppImage (this functionality is also built into the AppImageUpdate GUI).AppImageUpdate relies on Update information embedded directly within the AppImage. This information is stored in the ISO 9660 Volume Descriptor #1 field "Application Used" to allow for easy changes to download server locations without re-creating the entire file system inside the AppImage.
This embedded data tells the tool:
Because it uses delta updates, only the parts of the application that have changed are downloaded, making updates highly efficient.
To test AppImageUpdate, follow these steps:
linuxdeployqt).If you have the appimaged daemon installed, you can also perform updates via right-click in your application launcher.
# Example workflow (conceptual)
# 1. Download AppImageUpdate
# 2. chmod +x AppImageUpdate-x86_64.AppImage
# 3. ./AppImageUpdate-x86_64.AppImage
# 4. Select your target AppImage to update.You can use AppImageUpdate as a library in your own C++ projects. To integrate it using CMake:
add_subdirectory() pointing to the submodule path.libappimageupdate using target_link_libraries.Note: The project uses C++11. While public headers are designed to work with older C++ standards, it is recommended to use C++11 or newer. You generally do not need to manually set CMAKE_CXX_STANDARD or -std=c++11 as the library handles compatibility.
# Add the submodule
add_subdirectory(path/to/appimageupdate)
# Link your application
target_link_libraries(mytarget libappimageupdate)AppImageUpdate can use Pling services (such as AppImageHub or Pling.com) to find updates via the OCS v1 XML API (https://api.pling.com/ocs/v1/).
To use this provider, the update information component must follow this specific string format:
pling-v1-zsync|<content id>|<file name matching pattern>
The appimageupdatetool is a command-line utility used to describe, check for, or perform updates on AppImage files. It accepts an optional path to an AppImage as a positional argument.
appimageupdatetool [options...] [<path to AppImage>]If you use the --self-update flag, the tool does not take a path argument. Instead, it relies on the $APPIMAGE environment variable to identify the running AppImage to be updated.
0: Success (or no update available when using --check-for-update).1: General error or update available (when using --check-for-update).2: Error checking for changes or update process failure.appimageupdatetool [options...] [<path to AppImage>]When performing signature validation, the SignatureValidationResult object provides details about the outcome via the following methods:
type(): Returns a ResultType enum indicating the status:ResultType::SUCCESS: The signature is valid.ResultType::WARNING: The signature is valid, but there are non-critical issues.ResultType::ERROR: The signature validation failed.message(): Returns a std::string containing a human-readable description of the validation result or error.keyFingerprints(): Returns a std::vector<std::string> containing the fingerprints of the keys used during validation.The UpdatableAppImage class provides a programmatic interface for inspecting the properties and metadata of an AppImage file. It is used to extract information required for the update process, such as the file type, cryptographic signatures, and update information embedded within the image.
Key capabilities include:
#include "src/util/updatableappimage.h"
// Initialize with the path to the AppImage file
appimage::update::UpdatableAppImage appImage("/path/to/your/application.AppImage");
// Access metadata
std::string path = appImage.path();
int type = appImage.appImageType();
std::string signature = appImage.readSignature();
std::string updateInfo = appImage.readRawUpdateInformation();
std::string hash = appImage.calculateHash();The SignatureValidator class provides the primary interface for verifying the digital signatures of an UpdatableAppImage. You can use the validate() method to check the integrity and authenticity of an AppImage. The result is returned as a SignatureValidationResult object, which indicates whether the validation succeeded, produced a warning, or encountered an error.
#include "src/signing/signaturevalidator.h"
#include "util/updatableappimage.h"
// Assuming appImage is an instance of UpdatableAppImage
appimage::update::signing::SignatureValidator validator;
appimage::update::signing::SignatureValidationResult result = validator.validate(appImage);
if (result.type() == appimage::update::signing::SignatureValidationResult::ResultType::SUCCESS) {
// Signature is valid
} else {
// Handle error or warning using result.message()
}The appimage::update::qt::QtUpdater class is the primary interface for managing AppImage updates through the GUI.
new appimage::update::qt::QtUpdater(pathToAppImage). Calling .show() will launch the graphical interface.appimage::update::qt::QtUpdater::fromEnv() to initialize an updater for the tool itself. This relies on the $APPIMAGE environment variable being present.checkForUpdates(bool) can be called to check for available updates without launching the full UI. Passing true to the boolean parameter is used in the CLI mode.// Standard usage for a specific AppImage
appimage::update::qt::QtUpdater* updater = new appimage::update::qt::QtUpdater("/path/to/appimage");
updater->show();
// Self-update usage
appimage::update::qt::QtUpdater* updater = appimage::update::qt::QtUpdater::fromEnv();GpgError class is an exception thrown when underlying GPG (GNU Privacy Guard) operations fail. It wraps a gpg_error_t code and provides a descriptive error message via the standard what() method. When integrating with the signing API, you should be prepared to catch this exception to handle low-level cryptographic errors.The following command-line options and positional arguments are supported by the AppImageUpdate GUI entrypoint:
Options:
-v, --version Display version and exit.
-j, --check-for-update Check for update. Exits with code 1 if changes are available, 0 if there are not, other non-zero code in case of errors.
--self-update Update the tool itself and exit.
Positional Arguments:
path Path to AppImage that should be updated <path>