updater.h

 
 
 
/* !!!!!!!!!!!!!!!! THIS FILE IS AUTOGENERATED !!!!!!!!!!!!!!!! */
 
 }; }
 *     AFuture<void> downloadUpdateImpl(const APath& unpackedUpdateDir) override { return async { /* stub */ }; }
 * };
 * 
 * AUI_ENTRY {
 *     auto updater = _new<MyUpdater>();
 *     updater->handleStartup(args);
 * 
 *     // your program routines (i.e., open a window)
 *     _new<MainWindow>(updater)->show();
 *     return 0;
 * }
 * @endcode
 * 
 * 
 * You can pass updater instance to your window (as shown in the example) and display update information from
 * `AUpdater::status` and perform the update when requested.
 * 
 * # Observing update progress
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L191"></b>
 * 
 * @copydetails AUpdater::status
 * 
 * # Update process
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L195"></b>
 * 
 * ## Checking for updates
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L197"></b>
 * 
 * AUpdater expects @ref AUpdater::checkForUpdates to be called to check for updates. It can be called once per some
 * period of time. It calls user-defined @ref AUpdater::checkForUpdatesImpl to perform an update checking.
 * 
 * The update steps are reported by changing `AUpdater::status` property.
 * 
 * @msc
 * a[label = "Your App"],
 * u[label = "AUpdater", URL = "@ref AUpdater"];
 * a -> u [label = "handleStartup(...)", URL = "@ref AUpdater::handleStartup"];
 * a <- u [label = "status = AUpdater::StatusIdle", URL = "@ref AUpdater::StatusIdle"];
 * a <- u [label = "control flow"];
 * 
 * --- [label="App Normal Lifecycle"];
 * ...;
 * a -> u [label = "checkForUpdates()", URL = "@ref AUpdater::checkForUpdates"];
 * a <- u [label = "status = AUpdater::StatusCheckingForUpdates", URL = "@ref AUpdater::StatusCheckingForUpdates"];
 * a <- u [label = "control flow"];
 * u box u [label = "checkForUpdatesImpl()", URL = "@ref AUpdater::checkForUpdatesImpl"];
 * a <- u [label = "status = AUpdater::StatusIdle", URL = "@ref AUpdater::StatusIdle"];
 * 
 * ...;
 * --- [label="Update published"];
 * ...;
 * a -> u [label = "checkForUpdates()", URL = "@ref AUpdater::checkForUpdates"];
 * a <- u [label = "status = AUpdater::StatusCheckingForUpdates", URL = "@ref AUpdater::StatusCheckingForUpdates"];
 * a <- u [label = "control flow"];
 * u box u [label = "checkForUpdatesImpl()", URL = "@ref AUpdater::checkForUpdatesImpl"];
 * u box u [label = "update was found"];
 * a <- u [label = "status = AUpdater::StatusIdle", URL = "@ref AUpdater::StatusIdle"];
 * ...;
 * @endmsc
 * 
 * You might want to store update check results (i.e., download url) in your implementation of
 * @ref AUpdater::checkForUpdatesImpl so your @ref AUpdater::downloadUpdateImpl might reuse this information.
 * 
 * ## Downloading the update
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L234"></b>
 * 
 * When an update is found, your app should call @ref AUpdater::downloadUpdate to download and unpack the update. It is
 * up to you to decide when to download an update. If you wish, you can call @ref AUpdater::downloadUpdate in
 * @ref AUpdater::checkForUpdatesImpl to proceed to download process right after update was found (see
 * @ref UPDATER_WORKFLOWS for more information about update workflow decisions). It calls
 * user-defined @ref AUpdater::downloadUpdateImpl which might choose to call default
 * `AUpdater::downloadAndUnpack(<YOUR DOWNLOAD URL>, unpackedUpdateDir)`.
 * 
 * @msc
 * a[label = "Your App"],
 * u[label = "AUpdater", URL = "@ref AUpdater"];
 * ...;
 * a -> u [label = "downloadUpdate()", URL = "@ref AUpdater::downloadUpdate"];
 * a <- u [label = "status = AUpdater::StatusDownloading", URL = "@ref AUpdater::StatusDownloading"];
 * u box u [label = "downloadUpdateImpl()", URL = "@ref AUpdater::downloadUpdateImpl"];
 * a <- u [label = "status = AUpdater::StatusWaitingForApplyAndRestart", URL = "@ref AUpdater::StatusWaitingForApplyAndRestart"];
 * --- [label="Your App Prompts User to Update"];
 * ...;
 * @endmsc
 * 
 * ## Applying (deploying) the update
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L255"></b>
 * 
 * At this moment, AUpdater waits @ref AUpdater::applyUpdateAndRestart to be called. When
 * @ref AUpdater::applyUpdateAndRestart is called (i.e., when user accepted update installation), AUpdater executes the
 * newer copy of your app downloaded before with a special command line argument which is handled by
 * @ref AUpdater::handleStartup in that executable. The initial app process is finished, closing your app window as
 * well. From now, your app is in "downtime" state, so we need to apply the update and reopen app back again as quickly
 * as possible. This action is required to perform update installation. The copy then replaces old application (where it
 * actually installed) with itself (that is, the downloaded, newer copy). After operation is complete, it passes the
 * control back to the updated application executable. At last, the newly updated application performs a cleanup after
 * update.
 * 
 * @msc
 * a[label = "Your App"],
 * u[label = "AUpdater", URL = "@ref AUpdater"],
 * da[label = "Newer Copy of Your App"],
 * du[label = "AUpdater in App Copy", URL = "@ref AUpdater"];
 * a :> u [label = "applyUpdateAndRestart()", URL = "@ref AUpdater::applyUpdateAndRestart"];
 * u :> da [label = "Execute with update arg"];
 * u box u [label = "exit(0)"];
 * a box u [label = "Process Finished"];
 * da box du [label = "Process Started"];
 * da -> du [label = "handleStartup", URL = "@ref AUpdater::handleStartup"];
 * du box du [label = "AUpdater::deployUpdate(...)", URL = "@ref AUpdater::deployUpdate"];
 * a <: du [label = "Execute"];
 * du box du [label = "exit(0)"];
 * da box du [label = "Process Finished"];
 * a box u [label = "Process Started"];
 * a -> u [label = "handleStartup", URL = "@ref AUpdater::handleStartup"];
 * u box u [label = "cleanup download dir"];
 * a box u [label="App Normal Lifecycle"];
 * ...;
 * @endmsc
 * 
 * After these operations complete, your app is running in its normal lifecycle.
 * 
 * AUpdater is an abstract class; it needs some functions to be implemented by you.
 * 
 * In this example, let's implement auto update from GitHub release pages.
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L298"></b>
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L299"></b>
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L300"></b>
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L301"></b>
 * @code{cpp}
 *    static constexpr auto LOG_TAG = "MyUpdater";
 *    class MyUpdater: public AUpdater {
 *    public:
 *        ~MyUpdater() override = default;
 * 
 *    protected:
 *        AFuture<void> checkForUpdatesImpl() override {
 *            return async {
 *                try {
 *                    auto githubLatestRelease = aui::updater::github::latestRelease("aui-framework", "example_app");
 *                    ALogger::info(LOG_TAG) << "Found latest release: " << githubLatestRelease.tag_name;
 *                    auto ourVersion = aui::updater::Semver::fromString(AUI_PP_STRINGIZE(AUI_CMAKE_PROJECT_VERSION));
 *                    auto theirVersion = aui::updater::Semver::fromString(githubLatestRelease.tag_name);
 * 
 *                    if (theirVersion <= ourVersion) {
 *                        getThread()->enqueue([] {
 *                          AMessageBox::show(
 *                              nullptr, "No updates found", "You are running the latest version.", AMessageBox::Icon::INFO);
 *                        });
 *                        return;
 *                    }
 *                    aui::updater::AppropriatePortablePackagePredicate predicate {};
 *                    auto it = ranges::find_if(
 *                        githubLatestRelease.assets, predicate, &aui::updater::github::LatestReleaseResponse::Asset::name);
 *                    if (it == ranges::end(githubLatestRelease.assets)) {
 *                        ALogger::warn(LOG_TAG)
 *                            << "Newer version was found but a package appropriate for your platform is not available. "
 *                               "Expected: "
 *                            << predicate.getQualifierDebug() << ", got: "
 *                            << (githubLatestRelease.assets |
 *                                ranges::view::transform(&aui::updater::github::LatestReleaseResponse::Asset::name));
 *                        return;
 *                    }
 *                    ALogger::info(LOG_TAG) << "To download: " << (mDownloadUrl = it->browser_download_url);
 * 
 *                    getThread()->enqueue([this, self = shared_from_this(), version = githubLatestRelease.tag_name] {
 *                        if (AMessageBox::show(
 *                                nullptr, "New version found!", "Found version: {}\n\nWould you like to update?"_format(version),
 *                                AMessageBox::Icon::INFO, AMessageBox::Button::YES_NO) != AMessageBox::ResultButton::YES) {
 *                            return;
 *                        }
 * 
 *                        downloadUpdate();
 *                    });
 * 
 *                } catch (const AException& e) {
 *                    ALogger::err(LOG_TAG) << "Can't check for updates: " << e;
 *                    getThread()->enqueue([] {
 *                        AMessageBox::show(
 *                            nullptr, "Oops!", "There is an error occurred while checking for updates. Please try again later.",
 *                            AMessageBox::Icon::CRITICAL);
 *                    });
 *                }
 *            };
 *        }
 * 
 *        AFuture<void> downloadUpdateImpl(const APath& unpackedUpdateDir) override {
 *            return async {
 *              try {
 *                  AUI_ASSERTX(!mDownloadUrl.empty(), "make a successful call to checkForUpdates first");
 *                  downloadAndUnpack(mDownloadUrl, unpackedUpdateDir);
 *                  reportReadyToApplyAndRestart(makeDefaultInstallationCmdline());
 *              } catch (const AException& e) {
 *                  ALogger::err(LOG_TAG) << "Can't check for updates: " << e;
 *                  getThread()->enqueue([] {
 *                    AMessageBox::show(
 *                        nullptr, "Oops!", "There is an error occurred while downloading update. Please try again later.",
 *                        AMessageBox::Icon::CRITICAL);
 *                  });
 *              }
 *            };
 *        }
 * 
 *    private:
 *        AString mDownloadUrl;
 *    };
 * @endcode
 * 
 * # Updater workflows {#UPDATER_WORKFLOWS}
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L397"></b>
 * When using AUpdater for your application, you need to consider several factors including usability, user experience,
 * system resources, and particular needs of your project.
 * 
 * Either way, you might want to implement a way to disable auto update feature in your application.
 * 
 * ## Prompt user on every step
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L403"></b>
 * 
 * This approach is implemented in AUI's @ref example_app_template.
 * 
 * The updater checks for updater periodically or upon user request and informs the user that an update is available.
 * The user then decides whether to proceed with update or not. If they agree the application will download and install
 * the update.
 * 
 * This way can be considered as better approach because the user may feel they control the situation and the
 * application never does things that user never asked to (trust concerns). On the other hand, such requirement of
 * additional user interaction to can distract them from doing their work, so these interactions should not be annoying.
 * 
 * You should not use AMessageBox (unless user explicitly asked to check for update) as it literally interrupts the
 * user's workflow, opting them to make a decision before they can continue their work. A great example of a bad auto
 * update implementation is qBittorrent client on Windows: hence this application typically launches on OS startup,
 * it checks for updates in background and pops the message box if update was found, **even if user is focused on
 * another application or away from keyboard**.
 * 
 * ## Silent download
 * <b aui-src="aui.updater/tests/UpdaterTest.cpp#L421"></b>
 * 
 * This approach is implemented in @ref example_app_auigram, as well as in official Qt-based Telegram Desktop client.
 * 
 * The updater silently downloads the update in the background while the user continues working within the application
 * or even other tasks. The update then is applied automatically upon restart.
 * Optionally, the application might show a button/message/notification bubble to restart and apply update.
 * 
 * Despite user trust concerns, this approach allows seamless experience - users don't need to be interrupted during
 * their work. They even might not care about updates.
 * 
 * 
 */

© 2025 AUI Framework Contributors. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. All trademarks are property of their respective owners.