Updating the Omnis runtime

Because Omnis uses a split installation model, updating your application can be more complicated than simply installing a new version.

When installing a new version, several requirements must be met:

  1. Files in program directory must be replaced with new ones
  2. Files in the application data directory must be updated for each user using the application
  3. On Windows, the version registered in Windows Installer should be updated

Topics

Updating the program directory

The simplest way to update files in the program directory is to build an installer with new files, then run it. However, you may want to create a more optimized system that only changes the files that change frequently, such as your libraries and string tables. It’s possible to build this solution directly in Omnis, but such a solution is outside the scope of this guide.

Updating the application data directory

Once the files in firstruninstall/ under the program directory are changed, you need to replace those files in the application data directory with current ones for each user.

If using one of the installer templates listed in the Installing the Omnis runtime guide, the application data directory for the user running the installer will be cleared and replaced with fresh files from firstruninstall/ by the installer.

However, you may be operating in a multi-user environment when multiple users share the same application. This may be as simple as a laptop with two macOS or Windows user accounts, or as massive as an enterprise-level Microsoft Terminal Services environment hosting dozens or hundred of users.

Consider a laptop with two users, Alice and Bob. Both run the Omnis app "Coffee Picker":
  1. Alice installs Coffee Picker 1.0 and does some work
  2. Later, Bob logs on a fires up Coffee Picker
    1. Omnis copies version 1.0 to Bob's application data directory
    2. Bob gets version 1.0 with the app comes up
    3. Bob and Alice both work in Coffee Picker 1.0 without a problem

Two weeks later, Alice receives a notice that Coffee Picker 2.0 is available.

  1. Alice downloads and runs the installer for Coffee Picker 2.0:
    1. The installer updates her program directory, then clears and pre-populates her application data directory with the version 2.0 files
    2. Alice opens Coffee Picker and works in version 2.0
  2. Later that day, Bob logs on to the laptop and fires up Coffee Picker
    1. Even though the program data is version 2.0, version 1.0 is still installed in his application data directory
    2. Bob fires up Coffee Picker and gets version 1.0 instead of 2.0

Application data update example

If you are working in a multi-user environment, using an in-app updater, or using an installer solution that doesn’t reset the application data directory, you might consider the app-loader project from Suran Systems.

app_loader.lbs will compare a simple build number between the program directory and the application data directory. If you update this build number each time you release a new version of your app, app_loader.lbs will ensure the current version is loaded each time a user launches your app.

You can also manually trigger an update from within Omnis. This works extremely well with a built-in updater to provide a “live” update to your application, updating your libraries to the current version without ever exiting Omnis.

If you don’t want to use the app_loader.lbs tool, you will need to find another mechanism to ensure ALL copies of your application data directory are updated when installing a new version of the app.

Updating Windows Installer

When a program is installed on Windows using Window Installer, the registry is updated to track that program. This tracking allows Windows to provide a list of installed programs under the Apps & Features control panel. Many installers, including Advanced Installer, can register an uninstaller with the program, thereby allowing the user to trigger an uninstall from this control panel.

Windows Installer tracks two key identifiers for each installed product—the ProductCode and the UpgradeCode.

UpgradeCode

The UpgradeCode is a unique identifier for your application regardless of version. This allows Windows to know that version 3.1 and 3.4.5 are the same product. The UpgradeCode should not change during the lifespan of an application unless you are releasing an independent version of the app.

ProductCode

The ProductCode is a unique identifier for your application at a specific version. Windows Installer can use the UpgradeCode and ProductCode to detect if an update to your application is being installed and ask how the user wants to proceed.

When updating your Omnis application, ensure a new ProductCode is generated, especially if the version number changes. An in-app update that does not run an installer might not change the ProductCode, but this can create a disconnect between the version installed and the version registered. In practice, this disconnect does not adversely affect the user, but can cause confusion and support tickets, hence it should be mentioned.

Published 28 April 2019 by Alex Clay