Merge 4013575234 into 81d62d01d1

README.md

@@ -12,17 +12,17 @@ Luanti is a free open-source voxel game engine with easy modding and game creati
 Copyright (C) 2010-2025 Perttu Ahola <celeron55@gmail.com>
 and contributors (see source file comments and the version control log)
 
-Table of Contents
+Table of Contents <!-- omit from toc -->
 ------------------
 
-1. [Further Documentation](#further-documentation)
+- [Further documentation](#further-documentation)
-2. [Default Controls](#default-controls)
+- [Default controls](#default-controls)
-3. [Paths](#paths)
+- [Paths](#paths)
-4. [Configuration File](#configuration-file)
+- [Configuration file](#configuration-file)
-5. [Command-line Options](#command-line-options)
+- [Command-line options](#command-line-options)
-6. [Compiling](#compiling)
+- [Compiling](#compiling)
-7. [Docker](#docker)
+- [Docker](#docker)
-8. [Version Scheme](#version-scheme)
+- [Version scheme](#version-scheme)
 
 
 Further documentation
@@ -123,9 +123,11 @@ Compiling
 ---------
 
 - [Compiling - common information](doc/compiling/README.md)
-- [Compiling on GNU/Linux](doc/compiling/linux.md)
+- [Compiling on Linux](doc/compiling/linux.md)
-- [Compiling on Windows](doc/compiling/windows.md)
+- [Compiling on Windows using Visual Studio](doc/compiling/windows.md)
+- [Compiling on Windows using MSYS2](doc/compiling/windows_msys2.md)
 - [Compiling on MacOS](doc/compiling/macos.md)
+- [Compiling for Android](doc/compiling/android.md)
 
 Docker
 ------

doc/android.md

@@ -75,40 +75,3 @@ Supported architectures:
 Unlike on PC, Android devices use OpenGL ES which less powerful than OpenGL, thus
 some shader settings cannot be used on OpenGL ES.
 Changing the graphic driver setting to OpenGL will not work.
-
-## Building Requirements
-In order to build, your PC has to be set up to build Luanti in the usual
-manner (see the regular Luanti documentation for how to get this done).
-In addition to what is required for Luanti in general, you will need the
-following software packages. The version number in parenthesis denotes the
-version that was tested at the time this README was drafted; newer/older
-versions may or may not work.
-
-* Android SDK 29
-* Android NDK r21
-* Android Studio 3 [optional]
-
-Additionally, you'll need to have an Internet connection available on the
-build system, as the Android build will download some source packages.
-
-## Build
-The new build system Luanti Android is fully functional and is designed to
-speed up and simplify the work, as well as adding the possibility of
-cross-platform build.
-You can use `./gradlew assemblerelease` or `./gradlew assembledebug` from the
-command line or use Android Studio and click the build button.
-
-When using gradlew, the newest NDK will be downloaded and installed
-automatically. Or you can create a `local.properties` file and specify
-`sdk.dir` and `ndk.dir` yourself.
-
-* In order to make a release build you'll have to have a keystore setup to sign
-  the resulting apk package. How this is done is not part of this README. There
-  are different tutorials on the web explaining how to do it
-  - choose one yourself.
-
-* Once your keystore is setup, enter the android subdirectory and create a new
-  file "ant.properties" there. Add the following lines to that file:
-
-  > key.store=<path to your keystore>
-  > key.alias=Minetest

doc/compiling/README.md

@@ -1,8 +1,12 @@
 # Compiling Luanti
 
-- [Compiling on GNU/Linux](linux.md)
+- [Compiling on Linux](linux.md)
-- [Compiling on Windows](windows.md)
+- Windows
+  - [Compiling on Windows using Visual Studio](windows.md)
+  - [Compiling on Windows using MSYS2](windows_msys2.md)
 - [Compiling on MacOS](macos.md)
+- [Compiling for Android](android.md)
+- [Improving build times](improving_build_times.md)
 
 
 ## CMake options

doc/compiling/android.md

@@ -0,0 +1,148 @@
+# Compiling for Android
+
+The instructions in this article were written for and tested on Linux,
+but the tools used here should also work on other platforms.
+
+You can build Luanti for Android either using CLI tools or Android Studio.
+
+## Prerequisites
+
+- Basic familiarity with the command line.
+- You have a working network connection.
+- You have already downloaded / cloned a copy of Luanti to a folder called `luanti`.
+- You have an Android device you want to install Luanti on for testing purposes
+  or you want to produce a Luanti release build for distribution.
+
+## CLI tools
+
+### Setup
+
+You should have a recent version of OpenJDK installed (17 should be enough).
+
+Download the command line tools from the [corresponding section on the Android Studio downloads page](https://developer.android.com/studio#command-line-tools-only).
+Then extract it into an empty folder with the structure being as seen below.
+The `android-sdk` folder will then become your SDK folder.
+
+```
+- android-sdk/
+    - cmdline-tools/
+```
+
+Then open a terminal in `android-sdk/` and run the following command to accept the licenses for the SDK.
+Accept the licenses that you definitively should read carefully.
+
+```sh
+./cmdline-tools/bin/sdkmanager --licenses --sdk_root=.
+```
+
+Now create a file called `local.properties` and configure the path to the Android SDK there:
+
+```sh
+cd luanti/android
+echo 'sdk.dir=/home/<YOUR USER>/android-sdk' >local.properties
+```
+
+_(On Windows, if the above doesn't work, try running the command `sdkmanager --sdk_root="<path to the folder you want to install SDK tools to>" "platform-tools"`. You will likely need to add this path to your [PATH environment variable](https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/), so PowerShell can recognize the installed components.)_
+
+### Building
+
+Optional: First figure out the ABI of the device you wish to build for
+and disable all other ABIs to significantly reduce build times.
+(See [here](/for-engine-devs/compiling/improving-build-times/#android-disabling-unused-abis) for details.)
+
+Luanti uses a [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html),
+which makes building Luanti for Android very easy: You just run
+
+```sh
+cd luanti/android
+./gradlew app:assembleDebug
+```
+
+If the build is not working, try first cleaning the cache via `./gradlew clean` before building.
+
+_(If you're compiling on Windows, you can use the `gradle` command, so long as you install the additional Unix dependency [gettext](https://www.gnu.org/software/gettext/). Both of these are verified to work when installed by [Scoop](https://scoop.sh).)_
+
+This will produce a number of debug builds in the form of `.apk` files (depending on the enabled ABIs)
+in `android/app/build/outputs`:
+
+```sh
+$ find -name '*.apk'
+./app/build/outputs/apk/debug/app-armeabi-v7a-debug.apk
+./app/build/outputs/apk/debug/app-x86_64-debug.apk
+./app/build/outputs/apk/debug/app-x86-debug.apk
+./app/build/outputs/apk/debug/app-arm64-v8a-debug.apk
+```
+
+If you want to build a release, you would invoke `./gradlew app:assembleRelease` instead.
+To sign the release APK before distribution, you should use [`apksigner`](https://developer.android.com/tools/apksigner).
+(Debug APKs will already be signed automatically with a debug key.)
+
+### Installing
+
+If instead of building APKs you want to directly build and install the appropriate APK on your phone via the
+Android Debug Bridge (ADB) [^1], you can run `./gradlew app:installDebug`,
+or `./gradlew app:installRelease` if you want to install a release build
+(e.g. for performance testing) instead.
+
+## Using Android Studio
+
+First, install [Android Studio](https://developer.android.com/studio),
+for example by downloading an official release, unpacking it and then running `./android-studio/bin/studio.sh`.
+
+Then, open `luanti/android` (_not_ the `luanti` folder):
+
+![The Android Studio file picker, used to select `luanti/android`](images/open_folder.png)
+
+It will load for a while. Be patient.
+
+If you just want to quickly install and run a debug build on your phone,
+you can simply click the "run" button in the top bar,
+which will build Luanti for the correct ABI and install it afterwards via ADB [^1]:
+
+![Android Studio "Run" Button](images/run.png)
+
+Otherwise, click "Build" > "Generate Signed Bundle / APK" [^2]:
+
+![Android Studio menu](images/generate_bundle.png)
+
+Android Studio will now ask you to choose between a Bundle (for uploading to app stores) and an APK (for direct distribution & deployment).
+We want to create an APK:
+
+![Android Studio prompting the user to choose between a Bundle or APK](images/choose_bundle_format.png)
+
+Now we have to sign it. Android Studio guides you through this process.
+You first have to create a key store if you don't already have one.
+
+Choose a key store path (you should probably keep this in a safe location),
+then choose and confirm a key store password.
+
+You also have to choose and confirm an (ideally separate) password for the individual key
+(called `example_key` here).
+
+Key creation asks for personal information.
+Fill it out responsibly with as much information as you are comfortable providing.
+You can not leave it entirely blank.
+
+![Android Studio with a chosen key store path of `/home/lars/Android/Keystore.jks`](images/create_keystore.png)
+
+Now proceed: Click "OK" and then "Next".
+
+Android Studio will ask you to choose between a "debug" and a "release" build.
+Since you're already going through the hassle of signing, we assume you want a release build.
+
+Finally, you can just click "Create" and patiently wait for the release build to finish. This can take a while.
+
+Once it has finished, Android Studio then lets you "locate" the APK,
+which should be in `build/outputs/apk/release`
+(or `build/outputs/apk/debug` for a debug build) relative to `luanti/android`.
+
+If the build fails, you may try "Build" > "Clean Build" > "Clean Project" followed by "Build" > "Rebuild Project".
+
+[^1]:
+    This assumes your phone is connected and has USB debugging enabled (or you have set up an Android emulator).
+    For details see the [ADB](https://developer.android.com/tools/adb) and Android Studio documentation.
+
+[^2]:
+    If you can't find the "Build" option in the top bar,
+    you have to first click the hamburger in the top left corner.
+    Such is the downfall of modern UI design.

doc/compiling/improving_build_times.md

@@ -0,0 +1,58 @@
+# Improving build times
+
+This page contains useful tips for improving build times when compiling Luanti. This is useful when you are repeatedly building Luanti for testing or if you want to make incremental builds as quick as possible.
+
+The instructions assume you are on Linux, as that's where you can usually expect the best compile times in general.
+
+## Use Clang
+
+Luanti supports building with the Clang compiler, which generally compiles somewhat faster compared to GCC. You should be able to install Clang from your Linux distribution's package manager and then make CMake build with Clang instead of GCC with the following build options:
+
+```bash
+-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
+```
+
+## Use mold
+
+`mold` is a linker that runs much faster than the standard `ld` or even the `lld` linker.
+
+```bash
+-DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=mold" -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=mold"
+```
+
+## Use ninja
+
+Ninja is a build system that aims to have less overhead than regular makefiles, which should make it slightly faster. CMake supports generating Ninja build files by using `-G Ninja` when first generating a build directory. You cannot change the generator in an already created build folder.
+
+Do note that Ninja will automatically detect your processor count and set the amount of jobs if you don't manually set anything. This might be an issue if you want to do something while compiling in the background. You can check what is the default with `ninja --help` and manually pass the job count like one would do with make: `ninja -j4`.
+
+## Android: Disabling unused ABIs
+
+When building Luanti for Android by default it will build for all four supported ABIs, meaning it will build Luanti four times over. If you are doing testing and know the device you are using you can save build times by limiting it to only building a single ABI that works on the device.
+
+You can change the ABI filter `abiFilters` in `android/native/build.gradle`. Below is an explanation of each ABI listed:
+
+| ABI ID        | ABI name   | Where you may need it                   |
+| ------------- | ---------- | --------------------------------------- |
+| `armeabi-v7a` | 32-bit ARM | Very old phones                         |
+| `arm64-v8a`   | 64-bit ARM | Modern phones (likely the one you have) |
+| `x86`         | 32-bit x86 | Android SDK emulator (x86 images)       |
+| `x86_64`      | 64-bit x86 | Android SDK emulator (x86_64 images)    |
+
+## Luanti compile option tweaks
+
+These may reduce build times further, but at cost of some functionality being missing.
+
+- `-DENABLE_LTO=OFF` to disable LTO which may make linking take longer than expected. This is disabled by default in Debug builds.
+- `-DBUILD_UNITTESTS=OFF` which may save some time when doing full rebuilds. May not be useful if you want to actually run the unit tests.
+- `-ENABLE_GETTEXT=OFF` disables PO->MO compilation, if this takes a while to finish. Translations will be disabled in the resulting build.
+
+## When in a hurry
+
+Once you have cloned the Luanti repository:
+
+```bash
+mkdir build; cd build
+cmake .. -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=mold" -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=mold" -G Ninja
+ninja
+```

doc/compiling/linux.md

@@ -1,4 +1,4 @@
-# Compiling on GNU/Linux
+# Compiling on Linux
 
 ## Dependencies
 

doc/compiling/windows.md

@@ -1,4 +1,6 @@
-# Compiling on Windows using MSVC
+# Compiling on Windows using Visual Studio MSVC
+
+**Compiling with Visual Studio** | [Compiling with MSYS2](windows_msys2.md)
 
 ## Requirements
 
@@ -7,7 +9,6 @@
 - [vcpkg](https://github.com/Microsoft/vcpkg)
 - [Git](https://git-scm.com/downloads)
 
-
 ## Compiling and installing the dependencies
 
 It is highly recommended to use vcpkg as package manager.

doc/compiling/windows_msys2.md

@@ -0,0 +1,76 @@
+# Compiling on Windows using MSYS2
+
+[Compiling with Visual Studio](windows.md) | **Compiling with MSYS2**
+
+For a video tutorial of setting up a Luanti development environment on Windows using MSYS2 (including setting up VSCodium), you can see [this video](https://www.youtube.com/watch?v=y8eWDzLNa3E) by Exe_Virus.
+
+## Installation
+
+First, download and install the [latest version of MSYS2](https://www.msys2.org/).
+
+After installation, a terminal opens. Run the following command to update the environment:
+
+```bash
+pacman -Syu
+```
+
+The terminal will then ask you to close it when done, proceed with doing so. Then open the MSYS2 CLANG64 environment whose icon has a dark orange background. (For information on what the different environments do, see [Environments](https://www.msys2.org/docs/environments/) in MSYS2's documentation)
+
+## Compiling
+
+Install all the necessary dependencies:
+
+```bash
+pacman -S git mingw-w64-clang-x86_64-{clang,cmake,ninja,curl-winssl,libpng,libjpeg-turbo,freetype,libogg,libvorbis,sqlite3,openal,zstd,gettext,luajit,SDL2}
+```
+
+Navigate to some folder where you want to clone the Luanti repository. To get out of MSYS2's home folder and into your regular users folder, you would want to enter something like this:
+
+```bash
+cd /c/Users/$USER/Desktop
+```
+
+Clone Luanti:
+
+```bash
+git clone --depth 1 https://github.com/luanti-org/luanti
+cd luanti
+```
+
+And start the building process:
+
+```bash
+mkdir build; cd build
+cmake .. -G Ninja
+ninja
+```
+
+Once it's finished compiling, there should be a luanti.exe executable inside of `bin/` inside your Luanti folder. You can run it inside of the MSYS2 environment by running `../bin/luanti.exe` in the terminal, but it will not work if you try to open the executable from Windows explorer, as the necessary DLLs aren't next to the executable.
+
+## Bundling DLLs
+
+For bundling DLLs, you may want to use [msys2-bundledlls](https://github.com/rollerozxa/msys2-bundledlls) which is able to copy over any libraries the executable is linked against and put it next to the executable.
+
+Run the following commands from the build directory to download the script:
+
+```bash
+curl https://raw.githubusercontent.com/rollerozxa/msys2-bundledlls/master/bundledlls > ../bundledlls
+```
+
+When you have downloaded the script, usage is as such:
+
+```bash
+../bundledlls ../bin/luanti.exe ../bin/
+```
+
+It will print out a list of libraries it has copied to the binary folder once finished. Now it should be possible to run the Luanti executable outside of the MSYS2 environment.
+
+## Notes
+
+### Something about packages being untrusted or corrupted?
+
+If you have an existing MSYS2 install that has been dormant for a while without updates, you might run into issues trying to install or update packages as the keyring is outdated. See [potential issues](https://www.msys2.org/docs/updating/#potential-issues) on the MSYS2 website on how to solve this.
+
+### Graphics is broken in a VM
+
+If you're doing this inside of a VM and you want to test the executable but get graphics issues due to a lack of hardware acceleration, you can try downloading the Mesa software renderer as a DLL. [Download the 64-bit version of the DLL here](https://fdossena.com/?p=mesa/index.frag) and put it next to the executable in `bin/`. It will be slow but should be usable for testing.