JavaProgressia/docs/building/BuildScriptReference.md

Build Script Reference

This document is a user's reference for the build script of Progressia. For a beginner-friendly guide, see Build Guide.

Gradle tasks summary

• buildLocal – creates a build optimized for current platform. Use this to quickly build the game during development.
• buildCrossPlatform – creates a build that supports all known architectures. Use this to build a universal version of the game.
• build – currently a synonym of buildLocal; creates a default build.
• packageZip – creates a universal ZIP. Incompatible with other package tasks.
• packageDeb – creates a Debian package. Incompatible with other package tasks.
• packageNsis – creates a Windows NSIS installer. Incompatible with other package tasks.
• requestLinuxDependencies – requests that natives-linux, natives-linux-arm32 and natives-linux-arm64 binaries are included when building.
• requestWindowsDependencies – requests that natives-windows, natives-windows-arm64 and natives-windows-x86 binaries are included when building.
• requestMacOSDependencies – requests that natives-macos and natives-macos-arm64 binaries are included when building.
• requestCrossPlatformDependencies – requests that all binaries are included when building.

To execute a task, run ./gradlew <task-name>.

build-type tasks output the executable JAR and all libraries required at runtime into build/libs. package-type tasks output packages into build/packages.

Packaging tasks

Some packaging tasks require additional software in PATH.

Task	Commands required in PATH
packageDeb	dpkg-deb
packageZip	none
packageNsis	makensis, convert (from ImageMagick)

Version and metadata

Version scheme

Progressia builds are identified by four parameters: version, Git commit, Git branch and build ID.

Versions roughly follow semantic versioning, with each version fitting the MAJOR.MINOR.PATCH[-SUFFIX] pattern. Depending on the build environment (see below), version is either "real" with no metadata (e.g. 0.43.2 or 1.2.1-beta) or a dummy fallback with build metadata (e.g. 999.0.0-2021_07_23 or 999.0.0-WJ3).

Version detection

Build script considers three scenarios when determining the version:

1. version project property is set explicitly. This may be done in a variety of ways, for example with command line argument -Pversion=1.2.3 (see Gradle docs)
2. Local Git repository is found, and HEAD is tagged appropriately: version is the tag name with leading v stripped. Example: v1.2.3 is version 1.2.3
3. Local Git repository is found, and some ancestor of HEAD is tagged appropriately: version is the tag name with leading v stripped and PATCH incremented by one. Example: v1.2.3 is version 1.2.4

Tags not named like vMAJOR.MINOR.PATCH[-SUFFIX] are ignored for cases 2 and 3.

In all other cases, a fallback dummy value is used for version, appended with build ID or current date.

Git metadata

Git commit is determined from GIT_COMMIT environment variable if it exists, or the state of the local Git repository, if any, or -.

Git branch is determined from GIT_BRANCH environment variable if it exists, or the state of the local Git repository, if any, or -.

The names of the environment variables are picked to assist Jenkins builds.

Build ID

Build ID uniquely identifies artifacts produced by automated build systems. Build ID must be provided explicitly; it is - unless specified otherwise.

The proposed scheme for naming build IDs is <builder><build-system><build attempt no.>. For example, builds executed by WindCorp Jenkins suite have build IDs like WJ3 or WJ142.

Build ID may be set with buildId project property. This may be done in a variety of ways, for example with command line argument -PbuildId=WJ3 (see Gradle docs).

Native libraries

LWJGL uses native libraries. Build script declares platform-specific dependencies based on the set of target platforms, project.ext.lwjgl.targets (aka lwjgl.targets). These dependencies are added to runtimeOnly configuration.

When this set is empty, the script selects natives for current platform. Otherwise, all platforms in the set are included.

lwjgl.targets is populated automatically by packaging tasks and by buildCrossPlatform. To add extra targets, ``requestXxxDependencies` tasks may be used.

Target selection mechanism may be overridden with forceTargets project property. This may be done in a variety of ways, for example with command line argument -PforceTargets=windows-x86,local (see Gradle docs). The value is a comma-separated list of target architectures. local target will be replaced with the automatically detected current architecture.

Available targets

Name	Task
linux	requestLinuxDependencies
linux-arm32	requestLinuxDependencies
linux-arm64	requestLinuxDependencies
windows	requestWindowsDependencies
windows-arm64	requestWindowsDependencies
windows-x86	requestWindowsDependencies
macos	requestMacOSDependencies
macos-arm64	requestMacOSDependencies