docker run --name my-cge-container --volume="${HOME}":/home/sharedhome/ -it kambi/castle-engine-cloud-builds-tools:cge-unstable bash
Manual
Docker
Table of Contents
 |
1. Using Castle Game Engine inside a Docker image
We have a Docker image that contains Castle Game Engine along with various tools preconfigured. The image is available on Docker hub, the image is called "kambi/castle-engine-cloud-builds-tools".
Using the Docker image gives you a stable environment where we have:
-
Castle Game Engine (stable and unstable versions, depending on the Docker image tag:
cge-stable,cge-unstable,cge-none). -
FPC (latest stable version) with cross-compilers for various platforms
-
Android SDK and NDK
-
Texture compression tools useful with CGE from NVidia and PowerVR
This Docker image can be used by continuous integration systems like Jenkins and GitHub Actions. It can also be used on your local computer. Instead of downloading FPC, CGE, Android SDK and NDK etc., you only have to get the Docker image.
2. Getting the Docker, basic Docker concepts and links
Follow the https://www.docker.com/ to install Docker. You will most likely want to follow the official docs about Installing Docker Community Edition.
You should read the Docker documentation and Reference to understand some Docker terminology.
Here’s a short version:
-
"Docker image" is like a template for a virtual machine.
-
"Docker container" is like an actual virtual machine with installed OS (Linux).
-
A stopped container is like a stopped operating system, you can run it again (and have the same files).
There are two ways to use Docker container:
-
You can easily create and destroy temporary Docker containers, even to just execute a single command.
-
You can also just create and use one Docker container for a long time.
3. Using the Docker image
Commands below may serve as an example how to use our Docker image to easily create a Docker container my-cge-container, and use it quite like a virtual machine.
Treat these commands as an example, please. There are various ways of doing this. These commands are written with a Linux user in mind — on Windows you will have to adjust them.
First run a container from a console like this:
You can play around in the resulting shell, end by Ctrl + D (or exit and Enter).
|
Note
|
We recommend using container with cge-unstable (CGE version 7.0-alpha.snapshot), not cge-stable (CGE version 7.0-alpha.3) in most cases. As the engine grows fast lately — for most users using latest CGE snapshot is better (and it is, in practice, very stable — we test it a lot).
|
Next time, enter this container like this:
docker start my-cge-container --attach --interactive # The above command is basically a shortcut for: #docker start my-cge-container # make container running #docker attach my-cge-container # attach to the new "bash" process inside
To remove the container from your system:
docker rm my-cge-container
Inside the container, you have a regular Linux command-line.
-
Try commands like
fpc -lorcastle-engine --versionto make sure you have FPC and CGE inside the container. -
Try
ls /home/sharedhome/to make sure you see your shared directory, if you followed the above example usage of--volume. -
You can install whatever you need (
apt-get install ...works), and just use it as a regular virtual machine. -
Example above shows using
--volumeoption fordocker runto share your $HOME directory. You can also copy files between host/container usingdocker cp( https://docs.docker.com/engine/reference/commandline/cp/ ).
4. Using the Docker image to compile CGE applications
Inside the Docker container, just use the installed castle-engine build tool to compile your projects, like this:
cd /home/sharedhome/my-game/ castle-engine compile castle-engine package
Your project directory needs to have a CastleEngineManifest.xml file inside. Or you can compile any Pascal source with castle-engine simple-compile someunit.pas. There are many other commands available, see the build tool documentation.
You can easily create an Android application (APK file) with:
castle-engine package --target=android
This way you don’t need to install all the things mentioned at https://castle-engine.io/android — they are already available inside the Docker container. You get an APK, which you can copy to your Android device (phone, tablet) in any way, and then install and run it — like any other application in APK form.
If you want to generate compressed textures, you can run in Docker container
castle-engine auto-generate-textures
The advantage is, again, that you don’t need to install all the tools mentioned on the generating compressed textures docs. These tools are ready inside the Docker container.
You can also use command-line fpc or lazbuild to build Pascal applications.
5. Limitations
-
No GUI. Although Lazarus is installed inside the container, but it’s primary use is to run
lazbuildto compile Lazarus packages. The container doesn’t have visual libraries (X) installed, and is not connected to your host display, so you cannot readily use GUI Lazarus for development. It is possible to execute GUI application inside Docker, but it may be easier to just install Lazarus in a normal way, on your host system. -
No connection to host USB port to connect to your phone. Using Android SDK to install and run APK on your phone will not work, as inside the Docker container we don’t see your USB devices. So commands like this will not work within the container:
-
adb devices -
adb logcat -
castle-engine install --target=android -
castle-engine run --target=androidIf you need these commands to work, you need to link:android[install Android SDK/NDK on your regular host system] and work without the Docker.
You can also copy the APK file to your phone, and install APK by selecting it on your phone. This works, but you will not see the logs of the running application, which are quite valuable when debugging.
You can also use TestFairy integration to distribute the APK. This way we can get the logs remotely, using Android test_fairy service or iOS test_fairy service. Note that this is a paid feature of TestFairy (although you get 14-day trial).
-
6. Updating the Docker image
Our Docker image kambi/castle-engine-cloud-builds-tools:cge-unstable contains the very latest "unstable" engine version. It is updated automatically after every CGE commit. Our Jenkins runs many automated engine tests (making sure everything compiles, with various FPC versions and on various platforms), then rebuilds the engine binary release and then updates the ...:cge-unstable Docker image.
However, note that the Docker image on your local disk, and the containers you created based on it, are not automatically updated in any way. If you want to update your image to have the latest CGE, simply do it explicitly:
docker pull kambi/castle-engine-cloud-builds-tools:cge-unstable
After this, create a new container that starts from kambi/castle-engine-cloud-builds-tools:cge-unstable image, following the text above on this page.
|
Note
|
Your previous images and containers will continue to exist, unmodified. The previous image is no longer tagged docker ps -aq | xargs docker rm # remove all containers docker images -q | xargs docker rmi # remove all images |
|
Note
|
If you plan to update CGE often, but would still like to use Docker image (e.g. to easily get working environment to build Android APK), then another approach is to use the Docker image This way, there is no need to update the Docker image often. The Docker image |
7. Sources
The bash script, Dockerfiles, Jenkinksfiles etc. to generate these Docker images are open-source on https://github.com/castle-engine/castle-engine-docker .
8. Alternative FPC versions
Alternative FPC versions are in the alternative tags, right now:
-
cge-none-fpc320has FPC 3.2.0 -
cge-none-fpc331has recent FPC 3.3.1. The exact FPC 3.3.1 revision is listed here.
In the past, we used to have bigger images, with all FPC versions switchable at runtime, but this was making image size too big. It was problematic for GitHub action default runners, and useless for people who didn’t want to switch FPC versions.
Note that the "alternative FPC versions" images come without CGE included (only all CGE prerequisites). Follow compiling from source docs to set up CGE inside the container. Here are simple commands that should work within the container created from cge-none, cge-none-fpc331 or other cge-none* images to set up CGE and compile a sample project for Linux and Android:
# 1. Get CGE from GitHub
git clone --depth 1 --single-branch --branch master https://github.com/castle-engine/castle-engine/
# 2. Make build tool
cd castle-engine/tools/build-tool/
./castle-engine_compile.sh
# 3. Setup environment variables to use this CGE, with this build tool.
export CASTLE_ENGINE_PATH=$HOME/castle-engine
export PATH="${PATH}:"`pwd`
# Note: next time you run the shell, you will have to set this environment again.
# You can also add these lines to ~/.bashrc to make them permanent.
# Print their current values with "echo $CASTLE_ENGINE_PATH" and "echo $PATH".
# 4. Switch to some example project, and build it
cd ../../examples/mobile/simple_3d_demo/
castle-engine package # build for Linux by default
castle-engine package --target=android # build for AndroidTo improve this documentation just edit this page and create a pull request to cge-www repository.
