Promoting Updates

Create online installers to be able to promote updates to end users who install your product.

The following steps are needed to promote updates:

  1. Copy the updated content to the package directory.
  2. Increase the value of the <Version> element for the updated components in the package.xml file.
  3. Use the repogen tool to recreate the online repository with the updated contents and to generate the Updates.xml file in the root directory of the repository.
  4. Upload the repository to the web server.
  5. Use the binarycreator tool to create the installer.

Configuring Updates

The installer downloads the Updates.xml file on startup and compares the installed version with the version in the file. If the online version number in the file is greater than the local one, the installer displays it in the list of available updates.

Increase the value of the <Version> element for the component in the package.xml file.

Recreating Repositories

The easiest way to provide an update is to recreate the repository and upload it to the web server. For more information, see Creating Repositories.

Partially Updating Repositories

A full update of the whole repository might not be optimal if:

  • The repository is very large, as uploading would take a long time.
  • You want to deliver only the changed components.

Note: repogen recreates the 7zip archives each time it is being called. As 7zip stores the timestamps of the included files (which are moved or copied during this process), the SHA sum of each archive changes. SHA sums are used to verify the download of the archive and hence the SHA needs to match the 7zip. As the SHAs are stored in the Updates.xml file you will be forced to upload the full repository. This can be circumvented by using the --update option of repogen.

Creating Partial Updates

When recreating the online repository, use the --update parameter. It takes an existing repository as input and only changes the components that are specified as additional parameters. Only those SHA sums are changed in the global configuration as well.

Uploading Partial Updates

Upload the following items to the web server:

  • The component directory (usually something like com.vendor.product.updatedpart).
  • The global Updates.xml stored in the root directory of the online repository.

Note: The order of uploading items is very important. If you update the repository on a live server, first update the component and then Updates.xml. The package names include version numbers, and therefore, end users receive old packages until the new ones are fully uploaded.

Changing Repositories

To have the current update repository point to other repositories, edit the Updates.xml file in the current repository. You can add, replace, or remove repositories.

  <Repository action="..." OPTIONS />
  <Repository action="..." OPTIONS />

Adding Repositories

To update a repository, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

<Repository action="add" url="" name="user" password="password"
             displayname="Example Repository" />

url will be used as a base URL to resolve an Updates.xml file against. If url is itself relative, it will be resolved against the base URL of the current document.

displayname specifies how the repository should be named in the Settings page of the Maintenance Tool.

name and password optionally specify credentials for a protected repository.

Removing Repositories

To remove a repository, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

<Repository action="remove" url="" />

url must match exactly the URL that is to be removed.

Replacing Repositories

To replace one repository with another, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

<Repository action="replace" oldUrl=""
            newUrl="" name="user" password="password"
            displayname="New Example Repository" />

oldUrl must match exactly the URL that is to be replaced.

newUrl must match exactly the URL that it is replaced with.

Relocatable Repositories

Some projects contain multiple repositories. To create a relocatable set of repositories you should use relative paths.

So if the generic repository available at the address and Updates.xml contains <Repository> element with the following options:

<Repository action="add" url="../module" name="user" password="password"
             displayname="Module Repository" />

Then the resolved address of the added repository will be, so that the repository does not contain information about their absolute location.

If you want to change the address, you can simply copy a set of repositories as is. It is recommended to maintain the old generic repository for some time and replace the addresses as described above. You can also provide the updated installer with the new generic address.

You can use relative paths for the arguments url, oldUrl, and newUrl in the <Repository> element.

© 2021 The Qt Company Ltd. 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. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.