From ebe25da7addeeb1fe4a2bde9dc09b2b461011d06 Mon Sep 17 00:00:00 2001 From: Konrad Rosenbaum Date: Sun, 18 Aug 2013 21:38:52 +0200 Subject: [PATCH] enhanced README for Aurora --- aurora.pri | 4 +- aurora/README | 281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 279 insertions(+), 6 deletions(-) diff --git a/aurora.pri b/aurora.pri index f6b4b1a..648f15f 100644 --- a/aurora.pri +++ b/aurora.pri @@ -3,4 +3,6 @@ LIBS += -L$$PWD/lib -lAurora INCLUDEPATH += $$PWD/include/aurora -CONFIG += link_prl \ No newline at end of file +CONFIG += link_prl + +include ( $$PWD/zip.pri ) \ No newline at end of file diff --git a/aurora/README b/aurora/README index d6d1ac4..744a5a9 100644 --- a/aurora/README +++ b/aurora/README @@ -15,7 +15,7 @@ Requirements: ============== * Qt 5.x -* GnuPG/libassuan/GPGME (included as GIT submodules) +* GnuPG (included as GIT submodule) * GNU Autotools -> Linux: install the autotools packages autoconf and automake -> Windows: install MinGW and MSys @@ -36,16 +36,287 @@ Then build the actual Aurora library/generator: qmake && make For MinGW builds: do this in a normal cmd.exe shell, MSys may behave unexpectedly -For VC builds: if you somehow translated GPGME, this will work with your +For VC builds: GPG needs MinGW/MSys, the remainder will work with your favourite way of building Qt projects +Integrating into Projects +========================== + +In your project file include the aurora.pri file from the main directory of +Taurus. + +In your program add some code to this effect: + +#include + +Aurora updater=new Aurora(qApp->applicationDirPath()+"/myprogram.xml",this); +connect(updater,SIGNAL(newVersionAvailable(QString)),this,SLOT(updateReadyDownload(QString))); +connect(updater,SIGNAL(readyForInstallation()),this,SLOT(updaterReadyInstall())); +connect(updater,SIGNAL(installationFinished()),this,SLOT(updaterCompleted())); +connect(updater,SIGNAL(downloadFailed()),this,SLOT(updaterFailed())); +connect(updater,SIGNAL(installationFailed()),this,SLOT(updaterFailed())); + +The first parameter to the constructor should be the index file of your program +(see below). Aurora will put this file in the main directory of the program's +distribution - the code above assumes that the binary calling this constructor +is located in the root directory of the program - if it is not, you have to +correct the path. The file name must be the same index file specified in the +description file below. + +The slots have the following meaning: + +newVersionAvailable: Aurora has found a new program version online and has + validated its signature, the next step is to call updater->startDownload() + +readyForInstallation: the download is complete and successful, next step is + updater->startInstallation() + +downloadFailed: the download has somehow failed (file not found, checksum + is invalid, ...) + +installationFinished: the installation has finished successfully, you can + continue to work (unless your program relies on files that may have been + changed by the installation process, the binaries already in memory are + fine - they have been moved); the new version will be used when the program + is started next time + +installationFailed: the installation has failed for some reason (corrupt + archive, not enough space, etc.) and the old state has been restored + +Aurora also expects to find a directory named "aurora-gpg" in the root +directory which contains the public key and a minimal GPG configuration. Creating Packages ================== -Create a ZIP file that contains the entire program. For Aurora this includes -the following: +For Aurora you have to include the following files: libAurora.so* (or Aurora.dll) -gpg(.exe) (from gpg/bin/gpg(.exe)) +libQtZipHelper.so* (or QtZipHelper.dll) +gpg(.exe) +Plus all Qt dependencies (QtCore, QtXml, QtNetwork). + +Then create a description file and run it through instgen - it will create +ZIP files for each archive and it will create a test installation, which you +can ZIP or Tar and use for initial installations. See below for syntax. + + instgen myindex-source.xml + +Use of GPG +=========== + +Preparation +------------ + +Create a directory where you store your keys, I'll assume "mygpg" for the +example. + +Create your own key: gpg --homedir mygpg --gen-key + +Create a minimal gpg.conf file inside: +-gpg.conf- +trusted-key ABC1234567890DEF +batch +-end- + +Replace "ABC..." with the actual key ID of your new key, you have to use the +"long" key ID, which you can find using: + gpg --homedir mygpg --list-keys --keyid-format long + +You have to create a new "trusted-key" line every time you create a new +key that can sign packets and you should delete it if a key retires. In the +latter case you should also delete that key from this keyring (keep a copy +around): + gpg --homedir mygpg --export --armor ABC... >old-pubkey-backup.txt + gpg --homedir mygpg --export-secret-key --armor ABC... >old-seckey-backup.txt + gpg --homedir mygpg --delete-secret-and-public-key ABC... + +You should remove retired keys, so they are also removed from updated program +copies. + +Signing Packages +------------------ + +Once instgen is done you will end up with several archives and an index file. +If you build several platforms - each time you will have a separate and different +index file. You can merge them by copying the tags into one instance. +Each archive name should only appear once - so archives that are different for +different platforms should be disambiguated (using "*" in their names: see +below), while those that are identical on all platforms do not need this change. +Keep only one copy of identical files (os="all", cpu="all") and make sure you +keep the archive file matching the -tag that you are keeping. + +Make sure you include an archive that contains (part of) your GPG directory: + + + + gpg.conf + pubring.gpg + + + + +Once you have a complete index file, sign it: + gpg --no-batch --homedir mygpg --detach-sign --armor myindex.xml + +You will get a myindex.xml.asc file that is used by Aurora to verify that it is +downloading the correct update. + +Package Description Language +============================= + +Package Description Files are XML files that are used in three capacities: + +1) to describe how to package files +2) a generated (by instgen) version containing information about generated + archives, this is called the index file and is the one you should sign +3) a slightly enhanced version of 2) that is put into the installation + directory after a successful update + +The one you write manually to tell instgen how to create archives (in the +example above: myindex-source.xml): + + + + + + + + + + + + + + myprogram + gpg + lib*.so* + + + + + *.exe + elam.dll + Aurora.dll + QtTz*.dll + QtZip*.dll + + + + + + + + + gpg.conf + pubring.gpg + + + + + +The CurrentVersion and Settings tags are copied to the index file. During +step 2 instgen adds a buildDate="..." attribute to the CurrentVersion tag in +the index file with the current time as of the instgen run in it. The + tags are not copied, however it generates tags for +each archive that it creates. E.g. on a 64bit Linux the above generates: + + + + + + + + + + ./myprogram + ./gpg + ./libAurora.so + ./libAurora.so.1 + ./libAurora.so.1.0 + ./libAurora.so.1.0.0 + ./libQtTzData.so + ./libQtTzData.so.1 + ./libQtTzData.so.1.0 + ./libQtTzData.so.1.0.0 + ./libQtZipHelper.so + ./libQtZipHelper.so.1 + ./libQtZipHelper.so.1.0 + ./libQtZipHelper.so.1.0.0 + + + + + aurora-gpg/gpg.conf + aurora-gpg/pubring.gpg + + +Once your program picks up the update and installs it, the index file that is +copied into the root dir of the program gains an installDate attribute at the +Settings tag, but is otherwise identical to the above. -- 1.7.2.5