git.sur5r.net Git - minitube/blob - lib/updater/README.md

   1 # An updater for Qt apps
   2
   3 This is an extensible updater for Qt apps. It can wrap [Sparkle](https://sparkle-project.org/) on macOS and use its own implementation on Windows and Linux. I use it in my apps at https://flavio.tordini.org .
   4
   5 ## Design
   6
   7 The main interface is [Updater](https://github.com/flaviotordini/updater/blob/master/src/updater.h). A shared Updater subclass instance should be set on startup using `Updater::setInstance()`. Available implementations are:
   8
   9 - [`updater::DefaultUpdater`](https://github.com/flaviotordini/updater/blob/master/src/impl/defaultupdater.h), the default Qt-based implementation.
  10
  11 - [`updater::SparkleUpdater`](https://github.com/flaviotordini/updater/blob/master/src/sparkle/sparkleupdater.h), a Sparkle-based implementation for macOS
  12
  13 ## User Interface
  14
  15 ### Built-in Widgets
  16
  17 Updater provides ready-to-use widgets:
  18
  19 - `Updater::getAction()` returns a QAction suitable to be inserted in a QMenu.
  20 - `Updater::getLabel()` returns a QLabel that automatically changes its message. Typically used in the about box.
  21 - `Updater::getButton()` returns a QPushButton that autohides or automatically changes its function depending on the Updater status.
  22
  23 When the user triggers the action or pushes the button a dialog will show which is dependent on the Updater implementation.
  24
  25 ## Entension Points
  26
  27 [updater::DefaultUpdater](https://github.com/flaviotordini/updater/blob/master/src/impl/defaultupdater.h) has a number of extension points so it can be adapted to different release manifest formats and update mechanisms.
  28
  29 ### Parser
  30
  31 Implement [updater::Parser](https://github.com/flaviotordini/updater/blob/master/src/impl/parser.h) to parse your own manifest format. There are two ready-to-use parsers:
  32
  33 - [updater::AppcastParser](https://github.com/flaviotordini/updater/blob/master/src/impl/appcastparser.h). This the appcast format also used by Sparkle. It's a RSS feed with Sparkle extensions.
  34 - [updater::SimpleXmlParser](https://github.com/flaviotordini/updater/blob/master/src/impl/simplexmlparser.h). This is a very simple XML format
  35
  36 Set the desired Parser implementation using `updater::DefaultUpdater::setParser`. The default is [updater::AppcastParser].
  37
  38 ### Installer
  39
  40 [updater::Installer](https://github.com/flaviotordini/updater/blob/master/src/impl/installer.h) is the abstraction responsible for preparing and running the update process. Currently the only available Installer implementation is [updater::RunInstaller](https://github.com/flaviotordini/updater/blob/master/src/impl/runinstaller.h). It just runs an executable update payload, optionally with arguments.
  41
  42 Installer can be implemented in other ways, for example an Installer that unzips a payload and moves files. Or one that invokes an update helper. Another idea is signature validation.
  43
  44 Set the desired Installer implementation using `updater::DefaultUpdater::setInstaller`. The default is [updater::RunInstaller].
  45
  46 ## Build Instructions
  47
  48 ### qmake
  49 ```
  50 mkdir build
  51 cd build
  52 qmake ..
  53 make
  54 ```
  55
  56 ## Integration
  57
  58 You can use this library as a git submodule. For example, add it to your project inside a lib subdirectory:
  59
  60 ```
  61 git submodule add -b master https://github.com/flaviotordini/updater lib/updater
  62 ```
  63
  64 Then you can update your git submodules like this:
  65
  66 ```
  67 git submodule update --init --recursive --remote
  68 ```
  69
  70 To integrate the library in your qmake based project just add this to your .pro file:
  71
  72 ```
  73 include(lib/updater/updater.pri)
  74 ```
  75
  76 qmake builds all object files in the same directory. In order to avoid filename clashes use:
  77
  78 ```
  79 CONFIG += object_parallel_to_source
  80 ```
  81
  82 ## Examples
  83
  84 Example setup of the shared Updater instance:
  85
  86 ```
  87 #include "updater.h"
  88 #ifdef UPDATER_SPARKLE
  89 #include "sparkleupdater.h"
  90 #else
  91 #include "defaultupdater.h"
  92 #endif
  93
  94 void setupUpdater() {
  95     #ifdef UPDATER_SPARKLE
  96         Updater::setInstance(new updater::SparkleUpdater());
  97     #else
  98         auto updater = new updater::DefaultUpdater();
  99         updater->setManifestUrl(myAppcastUrl);
 100         Updater::setInstance(updater);
 101     #endif
 102 }
 103 ```
 104
 105 Updater provides a QAction instance ready to be used in a menu.
 106
 107 ```
 108 myMenu->addAction(Updater::instance().getAction());
 109 ```
 110
 111 In the About box you can use the standard widgets provided by Updater. A QLabel and a QPushButton.
 112
 113 ```
 114 myLayout->addWidget(Updater::instance().getLabel());
 115 myLayout->addWidget(Updater::instance().getButton());
 116 ```
 117
 118 ## Security
 119
 120 Always serve your manifest files and binary updates via HTTPS.
 121
 122 ## License
 123
 124 You can use this library under the GPLv3 license terms. If you do, you're welcome contributing your changes and fixes. Donations are welcome at https://flavio.tordini.org/donate
 125
 126 For commercial projects I ask for a one-time license fee, contact me at flavio.tordini@gmail.com