When supporting mods for Kerbal Space Program making a release archive is the most boring task. New binaries need to be build, all files need to be compiled into a specific file structure, and, eventually, it needs to be archived. Not to mention version control problem: you need to adjust several files and rename the archive.
This script solves the problem! Thru a .json
file you define the release files, and then just run the script. It will automatically
build new binaries, update version file (e.g. .version
), and pack the files into properly named archive.
Before using release script make sure to do the following:
- Update variable
SHELL_ZIP_BINARY
inmake_release.py
script to point to the right archiver.- Best candidate for the archiver is 7-Zip which is open source and free.
Download it from the official site. If you install it on drive
C:
into a default folder then no updates will be needed in the script.
- Best candidate for the archiver is 7-Zip which is open source and free.
Download it from the official site. If you install it on drive
- Update variable
BUILD_SCRIPT
inmake_release.py
script to point to the right batch script that builds your mod's binary in a release mode.- You may use template_make_binary.cmd as a template.
- Update
release_setup.json
file.- At the very least you have to adjust
PACKAGE_NAME
value. - In case of your project doesn't fit definition "standard" you also need to adjust release structure.
- At the very least you have to adjust
Run script in the default mode to have it creating the release folders structure:
make_release.py
The structure will be created in folder DEST
relative to the current folder (which is usually the folder where the script is located).
In order to create a release archive provide option -p
:
make_release.py -p
Archive will be created in ARCHIVE_DEST
folder, which by default is a parent of the script's folder. The name of the archive
will consist of PACKAGE_NAME
and current mod's version grabbed from AssemblyInfo.cs
.
In case of the archive already exists the release script will fail to not overwrite previous version. If you're confident you want
overwriting then provide option -o
:
make_release.py -p -o
Release script can work with almost any setup but if your mod source files are organized in a standard way then you may use template
.json
file with little or no changes. Here is how usual source structure looks like:
\
- project root.- Optional.
README.md
orREADME.txt
files that describe the mod. - Optional.
LICENSE.md
orLICENSE.txt
files that describe mod's license. - Optional.
Binaries
- various third-party libraries needed for the mod (e.g.MiniAVC
). - Optional.
PluginData
- mod configs that don't need to be indexed by the game. - Optional.
Parts
- part definitions. - Optional.
Patches
-ModuleManager
configs that update game database. - Required.
Source
- C# sources. - Optional.
Tools
- folder for various tools like a release script.
- Optional.
Given your mod's structure is as above (not all folders/files need to be existing) you may use template
release_setup.json to make a release.
You only need to change release version in your AssemblyInfo.cs
file and run the script.
Default template will result in the following structure in <project root>/Release
:
GameData
{PACKAGE_NAME}
README.md
and/orREADME.txt
if there were ones in the project's root.LICENSE.md
and/orLICENSE.txt
if there were ones in the project's root.Parts
- will only exist if there are actual folders and files inside.Patches
- will only exist if there are actual folders and files inside.Plugins
- will have allDLL
,TXT
, andMD
files located inSource/Binaries
.{PACKAGE_NAME}.dll
- main mod's DLL.{PACKAGE_NAME}.version
- this file will be updated with the proper version information.PluginData
- will have all files and sub-folders from the source. Won't be created if no real content found.
Note that {PACKAGE_NAME}.version
file will also be updated in the source so what you could commit it back to Guthub.
By default script searches for file release_setup.json
. Once it's found all the setup data is loaded from it. This file is nothing
more but just a definition of values for the
KspReleaseBuilder.Builder
class instance.
To get more information about each setting read the docs in the source file. Below are described the most important settings.
Key | Description |
---|---|
PACKAGE_NAME |
It's a base name for anything: release folder, archive name, version file, etc. E.g. if you set it to "ABC" then resulted archive name will look like ABC_v1.2.3.zip . |
SRC |
Base folder for the "source" patterns (see STRUCTURE ). Normally it's a project's root. If release script lives in /Tools then relative path to the project's root is .. . |
DEST |
A path to the folder where release structure will be built (see STRUCTURE ). |
ARCHIVE_DEST |
A path to the folder where release archive will be stored. |
STRUCTURE |
It's a dictionary where key defines destination and value defines a list of source patterns. Destination is relative to {DEST}/GameData if key starts with / and relative to {DEST}/GameData/{PACKAGE_NAME} otheriwse. Source pattern is relative to SRC and by the syntax requirement must always start with either / or a pattern modifier (see below). When source patterns match nothing the destination folder is not created. |
Pattern is a usual Unix pathname pattern which allows matching files and folders againts the specified condition(s). In the simplest case pattern is just a path to the file or directory which matches exactly one entry.
If pattern matched a directory then the entire directory tree will be copied. E.g. pattern /test/folder
will copy directory
{SRC}/test/folder
and all its subfolders into {DEST}/{KEY}/folder
. A little change to this pattern will result in completely
different behavior: for pattern /test/folder/*
all files and directories from {SRC}/test/folder
will be copied into {DEST}/{KEY}
.
KerbalReleaseBuilder
supports modifiers that change pattern interpretation. Modifier is a first symbol of the patter:
-
/
means a regular pattern which must return at least one element. E.g. if pattern is/Source/*.asc
and nothing has matched then an error will be thrown. -
?
means a regular pattern which is not required to match anything. E.g. if pattern is?/Source/DISCLAIMER.md
and the file is not found then script reports it but doesn't abort. -
-
means it's a cleanup pattern. It will be applied against the destination, and everything that is found will be deleted. E.g. with destination{DEST}/Test
and pattern-Subfolders/*
the following files and folders will be deleted:{DEST}/Test/Subfolders/*
. Note thatSubfolders
directory will not be dropped in this case.If cleanup pattern matches a directory then the entire directory with all its content will be deleted. Macros are not expanded for the cleanup patterns.
When defining a value for pattern in STRUCTURE
defintion a macro substitution can be used. "Macro" is a name of
KspReleaseBuilder.Builder
field which is enclosed in {}
. There can be any number of macros in the pattern, they will be
handled right before accessing the filesystem. E.g. when version file is stored in a non-standard location the following pattern can
be used:
"/My/Custom/Location/{PACKAGE_NAME}.version"
Note that some values get initialized to the default values during JSON file loading (see
KspReleaseBuilder.Builder.SetupDefaultLayout
). So you may use them thru macros in STRUCTURE
definition:
"STRUCTURE" : {
"Plugins" : [
"{SRC_COMPILED_BINARY}",
"{SRC_REPOSITORY_VERSION_FILE}",
]
}