Generating Release Installers

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 in packaging/artwork with your own mod specific versions. Right now these include your mod icon in several different resolutions (which are assembled into multi-resolution OS-specific icon formats by the packaging scripts) and the macOS disk image "installer" background image.
3. Identify and fix any errors that are detected by the automated checks on the "Actions" tab of your GitHub repository.

Automatic installer creation

The default configuration included with the Mod SDK will generate installers for your platform using the same GitHub 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 GitHub. 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 Actions tab and watch the build progress for the "Release Packaging" action. If it fails, then you will need to fix the reported issue and then create a new release. When the installer creation has completed, GitHub 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. This requires access to both a Linux or macOS machine, so is not recommended.

• 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 ~. Running this command on a Linux machine will create the Windows installer and Linux AppImage, and running it on macOS will create the macOS disk images.