search

KSPModdingLibs / KSPBuildTools

MIT License
2 stars 4 forks source link

readme

KSP Build Tools

This repository aims to provide a common set of tools for developing mods for Kerbal Space Program. Note that it's still in "alpha" stages so expect things to change or break.

To use it, either:

Most things in this repository will work best if you have a directory in your repository that corresponds to the directory that the user will install into GameData (or several such directories). Placing these into a GameData folder in your repository is recommended but not required.

While working on your mod, I recommend that you create a junction or symlink from the game's GameData folder pointing at the content folder in your repository. That way any changes you make will be immediately available, and you don't need to deploy or copy anything. If you'd like to see other workflows supported please ask!

Table of Contents

KSPCommon.targets

This is a msbuild targets file that you can include in your .csproj files.

What it does:

If not using a PackageReference, import KSPCommon.targets in your .csproj file after it imports Microsoft.CSharp.targets. You should remove ALL the existing assembly references to System, Assembly-CSharp, and Unity.

<Import Project="$(MSBuildToolsPath)/Microsoft.CSharp.targets" />
<Import Project="$(SolutionDir)KSPBuildTools/KSPCommon.targets" />

Here's an example from kOS.

Note that KSPCommon.targets makes use of KSPCommon.props for advanced users, which sets all the below properties but does not include the build targets. If you only want the properties and not the targets, you can use KSPCommon.props instead.

Versioning

MinVer is recommended for versioning mods. KSPCommon.targets will use the generated version correctly.

Customization

Properties can be customized at several points:

Canonical properties (committed to version control)

Per-User properties (not committed to version control)

You should have *.user files added to your .gitignore file.

The following properties are exposed to be customized per mod, project, or user. Properties that represent directories should not include a trailing slash.

RepoRootPath

Default value: $(SolutionDir)

This specifies the root directory of your mod repository. Generally you'll want to set this to be relative to $(SolutionDir).

BinariesOutputRelativePath

Default value: GameData\$(SolutionName)

This is the directory where compiled binaries should be copied. This is relative to the RepoRootPath. The binaries will be copied after each build.

KSPRoot

This property should be set to the root directory of your KSP install. If it is not specified, then KSPCommon.props will try some defaults:

CKANCompatibleVersions

Default value: 1.12 1.11 1.10 1.9 1.8

Used by the CKANInstall target to set additional KSP versions to treat as compatible when installing dependencies.

GenerateKSPAssemblyAttribute

If set to true, automatically generates the KSPAssembly for your assembly from the Version property.

GenerateKSPAssemblyDependencyAttributes

If set to true, automatically generates KSPAssemblyDependency attributes for each dependency. Dependencies should have either the CKANIdentifier metadata or KSPAssemblyName metadata. Versions can be supplied with CKANVersion or KSPAssemblyVersion. See Referencing Dependencies below.

Referencing Dependencies

Referencing assemblies (DLLs) from other mods should be done with a HintPath relative to $(KSPRoot). These should be placed after importing KSPCommon.targets so that $(KSPRoot) will be defined. In addition, you can include the CKAN identifier of the mod to make it installable when restoring the project. Dependencies should have the private flag set to false, unless they are intended to be included alongside the main dll.

Example from Shabby:

<ItemGroup>
    <Reference Include="0Harmony">
      <HintPath>$(KSPRoot)/GameData/000_Harmony/0Harmony.dll</HintPath>
      <CKANIdentifier>Harmony2</CKANIdentifier>
      <Private>false</Private>
    </Reference>
</ItemGroup>

Installing Dependencies

Dependencies are installed by the CKANInstall target, which automatically runs when the dotnet project is restored. Dependencies will be installed in $(KSPRoot).

Example usage:

msbuild -t:restore

Dependencies that get referenced in your assembly should be marked with its CKANIdentifier as shown above. If you want to install a dependency without referencing it, you can list it like so:

<ItemGroup>
    <CKANDependency Include="ModuleManager"/>
</ItemGroup>

update-version.sh

This is a bash shell script that can update version numbers in several text files (AssemblyInfo.cs, .version files, readme, etc). All it does is process files with a common extension and replaces certain tokens in them.

This file can be run from your own repository locally, and it's also used in some of the github actions and workflows. If you're already using git for windows, you have a bash shell that you can run this from.

Usage

update-version.sh [-g (true|false)] [-d (true|false)] VERSION_STRING TEMPLATE_EXTENSION [FILES]

Example:

update-version.sh 1.2.3.4 .vtxt AssemblyInfo.cs.vtxt

Example template files:

VERSION_STRING

Required. This is the new version you want to set, in MAJOR.MINOR.PATCH.BUILD form. Any of the values can be omitted (starting from the right).

TEMPLATE_EXTENSION

Optional. Default: .versiontemplate

This is a file extension that indicates which files the script should consider. When processing a file, if it ends with this extension then the script will store the output in a new file with the template extension removed. Otherwise the file is updated in-place.

FILES

Optional.

This is a list of files to process. If omitted, the script will process all files in the subtree that end with TEMPLATE_EXTENSION.

-g (true|false)

Optional. Default: false

If true, calls git add on each of the modified files (but does not commit).

-d (true|false)

Optional. Default: false

If true, deletes the template file after processing (if the file was not updated in-place).

Tokens

The script will replace the following tokens in processed files:

Github Workflows

These are full-blown workflows that can be triggered from your own repository on certain events.

build

Compiles a KSP mod and uploads the results as a workflow artifact. It's meant to be suitable for continuous integration builds, as it simply compiles whatever is in the repository without updating version numbers etc.

For details:

Example usage from RasterPropMonitor

create-release

Builds and packages a new version of mod. You can reference this workflow in your own repository on workflow-dispatch and have the developer type in a version number. Then it does the rest!

Note that this action DOES commit files to git (updated changelogs, version files, etc) so if you're testing it out you should do it on a separate branch.

After running update-version, this workflow commits the changelog and version file changes and creates a new tag. Then it runs compile and assemble-release. And then finally it creates a draft github release with the packaged mod attached.

For details:

Example usage from RasterPropMonitor

validate

Performs validation to help check for errors. Right now it just invokes CKAN's KSPMMCfgParser action to check for syntax errors in cfg files, but it may do more in the future. You may want to add this to a continuous integration workflow that is triggered on pull requests and commits.

Github Actions

These are smaller units of tasks that can be combined in workflows to help automate testing, building, and releasing mods.

assemble-release

Packages a mod for release or upload. Uses actions/upload-artifact so the output is attached to the workflow job and can be used by other workflow jobs.

Env:

Inputs:

Outputs:

compile

Compiles C# code using msbuild into a mod assembly. This action will install any dependent mods declared in the csproj file and restore NuGet packages.

Environment:

Inputs:

setup-ckan

Installs CKAN and sets up a KSP installation

Environment:

Inputs:

install-dependencies

Uses CKAN to install dependencies. You should generally prefer to specify them in the .csproj file. Requires setup-ckan to have already been run.

Inputs:

A space-separated list of CKAN identifiers to install.

update-version

Uses yaclog and yaclog-ksp to update a changelog and get release notes. Then runs update-version.sh to replace version tokens in several text files. All modifications will be staged to git but not committed.

Inputs:

Outputs: