From c15302510ac492eea4757fdbfac7a1c2501af7cb Mon Sep 17 00:00:00 2001 From: annel0 Date: Sat, 27 Sep 2025 14:06:51 +0300 Subject: [PATCH] docs: fix admonition syntax, improve build instructions, and add --parallel flag (#628) * docs: fix admonition syntax, improve build instructions, and add --parallel flag * docs: add libglfw3 to Debian dependencies per author note --- README.md | 117 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 71 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 4777cb25..30925fef 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ - [Download](https://github.com/MihailRis/VoxelCore/releases/latest) | [Скачать](https://github.com/MihailRis/VoxelCore/releases/latest) - [Documentation](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/en/main-page.md) | [Документация](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/ru/main-page.md) +--- + ## Build project in Linux ### Install libraries @@ -13,13 +15,14 @@ ```sh git clone https://github.com/skypjack/entt.git -cd entt/build -cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=on .. +cd entt +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=ON .. sudo make install ``` > [!WARNING] -> If you are using ALT Linux, you should not use this EnTT installation method +> If you are using ALT Linux, do **not** use this EnTT installation method. #### ALT Linux based distros @@ -31,11 +34,11 @@ apt-get install entt-devel libglfw3-devel libGLEW-devel libglm-devel libpng-deve #### Debian based distros ```sh -sudo apt install libglfw3-dev libglfw3 libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev +sudo apt install libglfw3 libglfw3-dev libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev ``` > [!TIP] -> CMake missing LUA_INCLUDE_DIR and LUA_LIBRARIES fix: +> 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 @@ -45,24 +48,24 @@ sudo apt install libglfw3-dev libglfw3 libglew-dev libglm-dev libpng-dev libopen #### RHEL based distros ```sh -sudo dnf install glfw-devel glfw glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel +sudo dnf install glfw-devel glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel ``` #### Arch based distros -If you use X11 +If you use X11: ```sh sudo pacman -S glfw-x11 glew glm libpng libvorbis openal luajit libcurl ``` -If you use Wayland +If you use Wayland: ```sh sudo pacman -S glfw-wayland glew glm libpng libvorbis openal luajit libcurl ``` -And you need entt. In yay you can use +And install EnTT: ```sh yay -S entt @@ -76,9 +79,14 @@ cd VoxelCore mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release .. -cmake --build . +cmake --build . --parallel ``` +> [!TIP] +> Use `--parallel` to utilize all CPU cores during build. + +--- + ## Building project in macOS ### Install libraries @@ -88,9 +96,7 @@ brew install glfw3 glew glm libpng libvorbis lua luajit libcurl openal-soft skyp ``` > [!TIP] -> If homebrew for some reason could not install the necessary packages: -> ```lua luajit openal-soft```, then download, install and compile them manually -> (Lua, LuaJIT and OpenAL). +> If Homebrew fails to install `lua`, `luajit`, or `openal-soft`, download, compile, and install them manually. ### Building engine with CMake @@ -100,90 +106,109 @@ cd VoxelCore mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release .. -cmake --build . +cmake --build . --parallel ``` +--- + ## Building in Windows ->[!NOTE] -> Requirement: -> -> vcpkg, CMake, Git +> [!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, most likely the **VCPKG_ROOT** environment variable will already exist in **Developer Command Prompt for VS** -2. If you want use **vcpkg**, install **vcpkg** from git to you system: -```PowerShell -cd C:/ + +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 ``` -After installing **vcpkg**, setup env variable **VCPKG_ROOT** and add it to **PATH**: -```PowerShell -$env:VCPKG_ROOT = "C:\path\to\vcpkg" + +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 you can read full [documentation](https://learn.microsoft.com/ru-ru/vcpkg/get_started/get-started?pivots=shell-powershell) for **vcpkg** -After installing **vcpkg** you can build project: -```PowerShell +> [!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. + +--- + ## Build using Docker -### Step 0. Install docker on your system +> [!NOTE] +> First, install Docker Engine: [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install) -See +### On Linux -### Do you have Linux - -### Step 1. Build docker container +#### Step 1. Build Docker image ```sh docker build -t voxel-engine . ``` -### Step 2. Build project using the docker container +#### 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" +docker run --rm -it -v "$(pwd):/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel" ``` -### Step 3. Run project using the docker container +#### 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 -eDISPLAY --network=host voxel-engine ./build/VoxelEngine +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/VoxelEngine ``` -### Do you have Windows +### On Windows -### Step 1. You need to install VcXsrv +> [!NOTE] +> You need an X server like **VcXsrv** to display the GUI. -### Step 2. Run VcXsrv with the command +#### Step 1. Install and run VcXsrv +Launch with: ```powershell .\vcxsrv.exe :0 -multiwindow -ac ``` -### Step 3. Build docker container +#### Step 2. Build Docker image ```powershell docker build -t voxel-engine . ``` -### Step 4. Build project using the docker container +#### 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" +docker run --rm -it -v "${PWD}:/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel" ``` -### Step 5. Run project using the docker container +#### 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/VoxelEngine +docker run --rm -it -v "${PWD}:/project" -e DISPLAY=host.docker.internal:0.0 --network=host voxel-engine ./build/VoxelEngine ```