Packaging

Last revision: v6.4 - 26 April 2015

The omegalib runtime and modules can be packaged into a binary installer to simplify deployment and automate updates. Packaging is currently only supported on windows, with OSX/Linux support planned for version 7.0.

Packaging uses the Omegalib Maintenance Tools.

For this guide we assume you are working on local omegalib install called master. Before packaging a build of omegalib, make sre all your desired modules are installed, and you have built at least once in release mode.

• You can make sure you are up to date with your build doing

>omega build master

• Next, prepare your build for packaging:

> omega pack.prepare master

This command will copy all the installation files in a staging area (the install directory inside your omegalib root dir).

• You can now generate the installer binaries and repository packages:

> omega pack.build master

After this command completes, you will have an executable in the install irectory called OmegalibSetup.exe. This is the executable you will distribute. Note that the size of this file does not depend on which modules you are packaging: they will be downloaded by the user when they are selected during the installation process.

• Finally, you can publish your package repository:

> omega pack.publish master

This will publish the package to S3: the default repository target is s3://omegalib/repository/master. The first time you run this command, the maintenance tool will download the AWS command line utilities. You will need to manually set your public/secret access keys to be able to publish to your S3 bucket. For more information see http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html

Publishing to a custom repository

To publish a package repository to a custom S3 bucket, do the following:

• Make a copy of cmake/pack.publish (ie. pack.publish.custom)
• Edit pack.publish.custom and change the variable REPO_S3_URL to point to your S3 repository url
• Edit <omega root>/install/config/config-online.xml.in and set your repository public url in the RemoteRepositories section:

    <RemoteRepositories>
     <Repository>
             <Url>http://yourbucket.s3.amazonaws.com/your/url</Url>
             <Enabled>1</Enabled>
             <DisplayName>Main repository</DisplayName>
     </Repository>
    </RemoteRepositories>

• run omega pack.prepare, omega pack.build and omega pack.publish.custom on your omegalib root.

Setting up a Module for Packaging

If you want to package your own module, you need to add a pack.cmake file to its root directory. See https://github.com/omega-hub/cyclops/blob/master/pack.cmake for an example.

This file must contain CMake file INSTALL commands that will copy files for this package into the appropriate package directory.

If you want to package all the files in the module (useful for script modules), just add

pack_module_dir()

As the only command in pack.cmake.

In the installer, your package will have the description it uses in its hub module_def, and will have the same dependencies as entered in its CMakeLists.txt file.

Package Auto-Updating

You can enable package auto-updating by adding a module_version command in the CMakeFiles.txt file for your module. (see https://github.com/omega-hub/cyclops/blob/master/CMakeLists.txt). When you increase this number and republish your package, users with that package installed will be notified by the omegalib package manager, and will be able to download your updated module.

How does packaging work

The packager uses a set of cmake scripts, the Qt Installer Framework and the AWS command line tools. The general mechanism is the following:

• During a cmake configuration, each module that has a pack.cmake file is considered for packaging
  • The pack.cmake file is decorated with some information about the module (name, description, dependencies, version) and added to a global pack.cmake in <omega root>/install. This file also contains the packaging instructions for the omegalib core, as specified in <omega root>/src/pack.cmake
• When running pack.prepare this global pack.cmake file is executed. it will copy all the package files from the build directory into the <omega root>/install/packages directory (the staging area) and it will create a package manifest for each package. (the package manifest template is https://github.com/uic-evl/omegalib/blob/master/install/packages/core/meta/package.xml.in, the code that sets it up is https://github.com/uic-evl/omegalib/blob/master/src/pack.cmake#L3)
• When running pack.build the package manifests will be used by the Qt Installer Framework to get files from the staging area and generate individual packages, plus the installer binary
• When running pack.publish the AWS command line tools will be used to sync the local package repository (<omega root>/install/repository) with the online bucket.