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: Daniel-Wieczorek

CMakeLists.txt

@@ -39,7 +39,7 @@ 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)
 
 # 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,62 +4,74 @@
 
 # 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)
+
+# Define minimum and fallback versions for Cython
+set(CYTHON_MIN_VERSION 3.0.10)
+set(CYTHON_MIN_VERSION_FALLBACK 0.29.31)
+
+find_package(Cython QUIET)
+if (CYTHON_FOUND AND
+    ((CYTHON_VERSION VERSION_GREATER_EQUAL ${CYTHON_MIN_VERSION}) OR
+    (CYTHON_VERSION VERSION_GREATER ${CYTHON_MIN_VERSION_FALLBACK} AND CYTHON_VERSION VERSION_LESS 3.0.0)))
+    message("Using Cython ${CYTHON_VERSION}")
+else()
+    message(FATAL_ERROR "Not found Cython compatible version (>= ${CYTHON_MIN_VERSION} or > ${CYTHON_MIN_VERSION_FALLBACK} in 0.29.x).")
+endif()
 
 py_get_config_var(EXT_SUFFIX PYEXT_SUFFIX)
 if(MINGW)
-	string(REGEX REPLACE "dll" "pyd" PYEXT_SUFFIX "${PYEXT_SUFFIX}")
+    string(REGEX REPLACE "dll" "pyd" PYEXT_SUFFIX "${PYEXT_SUFFIX}")
 endif()
 
 # This is the only useful thing after cleaning up what python suggests
 if(NOT "${CMAKE_CXX_COMPILER_ID}" STREQUAL "MSVC")
-	set(PYEXT_CXXFLAGS "-fwrapv")
+    set(PYEXT_CXXFLAGS "-fwrapv")
 endif()
 
 
 # numpy deprecated api
 # http://docs.cython.org/en/latest/src/userguide/source_files_and_compilation.html#configuring-the-c-build
 if(CYTHON_VERSION VERSION_GREATER_EQUAL 3)
-	set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -DNPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION")
+    set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -DNPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION")
 else()
 
-	# suppress #warning about deprecated numpy api
-	if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU")
-		set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -Wno-cpp")
-	elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang")
-		set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -Wno-#warnings")
-	endif()
+    # suppress #warning about deprecated numpy api
+    if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU")
+        set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -Wno-cpp")
+    elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang")
+        set(PYEXT_CXXFLAGS "${PYEXT_CXXFLAGS} -Wno-#warnings")
+    endif()
 endif()
 
 # silence cython+python3.8 tp_print deprecation warning
 # https://github.com/cython/cython/pull/3201
 # https://github.com/cython/cython/issues/3474
 if(PYTHON_VER VERSION_GREATER_EQUAL 3.8 AND PYTHON_VERSION VERSION_LESS 3.9)
-	set(PYEXT_CXXCLAGS "${PYEXT_CXXCLAGS}" "-Wno-deprecated-declarations")
+    set(PYEXT_CXXCLAGS "${PYEXT_CXXCLAGS}" "-Wno-deprecated-declarations")
 endif()
 
 set(PYEXT_LIBRARY "${PYTHON_LIBRARIES}")
 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)
-		MATH(EXPR _index "${_index}+1")
-		list(GET PYEXT_LIBRARY ${_index} PYEXT_LIBRARY)
-	endif()
-	message("force linking to python release lib, instead of debug lib when cythonising")
-	set(force_optimized_lib_flag "--force_optimized_lib")
+    #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)
+    	MATH(EXPR _index "${_index}+1")
+        list(GET PYEXT_LIBRARY ${_index} PYEXT_LIBRARY)
+    endif()
+    message("force linking to python release lib, instead of debug lib when cythonising")
+    set(force_optimized_lib_flag "--force_optimized_lib")
 endif()
 
 set(PYEXT_INCLUDE_DIRS "${PYTHON_INCLUDE_DIRS};${NUMPY_INCLUDE_DIR}")
 
 if(NOT CMAKE_PY_INSTALL_PREFIX)
-	if(MSVC)
-		set(CMAKE_PY_INSTALL_PREFIX "python")
-	else()
-		# get site-packages directory, prepended with cmake's install prefix
-		py_exec("import sys, sysconfig, os; print(os.path.join('${CMAKE_INSTALL_PREFIX}', os.path.relpath(sysconfig.get_path('purelib'), os.path.normpath(sys.prefix))))" PREFIX)
-		set(CMAKE_PY_INSTALL_PREFIX "${PREFIX}")
-	endif()
+    if(MSVC)
+        set(CMAKE_PY_INSTALL_PREFIX "python")
+    else()
+        # get site-packages directory, prepended with cmake's install prefix
+        py_exec("import sys, sysconfig, os; print(os.path.join('${CMAKE_INSTALL_PREFIX}', os.path.relpath(sysconfig.get_path('purelib'), os.path.normpath(sys.prefix))))" PREFIX)
+        set(CMAKE_PY_INSTALL_PREFIX "${PREFIX}")
+    endif()
 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
     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