Release builder script

Background

In the KSP mod development one of the most boring tasks is the release archive building and releasing. A new binary needs to be build, all the files need to be organized into a specific structure, and, eventually, all these files need to be archived. Not to mention the version control problem: you need to adjust files inside the archive and rename the archive according to the version number.

This script solves most of the problems! Thru a .json file you define the files needed for release, and then just run the script. It automatically builds the new binaries, updates the KSPAddonVersionChecker file if any, and packs the files into a properly named archive.

As an example, see configuration for KIS.

Running script

Prerequisites

• Ensure your system can execute Python 2.7+ scripts.
  • Get the Python download from here: https://www.python.org/download/releases/2.7/.
• Copy the release script file KspReleaseBuilder.py into your tool's location. It's usually a location within the mod's repository (e.g. /Tools).
• Prepare a shell script that will invoke compiler and build the binary:
  • You may use template_make_binary.cmd as a template.
• Setup the project settings via JSON file:
  • You may use release_setup_template.json as a template for your project settings. Note that it won't load as-is. You need to remove the comments from it first.
  • The required fields to be adjusted are: PACKAGE_NAME and SHELL_COMPILE_BINARY_SCRIPT. All the other fields may be left unchanged, and the standard mod will be built in this case.
• Setup the project from the Python code:
  • Implement method SetupBuildVariables in module KspReleaseBuilder.py. This method must adjust the fields in the provided builder instance.
  • The required fields to be adjusted are: PACKAGE_NAME and SHELL_COMPILE_BINARY_SCRIPT. All the other fields may be left unchanged, and the standard mod will be built in this case.

Examples of running the script

Building from the standard settings file

Usually the mod has just one release configuration. In this case the settings may be setup thru a JSON file with the hardcoded name release_setup.json. Then, a short syntax can be used to invoke the building script.

When the script and the JSON file live in the different directories:

d:
cd \ksp-mods\MyMod\Source
c:\myscripts\ksp\KspReleaseBuilder.py -J

When the script and the JSON file live in the same directory, it's even more simple:

d:
cd \ksp-mods\MyMod\Tools
KspReleaseBuilder.py -J

Building from a specific JSON file

When the project has multiple configs in the same directory, the required file may be defined via an argument:

KspReleaseBuilder.py -j d:\ksp-mods\MyMod\Tools\my_settings.json

Building via code

When the configuration logic is too complex to define it via a JSON, a Python code can be used to implement the logic. The configuration code should be declared in KspReleaseBuilder.py module in method SetupBuildVariables:

def SetupBuildVariables(builder):
  builder.PACKAGE_NAME = 'MyMod'
  builder.SHELL_COMPILE_BINARY_SCRIPT = 'build_binary.cmd'
  # Setup other fields...

Then, just invoke the script like this:

KspReleaseBuilder.py -c

Making a ZIP package

To instruct the script creating a ZIP package, add the argument -p

KspReleaseBuilder.py -J -p

By default, the script doesn't overwrite an existing package. If you need to overwrite itm either drop the old version manually or ask the script doing it via an argument:

KspReleaseBuilder.py -J -p -o

JSON settings

The JSON settings file allows setting and overriding values of almost all the public fields of the builder. It's the most convenient and highly recommended way to define the builds. Unless you need it dynamic, of course.

Schema version

From version to version the meaning and availability of the settings may change:

• The old settings may change their behavior and effect.
• New settings may be introduced.
• Some old settings may get removed.

To mitigate the incompatibility issues, every JSON file must have a special field JSON_SCHEMA_VERSION. The release script will use this information to determine if it can handle the settings. The version numbering agreement is the following:

• MAJOR number changes when an incompatible change is made. A script that handles schema version 2.0 will not be able to work with schema 1.x or 3.x.
• MINOR number changes when a backward compatible change was introduced. A script that handles schema version 1.2 will be able to also handle versions 1.0 and 1.1, but not 1.3 or higher.

To obtain the supported schema version run:

KspReleaseBuilder.py --version

Schema settings

Depending on the schema version, different configuration options are available. See the help on a specific version below:

• Version 1.0
• Version 1.1

Using older versions

It's usually better to always have the latest version of the script, and update the settings to the new schema version as needed. However, you may decide not to upgrade the settings and get the last compatible version instead. Use the table below to find the compatible script version.

Schema version	Script version	Latest version
1.0	2.0	Link
1.1	2.1+	Link

Code settings

See comments in the source of KspReleaseBuilder.py. Do not access or change private fields or methods of the builder.

Also, note that upgrading to the new version of the script will not be as easy as if you used JSON settings.

Standard folder structure

The release script can work with almost any setup, but if your mod source files are organized in a standard way, then you may use the template JSON file with little or no changes. Here is how usual source structure looks like:

• \ - project root.
  • Optional. README.md or README.txt files that describe the mod.
  • Optional. LICENSE.md or LICENSE.txt files that describe the mod's license.
  • Optional. Binaries - various third-party libraries needed for the mod (e.g. MiniAVC).
  • Optional. Deps - mods that are required for your mod to run. They are usually of a minimum version that let your mod to load. You have to explicitly instruct the users that they need installing the fresh versions of these mods. Note that when using CKAN these dependent mods will be ignored, and CKAN will install the dependencies based on the .netkan configuration.
  • Optional. PluginData - mod configs that don't need to be indexed by the game.
  • Optional. Parts - part definitions.
  • Optional. Patches - ModuleManager configs that update the game database.
  • Required. Source - C# sources.
  • Optional. Tools - folder for various tools like the release script.