Fix assets conversion bug. Add running with docker docs

Using Cython < 3.0.10 leads to the runtime errors on
assets conversion. Cython >= 3.0.10 shall be used.

Update docker build file and add chapter in documentation
about running image with Docker.

Issue: #1766

Author: DanyCppVito

CMakeLists.txt

@@ -39,7 +39,9 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 # Python and Cython requirements
 set(PYTHON_MIN_VERSION 3.9)
-set(CYTHON_MIN_VERSION 0.29.31)
+set(CYTHON_MIN_VERSION 3.0.10)
+set(CYTHON_MIN_VERSION_FALLBACK 0.29.31)
+set(CYTHON_MAX_VERSION_FALLBACK 3.0.7)
 
 # CMake policies
 foreach(pol

README.md

@@ -127,6 +127,9 @@ Quickstart
    make
    ```
 
+**Alternative approach:**
+You can build and run the project using Docker. See [Running with docker](/doc/build_instructions/docker.md) for more details.
+
 * **I compiled everything. Now how do I run it?**
     * Execute `cd bin && ./run main`.
     * [The convert script](/doc/media_convert.md) will transform original assets into openage formats, which are a lot saner and more moddable.
@@ -145,7 +148,6 @@ To turn them off, use `./bin/run --dont-segfault --no-errors --dont-eat-dog`.
 If this still does not help, try our [troubleshooting guide](/doc/troubleshooting.md), the [contact section](#contact)
 or the [bug tracker](https://github.com/SFTtech/openage/issues).
 
-
 Contributing
 ============
 

buildsystem/HandlePythonOptions.cmake

@@ -4,7 +4,17 @@
 
 # the Python version number requirement is in modules/FindPython_test.cpp
 find_package(Python ${PYTHON_MIN_VERSION} REQUIRED)
-find_package(Cython ${CYTHON_MIN_VERSION} REQUIRED)
+
+find_package(Cython ${CYTHON_MIN_VERSION})
+if(NOT CYTHON_FOUND)
+	message("Checking for alternative Cython fallback version (>=${CYTHON_MIN_VERSION_FALLBACK} AND <=${CYTHON_MAX_VERSION_FALLBACK})")
+	find_package(Cython ${CYTHON_MIN_VERSION_FALLBACK} QUIET)
+	if(CYTHON_VERSION VERSION_LESS ${CYTHON_MIN_VERSION} AND CYTHON_VERSION VERSION_GREATER ${CYTHON_MAX_VERSION_FALLBACK})
+		message(FATAL_ERROR "Cython version ${CYTHON_VERSION} is not compatible")
+	else()
+		message("Compatible Cython version ${CYTHON_VERSION} found")
+	endif()
+endif()
 
 py_get_config_var(EXT_SUFFIX PYEXT_SUFFIX)
 if(MINGW)
@@ -43,8 +53,8 @@ message("PYTHON_LIBRARIES: " "${PYTHON_LIBRARIES}")
 #Windows always uses optimized version of Python lib
 if(WIN32 AND "${CMAKE_BUILD_TYPE}" STREQUAL "Debug")
 	#get index of string "optimized" and increment it by 1 so index points at the path of the optimized lib
-	list (FIND PYEXT_LIBRARY "optimized" _index)
-	if (${_index} GREATER -1)
+	list(FIND PYEXT_LIBRARY "optimized" _index)
+	if(${_index} GREATER -1)
 		MATH(EXPR _index "${_index}+1")
 		list(GET PYEXT_LIBRARY ${_index} PYEXT_LIBRARY)
 	endif()

doc/build_instructions/docker.md

@@ -0,0 +1,70 @@
+### Running with Docker
+
+Docker simplifies the setup process by providing a consistent development environment. It allows you to build and run the project without manually installing dependencies. Currently provided [Dockerfile.ubuntu.2404](../../packaging/docker/devenv/Dockerfile.ubuntu.2404) supports Ubuntu 24.04 as the base operating system.
+
+#### Prerequisites
+
+- **Docker**: Ensure Docker is installed on your machine. Follow the [official documentation](https://docs.docker.com/) for installation instructions.
+- **Display Server**: This guide supports both **X11** and **Wayland** display servers for GUI applications.
+- **Tested Configuration**: These instructions were tested on Ubuntu 24.04 running on WSL2 on Windows 11.
+
+#### Steps to Build and Run
+
+1. **Enable GUI Support**
+
+   Depending on your display server, follow the appropriate steps:
+
+   - **For X11**:
+     Allow the Docker container to access your X server:
+     ```bash
+     xhost +local:root
+     ```
+
+   - **For Wayland**:
+     Allow the Docker container to access your Wayland socket:
+     ```bash
+     sudo chmod a+rw /run/user/$(id -u)/wayland-0
+     ```
+
+2. **Build the Docker Image**
+
+   Build the Docker image using the provided Dockerfile:
+   ```bash
+   sudo docker build -t openage -f packaging/docker/devenv/Dockerfile.ubuntu.2404 .
+   ```
+
+3. **Run the Docker Container**
+
+   Start the Docker container with the appropriate configuration for your display server:
+
+   - **For X11**:
+     ```bash
+     docker run -it \
+       -e DISPLAY=$DISPLAY \
+       -v /tmp/.X11-unix:/tmp/.X11-unix \
+       -v $HOME/.Xauthority:/root/.Xauthority \
+       --network host openage
+     ```
+
+   - **For Wayland**:
+     ```bash
+     docker run -it \
+       -e XDG_RUNTIME_DIR=/tmp \
+       -e QT_QPA_PLATFORM=wayland \
+       -e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
+       -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
+       --user=$(id -u):$(id -g) \
+       --network host openage
+     ```
+
+4. **Follow the Regular Setup**
+
+Once inside the container, follow the regular setup described in the [Development](../building.md#development) chapter. You can skip dependency installation since the Docker image already includes all required dependencies.
+
+#### Notes
+
+- **X11 vs. Wayland**: Ensure you know which display server your system is using. Most modern Linux distributions default to Wayland, but X11 is still widely used.
+- **Permissions**: For Wayland, you may need to adjust permissions for the Wayland socket (`/run/user/$(id -u)/wayland-0`) to allow Docker access.
+- **GUI Applications**: These configurations enable GUI applications to run inside the Docker container.
+
+By following these steps, you can build and run the `openage` project in a Dockerized environment with support X11 or Wayland display servers.

doc/build_instructions/ubuntu.md

@@ -2,19 +2,23 @@
 
 Run the following commands:
 
- - `sudo apt-get update`
- - `sudo apt-get install g++ cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libtoml11-dev python3-dev python3-mako python3-numpy python3-lz4 python3-pil python3-pip python3-pygments python3-toml qml6-module-qtquick-controls qt6-declarative-dev qt6-multimedia-dev  qml6-module-qtquick3d-spatialaudio`
+```bash
+ sudo apt-get update
+ sudo apt-get install g++ cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libtoml11-dev python3-dev python3-mako python3-numpy python3-lz4 python3-pil python3-pip python3-pygments python3-toml qml6-module-qtquick-controls qt6-declarative-dev qt6-multimedia-dev  qml6-module-qtquick3d-spatialaudio
+ ```
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
 
-# Additional steps for Ubuntu 22.04 LTS
+# Additional steps for Ubuntu 22.04 LTS & 24.04 LTS
 
-The available system version of Cython is too old in Ubuntu 22.04. You have to get the correct version
+The available system version of Cython is too old in Ubuntu 22.04 & 24.04. You have to get the correct version
 from pip:
 
-```
+```bash
 pip3 install cython --break-system-packages
 ```
 
+Please note that project requires at least **Cython 3.0.10**.
+
 # Linux Mint Issue
 Linux Mint has a [problem with `toml11`](https://github.com/SFTtech/openage/issues/1601), since CMake can't find it. To solve this, download the [toml11.zip](https://github.com/SFTtech/openage/files/13401192/toml11.zip), after, put the files in the `/usr/lib/x86_64-linux-gnu/cmake/toml11` path. (if the `toml11` directory doesn't exist, create it)

doc/building.md

@@ -29,7 +29,7 @@ Dependency list:
 
     C     gcc >=10 or clang >=10
     CRA   python >=3.9
-    C     cython >=0.29.31
+    C     cython >=3.0.10 OR (>=0.29.31 AND <=3.0.7)
     C     cmake >=3.16
       A   numpy
       A   lz4
@@ -161,7 +161,6 @@ The reference package is [created for Gentoo](https://github.com/SFTtech/gentoo-
 - Use `make install DESTDIR=/tmp/your_temporary_packaging_dir`,
   which will then be packed/installed by your package manager.
 
-
 ### Troubleshooting
 
 - I wanna see compiler invocations

packaging/docker/devenv/Dockerfile.ubuntu.2404

@@ -36,4 +36,8 @@ RUN apt-get update && DEBIAN_FRONTEND="noninteractive" apt-get install -y sudo \
     qt6-multimedia-dev \
     qml6-module-qtquick3d-spatialaudio \
     && sudo apt-get clean \
-    && truncate -s 0 ~/.bash_history
+    && truncate -s 0 ~/.bash_history
+
+# At least cython >= 3.0.10 < 4.0.0 is required to avoid runtime errors
+# TODO: Remove this line once cython is upgraded in Ubuntu 24.04.3 (expected around August 2025)
+RUN pip install "cython>=3.0.10,<4.0.0" --break-system-packages