Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
There are a few prerequisites that much be fulfilled before installers can be created:
- 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!
- Replace the Example Mod placeholder artwork with your own mod specific versions. Right now these include:
|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
|packaging/linux/mod_*.png||Application icons for Linux.||Also include a vector
- Follow the Travis CI Setup Guide to enable Travis CI integration for your mod.
- Identify and fix any errors that are detected by Travis CI for your mod (with
TRAVIS_TEST_MODenabled in your
mod.configand 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:
- Make sure that you have followed the prerequisites above, and that your mod compiles and passes all tests.
- 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.
- 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.
- 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
Target: This defines the source code branch or commit that the release is based on. Most of the time this will be your
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.
- 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_PACKAGINGfirst. When the installer creation has completed, Travis CI will automatically copy them to the Release page that you created in the last step.
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.
./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.