From 76b91a3ef685e288cc54e6a1131760d9c68faff0 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Sun, 5 Nov 2023 11:07:23 +0100
Subject: [PATCH] [dev] manage runtime versions with asdf

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 .tool-versions        |   2 +
 docs/dev/index.rst    |   1 +
 docs/dev/rtm_asdf.rst | 121 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 .tool-versions
 create mode 100644 docs/dev/rtm_asdf.rst

diff --git a/.tool-versions b/.tool-versions
new file mode 100644
index 000000000..a8d9d4672
--- /dev/null
+++ b/.tool-versions
@@ -0,0 +1,2 @@
+python 3.12.0
+shellcheck 0.9.0
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
index aa0667c58..09be9de5e 100644
--- a/docs/dev/index.rst
+++ b/docs/dev/index.rst
@@ -6,6 +6,7 @@ Developer documentation
    :maxdepth: 2
 
    quickstart
+   rtm_asdf
    contribution_guide
    engines/index
    search_api
diff --git a/docs/dev/rtm_asdf.rst b/docs/dev/rtm_asdf.rst
new file mode 100644
index 000000000..69180ef4e
--- /dev/null
+++ b/docs/dev/rtm_asdf.rst
@@ -0,0 +1,121 @@
+==================
+Runtime Management
+==================
+
+The runtimes are managed with asdf and are activated in this project via the
+`.tool-versions <.tool-versions>`_. If you have not yet installed asdf_, then
+chapter :ref:`introduce asdf` may be of help to you.
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+Get started
+===========
+
+If you have asdf installed you can install the runtimes of this project by:
+
+.. code:: bash
+
+   $ cd /path/to/searxng
+   $ asdf install          # will install runtimes listed in .tool-versions
+   ...
+
+Manage Versions
+===============
+
+If you want to perform a ``test`` with special runtime versions of nodejs,
+python or shellcheck, you can patch the ``.tool-versions``:
+
+.. code:: diff
+
+   --- a/.tool-versions
+   +++ b/.tool-versions
+   @@ -1,2 +1,2 @@
+   -python 3.12.0
+   -shellcheck 0.9.0
+   +python 3.11.6
+   +shellcheck 0.8.0
+
+To install use ``asdf install`` again.  If the runtime tools have changed, any
+existing (nodejs and python) environments should be cleaned up with a ``make
+clean``.
+
+.. code:: bash
+
+   $ asdf install
+   ...
+   $ make clean test
+
+
+.. _introduce asdf:
+
+Introduce asdf
+==============
+
+To `download asdf`_ and `install asdf`_:
+
+.. code:: bash
+
+   $ git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch <version>
+   $ echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
+   $ echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
+
+Start a new shell and try to `install plugins`_:
+
+.. code:: bash
+
+   $ asdf plugin-list-all | grep -E '(golang|python|nodejs|shellcheck).git'
+   golang                        https://github.com/asdf-community/asdf-golang.git
+   nodejs                        https://github.com/asdf-vm/asdf-nodejs.git
+   python                        https://github.com/danhper/asdf-python.git
+   shellcheck                    https://github.com/luizm/asdf-shellcheck.git
+
+   $ asdf plugin add golang https://github.com/asdf-community/asdf-golang.git
+   $ asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
+   $ asdf plugin add python https://github.com/danhper/asdf-python.git
+   $ asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git
+
+Each plugin has dependencies, to compile runtimes visit the URLs from above and
+look out for the dependencies you need to install on your OS, on Debian for the
+runtimes listed above you will need:
+
+.. code:: bash
+
+  $ sudo apt update
+  $ sudo apt install \
+         dirmngr gpg curl gawk coreutils build-essential libssl-dev zlib1g-dev \
+         libbz2-dev libreadline-dev libsqlite3-dev \
+         libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
+
+With dependencies installed you can install/compile runtimes:
+
+.. code:: bash
+
+  $ asdf install golang latest
+  $ asdf install nodejs latest
+  $ asdf install python latest
+  $ asdf install shellcheck latest
+
+Python will be compiled and will take a while.
+
+In the repository the version is defined in `.tool-versions`_. Outside the
+repository, its recommended that the runtime should use the versions of the OS
+(`Fallback to System Version`_) / if not already done register the system
+versions global:
+
+.. code:: bash
+
+   $ cd /
+   $ asdf global golang system
+   $ asdf global nodejs system
+   $ asdf global python system
+   $ asdf global shellcheck system
+
+.. _asdf: https://asdf-vm.com/
+.. _download asdf: https://asdf-vm.com/guide/getting-started.html#_2-download-asdf
+.. _install asdf: https://asdf-vm.com/guide/getting-started.html#_3-install-asdf
+.. _install plugins: https://asdf-vm.com/guide/getting-started.html#install-the-plugin
+.. _Fallback to System Version: https://asdf-vm.com/manage/versions.html#fallback-to-system-version