Use Castle Game Engine in CI/CD like GitHub Actions

Script setup_castle_engine to easily setup:

• Castle Game Engine

• and FPC (Free Pascal Compiler (with recommended version for CGE)

• and Lazarus (with recommended version for CGE). Note that Lazarus is not installed by default (because regular CGE projects don't need it), pass --install-lazarus=true to install it.

The primary usage is within CI/CD, like GitHub Actions (but also other CI/CD systems).

Details what it does

Overall goal: After the setup_castle_engine script is called, you can use castle-engine package within your CI job to package your project.

The script enhances the $PATH variable (and sets up a few other environment variables) to include FPC and CGE build tool by:

• enhancing $GITHUB_ENV and $GITHUB_PATH (if defined, within GitHub Actions)

• and generating setup_castle_engine_env.sh (this is useful for non-GitHub Action CI, and even within GHA to define variables within the same step).

Details what it does:

• Get and setup FPC recommended to use with CGE.

  Downloads FPC (to fpc/ subdir) from our castle-fpc releases which have prebuild FPC binary + FPC sources.

  And sets up fpc.cfg to use it properly (see castle-fpc/README.md docs). The environment variable $PPC_CONFIG_PATH will point to it.

• Get and setup CGE in recommended way for CI/CD.

  This downloads CGE sources from the snapshot tag by default (latest engine that passed automatic tests) and builds our build tool ("castle-engine") and sets $CASTLE_ENGINE_PATH and $PATH to use it.

Usage

Simply checkout this repo, and run setup_castle_engine.

This is a bash script. On GitHub-hosted runners, bash is available on all systems, including Windows (through MSys2).

Usage example in GitHub Actions

...
defaults:
  run:
    shell: bash

jobs:
  build:
    name: Build Project using castle-build-ci
    strategy:
      matrix:
        runner: [
          ubuntu-latest,
          windows-latest
        ]
    runs-on: ${{ matrix.runner }}
    steps:
      - name: Checkout application
        uses: actions/checkout@v6

      - name: Setup Castle Game Engine
        run: |
          cd /tmp/ # temporary directory, to be separate from the current project files
          git clone https://github.com/castle-engine/castle-build-ci.git \
            --depth=1 --single-branch --branch=master
          castle-build-ci/install_dependencies
          castle-build-ci/setup_castle_engine

      - name: Package
        run: castle-engine package --verbose

More complete example in the workflow within this repo, which is our own test: .github/workflows/test.yml.

Optional command-line arguments:

• --os=<os>

  OS (operating system) name, following the FPC naming conventions. This specifies both source and target OS. See castle-fpc/build_fpc script documentation for details why it is useful, (despite specifying both source and target OS). We auto-detect it if not specified.

• --cpu=<cpu>

  CPU (processor, architecture) name, following the FPC naming conventions. This specifies both source and target CPU. We auto-detect it if not specified.

• --castle-engine-version=<git-branch-or-tag>

  Castle Game Engine version (GIT branch or tag name). We use snapshot by default.

• --fpc-version=stable|unstable

  FPC version to use. See castle-fpc for the exact meaninig of stable and unstable, in short:

  • stable is the "best stable" FPC version that we test with CGE. Equals now FPC 3.2.2 on most platforms, and 3.2.3 (from fixes_3_2 branch) some some exceptions.

  • unstable is a particular tested commit of the FPC main branch, with FPC 3.3.1.

  We use stable by default.

• --install-castle-engine=true|false

  Install Castle Game Engine. Enabled by default.

• --install-fpc=true|false

  Install FPC (Free Pascal Compiler). Enabled by default.

  Note that you need fpc to install CGE or Lazarus, so if you pass --fpc=false we assume that you have installed FPC in your CI job in some other way (e.g. apt-get install fpc on Linux). We also assume it's a version supported by CGE.

• --install-lazarus=true|false

  Install Lazarus. Disabled by default.

Example execution with parameters:

setup_castle_engine --os=linux --cpu=x86_64 --castle-engine-version=v7.0-alpha.3

Current directory

Current directory when this is called matters:

• We will create fpc/ and castle-engine/ subdirs there.

• We will create setup_castle_engine_env.sh there.

• In CI jobs, it is most comfortable to use a temporary directory like /tmp/, also to clone this repo (castle-build-ci) into a temporary directory. See above for example usage.

Environment variables and usage outside of GitHub Actions

The script defines a few environment variables which should "survive" to the next steps.

• The variable definitions are written to setup_castle_engine_env.sh, which is a bash script that you can source to load the variables.

• We also write variables (except PATH) following GitHub Actions conventions to $GITHUB_ENV.

• We also write path extensions to $GITHUB_PATH. See github_actions_prepend_path.md for more information.

There are 2 practical conclusions:

• If you want to rely on new environment variables within the same CI step, you need to source setup_castle_engine_env.sh after running setup_castle_engine.

  This goes for both usage in GitHub Actions and in other CI systems.

  Like this:

  castle-build-ci/setup_castle_engine ...
  source setup_castle_engine_env.sh

• To use this script outside of GitHub Actions, do source setup_castle_engine_env.sh to load the variables at the beginning of all future steps to have the variables available.

Alternatives to setup FPC and CGE in CI/CD

This is by far not the way to setup FPC and CGE in CI/CD.

Alternatives:

• You can use our Docker images that give you ready FPC and CGE tools, with cross-compilers for various platforms.

  It's more powerful in some ways than this script. E.g. Docker has FPC with cross-compiler for Android, and Android build toolchain.

  However, our Docker images cannot be used to make macOS builds. This script can.

• Or you can get only FPC using:

  • setup-lazarus action
  • Or by installing it in runners from packages, like brew install fpc (macOS) or apt-get install fpc (Linux).

• Or you can get only CGE by:

  • just git clone the CGE repository and build the build tool following instructions. This is what we do in the 2nd part of setup_castle_engine script for you, but it's really not difficult to do it yourself :)
  • downloading binary release using curl or wget in your script.

See also: Apple signing scripts

As a bonus, see apple/README.md for scripts to sign and notarize macOS applications.

If you make macOS applications, you can use these scripts to have your application signed and notarized automatically in CI/CD.