From dd094d76065185bf4c38ab4b5f2677d40b24f0fc Mon Sep 17 00:00:00 2001
From: sfan5 <sfan5@live.de>
Date: Wed, 10 Jan 2024 18:20:07 +0100
Subject: [PATCH] Write down some developer documentation

I think it's better suited here than in the wiki.
---
 README.md                |  4 +--
 doc/developing/README.md | 24 +++++++++++++++
 doc/developing/misc.md   | 65 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+), 2 deletions(-)
 create mode 100644 doc/developing/README.md
 create mode 100644 doc/developing/misc.md

diff --git a/README.md b/README.md
index 231a5c3fd..ff7ef5a69 100644
--- a/README.md
+++ b/README.md
@@ -25,11 +25,11 @@ Table of Contents
 
 Further documentation
 ----------------------
-- Website: https://minetest.net/
+- Website: https://www.minetest.net/
 - Wiki: https://wiki.minetest.net/
-- Developer wiki: https://dev.minetest.net/
 - Forum: https://forum.minetest.net/
 - GitHub: https://github.com/minetest/minetest/
+- [Developer documentation](doc/developing/)
 - [doc/](doc/) directory of source distribution
 
 Default controls
diff --git a/doc/developing/README.md b/doc/developing/README.md
new file mode 100644
index 000000000..b12e75ce4
--- /dev/null
+++ b/doc/developing/README.md
@@ -0,0 +1,24 @@
+# Developer documentation
+
+## Wiki
+
+Some important development docs are found in the wiki: https://dev.minetest.net/
+
+Notable pages:
+
+- [Releasing Minetest](https://dev.minetest.net/Releasing_Minetest)
+- [Engine translations](https://dev.minetest.net/Translation#Maintaining_engine_translations)
+- [Changelog](https://dev.minetest.net/Changelog)
+- [Organisation](https://dev.minetest.net/Organisation)
+- [Code style guidelines](https://dev.minetest.net/Code_style_guidelines)
+
+## In this folder
+
+- [Developing minetestserver with Docker](docker.md)
+- [Miscellaneous](misc.md)
+
+## IRC
+
+Oftentimes knowledge hasn't been written down (yet) and your best bet is to ask someone experienced and/or the core developers.
+
+Feel free to join the [#minetest-dev IRC](https://wiki.minetest.net/IRC) and ask questions related to **engine development**.
diff --git a/doc/developing/misc.md b/doc/developing/misc.md
new file mode 100644
index 000000000..a48ed2237
--- /dev/null
+++ b/doc/developing/misc.md
@@ -0,0 +1,65 @@
+# Miscellaneous
+
+## Sign the Android APK from CI
+
+The [Github Actions Workflow](https://github.com/minetest/minetest/actions?query=workflow%3Aandroid+event%3Apush)
+automatically produces an APK for each architecture.
+Before installing them onto a device they however need to be signed.
+
+This requires an installation of the Android SDK and `adb`.
+```bash
+.../android-sdk/build-tools/30.0.3/apksigner sign --ks ~/.android/debug.keystore \
+	app-arm64-v8a-release-unsigned.apk
+# Enter 'android' (without quotes) when asked for a password
+```
+
+Note that the `debug.keystore` will not exist if you have never compiled an
+Android app on your system (probably).
+
+After that installing it will work:
+```bash
+adb install -r -d ./app-arm64-v8a-release-unsigned.apk
+```
+
+## How to get debug output from Minetest on Android
+
+In case debug.txt isn't enough (e.g. when debugging a crash), you can get debug
+output using logcat:
+
+`adb logcat -s 'Minetest:*' '*:F'`
+
+Note that you can do this even *after* the app has crashed,
+since Android keeps an internal buffer.
+
+A segmentation fault for example looks like this:
+
+```
+01-10 17:20:22.215 19308 20560 F libc    : Fatal signal 6 (SIGABRT), code -1 (SI_QUEUE) in tid 20560 (MinetestNativeT), pid 19308 (netest.minetest)
+01-10 17:20:22.287 20576 20576 F DEBUG   : *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
+01-10 17:20:22.287 20576 20576 F DEBUG   : Build fingerprint: '...'
+01-10 17:20:22.287 20576 20576 F DEBUG   : Revision: '4'
+01-10 17:20:22.287 20576 20576 F DEBUG   : ABI: 'arm64'
+01-10 17:20:22.288 20576 20576 F DEBUG   : Timestamp: 2024-01-10 17:20:22+0100
+01-10 17:20:22.288 20576 20576 F DEBUG   : pid: 19308, tid: 20560, name: MinetestNativeT  >>> net.minetest.minetest <<<
+01-10 17:20:22.288 20576 20576 F DEBUG   : uid: 10385
+01-10 17:20:22.288 20576 20576 F DEBUG   : signal 6 (SIGABRT), code -1 (SI_QUEUE), fault addr --------
+[ ... more information follows ... ]
+```
+
+## Profiling Minetest on Linux
+
+We will be using a tool called "perf", which you can get by installing `perf` or `linux-perf` or `linux-tools-common`.
+
+For best results build Minetest and Irrlicht with debug symbols
+(`-DCMAKE_BUILD_TYPE=RelWithDebInfo` or `-DCMAKE_BUILD_TYPE=Debug`).
+
+Run the client (or server) like this and do whatever you wanted to test:
+```bash
+perf record -z --call-graph dwarf -- ./bin/minetest
+```
+
+This will leave a file called "perf.data".
+
+You can open this file with perf built-in tools but much more interesting
+is the visualization using a GUI tool: **[Hotspot](https://github.com/KDAB/hotspot)**.
+It will give you flamegraphs, per-thread, per-function views and much more.