Generating Release Installers

Paul Chote edited this page Jul 29, 2018 · 14 revisions

This page contains all the basic information, but could use some polish and simplifications. Please help us make it more understandable!

When you are ready to release your project, you can generate installers for your players. A standard NSIS installer package plus a "portable" zip file is created for Windows; a standard portable .app file is created for macOS, and a portable AppImage is created for wide Linux support.

Preparation

There are a few prerequisites that much be fulfilled before installers can be created:

  1. Read through and update the Packaging settings in your mod.config. These settings define how your mod integrates with the target operating system after installation. Make sure you have correctly defined PACKAGING_COPY_ENGINE_FILES: files that you reference from the default mods will not be available if they are not referenced here!
  2. Replace the Example Mod placeholder artwork with your own mod specific versions. Right now these include:
File Purpose Notes
packaging/windows/mod.ico Desktop/Start Menu/etc icon for Windows. Create a multi-resolution icon for best compatibility with modern Windows versions.
packaging/osx/mod.icns Application icon for macOS. Create a multi-resolution icon using iconutil on macOS for best compatibility.
packaging/linux/mod_*.png Application icons for Linux. Also include a vector mod_scalable.svg file for best compatibility with modern Linux versions.
  1. Follow the Travis CI Setup Guide to enable Travis CI integration for your mod.
  2. Identify and fix any errors that are detected by Travis CI for your mod (with TRAVIS_TEST_MOD enabled in your mod.config).
  3. Enable TRAVIS_TEST_PACKAGING in your mod.config and identify and fix any errors that are detected during packaging.

Automatic installer creation

The default configuration included with the Mod SDK will generate installers for your platform using the same Travis CI infrastructure that is used by the main OpenRA project. This makes it easy for you to create installers for all of our supported operating systems no matter which operating system you use yourself.

When you are ready to ship a new release you can generate the installers as follows:

  1. Make sure that you have followed the prerequisites above, and that your mod compiles and passes all tests.
  2. Open the main GitHub page for your mod and then click on the "Releases" link in the header above the file list. This will take you to your mod releases page, e.g. https://github.com/OpenRA/OpenRA/releases.
  3. If you are logged in to GitHub and have the appropriate permissions then you should see a "Draft a new release" button on the top right of the page. Click this.
  4. Fill in the form fields as follows:

    Tag Version: This defines the version that will be shown in-game and the installers. This could be a string like 0.5, alpha-3, or 20170721.
    Target: This defines the source code branch or commit that the release is based on. Most of the time this will be your master branch.
    Release title / Describe this release: A human-readable title and description for your release. This is not used by the installers, but is useful for people who want to view older releases of your mod. See https://github.com/OpenRA/OpenRA/releases for some examples if you need them.
    Attach binaries by...: You can use this section to associate any other files to the release web page, but they will be ignored by the installer generation. The generated installers will be automatically added to this section after the release has been submitted.
    This is a pre-release: This specified whether the releases page should add a "Pre-release" label to this release. It is not used by the installers.

    When you are ready, press the "Publish release" button to create the release. Behind the scenes, this creates a new git tag that is detected by Travis CI. If you are familiar with git, then you can push a tag directly to the repository instead of using the web interface.
  5. Go to your Travis CI dashboard (it has the same URL path as your GitHub repository, e.g. for https://github.com/OpenRA/OpenRA/ the Travis CI dashboard is at https://travis-ci.org/OpenRA/OpenRA) and watch the build progress. If it fails, then you will need to fix the reported issue and then create a new release (this is why we strongly recommend that you perform a dry run using TRAVIS_TEST_PACKAGING first. When the installer creation has completed, Travis CI will automatically copy them to the Release page that you created in the last step.

Manual builds

If you wish to manually build installers for testing or private release, then you can run the packaging scripts manually from a Linux or macOS machine.

  • Run ./packaging/package-all.sh <version tag> <path to output directory>. The version tag will be automatically written into your mod.yaml and installer filenames. For example, to compile an "alpha-1.0" release and save the output files to your home directory, you would run ./packaging/package-all.sh alpha-1.0 ~.

If you see the error error CS8001: Warning as Error: SDK path could not be resolved then it means that your distro's mono packages do not support creating portable builds. Follow the instructions on the Mono website to switch to the upstream Mono packages which include the required support files. Alternatively, you can modify your local copy of the packaging scripts to remove the -sdk:4.5 arguments, but please note that this will break compatibility for your users who want to play your mod on older versions of Mono and the .NET Framework.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.