voxelcore/README.md
alexei-zebra b6f6235249
Fix the issues found while reviewing the build files
Install the Wayland development packages in both workflows and bundle the
runtime libraries in the AppImage: the release build had no native Wayland
backend at all, and the engine silently fell back to GLFW there.

Build the window backends on every platform that is not Windows and not
Apple, glob the wayland sources with CONFIGURE_DEPENDS, and report a
missing Wayland dependency with the list of what is missing.

Also drop the dead nested project() calls and the duplicate -no-pie
option, make .dirIcon the file appimagetool expects, and describe the
real Linux dependencies in the README.
2026-10-11 20:06:19 +03:00

228 lines
5.8 KiB
Markdown

# ![voxel-core](dev/VoxelCore.png) VoxelCore
## Latest release
- [Download](https://github.com/MihailRis/VoxelCore/releases/latest) | [Скачать](https://github.com/MihailRis/VoxelCore/releases/latest)
- [Documentation](https://github.com/MihailRis/VoxelCore/blob/release-0.32/doc/en/main-page.md) | [Документация](https://github.com/MihailRis/VoxelCore/blob/release-0.32/doc/ru/main-page.md)
---
## Build project in Linux
### Install libraries
#### Install EnTT
Installing last version that supports C++17.
```sh
git clone --branch v3.16.0 https://github.com/skypjack/entt.git
cd entt
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=ON ..
sudo make install
```
#### ALT Linux based distros
```sh
su -
apt-get install entt-devel libglfw3-devel libGLEW-devel libglm-devel libpng-devel libvorbis-devel libopenal-devel libluajit-devel libstdc++13-devel-static libcurl-devel libfreetype-devel libssl-devel
```
#### Debian based distros
```sh
sudo apt install libglfw3 libglfw3-dev libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev libssl-dev libfreetype6-dev
```
> [!TIP]
> CMake missing `LUA_INCLUDE_DIR` and `LUA_LIBRARIES` fix:
>
> ```sh
> sudo ln -s /usr/lib/x86_64-linux-gnu/libluajit-5.1.a /usr/lib/x86_64-linux-gnu/liblua5.1.a
> sudo ln -s /usr/include/luajit-2.1 /usr/include/lua
> ```
#### RHEL based distros
```sh
sudo dnf install glfw-devel glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel libfreetype-devel openssl-devel
```
#### Arch based distros
```sh
sudo pacman -S glfw glew glm libpng libvorbis openal luajit curl freetype2 openssl
```
#### Wayland
On Linux the engine draws the window frame itself and needs `libwayland-dev`
(with `libwayland-bin` for `wayland-scanner`), `libxkbcommon-dev` and
`libegl-dev`. The protocol XML descriptions are vendored in
`src/window/wayland/protocols`, so the `wayland-protocols` package is not used.
`libsystemd-dev` is optional and adds the window button layout read through
sd-bus. Build with `-DVOXELCORE_WAYLAND=OFF` to fall back to GLFW.
### Building engine with CMake
```sh
git clone --recursive https://github.com/MihailRis/VoxelCore.git
cd VoxelCore
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
```
> [!TIP]
> Use `--parallel` to utilize all CPU cores during build.
---
## Building project in macOS
### Install libraries
```sh
brew install glfw3 glew glm libpng libvorbis lua luajit libcurl openal-soft skypjack/entt/entt freetype
```
> [!TIP]
> If Homebrew fails to install `lua`, `luajit`, or `openal-soft`, download, compile, and install them manually.
### Building engine with CMake
```sh
git clone --recursive https://github.com/MihailRis/VoxelCore.git
cd VoxelCore
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
```
---
## Building in Windows
> [!NOTE]
> Requirements: **vcpkg**, **CMake**, **Git**, and **Visual Studio** (with C++ tools).
There are two options to use vcpkg:
1. If you have Visual Studio installed, the **VCPKG_ROOT** environment variable is often already set in the **Developer Command Prompt for VS**.
2. Otherwise, install **vcpkg** manually:
```powershell
cd C:\
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
```
Then set the `VCPKG_ROOT` environment variable and add it to `PATH`:
```powershell
$env:VCPKG_ROOT = "C:\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"
```
> [!TIP]
> For troubleshooting, refer to the official [vcpkg documentation](https://learn.microsoft.com/ru-ru/vcpkg/get_started/get-started?pivots=shell-powershell).
After installing **vcpkg**, build the project:
```powershell
git clone --recursive https://github.com/MihailRis/VoxelCore.git
cd VoxelCore
cmake --preset default-vs-msvc-windows
cmake --build --preset default-vs-msvc-windows
```
> [!NOTE]
> Make sure your `CMakeUserPresets.json` (if used) contains the correct `VCPKG_ROOT` path.
---
### Building with CLion (MinGW / Ninja)
> [!NOTE]
> Requirements: **vcpkg**, **Git**, and **CLion** (bundled with CMake, Ninja and MinGW toolchain).
> [!WARNING]
> Avoid installing tools in paths with spaces (e.g. `Program Files`).
> This may break MinGW builds (especially `windres`).
Install **vcpkg** manually as described in the Visual Studio section.
#### Configure CLion
Open the project in CLion and configure CMake profile:
```text
Settings → Build, Execution, Deployment → CMake
```
Reload CMake project and build the engine.
---
## Build using Docker
> [!NOTE]
> First, install Docker Engine: [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install)
### On Linux
#### Step 1. Build Docker image
```sh
docker build -t voxel-engine .
```
#### Step 2. Build project inside container
```sh
docker run --rm -it -v "$(pwd):/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"
```
#### Step 3. Run the application (requires X11 forwarding)
```sh
docker run --rm -it \
-v "$(pwd):/project" \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v "$XAUTHORITY:/home/user/.Xauthority:ro" \
-e DISPLAY="$DISPLAY" \
--network=host \
voxel-engine ./build/VoxelCore
```
### On Windows
> [!NOTE]
> You need an X server like **VcXsrv** to display the GUI.
#### Step 1. Install and run VcXsrv
Launch with:
```powershell
.\vcxsrv.exe :0 -multiwindow -ac
```
#### Step 2. Build Docker image
```powershell
docker build -t voxel-engine .
```
#### Step 3. Build project
```powershell
docker run --rm -it -v "${PWD}:/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"
```
#### Step 4. Run the application
```powershell
docker run --rm -it -v "${PWD}:/project" -e DISPLAY=host.docker.internal:0.0 --network=host voxel-engine ./build/VoxelCore
```