Jenkins | Manual | Castle Game Engine

Jenkins

Table of Contents

1. Introduction
2. Jenkins features, from the perspective of game developers using CGE
3. Setting up Jenkins
4. Castle Game Engine Jenkins server

1. Introduction

Jenkins is an open-source automation server, that can be used to automatically test and build any application, including applications written using Castle Game Engine.

2. Jenkins features, from the perspective of game developers using CGE

There are lots of possibilities how you can use Jenkins in your projects:

Automatically build and package your application when you make a commit.
Publish the builds in any way you want. You can connect Jenkins to upload the builds to Steam, Google Play etc.
Browse the build history of your project, see which commits failed/succeeded, download the packages from each build, see compilation logs and more. You can also get automatic email notification when a build fails.
Run automated tests of your application (e.g. you can use FpcUnit testing framework, built in FPC).
Automatically generate API docs of your code (e.g. using FpDoc or PasDoc).
Use Docker images. In particular you can use Castle Game Engine Docker image to have a ready FPC + Lazarus build environment to build for multiple systems (Linux, Windows, Android) using CGE build tool and FPC. The FPC version can be switched, so you can check whether your software compiles with all FPC versions that matter to you.
The builds can be done using CGE build tool. As a simple tool operated from the command-line, it nicely works as part of Jenkins job execution.

3. Setting up Jenkins

3.1. Installation

You can install Jenkins on your own host.

You can buy your own machine e.g. on Vultr or any other hosting service that provides you with a Linux machine with full root access over ssh. Some hosting services may even offer ready hosts with Jenkins preinstalled.

Note	If you buy Vultr host through this referral link we will get a small commission which we’ll treat as a CGE donation. Thank you!

We recommend that you install at least these plugins in Jenkins:

Pipeline. This allows to define jobs using Jenkinsfile files in your repository, which is IMHO the most comfortable and flexible way to control Jenkins. This plugin will be suggested during the Jenkins installation.
Docker Pipeline. This allows to use Docker within Jenkins Pipeline jobs, in particular to use Castle Game Engine Docker image that gives you a great environment to build CGE applications.

3.2. Create a project

You can make Jennkins observe a particular repository (using GIT, SVN or other version control). We recommend setting Jenkins to scan all the branches in the indicated repository for Jenkinsfile files, and execute the builds for all branches where Jenkinsfile is present. To do this, just create "Multibranch Pipeline".

Or, you can go one step further, and observe whole GitHub organization, with all projects within. To do this, create "Organization Folder".

There is not much to configure within the project initially. Just point Jenkins to the correct version control (GIT, SVN…) URL and provide any necessary credentials. Jenkins will scan the branches within the repository for Jenkinsfile and execute them. (Don’t worry if you didn’t commit Jenkinsfile yet; you can commit it later and Jenkins will detect it.)

3.3. Basic Jenkinsfile

Jenkinsfile is a file that you should commit to your repository and it will configrue the build job.

Below is a basic Jenkinsfile that

uses Castle Game Engine Docker image,
uses CGE build tool within the Docker image,
builds and packages for Windows and Linux using a series of castle-engine package … commands,
archives (saves for later download) the results, i.e. the xxx.zip, xxx.tar.gz produced builds,
makes email notification in case things go wrong.

Go ahead, adjust it and commit it as Jenkinsfile to the top level directory of your repository.

Note	In case of SVN, `Jenkinsfile` should be right within the `trunk/`, or `branches/xxx/` subdirectories of the repository. IOW, each branch can have a (potentially different) `Jenkinsfile`.

Sample Jenkinsfile:

/* -*- mode: groovy -*-
  Configure how to run the job in Jenkins.
  See https://castle-engine.io/jenkins .
*/

pipeline {
  agent {
    docker {
      image 'kambi/castle-engine-cloud-builds-tools:cge-unstable'
    }
  }
  stages {
    stage('Build Desktop') {
      steps {
        sh 'castle-engine auto-generate-textures'
        sh 'castle-engine package --os=win64 --cpu=x86_64 --verbose'
        sh 'castle-engine package --os=win32 --cpu=i386 --verbose'
        sh 'castle-engine package --os=linux --cpu=x86_64 --verbose'
      }
    }
  }
  post {
    success {
      archiveArtifacts artifacts: 'my_game*.tar.gz,my_game*.zip,my_game*.apk'
    }
    regression {
      mail to: '[email protected]',
        subject: "[jenkins] Build started failing: ${currentBuild.fullDisplayName}",
        body: "See the build details on ${env.BUILD_URL}"
    }
    failure {
      mail to: '[email protected]',
        subject: "[jenkins] Build failed: ${currentBuild.fullDisplayName}",
        body: "See the build details on ${env.BUILD_URL}"
    }
    fixed {
      mail to: '[email protected]',
        subject: "[jenkins] Build is again successfull: ${currentBuild.fullDisplayName}",
        body: "See the build details on ${env.BUILD_URL}"
    }
  }
}

3.4. Jenkinsfile examples

You can find many Jenkinsfile examples in our repositories:

Jenkinsfile in castle-game.
"Wyrd Forest" Jenkinsfile.
"Castle Game Engine" Jenkinsfile — trivially run a number of tests.

3.5. Download and test the artifacts

Once the build is done, on the Jenkins page you can see the statistics about recent builds (how long they took, whether they succeeded) and you can download artifacts of your project. The "artifacts" are just files that you consider the "output" from the build process. In case of CGE games, it is usually a couple of archives like my_game-0.1.0-linux-x86_64.tar.gz, my_game-0.1.0-win32-i386.zip, my_game-0.1.0-win64-x86_64.zip, produced by the build tool package command.

You can also see the logs for each build. If a build compilation failed, these logs will contain the information "why". The logs are the first thing to consult if you want to know what happened (and what failed) during the build.

3.6. Building release APK for Android, providing credentials to Android keystore

If you have a keystore to build release APK versions, you can use it with Jenkins. (See Android FAQ: Signing a release APK / AAB how to create such keystore.)

We recommend storing the keystore and the passwords to access it using Jenkins credentials (this is a way to store secrets (needed to access something) in Jenkins).

The add a Jenkins stage like this to build a release APK:

stage('Build Mobile') {
  steps {
    withCredentials([
      file(credentialsId: 'android-my-keystore', variable: 'android_my_keystore'),
      string(credentialsId: 'android-my-keystore-alias', variable: 'android_my_keystore_alias'),
      string(credentialsId: 'android-my-keystore-alias-password', variable: 'android_my_keystore_alias_password'),
      string(credentialsId: 'android-my-keystore-store-password', variable: 'android_my_keystore_store_password')
    ]) {
      sh '''
      echo "key.store=${android_my_keystore}" > AndroidSigningProperties.txt
      echo "key.alias=${android_my_keystore_alias}" >> AndroidSigningProperties.txt
      echo "key.store.password=${android_my_keystore_store_password}" >> AndroidSigningProperties.txt
      echo "key.alias.password=${android_my_keystore_alias_password}" >> AndroidSigningProperties.txt
      '''
      sh 'castle-engine package --target=android --verbose'
    }
  }
}

3.7. Customize FPC and Lazarus version used

By default, building uses the latest stable FPC version (currently 3.2.2), as advised by CGE. To switch to another FPC/Lazarus version, use instead the alternative Docker image version, like cge-none-fpc320 or cge-none-fpc331. These alternative images don’t include CGE, so you will need to also build CGE inside the Docker, following compiling from source docs (in practice, just download CGE sources and compile our build tool, that’s likely all you need).

3.8. Jenkinsfile documentation

For more information about Jenkinsfile, and Jenkins with Pipeline plugin (which is what is happening here), see

Jenkins Pipeline documentation.
Jenkinsfile syntax. We advise using the "declarative" syntax of Jenkinsfile, as it’s just simpler. All the examples on this page use it.
All possible "steps" (think: "commands you can use") in the Jenkinsfile.

4. Castle Game Engine Jenkins server

We maintain a Jenkins for Castle Game Engine server. It is used for Castle Game Engine development, running a lot of CGE tests and builds on various slaves (Linux, Windows, macOS, Raspberry Pi). Michalis grants access to it. If you are a regular CGE contributor and you would like such access, send an email to Michalis Kamburelis.

In the past we considered even making this server public. That is, make it available to anyone who makes open-source applications using CGE (for free) or even closed-source (if you are on a specific Patreon tier). But this idea was abandoned — as 100% securely isolating multiple projects managed by a single Jenkins master is not easy, and maintaining multiple isolated Jenkins master machines is just too costly for us to provide such service.

However, both GitHub Actions and GitLab CI are available and we document how to use them with CGE applications. Their usage is generally free for open-source projects.

To improve this documentation just edit this page and create a pull request to cge-www repository.