==============
* 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
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>
+
+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 <Archive> 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 <Archive>-tag that you are keeping.
+
+Make sure you include an archive that contains (part of) your GPG directory:
+<ArchiveSource name="updatekeys.zip">
+ <Platform os="all" cpu="all">
+ <Files buildbase="mygpg" zipbase="aurora-gpg">
+ gpg.conf
+ pubring.gpg
+ </Files>
+ </Platform>
+</ArchiveSource>
+
+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):
+<AuroraInfo>
+ <!-- Version Numbers
+ version="..." human readable version number (not used by program,
+ for display)
+ mrv="..." machine readable (ASCII sort-algo used for comparison),
+ this one is used to determine if a new version is available for
+ update
+ -->
+ <CurrentVersion version="2.0.1" mrv="020001"/>
+
+ <!-- Settings used by Aurora
+ baseurl - the directory on the web server where the index file and
+ the archives are found
+ indexfile - the name of the index file, make sure this differes from
+ this files name and it is not used by the program already,
+ the signature is expected in a file with ".asc" appended
+ pollinterval - the interval in seconds in which the application
+ will poll for updates, make this a useful value, e.g. 1800 means 30minutes
+ fulltargetdir - a local directory that will receive a copy of the content
+ of all generated archives and the index file - you can use this for
+ testing purposes
+
+ baseurl, indexfile, pollinterval are copied to step 2) and 3)
+ -->
+ <Settings
+ baseurl="http://www.example.com/myprogram"
+ indexfile="myindex.xml"
+ pollinterval="1800"
+ fulltargetdir="dist-*"/>
+
+ <!-- source specs for archives
+ name - the file name of the archive, if a * appears it is replaced by
+ the OS/CPU spec (e.g. "linux-x86") for the local platform when building
+ buildbase - the directory in which to look for files, this attribute is
+ valid here, in Platform, and Files;
+ instead of a relative (to this file) or absolute path you can specify
+ a program to determine the path, e.g. this will give you the Qt root dir:
+ buildbase="|qmake -query QT_INSTALL_PREFIX"
+ zipbase - the directory inside the archive file, or in the final installation,
+ this must be a relative path
+
+ These tags are not copied to 2/3, instead <Archive> tags are generated
+ -->
+ <ArchiveSource name="myprogram-*.zip" buildbase="bin">
+ <!-- list of files or file patterns for one platform
+ os="..." - operating system,
+ valid: "linux", "windows", "any", "all"
+ any=same for all OS, separate archive files
+ all=same for all OS, just one archive file for all of them
+ the default is "any"
+ cpu="..." - the CPU type this platform refers to,
+ valid: "x86", "x86-64", "any", "all"
+ any=same for all CPUs, separate archive files
+ all=same for all CPUs, just one archive file for all of them
+ default "any"
+ buildbase/zipbase - see above,
+ if one is specified here it is appended to the one from
+ above
+ -->
+ <Platform os="linux">
+ <!-- some files to include:
+ exclude - an optional pattern that tells instgen which files
+ never to include, even if they match an individual pattern
+ buildbase/zipbase - see above
+
+ The content of this tag: every non-empty line is a file name
+ or pattern that is searched in the current buildbase directory
+ and included below zipbase in the archive.
+
+ Note on patterns: they are similar, but not identical to real
+ shell patterns. The wildcards "?" and "*" can also match
+ directory separators.
+ -->
+ <Files exclude="*.debug">
+ myprogram
+ gpg
+ lib*.so*
+ </Files>
+ </Platform>
+ <Platform os="windows">
+ <Files>
+ *.exe
+ elam.dll
+ Aurora.dll
+ QtTz*.dll
+ QtZip*.dll
+ </Files>
+ </Platform>
+ </ArchiveSource>
+
+ <!-- example from above: you should have this or the program will
+ not be able to verify updates -->
+ <ArchiveSource name="updatekeys.zip">
+ <Platform os="all" cpu="all">
+ <Files buildbase="mygpg" zipbase="aurora-gpg">
+ gpg.conf
+ pubring.gpg
+ </Files>
+ </Platform>
+ </ArchiveSource>
+</AuroraInfo>
+
+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
+<ArchiveSource> tags are not copied, however it generates <Archive> tags for
+each archive that it creates. E.g. on a 64bit Linux the above generates:
+
+<AuroraInfo>
+ <!-- Version Numbers, unchanged -->
+ <CurrentVersion version="2.0.1" mrv="020001"/>
+
+ <!-- additional buildDate, no fulltargetdir -->
+ <Settings baseurl="http://www.example.com/myprogram" indexfile="myindex.xml"
+ pollinterval="1800" buildDate="2013-01-22T13:56:32"/>
+
+ <Archive name="magicsmoke-linux-x86-64.zip" size="2833008" cpu="x86-64" os="linux"
+ sha256sum="b2e037f60c57f15f952cd826617a7ffb485a0203d38b977719d0700bfd887dfa">
+ ./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
+ </Archive>
+
+
+ <Archive name="updatekeys.zip" size="1203" cpu="all" os="all"
+ sha256sum="66caecb9a29ce2ba4c66dde099af5205e1647b1086bbed976f54679962d5eb46">
+ aurora-gpg/gpg.conf
+ aurora-gpg/pubring.gpg
+ </Archive>
+</AuroraInfo>
+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.
projects / web/konrad/taurus.git / commitdiff